vxe-grid中VxeGridProps如何正确配置分页参数？

Question

在使用 `vxe-grid` 时，如何通过 `VxeGridProps` 正确配置分页参数是一个常见问题。开发者常因未正确设置 `pagerConfig` 导致分页不显示或交互异常。需明确 `pageSize`、`pageSizes`、`total` 等字段，并结合 `remote` 实现服务端分页。问题在于：若 `pagerConfig` 结构不完整或与 `data`、`loading` 配合不当，将导致页码错乱或请求重复。如何正确初始化并同步分页状态？

Answer 1

1. 分页配置基础：理解 VxeGridProps 中的 pagerConfig 结构

在使用 vxe-grid 组件时，分页功能通过 VxeGridProps 接口中的 pagerConfig 字段进行控制。该字段是一个对象，用于定义分页器的外观与行为。

最基本的配置包括：

• pageSize：每页显示的数据条数，默认为 10；
• pageSizes：可选的每页条数数组，如 [10, 20, 50, 100]；
• total：数据总条数，必须由服务端返回或本地计算得出；
• currentPage：当前页码，通常初始化为 1。

若未设置这些字段，分页组件将无法正确渲染或响应用户操作。

2. 配置示例：基础 pagerConfig 定义

const gridOptions: VxeGridProps = {
  data: [],
  loading: false,
  pagerConfig: {
    pageSize: 10,
    pageSizes: [10, 20, 50, 100],
    total: 0,
    currentPage: 1
  }
};

上述代码展示了如何在 VxeGridProps 中声明一个完整的分页配置结构。注意：data 初始为空数组，loading 控制加载状态，二者需与分页逻辑联动。

3. 实现服务端分页：启用 remote 模式

当数据量较大时，应采用服务端分页（remote pagination）。此时需设置 pagerConfig.remote = true，表示分页参数变更时不自动更新本地数据，而是触发外部请求。

关键点在于监听 page-change 事件或结合 proxy-config 自动管理异步流程。

字段名	类型	说明
pageSize	number	每页记录数
currentPage	number	当前页码
total	number	总记录数
remote	boolean	是否启用远程分页
align	string	对齐方式（left/center/right）
perfect	boolean	是否启用完美模式（兼容滚动）
enabled	boolean	是否启用分页器
size	string	尺寸（medium/small/minimal）
layouts	array	自定义布局顺序
current-page	number	同 currentPage

4. 状态同步机制：避免页码错乱与重复请求

常见问题出现在页面切换时，由于未正确维护 currentPage 和 total 的同步关系，导致页码跳转异常或请求发送多次。

解决方案是确保每次分页事件触发后：

1. 设置 loading = true 防止重复提交；
2. 调用 API 获取新页数据；
3. 成功后更新 data、pagerConfig.total 和 pagerConfig.currentPage；
4. 最后设置 loading = false。

5. 流程图：服务端分页交互流程

graph TD
            A[初始化 gridOptions] --> B{是否 remote 分页?}
            B -- 是 --> C[监听 page-change 或 proxy-config]
            B -- 否 --> D[本地分页处理]
            C --> E[设置 loading=true]
            E --> F[发送 AJAX 请求]
            F --> G{响应成功?}
            G -- 是 --> H[更新 data & total & currentPage]
            G -- 否 --> I[错误处理]
            H --> J[设置 loading=false]
            I --> J

6. 使用 ProxyConfig 提升分页管理效率

vxe-grid 提供了 proxy-config 机制，可集中管理数据代理逻辑，自动处理分页、排序、筛选等远程请求。

pagerConfig: {
  pageSize: 10,
  pageSizes: [10, 20, 50],
  total: 0,
  remote: true
},
proxyConfig: {
  seq: true,
  sort: true,
  filter: true,
  ajax: {
    query: ({ page }) => {
      return fetchApi({
        page: page.currentPage,
        size: page.pageSize
      });
    }
  }
}

通过 proxy-config，框架会自动拦截分页变化并执行查询函数，减少手动状态管理出错概率。