syncfusion-maui-datapager

Syncfusion .NET MAUI DataPager 技能

用途

该技能用于实现和自定义 Syncfusion .NET MAUI DataPager（SfDataPager）控件。SfDataPager 是一个独立分页控件，可将大型数据集拆分为可管理的页面，并与 SfDataGrid 等数据显示控件无缝集成。

适用场景包括：

在 .NET MAUI 应用中以分页视图显示大型数据集
为 SfDataGrid 或任意项控件添加分页
在普通分页（一次性加载全部）与按需分页（逐页加载）之间选择
配置数字按钮与导航按钮（First、Last、Previous、Next）
控制按钮形状、大小、字体大小或方向
用自定义颜色或按钮模板设置分页器样式
处理页面导航事件（PageChanging、PageChanged）
以编程方式导航页面（MoveToFirstPage、MoveToPage 等）
为大量页码启用自动省略号
通过 ResetCache 优化超大数据集的内存

组件概览

核心能力：

普通与按需两种分页模式
First、Last、Previous、Next 及数字按钮导航
编程式页面切换（MoveToFirstPage、MoveToLastPage、MoveToNextPage、MoveToPreviousPage、MoveToPage）
可自定义的显示模式（选择显示哪些按钮）
按钮形状、大小与字体大小自定义
水平或垂直方向
大量页码范围的自动省略号支持
通过 DataPagerStyle 实现全面的样式与模板自定义
PageChanging 与 PageChanged 事件
按需分页下通过 ResetCache 进行内存优化

数据流：

将数据集合绑定到 SfDataPager.Source
SfDataPager.PagedSource 暴露当前页数据
将 PagedSource 绑定到显示控件的 ItemsSource（例如 SfDataGrid）

NuGet 包：Syncfusion.Maui.DataPager

入门

前置条件包括 .NET 9 SDK 以及 Visual Studio / VS Code / Rider。主要步骤：

安装 Syncfusion.Maui.DataPager NuGet 包
在 MauiProgram.cs 中注册 Syncfusion 核心处理程序：builder.ConfigureSyncfusionCore();
导入 DataPager 命名空间（XAML 与 C#）
创建数据模型（OrderInfo）与仓库（OrderInfoRepository）
添加 SfDataPager 与 SfDataGrid（XAML 与 C#）
使用 Source 到 PagedSource 的绑定模式

注意：忘记调用 ConfigureSyncfusionCore() 会导致渲染 DataPager 时出现运行时错误。

XAML 命名空间：

xmlns:pager="clr-namespace:Syncfusion.Maui.DataPager;assembly=Syncfusion.Maui.DataPager"

分页模式与导航

普通分页（一次性预先加载整个集合）
按需分页（UseOnDemandPaging、OnDemandLoading 事件）
LoadDynamicItems(StartIndex, PageSize)
按需分页下的 PageCount（替代 Source）
ResetCache() 用于内存优化
编程式导航（MoveToFirstPage、MoveToLastPage、MoveToNextPage、MoveToPreviousPage、MoveToPage）
动画页面导航（带 duration 的 MoveToPage）
边界行为（在第一页/最后一页不抛出异常）

自定义

ButtonShape（Rectangle、Circle）
NumericButtonsGenerateMode（Auto，或通过 NumericButtonCount 显式指定）
ButtonSize 与 ButtonFontSize
DisplayMode（None、First、Last、Previous、Next、Numeric 及其组合）
AutoEllipsisMode（None、Before、After、Both）
AutoEllipsisText 自定义
Orientation（Horizontal、Vertical）

外观与样式

DataPagerStyle 概览与 DefaultStyle 赋值
背景颜色（DataPager、导航按钮、数字按钮）
选中颜色（数字按钮选中背景与文字）
禁用状态导航按钮颜色
导航按钮模板（FirstPageButtonTemplate、LastPageButtonTemplate、NextPageButtonTemplate、PreviousPageButtonTemplate）

事件

PageChanging 事件（PageChangingEventArgs：OldPageIndex、NewPageIndex）
PageChanged 事件（PageChangedEventArgs：OldPageIndex、NewPageIndex）
各自的使用时机（导航前与导航后）
事件处理程序签名与接线（XAML 与 C#）

快速开始

以下为绑定到集合并与 SfDataGrid 搭配的最小示例：

using Syncfusion.Maui.DataPager;
using Syncfusion.Maui.DataGrid;
using System.Collections.ObjectModel;

public class OrderInfo
{
    public string? OrderID { get; set; }
    public string? CustomerID { get; set; }
    public string? ShipCountry { get; set; }

    public OrderInfo(string orderId, string customerId, string country)
    {
        OrderID = orderId;
        CustomerID = customerId;
        ShipCountry = country;
    }
}

var orders = new ObservableCollection<OrderInfo>
{
    new OrderInfo("1001", "Maria Anders", "Germany"),
    new OrderInfo("1002", "Ana Trujillo", "Mexico"),
    new OrderInfo("1003", "Ant Fuller", "Mexico"),
    // ... more items
};

SfDataPager dataPager = new SfDataPager();
dataPager.PageSize = 15;
dataPager.NumericButtonCount = 10;
dataPager.Source = orders;

SfDataGrid dataGrid = new SfDataGrid();
dataGrid.ItemsSource = dataPager.PagedSource;

this.Content = dataGrid;

常见模式

将 DataGrid 绑定到分页数据：

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="*" />
        <RowDefinition Height="Auto" />
    </Grid.RowDefinitions>
    <syncfusion:SfDataGrid x:Name="dataGrid"
                           Grid.Row="0"
                           ItemsSource="{Binding Source={x:Reference dataPager}, Path=PagedSource}" />
    <Border Grid.Row="1" Padding="5">
        <pager:SfDataPager x:Name="dataPager"
                           PageSize="15"
                           NumericButtonCount="10"
                           Source="{Binding Orders}" />
    </Border>
</Grid>

按需加载页面：

dataPager.UseOnDemandPaging = true;
dataPager.PageCount = 67; // total pages, e.g. 1000 items / 15 per page
dataPager.OnDemandLoading += (sender, e) =>
{
    dataPager.LoadDynamicItems(e.StartIndex, orders.Skip(e.StartIndex).Take(e.PageSize));
};

编程式导航：

dataPager.MoveToFirstPage();
dataPager.MoveToPreviousPage();
dataPager.MoveToNextPage();
dataPager.MoveToLastPage();
dataPager.MoveToPage(5);
// Animated navigation: MoveToPage(pageIndex, durationMs, animate)
dataPager.MoveToPage(5, 300, true);

设置分页器样式：

DataPagerStyle style = new DataPagerStyle();
style.NumericButtonSelectionBackgroundColor = Color.FromArgb("#CDB4DB");
style.NumericButtonBackgroundColor = Color.FromArgb("#FFC8DD");
style.NavigationButtonBackgroundColor = Color.FromArgb("#90E0EF");
style.NavigationButtonIconColor = Color.FromArgb("#0077B6");
dataPager.DefaultStyle = style;

选择正确的参考文档

首次设置 DataPager：references/getting-started.md
选择普通或按需分页、导航页面：references/paging-modes.md
更改按钮形状、大小、显示模式、省略号或方向：references/customization.md
应用颜色、样式或按钮模板：references/appearance.md
处理页面切换事件：references/events.md

限制

资料未提供该技能的具体收费、价格、平台兼容性明细或效果承诺，这些信息暂未提供。