尧图网页设计 
ToolJet 服务端分页实战指南Table 组件大规模数据高效加载【免费下载链接】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。当数据表承载的数据量达到数千、数万乃至更多记录时一次性把全部数据拉取到浏览器会导致应用卡顿、接口响应缓慢而服务端分页让查询在服务端执行、只返回当前页所需的最小记录集从而显著降低网络传输与前端渲染压力。读完本文你将掌握在 ToolJet 中启用服务端分页、编写分页查询、计算总记录数、绑定翻页事件与加载状态以及禁用末页“下一页”按钮的完整实操链路并理解其底层实现原理。前置准备添加 Table 组件并填充数据在执行服务端分页之前需要先在画布上放置Table组件并让数据先“跑”起来。步骤如下从右侧组件库中将Table组件拖拽到画布中。在底部的查询面板中选择一个数据源并新建查询。本文以 ToolJet 内置的示例数据源Postgres为例执行以下 SQL 查询拉取数据SELECT * FROM public.sample_data_orders LIMIT 100说明先用LIMIT 100限制初始返回的行数避免首次渲染时加载过多数据。在 Table 组件的Data属性中填入{{queries.query_name.data}}即可将查询结果绑定到表格组件。例如查询名为getOrders则填写{{queries.getOrders.data}}。完成以上步骤后表格即可正常展示数据为后续的服务端分页配置打下基础。启用服务端分页分页Pagination是表格处理大量数据时最基础的能力。在 ToolJet 的 Table 组件中分页有客户端分页与服务端分页两种模式客户端分页Client side所有数据一次性加载到浏览器内存中由前端进行切片分页适合数据量较小的场景服务端分页Server side每次翻页都重新向数据源发起查询仅取回当前页数据适合大规模数据集。这一模式定义在 Table 组件的属性配置中。查看 Table 组件属性定义 可以看到serverSidePagination属性是一个clientServerSwitch类型的开关其两个选项即Client side与Server side默认值为false即客户端分页。在 Table 组件属性面板中找到并开启Server Side Pagination即可启用服务端分页模式。分页相关的核心属性除serverSidePagination外服务端分页还涉及以下关键属性同样定义于 table.js 组件属性定义属性类型默认值说明totalRecordscode10服务端总记录数即“Total records server side”用于计算总页数serverSideRowsPerPagecode—服务端模式下每页显示的行数Number of rows per pageenablePaginationtoggletrue是否启用分页enablePrevButtontoggle—是否启用“上一页”按钮serverSidePaginationclientServerSwitchfalse分页模式客户端 / 服务端此外Table 组件还提供了serverSideSort、serverSideFilter、serverSideSearch三个同类型开关分别用于将排序、过滤、搜索也切换为服务端模式可与服务端分页组合使用见 table.js 属性定义。第一步创建总记录数查询服务端分页需要知道数据集的总行数才能正确计算总页数并渲染页码。新建一个查询来计算服务端的总记录数SELECT COUNT(*) FROM public.sample_data_orders以查询名countOrders为例该查询将返回形如[{ count: 1234 }]的结果。第二步绑定服务端总记录数在 Table 组件属性的Pagination部分找到Total record server side输入框填入{{queries.countOrders.data[0].count}}注意请将countOrders替换为你上一步实际创建的查询名称。这里的totalRecords属性会被用于分页逻辑计算。从 Pagination 组件源码 可以看到当启用服务端分页且serverSideRowsPerPage与totalRecords均大于 0 时总页数按如下公式计算const effectivePageCount Math.ceil(parsedTotalRecords / parsedServerSideRowsPerPage);即总页数 向上取整总记录数 ÷ 每页行数。这也解释了为什么正确填写这两个属性是分页条正确渲染的前提。同时表格页脚的记录数显示也会读取该属性。在 RowCount 组件 中当启用服务端分页且totalRecords存在时页脚会显示${totalRecords} Records。第三步编写分页查询分页查询的核心思路是根据当前页码pageIndex与每页行数本示例为 100动态计算OFFSET值。新建或改造数据查询SELECT * FROM public.sample_data_orders LIMIT 100 OFFSET {{(components.table1.pageIndex-1)*100}}注意请将table1替换为你实际的Table组件名称。理解pageIndex暴露变量components.table1.pageIndex是 Table 组件对外暴露的当前页码从 1 开始。该变量由表格运行时的分页状态实时驱动在 useTable 分页状态 中表格内部维护一个pagination状态对象其中pageIndex从 0 开始计数即第 1 页的内部值为 0在 TableContainer 组件 中对外暴露时做了1处理pageIndex{pagination.pageIndex 1}因此你在表达式中使用的components.table1.pageIndex是从 1 开始的人类可读页码同时该值会通过setExposedVariables同步到组件暴露变量中见 TableExposedVariables 组件。因此当位于第 1 页时pageIndex为 1OFFSET为 0位于第 2 页时pageIndex为 2OFFSET为 100依此类推——这正是LIMIT 100 OFFSET {{(components.table1.pageIndex-1)*100}}的数学含义。服务端模式下的分页状态保持在服务端分页模式下翻页时前端不应清空页码状态。从 useTable 分页状态同步逻辑 可以看到useEffect(() { setPagination((prev) ({ pageIndex: serverSidePagination ? (prev.pageIndex ?? 0) : 0, pageSize: enablePagination ? rowsPerPage : data.length, })); }, [enablePagination, rowsPerPage, data.length, serverSidePagination]);即客户端模式下每次数据变化会重置回第 1 页而服务端模式下会保留prev.pageIndex避免因查询返回新数据而导致页码跳动。第四步绑定翻页事件触发查询仅编写分页查询还不够还需要在用户翻页时自动重新执行查询。为 Table 组件添加Event HandlerEventPage changed对应源码中的onPageChanged见 table.js 事件定义ActionRun QueryQuery选择你创建的分页查询如getOrders这样每次页码变化时ToolJet 都会重新运行查询并获取当前页对应的数据。从实现层面看表格页脚的翻页按钮上一页 / 下一页 / 页码跳转 / 首页 / 末页在 Pagination 组件 中通过table.nextPage()、table.previousPage()、table.setPageIndex(targetPage - 1)驱动内部分页状态pageIndex变化后即触发Page changed事件进而运行绑定的事件处理器中的查询动作。第五步禁用末页的“下一页”按钮当到达最后一页时“下一页”按钮应当被禁用否则用户会点到无数据的空页。在 Table 组件属性的Pagination部分点击Enable next page button旁的fx图标输入{{components.table1.pageIndex queries.countOrders.data[0].count / 100}}该表达式的含义是当当前页小于总页数总记录数 ÷ 每页行数 100时允许点击下一页否则禁用。从源码层面验证在 Pagination 组件 中服务端模式下“下一页”按钮的可点击状态直接由enableNextButton属性驱动const canGoToNextPage serverSidePagination ? enableNextButton : table.getCanNextPage();也就是说服务端模式下前端无法自行推断是否还有下一页必须由开发者通过表达式计算结果来显式控制enableNextButton这正是本步骤存在的意义。进阶提示同理enablePrevButton属性控制“上一页”按钮当你希望在第一页时禁用“上一页”按钮可以通过类似表达式{{components.table1.pageIndex 1}}进行控制。第六步添加加载状态服务端查询期间表格应显示加载状态以提升交互体验。在 Table 组件属性的Additional Actions部分点击Loading State旁的fx图标输入{{queries.getOrders.isLoading}}注意请将getOrders替换为你实际的分页查询名称。queries.query_name.isLoading是查询运行期间的响应式状态变量查询进行中为true、完成后为false。将其绑定到表格的 Loading State 后翻页时表格会自动进入加载态数据返回后自动恢复避免用户误以为页面无响应。底层机制manualPagination 与按需取数从整体架构来看ToolJet Table 组件基于tanstack/react-table构建见 useTable hook 的引入。当启用服务端分页时表格会进入“手动分页manual pagination”模式manualPagination: serverSidePagination, manualSorting: serverSideSort, manualFiltering: serverSideFilter,见 useTable hookmanualPagination: true意味着 TanStack Table 不再基于本地数据自动切片而是完全信任开发者提供的当前页数据——分页状态只用于触发事件、计算 OFFSET真正的数据切片发生在服务端。这正是“服务端分页”的精髓用户点击翻页按钮 →pageIndex更新Page changed事件触发Run Query分页查询使用新的pageIndex计算OFFSET在数据库端执行LIMIT/OFFSET切片服务端只返回当前页的少量记录前端表格仅渲染这页数据无需承载全量数据集。这种模式确保数据从服务端高效拉取而不是一次性加载整个数据集从而显著提升大数据量场景下的性能与可扩展性。另外值得注意的是服务端模式下effectivePageSize的解析逻辑位于 TableContainer 组件当启用服务端分页时优先使用serverSideRowsPerPage须大于 0否则回退到常规的rowsPerPage。完整配置清单为便于快速落地将上述所有步骤汇总为一张配置清单配置项位置值 / 操作Data 属性Table 属性 → Data{{queries.getOrders.data}}初始数据查询查询面板SELECT * FROM public.sample_data_orders LIMIT 100Server Side PaginationTable 属性 → Pagination开启总记录数查询查询面板SELECT COUNT(*) FROM public.sample_data_ordersTotal record server sideTable 属性 → Pagination{{queries.countOrders.data[0].count}}分页查询查询面板SELECT * FROM public.sample_data_orders LIMIT 100 OFFSET {{(components.table1.pageIndex-1)*100}}Event HandlerTable 属性 → EventsEvent:Page changedAction:Run QueryQuery: 分页查询Enable next page buttonTable 属性 → Pagination → fx{{components.table1.pageIndex queries.countOrders.data[0].count / 100}}Loading StateTable 属性 → Additional Actions → fx{{queries.getOrders.isLoading}}以上所有table1、getOrders、countOrders均为示例名称请替换为你的实际组件名与查询名。进阶扩展本文介绍的服务端分页是 Table 组件服务端操作体系中的一环。ToolJet 还提供了配套的服务端排序、服务端过滤与服务端搜索能力操作方式与分页高度一致服务端排序serverSideSort属性开启后排序状态由前端传递到查询表达式如ORDER BY子句在服务端执行参见 服务端操作排序指南服务端过滤serverSideFilter属性开启后筛选条件同样下沉到服务端查询参见 服务端操作过滤指南服务端搜索serverSideSearch属性开启后搜索关键词可用于服务端LIKE/全文检索参见 服务端操作搜索指南相关概念综述可参考 服务端操作总览。此外Table 组件还有其他常用属性如启用排序、显示搜索框、启用过滤等可参考 Table 组件属性文档组件对外暴露的变量如pageIndex、selectedRow、currentPageData等详见 组件状态与变量文档。结语通过本文的六个步骤——创建初始查询、统计总记录数、绑定总数、编写带OFFSET的动态分页查询、挂载Page changed事件处理器、控制按钮可用性与加载状态——你可以在 ToolJet 的 Table 组件上完整落地服务端分页。其核心价值在于把数据切片从浏览器迁移到数据库端让应用在面对海量数据时依然保持流畅响应。配合服务端排序、过滤与搜索能力即可构建出可扩展到任意数据规模的表格应用。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ToolJet 服务端分页实战指南：Table 组件大规模数据高效加载
ToolJet 服务端分页实战指南Table 组件大规模数据高效加载【免费下载链接】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。当数据表承载的数据量达到数千、数万乃至更多记录时一次性把全部数据拉取到浏览器会导致应用卡顿、接口响应缓慢而服务端分页让查询在服务端执行、只返回当前页所需的最小记录集从而显著降低网络传输与前端渲染压力。读完本文你将掌握在 ToolJet 中启用服务端分页、编写分页查询、计算总记录数、绑定翻页事件与加载状态以及禁用末页“下一页”按钮的完整实操链路并理解其底层实现原理。前置准备添加 Table 组件并填充数据在执行服务端分页之前需要先在画布上放置Table组件并让数据先“跑”起来。步骤如下从右侧组件库中将Table组件拖拽到画布中。在底部的查询面板中选择一个数据源并新建查询。本文以 ToolJet 内置的示例数据源Postgres为例执行以下 SQL 查询拉取数据SELECT * FROM public.sample_data_orders LIMIT 100说明先用LIMIT 100限制初始返回的行数避免首次渲染时加载过多数据。在 Table 组件的Data属性中填入{{queries.query_name.data}}即可将查询结果绑定到表格组件。例如查询名为getOrders则填写{{queries.getOrders.data}}。完成以上步骤后表格即可正常展示数据为后续的服务端分页配置打下基础。启用服务端分页分页Pagination是表格处理大量数据时最基础的能力。在 ToolJet 的 Table 组件中分页有客户端分页与服务端分页两种模式客户端分页Client side所有数据一次性加载到浏览器内存中由前端进行切片分页适合数据量较小的场景服务端分页Server side每次翻页都重新向数据源发起查询仅取回当前页数据适合大规模数据集。这一模式定义在 Table 组件的属性配置中。查看 Table 组件属性定义 可以看到serverSidePagination属性是一个clientServerSwitch类型的开关其两个选项即Client side与Server side默认值为false即客户端分页。在 Table 组件属性面板中找到并开启Server Side Pagination即可启用服务端分页模式。分页相关的核心属性除serverSidePagination外服务端分页还涉及以下关键属性同样定义于 table.js 组件属性定义属性类型默认值说明totalRecordscode10服务端总记录数即“Total records server side”用于计算总页数serverSideRowsPerPagecode—服务端模式下每页显示的行数Number of rows per pageenablePaginationtoggletrue是否启用分页enablePrevButtontoggle—是否启用“上一页”按钮serverSidePaginationclientServerSwitchfalse分页模式客户端 / 服务端此外Table 组件还提供了serverSideSort、serverSideFilter、serverSideSearch三个同类型开关分别用于将排序、过滤、搜索也切换为服务端模式可与服务端分页组合使用见 table.js 属性定义。第一步创建总记录数查询服务端分页需要知道数据集的总行数才能正确计算总页数并渲染页码。新建一个查询来计算服务端的总记录数SELECT COUNT(*) FROM public.sample_data_orders以查询名countOrders为例该查询将返回形如[{ count: 1234 }]的结果。第二步绑定服务端总记录数在 Table 组件属性的Pagination部分找到Total record server side输入框填入{{queries.countOrders.data[0].count}}注意请将countOrders替换为你上一步实际创建的查询名称。这里的totalRecords属性会被用于分页逻辑计算。从 Pagination 组件源码 可以看到当启用服务端分页且serverSideRowsPerPage与totalRecords均大于 0 时总页数按如下公式计算const effectivePageCount Math.ceil(parsedTotalRecords / parsedServerSideRowsPerPage);即总页数 向上取整总记录数 ÷ 每页行数。这也解释了为什么正确填写这两个属性是分页条正确渲染的前提。同时表格页脚的记录数显示也会读取该属性。在 RowCount 组件 中当启用服务端分页且totalRecords存在时页脚会显示${totalRecords} Records。第三步编写分页查询分页查询的核心思路是根据当前页码pageIndex与每页行数本示例为 100动态计算OFFSET值。新建或改造数据查询SELECT * FROM public.sample_data_orders LIMIT 100 OFFSET {{(components.table1.pageIndex-1)*100}}注意请将table1替换为你实际的Table组件名称。理解pageIndex暴露变量components.table1.pageIndex是 Table 组件对外暴露的当前页码从 1 开始。该变量由表格运行时的分页状态实时驱动在 useTable 分页状态 中表格内部维护一个pagination状态对象其中pageIndex从 0 开始计数即第 1 页的内部值为 0在 TableContainer 组件 中对外暴露时做了1处理pageIndex{pagination.pageIndex 1}因此你在表达式中使用的components.table1.pageIndex是从 1 开始的人类可读页码同时该值会通过setExposedVariables同步到组件暴露变量中见 TableExposedVariables 组件。因此当位于第 1 页时pageIndex为 1OFFSET为 0位于第 2 页时pageIndex为 2OFFSET为 100依此类推——这正是LIMIT 100 OFFSET {{(components.table1.pageIndex-1)*100}}的数学含义。服务端模式下的分页状态保持在服务端分页模式下翻页时前端不应清空页码状态。从 useTable 分页状态同步逻辑 可以看到useEffect(() { setPagination((prev) ({ pageIndex: serverSidePagination ? (prev.pageIndex ?? 0) : 0, pageSize: enablePagination ? rowsPerPage : data.length, })); }, [enablePagination, rowsPerPage, data.length, serverSidePagination]);即客户端模式下每次数据变化会重置回第 1 页而服务端模式下会保留prev.pageIndex避免因查询返回新数据而导致页码跳动。第四步绑定翻页事件触发查询仅编写分页查询还不够还需要在用户翻页时自动重新执行查询。为 Table 组件添加Event HandlerEventPage changed对应源码中的onPageChanged见 table.js 事件定义ActionRun QueryQuery选择你创建的分页查询如getOrders这样每次页码变化时ToolJet 都会重新运行查询并获取当前页对应的数据。从实现层面看表格页脚的翻页按钮上一页 / 下一页 / 页码跳转 / 首页 / 末页在 Pagination 组件 中通过table.nextPage()、table.previousPage()、table.setPageIndex(targetPage - 1)驱动内部分页状态pageIndex变化后即触发Page changed事件进而运行绑定的事件处理器中的查询动作。第五步禁用末页的“下一页”按钮当到达最后一页时“下一页”按钮应当被禁用否则用户会点到无数据的空页。在 Table 组件属性的Pagination部分点击Enable next page button旁的fx图标输入{{components.table1.pageIndex queries.countOrders.data[0].count / 100}}该表达式的含义是当当前页小于总页数总记录数 ÷ 每页行数 100时允许点击下一页否则禁用。从源码层面验证在 Pagination 组件 中服务端模式下“下一页”按钮的可点击状态直接由enableNextButton属性驱动const canGoToNextPage serverSidePagination ? enableNextButton : table.getCanNextPage();也就是说服务端模式下前端无法自行推断是否还有下一页必须由开发者通过表达式计算结果来显式控制enableNextButton这正是本步骤存在的意义。进阶提示同理enablePrevButton属性控制“上一页”按钮当你希望在第一页时禁用“上一页”按钮可以通过类似表达式{{components.table1.pageIndex 1}}进行控制。第六步添加加载状态服务端查询期间表格应显示加载状态以提升交互体验。在 Table 组件属性的Additional Actions部分点击Loading State旁的fx图标输入{{queries.getOrders.isLoading}}注意请将getOrders替换为你实际的分页查询名称。queries.query_name.isLoading是查询运行期间的响应式状态变量查询进行中为true、完成后为false。将其绑定到表格的 Loading State 后翻页时表格会自动进入加载态数据返回后自动恢复避免用户误以为页面无响应。底层机制manualPagination 与按需取数从整体架构来看ToolJet Table 组件基于tanstack/react-table构建见 useTable hook 的引入。当启用服务端分页时表格会进入“手动分页manual pagination”模式manualPagination: serverSidePagination, manualSorting: serverSideSort, manualFiltering: serverSideFilter,见 useTable hookmanualPagination: true意味着 TanStack Table 不再基于本地数据自动切片而是完全信任开发者提供的当前页数据——分页状态只用于触发事件、计算 OFFSET真正的数据切片发生在服务端。这正是“服务端分页”的精髓用户点击翻页按钮 →pageIndex更新Page changed事件触发Run Query分页查询使用新的pageIndex计算OFFSET在数据库端执行LIMIT/OFFSET切片服务端只返回当前页的少量记录前端表格仅渲染这页数据无需承载全量数据集。这种模式确保数据从服务端高效拉取而不是一次性加载整个数据集从而显著提升大数据量场景下的性能与可扩展性。另外值得注意的是服务端模式下effectivePageSize的解析逻辑位于 TableContainer 组件当启用服务端分页时优先使用serverSideRowsPerPage须大于 0否则回退到常规的rowsPerPage。完整配置清单为便于快速落地将上述所有步骤汇总为一张配置清单配置项位置值 / 操作Data 属性Table 属性 → Data{{queries.getOrders.data}}初始数据查询查询面板SELECT * FROM public.sample_data_orders LIMIT 100Server Side PaginationTable 属性 → Pagination开启总记录数查询查询面板SELECT COUNT(*) FROM public.sample_data_ordersTotal record server sideTable 属性 → Pagination{{queries.countOrders.data[0].count}}分页查询查询面板SELECT * FROM public.sample_data_orders LIMIT 100 OFFSET {{(components.table1.pageIndex-1)*100}}Event HandlerTable 属性 → EventsEvent:Page changedAction:Run QueryQuery: 分页查询Enable next page buttonTable 属性 → Pagination → fx{{components.table1.pageIndex queries.countOrders.data[0].count / 100}}Loading StateTable 属性 → Additional Actions → fx{{queries.getOrders.isLoading}}以上所有table1、getOrders、countOrders均为示例名称请替换为你的实际组件名与查询名。进阶扩展本文介绍的服务端分页是 Table 组件服务端操作体系中的一环。ToolJet 还提供了配套的服务端排序、服务端过滤与服务端搜索能力操作方式与分页高度一致服务端排序serverSideSort属性开启后排序状态由前端传递到查询表达式如ORDER BY子句在服务端执行参见 服务端操作排序指南服务端过滤serverSideFilter属性开启后筛选条件同样下沉到服务端查询参见 服务端操作过滤指南服务端搜索serverSideSearch属性开启后搜索关键词可用于服务端LIKE/全文检索参见 服务端操作搜索指南相关概念综述可参考 服务端操作总览。此外Table 组件还有其他常用属性如启用排序、显示搜索框、启用过滤等可参考 Table 组件属性文档组件对外暴露的变量如pageIndex、selectedRow、currentPageData等详见 组件状态与变量文档。结语通过本文的六个步骤——创建初始查询、统计总记录数、绑定总数、编写带OFFSET的动态分页查询、挂载Page changed事件处理器、控制按钮可用性与加载状态——你可以在 ToolJet 的 Table 组件上完整落地服务端分页。其核心价值在于把数据切片从浏览器迁移到数据库端让应用在面对海量数据时依然保持流畅响应。配合服务端排序、过滤与搜索能力即可构建出可扩展到任意数据规模的表格应用。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考