ToolJet 表格服务端分页实战指南：用 LIMIT/OFFSET 分块加载大数据集

ToolJet 表格服务端分页实战指南：用 LIMIT/OFFSET 分块加载大数据集

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

本指南讲解如何在 ToolJet 中为表格（Table）组件实现服务端分页（Server-side Pagination），通过数据库原生LIMIT/OFFSET能力分块拉取数据，避免一次性加载百万行数据集带来的性能问题。本文以 PostgreSQLusers表为例，完整覆盖分页查询 SQL、表格属性配置、翻页事件联动与加载状态提示，并补充源码级原理说明，读完即可在 MySQL、PostgreSQL、MSSQL、MongoDB 等支持limit/offset的数据库中落地同样的方案。

一、为什么需要服务端分页

当数据集规模较小时，把全部数据一次性绑定到表格并让前端做客户端分页（Client-side Pagination）完全够用。但数据量增长到数万甚至百万行时：

• 每次查询都传输全量数据，网络与内存开销巨大；
• 前端渲染大量 DOM 节点，交互卡顿；
• 数据库返回结果集耗时变长，页面初始化缓慢。

服务端分页的核心思路是：前端只请求当前页需要的那一小段数据，由数据库使用LIMIT与OFFSET按页截取。ToolJet 表格组件对外暴露当前页码pageIndex，把它代入 SQL 的OFFSET表达式，即可实现"翻页即查询"的按需加载。本指南适用于 MySQL、PostgreSQL、MSSQL、MongoDB 等支持limit/offset分块取数的数据库。

二、第一步：用 PostgreSQL 分块加载数据

在 ToolJet 数据源中创建针对 PostgreSQL 的连接，然后编写如下查询，从users表按页取数：

SELECT * FROM users ORDER BY id LIMIT 100 OFFSET {{(components.table1.pageIndex-1)*100}};

每次查询只返回 100 行，具体返回哪一段由表格组件暴露的变量pageIndex（当前页码）动态决定。该查询可拆解为三个部分：

• ORDER BY id：按id列对结果集排序。分页场景下排序必不可少，否则翻页时数据顺序不稳定，可能出现重复或漏行。
• LIMIT 100：限制每次查询最多返回 100 条记录，即每页大小。
• OFFSET {{(components.table1.pageIndex-1)*100}}：根据当前页码计算起始行号。第 1 页跳过 0 行、第 2 页跳过 100 行、第 3 页跳过 200 行，以此类推。pageIndex是表格组件暴露的内置变量，默认从 1 开始。

此外还需要一个查询获取总记录数，用于渲染分页器、控制"下一页"按钮可用性：

SELECT COUNT(*) FROM users;

MongoDB 对应写法：db.users.find({}).sort({id: 1}).skip((pageIndex-1)*100).limit(100)，skip对应OFFSET、limit对应LIMIT，其余配置步骤完全一致。

三、第二步：配置 Table 组件属性

将表格组件从组件库拖入画布，按以下步骤配置属性（对应 ToolJet 前端组件定义 frontend/src/AppBuilder/WidgetManager/widgets/table.js）：

1. 绑定数据源：将Data属性设为{{queries.<postgresquery>.data}}（<postgresquery>替换为你实际创建的分页查询名称），表格即显示当前页数据。

2. 开启服务端分页：启用Server-side pagination选项。该属性在源码中对应serverSidePagination配置项，类型为clientServerSwitch，提供Client side/Server side两个选项，默认值为false（客户端模式）；切换到 Server side 后，分页、排序、过滤等操作将交由后端/数据库处理。

3. 控制"上一页"按钮：点击Enable previous page button旁的Fx，输入：

   {{components.table1.pageIndex >=2 ? true : false}}

   该条件表达式的含义是：只有当前页码 ≥ 2 时才启用"上一页"按钮，即第一页时按钮禁用。

4. 控制"下一页"按钮：点击Enable next page button旁的Fx，输入：

   {{components.table1.pageIndex < queries.<countquery>.data[0].count/100 ? true : false}}

   其中<countquery>是执行SELECT COUNT(*)的查询名。count/100得到总页数（100与分页查询的LIMIT保持一致），当前页小于总页数时按钮可用；到达最后一页自动禁用。

5. 设置总记录数：将Total records server side属性设为：

   {{queries.<countquery>.data[0].count}}

   该属性在源码中对应totalRecords配置项，类型为code，默认值10。正确设置后，表格页脚会显示总记录数并基于它计算总页数，从而正确渲染页码。

6. 设置加载状态：将Loading state属性设为{{queries.<postgresquery>.isLoading}}。查询执行期间表格显示加载指示器，避免用户误以为卡死；这也对应了源码中表格默认的loadingState属性（默认{{false}}）。

