ToolJet Table 组件服务端排序（Server Side Sort）实现指南：基于 sortApplied 暴露变量与事件驱动的全量数据排序方案-开发者社区

ToolJet Table 组件服务端排序（Server Side Sort）实现指南：基于 sortApplied 暴露变量与事件驱动的全量数据排序方案

【免费下载链接】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

本文是一份聚焦 ToolJetTable 组件服务端排序（Server Side Sort）的完整实战指南。在 ToolJet 中构建数据密集型的内部工具、仪表盘或业务应用时，当数据量远超单次查询可加载范围，客户端排序只能对已加载到浏览器中的数据进行排序，无法覆盖数据库全量记录；而服务端排序通过把「排序列 + 排序方向」回传给查询（Query），让数据库在服务器端完成 ORDER BY，从而实现对全量数据的排序。读完本文，你将掌握 Table 组件的服务端排序开关配置、基于sortApplied暴露变量的动态 SQL 写法、「Sort applied」事件驱动查询重跑、以及 Loading State 联动的完整链路，并了解其底层源码实现原理。

前置概念：服务端操作与客户端操作的区别

在进入排序实战之前，先明确服务端排序在整个 Table 组件服务端操作体系中的位置。服务端操作指在服务器端执行的数据获取、搜索、排序、过滤和分页等任务，它们使用服务器资源，能够高效处理大型数据集，并为用户带来更快的加载体验；与之相对的客户端操作则在浏览器中完成，需要先把数据全部拉到前端再本地处理，大数据量下容易出现性能问题。相关的服务端操作说明可参见服务端操作概览，该体系下 Table 组件共支持四种服务端操作：

Search（服务端搜索）
Sort（服务端排序）
Filter（服务端过滤）
Pagination（服务端分页）

本文以PostgreSQL数据源（ToolJet 内置的sample_data_orders示例表）演示服务端排序的实现过程。大多数数据库都支持服务端操作，但具体实现方式可能因数据库而异。

第一步：添加 Table 组件并准备数据

在实现排序之前，先添加Table组件并为其填充数据：

从右侧组件库中拖拽一个Table组件到画布上。
在底部查询面板（Query Panel）中选择数据源并创建新查询。本指南使用 ToolJet 的示例数据源（Postgres），添加如下查询从数据库获取数据：

SELECT * FROM public.sample_data_orders LIMIT 100

将 Table 组件的Data（数据）属性值设置为{{queries.<query_name>.data}}，用查询返回的数据填充 Table 组件。

从源码结构看，Table 组件的data属性在 widgets/table.js 中被定义为数组类型（type: 'array'，元素为对象），默认值为[{ id: 1, name: 'Sarah', email: 'sarah@mail.com' }]，这与{{queries.<query_name>.data}}返回数组数据的绑定方式一致。

第二步：开启 Server Side Sort

按照以下步骤在 Table 组件上执行服务端排序操作：

在Table组件的属性面板中找到排序相关配置，将Type切换为Server side，即启用服务端排序。

该开关对应的属性名为serverSideSort。在 widgets/table.js 中，它被定义为一个clientServerSwitch类型的开关，提供Client side与Server side两个选项，默认值为false（即默认客户端排序）；同时 initSlice.js 在组件初始化时也会将serverSideSort的默认值设为false。

输入如下查询（这是整个服务端排序的核心）：

SELECT * FROM public.sample_data_orders {{components.table1.sortApplied ? ` ORDER BY ${components.table1.sortApplied[0].column} ${components.table1.sortApplied[0].direction} ` : ""}} LIMIT 100

注意：请务必将table1替换为你实际使用的Table组件名称。

这段 SQL 的精妙之处在于利用 ToolJet 的模板语法（{{ }}）做了条件渲染：

当用户在 Table 上应用了排序时，暴露变量components.table1.sortApplied非空，于是 SQL 中注入ORDER BY <排序列> <排序方向>子句；
当用户未应用排序或清除排序时，sortApplied为空数组，条件判断为假，整个子句被替换为空字符串""，查询退化为普通的全表扫描 +LIMIT 100。

由于ORDER BY子句在服务器端执行，排序作用范围是数据库中的全量记录，而不是前端已加载的那 100 条数据——这正是服务端排序与客户端排序的本质区别。

sortApplied 暴露变量的数据结构

sortApplied是 Table 组件在服务端排序模式下暴露的关键变量。从 TableExposedVariables.jsx 的源码可以看到，当表格的排序状态（sorting）发生变化时，组件会构造如下结构并写入暴露变量：

