AtomUI/docs/Desktop.Controls/Pagination/PaginationAPI.md

Pagination API 参考

命名空间

namespace AtomUI.Desktop.Controls;

AXAML 命名空间前缀：atom（xmlns:atom="https://atomui.net"）

---

枚举类型

PaginationAlign

分页对齐方式枚举，控制分页组件在父容器中的水平对齐。

值	说明
Start	左对齐（默认）
Center	居中对齐
End	右对齐

SizeType（来自 AtomUI.Controls）

尺寸类型枚举。

值	说明
Small	迷你尺寸
Middle	标准尺寸（默认）
Large	大号尺寸

PaginationItemType（internal）

页码导航项类型枚举，控制每个导航项的外观和行为。

值	说明
Previous	上一页按钮
PageIndicator	页码数字按钮
Next	下一页按钮
Ellipses	省略号按钮

---

AbstractPagination（抽象基类）

AbstractPagination 是 Pagination 和 SimplePagination 的公共抽象基类，定义了所有分页控件共享的核心属性、事件和分页逻辑。

继承：TemplatedControl → AbstractPagination 实现接口：ISizeTypeAware、IMotionAwareControl

常量

常量名	值	说明
DefaultPageSize	10	默认每页条数
DefaultCurrentPage	1	默认当前页码

公共属性（StyledProperty）

属性名	类型	默认值	说明
IsHideOnSinglePage	bool	false	仅一页时是否自动隐藏分页组件
Align	PaginationAlign	PaginationAlign.Start	分页组件水平对齐方式
SizeType	SizeType	SizeType.Middle	分页尺寸（共享属性，通过 AddOwner 注册）
CurrentPage	int	1	当前页码（必须 > 0）
PageSize	int	10	每页数据条数（允许值：0, 10, 20, 50, 100）
Total	int	0	数据总条数（必须 ≥ 0）
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画（共享属性）

只读属性（DirectProperty）

属性名	类型	说明
PageCount	int	总页数，由 Total / PageSize 自动计算（向上取整）

事件

事件名	类型	说明
CurrentPageChanged	EventHandler<PageChangedEventArgs>	当前页码变更时触发

PageChangedEventArgs（来自 AtomUI.Controls，共享层）

定义于 src/AtomUI.Controls.Shared/EventArgs/PageChangedArgs.cs。

属性	类型	说明
PageIndex	int	当前页码
TotalPages	int	总页数
PageSize	int	每页条数

---

Pagination（标准分页）

Pagination 继承自 AbstractPagination，提供完整的页码导航功能，包括省略号折叠、页面大小选择器、快速跳转和总数信息显示。

继承：TemplatedControl → AbstractPagination → Pagination

常量

常量名	值	说明
MaxNavItemCount	11	导航区最大项数（1 上一页 + 9 页码/省略号 + 1 下一页）

公共属性（StyledProperty）

属性名	类型	默认值	说明
IsShowSizeChanger	bool	false	是否显示页面大小选择器（10/20/50/100）
IsShowQuickJumper	bool	false	是否显示快速跳转输入框
IsShowTotalInfo	bool	false	是否显示总数信息
TotalInfoTemplate	string?	由本地化资源控制	总数信息模板字符串，支持 ${Total}、${RangeStart}、${RangeEnd} 变量

继承自 AbstractPagination 的属性

属性名	类型	默认值	说明
IsHideOnSinglePage	bool	false	仅一页时是否自动隐藏
Align	PaginationAlign	Start	水平对齐方式
SizeType	SizeType	Middle	分页尺寸
CurrentPage	int	1	当前页码
PageSize	int	10	每页条数
Total	int	0	数据总条数
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画
PageCount	int	自动计算	总页数（只读）

继承自 TemplatedControl 的常用属性

属性名	类型	默认值	说明
IsEnabled	bool	true	是否启用
Foreground	IBrush?	由主题控制	前景色
HorizontalAlignment	HorizontalAlignment	Left	水平对齐

事件

事件名	类型	说明
CurrentPageChanged	EventHandler<PageChangedEventArgs>	当前页码变更时触发（继承自 AbstractPagination）

---

SimplePagination（简洁分页）

SimplePagination 继承自 AbstractPagination，提供紧凑的前进/后退分页体验，支持只读和可编辑两种模式。

继承：TemplatedControl → AbstractPagination → SimplePagination

公共属性（StyledProperty）

属性名	类型	默认值	说明
IsReadOnly	bool	true	是否只读模式。true 时显示纯文本 "当前页 / 总页数"；false 时当前页替换为可编辑输入框

继承自 AbstractPagination 的属性

属性名	类型	默认值	说明
IsHideOnSinglePage	bool	false	仅一页时是否自动隐藏
Align	PaginationAlign	Start	水平对齐方式
SizeType	SizeType	Middle	分页尺寸
CurrentPage	int	1	当前页码
PageSize	int	10	每页条数
Total	int	0	数据总条数
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画
PageCount	int	自动计算	总页数（只读）

事件

事件名	类型	说明
CurrentPageChanged	EventHandler<PageChangedEventArgs>	当前页码变更时触发（继承自 AbstractPagination）