提示：步骤 3、4 中的Fx即"函数/表达式"切换按钮，点击后可把普通静态值切换为{{ }}包裹的 ToolJet 表达式，支持引用组件变量、查询结果并执行三元运算。

四、第三步：用事件处理器实现翻页联动

要让"翻页即重新查询"真正生效，还需把表格的翻页事件与数据查询绑定：

1. 选中表格组件，在右侧属性面板的事件（Events）区域点击New event handler添加事件处理器；
2. Event选择Page changed；
3. Action选择Run Query；
4. 在Query下拉框中选择第一步创建的分页查询（如postgresql1）。

完成后，每当用户在表格页脚切换页码，ToolJet 都会自动执行该查询：pageIndex变化 →OFFSET表达式重算 → 数据库返回新一页数据 → 表格刷新。加载状态提示则会随查询的isLoading同步出现。

五、源码视角：服务端分页的底层实现

在 frontend/src/AppBuilder/Widgets/NewTable/_hooks/useTable.js 中可以看到表格分页的驱动逻辑：

• 第 27 行附近，分页状态pageIndex初始化为 0；当serverSidePagination开启时，翻页后保留当前页（prev.pageIndex ?? 0），否则回到第 1 页——这保证服务端模式下切换页码不会被前端重置；
• 第 108 行附近，manualPagination: serverSidePagination被传给底层表格实例，表示开启手动分页模式：分页完全交由用户（服务端）控制，前端不做自动切片。

组件内部变量与事件的暴露逻辑位于 frontend/src/AppBuilder/Widgets/NewTable/_components/TableExposedVariables/TableExposedVariables.jsx：

• 第 148-160 行，pageIndex通过setExposedVariables({ pageIndex })暴露给表达式引擎，这就是 SQL 中{{components.table1.pageIndex}}能动态求值的原因；同时，仅当用户通过页脚分页按钮/输入框翻页（paginationBtnClicked标志）时才触发onPageChanged事件——这正对应上面配置的Page changed事件处理器；
• 第 224-231 行，还暴露了setPage(targetPageIndex)的组件方法（CSA），可在其他组件/查询中以编程方式跳转页码。

分页按钮的渲染与禁用逻辑见 frontend/src/AppBuilder/Widgets/NewTable/_components/Footer/_components/Pagination/Pagination.jsx 与 frontend/src/AppBuilder/Widgets/NewTable/_components/Footer/_components/ControlButtons.jsx，它们消费enablePrevButton/enableNextButton/totalRecords等属性，与我们在属性面板中填写的表达式一一对应。

由此可以推断完整的数据流：用户翻页 →pageIndex更新并暴露 → 触发onPageChanged→ 事件处理器运行分页查询 → SQL 中OFFSET基于新页码重算 → 数据库返回该页数据 →queries.<postgresquery>.data更新 → 表格重新渲染。

六、方案验证与常见问题

验证方法：打开浏览器开发者工具的网络面板，观察翻页时是否只发起单次数据库查询；或直接修改第 1 页的LIMIT值，确认表格单页行数随之变化。也可以临时把Loading state绑定为{{queries.<postgresquery>.isLoading}}后刷新页面，观察加载指示器是否随查询起止出现。

常见问题排查：

• 翻页后数据不刷新：检查事件处理器是否正确配置为Page changed → Run Query → 选择分页查询；
• "下一页"按钮始终不可用或总页数不对：确认Total records server side与SELECT COUNT(*)查询结果绑定正确，且LIMIT数值与判断表达式中的100完全一致；
• OFFSET 越界报错：当pageIndex大于总页数时 OFFSET 会超过数据总量，可在查询中追加条件或用LEAST/OFFSET 0兜底，例如OFFSET {{Math.min((components.table1.pageIndex-1)*100, (queries.countquery.data[0].count || 0))}}；
• 翻页后页码被重置为第 1 页：确认Server-side pagination已开启，客户端模式下前端会自动分页并重置页码。

七、更进一步

• 服务端排序与过滤：表格还提供serverSideSort（服务端排序）、serverSideFilter（服务端过滤）、serverSideSearch（服务端搜索）开关，定义于 frontend/src/AppBuilder/WidgetManager/widgets/table.js，可结合sortApplied、filters、searchText等暴露变量把排序、过滤、搜索也下推到 SQL，进一步减轻前端负担；
• 分页大小可调：属性面板中的Number of rows per page（源码serverSideRowsPerPage）可覆盖每页行数，使LIMIT不再写死；
• 编程跳页：利用暴露的setPage(page)方法，可在自定义按钮或 RunJS 查询中实现"跳转到指定页"。

本文以 PostgreSQL 为例的完整配置链路——分页 SQL + 计数 SQL → 表格属性（数据源、服务端分页、按钮启用条件、总记录数、加载状态）→ Page changed 事件触发 Run Query——在其他支持limit/offset的数据库上完全通用，是 ToolJet 中处理大型数据集的标准实践。

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet