syncfusion-wpf-datapager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing DataPager

实现DataPager控件

Guide for implementing the Syncfusion WPF DataPager (SfDataPager) to paginate large datasets in WPF applications. The DataPager control provides navigation buttons, numeric page buttons, and flexible data‑binding options for dividing data into manageable pages.

本文档介绍如何在WPF应用中实现Syncfusion WPF DataPager（SfDataPager）以对大型数据集进行分页。DataPager控件提供导航按钮、数字页码按钮以及灵活的数据绑定选项，可将数据划分为便于管理的页面。

When to Use This Skill

何时使用该技能

Use this skill when the user needs to:

Paginate large datasets in WPF applications
Add page navigation controls (first, last, next, previous buttons)
Display data in manageable page sizes
Implement on-demand paging for large datasets
Bind paginated data to any ItemsControl (DataGrid, ListBox, ListView)
Customize pagination appearance (colors, display modes, orientation)
Handle page change events and validation
Create paginated views with numeric page buttons
Change page size at runtime
Navigate programmatically between pages

当用户需要以下功能时使用本技能：

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

Component Overview

组件概述

SfDataPager is a WPF control that divides data collections into pages and provides navigation UI:

Navigation buttons: First, Last, Previous, Next page buttons
Numeric buttons: Direct page access (e.g., 1, 2, 3, 4, 5)
Auto ellipsis: Shows ellipsis button when page count exceeds numeric button count
Flexible binding: Works with any ItemsControl through PagedSource property
On-demand paging: Load data dynamically for current page only
Events: PageIndexChanging and PageIndexChanged for validation and custom logic
Appearance: Customizable colors, display modes, and orientation

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

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

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Required assemblies (Syncfusion.SfGrid.WPF, Syncfusion.Data.WPF)
Control structure and elements
Creating first SfDataPager application
Integrating with SfDataGrid
Adding SfDataPager to toolbox
Theme support and theming

📄 阅读： references/getting-started.md

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

Data Binding and Paging

数据绑定与分页

📄 Read: references/data-binding.md

Source and PagedSource properties
PageIndex property and events
Binding to ListBox, ListView, or other ItemsControls
On-demand paging with UseOnDemandPaging
LoadDynamicItems method for dynamic data loading
PageSize configuration
Runtime PageSize changes with ComboBox

📄 阅读： references/data-binding.md

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

Appearance and Styling

外观与样式

📄 Read: references/appearance.md

AutoEllipsisMode (After, Before, Both, None)
AccentBackground and AccentForeground colors
NumericButtonStyle customization
DisplayMode options (12 different modes)
Orientation (Horizontal, Vertical)

📄 阅读： references/appearance.md

AutoEllipsisMode（After、Before、Both、None）
AccentBackground和AccentForeground颜色设置
数字按钮样式定制
DisplayMode选项（12种不同模式）
布局方向（Horizontal、Vertical）

Page Navigation

页面导航

📄 Read: references/page-navigation.md

MoveToFirstPage(), MoveToLastPage() methods
MoveToNextPage(), MoveToPreviousPage() methods
MoveToPage(int pageIndex) for direct navigation
PageIndexChanging event for validation
Interacting with users before page changes

📄 阅读： references/page-navigation.md

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

Styles and Templates

样式与模板

📄 Read: references/styles-templates.md

Editing styles in Expression Blend
Editing styles in Visual Studio
Edit a Copy vs Create Empty options
Custom control templates
Resource management

📄 阅读： references/styles-templates.md

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

Quick Start Example

快速入门示例

Basic SfDataPager with SfDataGrid integration:

xml

<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>
        
        <!-- DataGrid displays paginated data -->
        <sfgrid:SfDataGrid AutoGenerateColumns="True"
                           ItemsSource="{Binding ElementName=sfDataPager, Path=PagedSource}"/>
        
        <!-- DataPager provides navigation -->
        <datapager:SfDataPager x:Name="sfDataPager"
                               Grid.Row="1"
                               NumericButtonCount="10"
                               PageSize="10"
                               Source="{Binding OrdersDetails}"/>
    </Grid>
</Window>

Key concepts:

Source: Bind to your data collection (e.g.,
```
OrdersDetails
```
)
PagedSource: Automatically wrapped PagedCollectionView for ItemsControl
PageSize: Number of items per page
NumericButtonCount: Number of numeric page buttons to display

与SfDataGrid集成的基础SfDataPager示例：

xml

<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>
        
        <!-- DataGrid显示分页后的数据 -->
        <sfgrid:SfDataGrid AutoGenerateColumns="True"
                           ItemsSource="{Binding ElementName=sfDataPager, Path=PagedSource}"/>
        
        <!-- DataPager提供导航功能 -->
        <datapager:SfDataPager x:Name="sfDataPager"
                               Grid.Row="1"
                               NumericButtonCount="10"
                               PageSize="10"
                               Source="{Binding OrdersDetails}"/>
    </Grid>
</Window>

核心概念：

Source：绑定到你的数据集合（如
```
OrdersDetails
```
）
PagedSource：自动包装的PagedCollectionView，用于绑定到ItemsControl
PageSize：每页显示的条目数量
NumericButtonCount：显示的数字页码按钮数量

Common Patterns

常见模式

Pattern 1: Basic Pagination with DataGrid

模式1：与DataGrid配合的基础分页