const sortApplied = [ { column: getColumnName(sorting[0].id), // 列的显示名称（表头文本） columnKey: getColumnKey(sorting[0].id), // 列的 accessorKey（字段键名） direction: sorting[0].desc ? 'desc' : 'asc' // 排序方向 }, ]; setExposedVariables({ sortApplied }); fireEvent('onSort');

也就是说，sortApplied是一个对象数组，每个元素包含三个字段：

字段	含义	示例值
`column`	被排序列的显示名称（表头标题）	`Order ID`
`columnKey`	被排序列的数据字段键名（accessorKey）	`order_id`
`direction`	排序方向，`asc`表示升序，`desc`表示降序	`asc`/`desc`

因此文档示例 SQL 中的components.table1.sortApplied[0].column会取到排序列的列名，components.table1.sortApplied[0].direction会取到asc或desc，两者拼接后正好构成合法的ORDER BY子句。当排序被清除时，组件会把sortApplied重置为空数组[]，SQL 中的条件渲染随之关闭ORDER BY。

第三步：绑定 Sort Applied 事件触发查询

为Table组件添加一个事件处理器（Event Handler）：

Event（事件）：Sort applied
Action（动作）：Run Query
Query（查询）：选择你创建的查询（如getOrders）

这样每次在 Table 上应用排序时，都会自动运行该查询并重新拉取数据。事件与查询的联动机制在源码中同样有迹可循：

事件onSort在 widgets/table.js 中被注册，显示名为Sort applied；
触发时机见 TableExposedVariables.jsx：当排序状态sorting长度大于 0 时写入sortApplied并触发onSort；当排序被清除（长度变为 0）且此前已有排序时，也会触发一次onSort，确保清除排序后查询同样会重跑以回到未排序状态；
事件合法性声明位于 eventsSlice.js，onSort被列入 Table 组件可注册的事件清单。

同时，从 useTable.js 可以看到，Table 组件底层基于 TanStack Table 构建，当serverSideSort为true时，useReactTable会启用manualSorting: serverSideSort。manualSorting是 TanStack Table 的「手动排序」模式：开启后框架不再对data做本地排序，而只负责维护排序状态、把排序结果通过上述机制暴露出来，真正的排序逻辑完全交由用户自己的服务端查询完成——这正是服务端排序在实现层面的关键开关。

第四步：联动 Loading State 提升交互体验

进入 Table 组件属性的Additional Actions（附加操作）区域，点击Loading State旁边的fx图标，在输入框中填入{{queries.getOrders.isLoading}}，为表格添加加载状态。注意：请将getOrders替换为你实际的查询名称。

当查询正在执行时，queries.getOrders.isLoading为true，Table 组件会显示加载动画，避免用户在大数据集排序期间误操作或产生困惑；查询完成后isLoading变为false，表格恢复可交互状态。这一设置尤其重要，因为服务端排序需要对数据库全量数据执行ORDER BY，查询耗时通常长于纯客户端排序，明确的加载反馈能显著提升用户体验。

工作链路总结与源码验证

至此，ToolJet Table 组件的服务端排序已完整实现。整个机制的运转链路可以概括为：

用户操作：点击 Table 表头对某列应用排序（升序/降序切换）；
状态更新：Table 底层（TanStack Table 的manualSorting模式）更新排序状态sorting；
变量暴露：TableExposedVariables.jsx 将排序状态转换为sortApplied（含column、columnKey、direction）暴露给查询，同时触发onSort（Sort applied）事件；
事件响应：事件处理器执行Run Query，携带sortApplied信息的查询被重新运行；
服务端排序：SQL 模板中的{{components.table1.sortApplied ? ...}}条件渲染出ORDER BY子句，数据库在服务器端完成全量排序；
结果回填：查询返回排序后的数据，通过{{queries.<query_name>.data}}回填 Table 组件的 Data 属性，期间 Loading State 通过{{queries.<query_name>.isLoading}}显示加载状态。

当用户在 Table 上对某一列应用排序时，查询会在服务器端执行，从而实现对整个数据集的排序，而不仅限于已加载进 Table 的数据——这保证了排序结果覆盖数据库中的所有记录。当你需要将服务端排序与服务端搜索、过滤、分页组合使用时，可以分别参考对应的 Search、Filter、Pagination 指南，它们在架构上遵循同一套「暴露变量 + 动态查询 + 事件触发」模式，可无缝组合进同一条 SQL 查询中。