syncfusion-wpf-datapager

实现 DataPager

在 WPF 应用程序中使用 Syncfusion WPF DataPager（SfDataPager）对大型数据集进行分页的指南。DataPager 控件提供导航按钮、数字页码按钮和灵活的数据绑定选项，可将数据划分为易于管理的页面。

何时使用此技能

当用户需要以下功能时，请使用此技能：

• 在 WPF 应用程序中对大型数据集进行分页
• 添加页面导航控件（首页、末页、下一页、上一页按钮）
• 以易于管理的页面大小显示数据
• 为大型数据集实现按需分页
• 将分页数据绑定到任意 ItemsControl（DataGrid、ListBox、ListView）
• 自定义分页外观（颜色、显示模式、方向）
• 处理页面更改事件并进行验证
• 创建带有数字页码按钮的分页视图
• 在运行时更改页面大小
• 以编程方式在页面之间导航

组件概述

SfDataPager 是一个 WPF 控件，可将数据集合划分为多个页面并提供导航 UI：

• 导航按钮：首页、末页、上一页、下一页按钮
• 数字按钮：直接跳转到指定页面（例如，1、2、3、4、5）
• 自动省略号：当页面数超过数字按钮数量时显示省略号按钮
• 灵活绑定：通过 PagedSource 属性与任意 ItemsControl 配合使用
• 按需分页：仅为当前页面动态加载数据
• 事件：通过 PageIndexChanging 和 PageIndexChanged 进行验证并实现自定义逻辑
• 外观：可自定义颜色、显示模式和方向

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 所需程序集（Syncfusion.SfGrid.WPF、Syncfusion.Data.WPF）
• 控件结构和元素
• 创建第一个 SfDataPager 应用程序
• 与 SfDataGrid 集成
• 将 SfDataPager 添加到工具箱
• 主题支持和主题设置

数据绑定和分页

📄 阅读： references/data-binding.md

• Source 和 PagedSource 属性
• PageIndex 属性和事件
• 绑定到 ListBox、ListView 或其他 ItemsControl
• 使用 UseOnDemandPaging 实现按需分页
• 使用 LoadDynamicItems 方法动态加载数据
• PageSize 配置
• 使用 ComboBox 在运行时更改 PageSize

外观和样式

📄 阅读： references/appearance.md

• AutoEllipsisMode（After、Before、Both、None）
• AccentBackground 和 AccentForeground 颜色
• NumericButtonStyle 自定义
• DisplayMode 选项（12 种不同模式）
• Orientation（Horizontal、Vertical）

页面导航

📄 阅读： references/page-navigation.md

• MoveToFirstPage()、MoveToLastPage() 方法
• MoveToNextPage()、MoveToPreviousPage() 方法
• 使用 MoveToPage(int pageIndex) 直接导航
• 用于验证的 PageIndexChanging 事件
• 在更改页面前与用户交互

样式和模板

📄 阅读： references/styles-templates.md

• 在 Expression Blend 中编辑样式
• 在 Visual Studio 中编辑样式
• “编辑副本”与“创建空白”选项
• 自定义控件模板
• 资源管理

快速入门示例

将 SfDataPager 与 SfDataGrid 集成的基本示例：

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:sfgrid="clr-namespace:Syncfusion.UI.Xaml.Grid;assembly=Syncfusion.SfGrid.WPF"
        xmlns:datapager="clr-namespace:Syncfusion.UI.Xaml.Controls.DataPager;assembly=Syncfusion.SfGrid.WPF">
    
    <Window.DataContext>
        <local:ViewModel/>
    </Window.DataContext>
    
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="*" />
            <RowDefinition Height="Auto" />
        </Grid.RowDefinitions>
        
        
        <sfgrid:SfDataGrid AutoGenerateColumns="True"
                           ItemsSource="{Binding ElementName=sfDataPager, Path=PagedSource}"/>
        
        
        <datapager:SfDataPager x:Name="sfDataPager"
                               Grid.Row="1"
                               NumericButtonCount="10"
                               PageSize="10"
                               Source="{Binding OrdersDetails}"/>
    </Grid>
</Window>

关键概念：

• Source：绑定到数据集合（例如，OrdersDetails）
• PagedSource：为 ItemsControl 自动包装的 PagedCollectionView
• PageSize：每页的项目数
• NumericButtonCount：要显示的数字页码按钮数

常见模式

模式 1：使用 DataGrid 实现基本分页

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="*"/>
        <RowDefinition Height="Auto"/>
    </Grid.RowDefinitions>
    
    <sfgrid:SfDataGrid ItemsSource="{Binding ElementName=sfDataPager, Path=PagedSource}"/>
    
    <datapager:SfDataPager x:Name="sfDataPager"
                           Grid.Row="1"
                           PageSize="20"
                           Source="{Binding DataCollection}"/>