---

内部控件类型（Internal）

以下控件为 internal 类型，开发者不能直接实例化使用，但了解它们有助于理解模板结构和样式选择器。

PaginationNav

页码导航容器，继承自 SelectingItemsControl，管理所有 PaginationNavItem 实例。

属性名	类型	说明
SizeType	SizeType	尺寸类型（双向绑定至父 Pagination）
IsMotionEnabled	bool	是否启用动画
ItemSpacing	double	页码按钮之间的间距（internal）

PaginationNavItem

单个页码按钮，继承自 ContentControl，实现 ISelectable。

属性名	类型	说明
IsSelected	bool	是否被选中（当前页）
PaginationItemType	PaginationItemType	导航项类型（Previous/PageIndicator/Next/Ellipses）
SizeType	SizeType	尺寸类型
IsMotionEnabled	bool	是否启用动画
Icon	PathIcon?	导航项图标（用于 ←/→/... 等）
IsPressed	bool	是否按下状态（只读）

事件名	类型	说明
Click	EventHandler<RoutedEventArgs>	点击事件（冒泡路由）

QuickJumperBar

快速跳转栏，显示 "Go to [输入框] Page" 布局。

属性名	类型	说明
JumpToText	string?	跳转提示文本（如 "Go to"）
PageText	string?	页文本（如 "Page"）
SizeType	SizeType	尺寸类型

事件名	类型	说明
JumpRequest	EventHandler<QuickJumpArgs>	用户输入页码按 Enter 后触发

QuickJumpEdit

纯数字输入框，继承自 LineEdit，限制输入范围。

属性名	类型	默认值	说明
Minimum	int	1	最小允许输入值
Maximum	int	int.MaxValue	最大允许输入值

PageSizeComboBoxItem

页面大小下拉选项，继承自 ComboBoxItem。

属性名	类型	说明
PageSize	int	对应的每页条数

---

伪类（Pseudo-Classes）

PaginationNavItem 支持的伪类

伪类	触发条件
:selected	当前页码被选中
:pressed	按钮按下状态
:pointerover	鼠标悬浮
:disabled	禁用状态

Pagination / SimplePagination 支持的伪类

伪类	触发条件
:disabled	IsEnabled == false

PaginationNavItem 属性选择器

选择器	说明
[PaginationItemType=Previous]	上一页按钮
[PaginationItemType=Next]	下一页按钮
[PaginationItemType=PageIndicator]	页码数字按钮
[PaginationItemType=Ellipses]	省略号
[SizeType=Small]	迷你尺寸
[SizeType=Middle]	标准尺寸
[SizeType=Large]	大号尺寸

---

实现的接口

ISizeTypeAware

public SizeType SizeType { get; set; }

通过 SizeType 属性控制分页组件的整体尺寸，影响页码按钮高度、图标大小、字体大小等。

IMotionAwareControl

public bool IsMotionEnabled { get; set; }

控制页码按钮的背景色、边框色、前景色过渡动画是否启用。

---

本地化资源

Pagination 通过 LanguageProvider 系统支持本地化文本。

英文 (en_US)

资源键	值	说明
JumpToText	"Go to"	快速跳转提示文本
PageText	"Page"	页面文本
TotalInfoFormat	"Total ${Total} items"	总数信息默认模板

中文 (zh_CN)

资源键	值	说明
JumpToText	"跳至"	快速跳转提示文本
PageText	"页"	页面文本
TotalInfoFormat	"共 ${Total} 项"	总数信息默认模板

---

模板部件常量

PaginationThemeConstants

常量	值	说明
RootLayoutPart	"PART_RootLayout"	根布局 StackPanel
NavPart	"PART_Nav"	PaginationNav 导航容器
SizeChangerPresenterPart	"PART_SizeChangerPresenter"	页面大小选择器 ContentPresenter
QuickJumperBarPresenterPart	"PART_QuickJumperBarPresenter"	快速跳转栏 ContentPresenter
TotalInfoPresenterPart	"PART_TotalInfoPresenter"	总数信息 ContentPresenter

SimplePaginationThemeConstants

常量	值	说明
RootLayoutPart	"PART_RootLayoutPart"	根布局 StackPanel
PreviousNavItemPart	"PART_PreviousNavItem"	上一页按钮
NextNavItemPart	"PART_NextNavItem"	下一页按钮
InfoIndicatorPart	"PART_InfoIndicator"	页码文本 TextBlock
QuickJumperPart	"PART_QuickJumper"	可编辑页码输入框

PaginationNavThemeConstants

常量	值	说明
FramePart	"PART_Frame"	导航区外框 Border
ItemsPresenterPart	"PART_ItemsPresenter"	项目展示器

PaginationQuickJumperBarThemeConstants

常量	值	说明
RootLayoutPart	"PART_RootLayout"	根布局 StackPanel
JumpToContentPresenterPart	"PART_JumpToContentPresenter"	"Go to" 文本展示器
PageContentPresenterPart	"PART_PageContentPresenter"	"Page" 文本展示器
PageLineEditPart	"PART_PageLineEdit"	页码输入框