xml

<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>

xml

<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>

Pattern 2: Customized Appearance

模式2：自定义外观

xml

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

xml

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

Pattern 3: Runtime PageSize Change

模式3：运行时更改PageSize

xml

<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>

xml

<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>

Pattern 4: On-Demand Paging (Large Datasets)

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

xml

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

csharp

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);
}

xml

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

csharp

private void OnDemandDataLoading(object sender, OnDemandLoadingEventArgs args)
{
    // 仅加载当前页面的数据
    var pageData = dataSource.Skip(args.StartIndex).Take(args.PageSize);
    sfDataPager.LoadDynamicItems(args.StartIndex, pageData);
}

Pattern 5: Page Change Validation

模式5：页面切换验证

xml

<datapager:SfDataPager PageIndexChanging="sfDataPager_PageIndexChanging"/>

csharp

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
        }
    }
}

xml

<datapager:SfDataPager PageIndexChanging="sfDataPager_PageIndexChanging"/>

csharp

private void sfDataPager_PageIndexChanging(object sender, PageIndexChangingEventArgs e)
{
    // 在页面切换前进行验证或提示用户
    if (HasUnsavedChanges())
    {
        var result = MessageBox.Show("存在未保存的更改，是否继续？", 
                                     "确认", 
                                     MessageBoxButton.YesNo);
        if (result == MessageBoxResult.No)
        {
            e.Cancel = true; // 取消页面导航
        }
    }
}

Key Properties

核心属性

Property	Type	Description
`Source`	IEnumerable	Data collection for paging
`PagedSource`	PagedCollectionView	Paginated data (bind to ItemsSource)
`PageSize`	int	Items per page (default: 0 = all items)
`PageIndex`	int	Current page index (0-based)
`PageCount`	int	Total number of pages
`NumericButtonCount`	int	Number of numeric buttons to display
`AutoEllipsisMode`	AutoEllipsisMode	Ellipsis button placement (After, Before, Both, None)
`AccentBackground`	Brush	Background color for navigation/selected buttons
`AccentForeground`	Brush	Foreground color for selected button
`DisplayMode`	PageDisplayMode	Which buttons to show (e.g., FirstLastPreviousNextNumeric)
`Orientation`	Orientation	Horizontal or Vertical layout
`UseOnDemandPaging`	bool	Enable on-demand data loading

属性	类型	描述
`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	启用按需数据加载

Key Methods

核心方法

Method	Description
`MoveToFirstPage()`	Navigate to first page
`MoveToLastPage()`	Navigate to last page
`MoveToNextPage()`	Navigate to next page
`MoveToPreviousPage()`	Navigate to previous page
`MoveToPage(int pageIndex)`	Navigate to specific page
`LoadDynamicItems(int startIndex, IEnumerable items)`	Load data for on-demand paging

方法	描述
`MoveToFirstPage()`	导航到首页
`MoveToLastPage()`	导航到末页
`MoveToNextPage()`	导航到下一页
`MoveToPreviousPage()`	导航到上一页
`MoveToPage(int pageIndex)`	导航到指定页码
`LoadDynamicItems(int startIndex, IEnumerable items)`	为按需分页加载数据

Key Events

核心事件

Event	Description
`PageIndexChanging`	Before page changes (cancelable)
`PageIndexChanged`	After page changes

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

Implementation Workflow

实现流程

When user requests DataPager implementation:

Assess requirements: Determine data size, page size needs, appearance preferences
Choose paging mode:
- Normal paging (small to medium datasets)
- On-demand paging (large datasets, millions of records)
Add assemblies: Syncfusion.SfGrid.WPF, Syncfusion.Data.WPF (if using with DataGrid)
Set up data binding: Source → PagedSource → ItemsControl.ItemsSource
Configure appearance: PageSize, NumericButtonCount, AccentColors, DisplayMode
Add event handlers (if needed): PageIndexChanging for validation
Test navigation: Verify all navigation buttons work correctly

当用户需要实现DataPager时：

评估需求 : 确定数据规模、页面大小需求、外观偏好
选择分页模式 :
- 常规分页（中小型数据集）
- 按需分页（大型数据集，数百万条记录）
添加程序集 : Syncfusion.SfGrid.WPF、Syncfusion.Data.WPF（如果与DataGrid配合使用）
设置数据绑定 : Source → PagedSource → ItemsControl.ItemsSource
配置外观 : PageSize、NumericButtonCount、AccentColors丶DisplayMode
添加事件处理程序（如有需要）: 使用PageIndexChanging进行验证
测试导航 : 验证所有导航按钮功能正常

Common Use Cases

常见使用场景

Paginated data grids: Display large datasets in DataGrid with page navigation
Document viewers: Navigate through document pages
Product catalogs: Browse items across multiple pages
Search results: Display search results with pagination
Report viewers: Navigate multi-page reports
Large list displays: Any scenario with 100+ items that need pagination
Lazy loading scenarios: Load data as user navigates pages

分页数据网格 : 在DataGrid中显示大型数据集并提供页面导航
文档查看器 : 浏览文档的不同页面
产品目录 : 跨多个页面浏览商品
搜索结果 : 带分页的搜索结果展示
报表查看器 : 浏览多页报表
大型列表展示 : 任何包含100+条目的场景，需要分页处理
懒加载场景 : 在用户导航页面时加载数据