</Grid>

模式 2：自定义外观

<datapager:SfDataPager x:Name="sfDataPager"
                       AccentBackground="DodgerBlue"
                       AccentForeground="White"
                       AutoEllipsisMode="Both"
                       NumericButtonCount="5"
                       PageSize="15"
                       Source="{Binding DataCollection}"/>

模式 3：在运行时更改 PageSize

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="*"/>
        <RowDefinition Height="Auto"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>
    
    <sfgrid:SfDataGrid ItemsSource="{Binding ElementName=sfDataPager, Path=PagedSource}"/>
    
    <ComboBox Name="pageSizeComboBox"
              Grid.Column="1" Grid.Row="1"
              SelectedIndex="0"
              ItemsSource="{Binding PageSizeOptions}"/>
    
    <datapager:SfDataPager x:Name="sfDataPager"
                           Grid.Row="1"
                           PageSize="{Binding SelectedValue, ElementName=pageSizeComboBox}"
                           Source="{Binding DataCollection}"/>
</Grid>

模式 4：按需分页（大型数据集）

<datapager:SfDataPager x:Name="sfDataPager"
                       UseOnDemandPaging="True"
                       PageCount="100"
                       PageSize="20"
                       OnDemandLoading="OnDemandDataLoading"/>

private void OnDemandDataLoading(object sender, OnDemandLoadingEventArgs args)
{
    // Load data for current page only
    var pageData = dataSource.Skip(args.StartIndex).Take(args.PageSize);
    sfDataPager.LoadDynamicItems(args.StartIndex, pageData);
}

模式 5：页面更改验证

<datapager:SfDataPager PageIndexChanging="sfDataPager_PageIndexChanging"/>

private void sfDataPager_PageIndexChanging(object sender, PageIndexChangingEventArgs e)
{
    // Validate or prompt user before page change
    if (HasUnsavedChanges())
    {
        var result = MessageBox.Show("Unsaved changes. Continue?", 
                                     "Confirm", 
                                     MessageBoxButton.YesNo);
        if (result == MessageBoxResult.No)
        {
            e.Cancel = true; // Cancel page navigation
        }
    }
}

关键属性

属性	类型	描述
Source	IEnumerable	用于分页的数据集合
PagedSource	PagedCollectionView	分页数据（绑定到 ItemsSource）
PageSize	int	每页的项目数（默认值：0 = 所有项目）
PageIndex	int	当前页索引（从 0 开始）
PageCount	int	总页数
NumericButtonCount	int	要显示的数字按钮数量
AutoEllipsisMode	AutoEllipsisMode	省略号按钮的位置（After、Before、Both、None）
AccentBackground	Brush	导航按钮/选中按钮的背景色
AccentForeground	Brush	选中按钮的前景色
DisplayMode	PageDisplayMode	要显示的按钮（例如 FirstLastPreviousNextNumeric）
Orientation	Orientation	水平或垂直布局
UseOnDemandPaging	bool	启用按需加载数据

关键方法

方法	描述
MoveToFirstPage()	转到第一页
MoveToLastPage()	转到最后一页
MoveToNextPage()	转到下一页
MoveToPreviousPage()	转到上一页
MoveToPage(int pageIndex)	转到指定页面
LoadDynamicItems(int startIndex, IEnumerable items)	为按需分页加载数据

关键事件

事件	描述
PageIndexChanging	页面切换前触发（可取消）
PageIndexChanged	页面切换后触发

实现工作流

用户请求实现 DataPager 时：

1. 评估需求：确定数据量、每页大小需求和外观偏好
2. 选择分页模式：
   • 普通分页（中小型数据集）
   • 按需分页（大型数据集，数百万条记录）
3. 添加程序集：Syncfusion.SfGrid.WPF、Syncfusion.Data.WPF（如果与 DataGrid 一起使用）
4. 设置数据绑定：Source → PagedSource → ItemsControl.ItemsSource
5. 配置外观：PageSize、NumericButtonCount、AccentColors、DisplayMode
6. 添加事件处理程序（如有需要）：使用 PageIndexChanging 进行验证
7. 测试导航：确认所有导航按钮均能正常工作

常见用例

• 分页数据网格：在 DataGrid 中显示大型数据集并提供页面导航
• 文档查看器：浏览文档页面
• 产品目录：跨多个页面浏览商品
• 搜索结果：以分页方式显示搜索结果
• 报表查看器：浏览多页报表
• 大型列表显示：任何需要对 100 项以上内容进行分页的场景
• 延迟加载场景：在用户浏览页面时加载数据