【DevUI】Pagination 分页组件使用详解

📄 DevUI Pagination 分页组件使用详解

Pagination（分页）组件用于将大量数据分割成多个页面进行展示，用户可以通过它直观地在不同数据页之间导航，是数据表格、列表等场景中不可或缺的一部分。

1. 基本用法与尺寸

最基本的用法是绑定总条目数、当前页码和每页大小。组件提供三种尺寸（sm, md, lg）以适应不同设计需求。

<!-- 小尺寸 (sm) -->
<d-pagination
    [size]="‘sm‘"
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize"
    [canViewTotal]="true"
    [canChangePageSize]="true">
</d-pagination>

<!-- 中尺寸 (md) - 默认值 -->
<d-pagination
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize">
</d-pagination>

<!-- 大尺寸 (lg) -->
<d-pagination
    [size]="‘lg‘"
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize">
</d-pagination>

在组件类中定义数据模型：

export class YourComponent {
  pager = {
    total: 1000,
    pageIndex: 1,
    pageSize: 20
  };
}

2. 极简模式

极简模式 (lite) 简化了视觉元素，适用于信息密集、需要节省空间的页面。

<!-- 标准极简模式 -->
<d-pagination
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize"
    [lite]="true"
    [canViewTotal]="true"
    [canChangePageSize]="true">
</d-pagination>

<!-- 超极简模式：隐藏页码列表 -->
<d-pagination
    [size]="‘sm‘"
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize"
    [lite]="true"
    [showPageSelector]="false" <!-- 隐藏数字页码 -->
    [canChangePageSize]="true">
</d-pagination>

<!-- 带配置菜单的极简模式 -->
<d-pagination
    [size]="‘sm‘"
    [lite]="true"
    [haveConfigMenu]="true"
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize">
    <!-- 可以插入自定义的配置项 -->
    <div class="custom-config-item">自定义设置项</div>
</d-pagination>

3. 多种高级配置

组件支持丰富的功能扩展，如页面跳转、自定义样式和下拉框方向控制。

<!-- 启用输入框跳转功能 -->
<d-pagination
    [canJumpPage]="true"
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize">
</d-pagination>

<!-- 同时显示跳转输入框和按钮 -->
<d-pagination
    [canJumpPage]="true"
    [showJumpButton]="true" <!-- 显示“跳转”按钮 -->
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize">
</d-pagination>

<!-- 完全自定义文本和前后页按钮 -->
<d-pagination
    [canJumpPage]="true"
    [goToText]="‘Jump to‘" <!-- 自定义跳转框前的文字 -->
    [preLink]="‘上一页‘"    <!-- 自定义上一页按钮文字 -->
    [nextLink]="‘下一页‘"    <!-- 自定义下一页按钮文字 -->
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize">
</d-pagination>

<!-- 自定义每页条数下拉框选项和弹出方向 -->
<d-pagination
    [canChangePageSize]="true"
    [pageSizeOptions]="[10, 20, 50, 100]" <!-- 自定义可选条数 -->
    [pageSizeDirection]="[‘centerUp‘]"    <!-- 下拉菜单向上展开 -->
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize">
</d-pagination>

4. 特殊情况处理

组件对边界情况提供了良好的处理方式。

<!-- 当页码超出最大范围时，显示真实的无效页码（用于特定编辑场景） -->
<d-pagination
    [showTruePageIndex]="true"
    [total]="10"
    [(pageIndex)]="invalidPageIndex" <!-- 比如设置为5，但实际只有1页 -->
    [(pageSize)]="pageSize">
</d-pagination>

<!-- 总条目数为0时的优雅显示 -->
<d-pagination
    [total]="0"
    [(pageIndex)]="pageIndex"
    [(pageSize)]="pageSize"
    [canViewTotal]="true">
</d-pagination>

5. 事件监听

通过事件可以响应分页操作，以便向服务器请求新数据。

<d-pagination
    [total]="pager.total"
    [(pageIndex)]="pager.pageIndex"
    [(pageSize)]="pager.pageSize"
    (pageIndexChange)="onPageIndexChange($event)"
    (pageSizeChange)="onPageSizeChange($event)">
</d-pagination>

export class YourComponent {
  onPageIndexChange(newIndex: number) {
    console.log(‘页码变为：‘, newIndex);
    // 通常在这里触发数据加载
    this.loadData(newIndex, this.pager.pageSize);
  }

  onPageSizeChange(newSize: number) {
    console.log(‘每页大小变为：‘, newSize);
    // 改变每页大小后，通常回到第一页并加载数据
    this.pager.pageIndex = 1;
    this.loadData(1, newSize);
  }

  loadData(pageIndex: number, pageSize: number) {
    // 调用API获取对应页的数据
  }
}

6. 功能特性速查表

下表汇总了核心属性，方便您快速查阅：

功能	属性/事件	说明与常用值
数据绑定	[total], [(pageIndex)], [(pageSize)]	必须绑定的三个核心属性
尺寸	[size]	‘sm‘, ‘md‘(默认), ‘lg‘
极简模式	[lite]="true"	启用简洁视觉样式
显示总条数	[canViewTotal]="true"	显示“共 X 条”文本
自定义总条数文本	[totalItemText]="‘Total‘"	替换“共”字
切换每页条数	[canChangePageSize]="true"	显示下拉选择框
自定义条数选项	[pageSizeOptions]="[10,20,50]"	自定义下拉选项
页面跳转	[canJumpPage]="true"	显示跳转输入框
显示跳转按钮	[showJumpButton]="true"	在跳转输入框后显示按钮
隐藏数字页码	[showPageSelector]="false"	仅显示上下页按钮，不显示数字
自定义最大页码按钮数	[maxItems]="5"	控制同时显示的页码数量
超出页码显示	[showTruePageIndex]	为true时显示超出的无效页码
自定义文本	[preLink], [nextLink], [goToText]	自定义按钮和提示文本
事件监听	(pageIndexChange), (pageSizeChange)	页码或页大小变化时触发

💡 总结与最佳实践

DevUI Pagination 组件功能全面，配置灵活。在使用时，建议：

1. 明确需求：先确定是否需要每页条数切换、页面跳转等高级功能，按需启用。
2. 绑定数据：确保正确绑定 total、pageIndex 和 pageSize，这是组件运行的基础。
3. 处理事件：在 pageIndexChange 和 pageSizeChange 事件中处理数据加载逻辑。
4. 注意边界：在数据量为0或1页时，组件会自动调整显示状态，保持界面友好。

参考文档

MateChat：https://gitcode.com/DevCloudFE/MateChat

MateChat官网：https://matechat.gitcode.com

DevUI官网：https://devui.design/home