simplePagination 简单分页器

在线示例

simplePagination 是一个分页加载数据的组件。可以在 dataGrid 和 treeDataGrid 组件使用。

  • XML 元素：simplePagination

  • Java 类：SimplePagination

基本用法

simplePagination 的外观很简单，包含行数和导航按钮。

也可以带包含每页条数的 下拉列表。

simple pagination

Jmix Studio 在为实体创建 StandardListView 时，默认生成 simplePagination。

<data readOnly="true">
    <collection id="usersDc"
                class="com.company.onboarding.entity.User">
        <fetchPlan extends="_base">
            <property name="department" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="usersDl">
            <query>
                <![CDATA[select e from User e order by e.username]]> (1)
            </query>
        </loader>
    </collection>
</data>
<layout expand="usersTable">
        <simplePagination itemsPerPageVisible="true"
                          id="simplePagination"
                          dataLoader="usersDl"/> (2)
</layout>
1 定义 集合加载器 加载 User 实体。
2 将 simplePagination 与 dataLoader 连接。

Items per Page

simplePagination 有一个特殊的 comboBox 提供选项可以限制每页展示的条数。设置 itemsPerPageVisible 属性为 true 可以显示。默认值为 false。

items per page

该列表的默认值通过 jmix.ui.component.pagination-items-per-page-items 属性配置。

也可以通过 itemsPerPageItems 属性配置自定义的选项列表。属性值必须是逗号分隔的选项：

<simplePagination dataLoader="usersDl"
                  itemsPerPageVisible="true"
                  itemsPerPageItems="2, 4, 6"/>

小于等于 0 的选项会被忽略。大于实体 最大加载数 的选项会用该值替换。

使用 itemsPerPageDefaultValue 属性设置选项的默认值：

<simplePagination dataLoader="usersDl"
                  itemsPerPageVisible="true"
                  itemsPerPageItems="2, 4, 6"
                  itemsPerPageDefaultValue="4"/>

itemsPerPageUnlimitedItemVisible 属性设置是否在每页显示数量的下拉列表中显示无限制（null）选项。默认值为 true。

当在 comboBox 中选择 null 选项时，组件会尝试在当前最大加载数的限制下加载所有数据。

所有实体的最大加载数是通过 jmix.ui.default-max-fetch-size UI 属性定义。默认值为 10000。某些特定实体可能有不同的加载要求，可以用 jmix.ui.entity-max-fetch-size 设置。

空项标签

当 itemsPerPageUnlimitedItemVisible="true" 时，下拉列表会显示一个空项，用来加载所有数据（受最大获取量限制）。默认情况下，此项显示为空字符串。

可以通过向 消息包 添加消息键值自定义此项的标签：

pagination.itemsPerPage.emptySelectionCaption=Show all

如果消息包中存在消息键值 pagination.itemsPerPage.emptySelectionCaption，则其值将显示在下拉列表中，而不是显示为空项。如果未找到该键值，则该项显示为空。

XML 属性

id - alignSelf - autoLoad - classNames - colspan - css - dataLoader - itemsPerPageDefaultValue - itemsPerPageItems - itemsPerPageUnlimitedItemVisible - itemsPerPageVisible - visible

autoLoad

autoLoad 属性可以设置是否自动加载数据的数量。当 autoLoad 禁用时，组件不知道数据的总量，从而显示一个 [?] 按钮。启用时，组件会组织一个查询语句获取数据总量并显示。默认值为 false。

当 autoLoad 设置为 true 时，totalCountDelegate 可能会在一个 BackgroundTask 中调用。此时，无法在该代理方法中更新 UI。

dataLoader

用 dataLoader 属性为 simplePagination 连接数据。

事件和处理器

AfterRefreshEvent - AttachEvent - BeforeRefreshEvent - DetachEvent - totalCountDelegate

在 Jmix Studio 生成处理器桩代码时，可以使用 Jmix UI 组件面板的 Handlers 标签页或者视图类顶部面板的 Generate Handler 添加，也可以通过 Code → Generate 菜单（Alt+Insert / Cmd+N）生成。

AfterRefreshEvent

io.jmix.flowui.component.PaginationComponent.AfterRefreshEvent 在刷新后发送。

BeforeRefreshEvent

io.jmix.flowui.component.PaginationComponent.BeforeRefreshEvent 在用户点击下一页、前一页等操作而还没有刷新数据时发送。可以通过调用 preventRefresh() 方法阻止数据容器更新。示例：

@Subscribe("simplePagination")
public void onSimplePaginationBeforeRefresh(
        final PaginationComponent.BeforeRefreshEvent<SimplePagination> event) {
    if (Objects.requireNonNull(event.getSource().getPaginationLoader()).size() > 10) (1)
        event.preventRefresh(); (2)
}
1 检查数据加载器中的实例数量。
2 阻止刷新数据。

totalCountDelegate

设置获取数据总量的代理。示例：

@Autowired
private DataManager dataManager;

@Install(to = "simplePagination", subject = "totalCountDelegate")
private Integer simplePaginationTotalCountDelegate(
        final LoadContext<User> loadContext) {
    return dataManager.loadValue("select count(e) from User e", Integer.class).one();
}

当 simplePagination 的 autoLoad="true" 时，totalCountDelegate 可能会在 BackgroundTask 中调用。即 totalCountDelegate 处理器内部的代码 不能更新 UI 组件（例如在 TextField 上调用 setText() 或其他 UI 修改）。尝试这样做将导致 IllegalStateException。

不要在 totalCountDelegate 内部更新 UI 组件。仅使用此处理器来计算并返回总计数。

totalCountByRepositoryDelegate

设置代理方法，用于从 data repository 获取条目的总计数。例如：

@Autowired
private DepartmentRepository repository;

@Install(to = "pagination", subject = "totalCountByRepositoryDelegate")
private Long paginationTotalCountByRepositoryDelegate(
        final JmixDataRepositoryContext context) {
    return repository.count(context);
}