ToolJet Table 组件服务端过滤Server Side Filter完整实现指南【免费下载链接】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过滤操作通过开启serverSideFilter属性、用 RunJS 动态拼接 SQL、借助事件处理器将过滤器变化回传到数据库查询让过滤作用于全量数据集而非当前已加载到前端的记录。读完本文你将掌握从组件配置、查询编排到事件链路的完整实操方案并能理解其背后的前端源码实现原理。为什么需要服务端过滤在 ToolJet 的 Table 组件中过滤既可以在客户端完成也可以在服务端完成二者适用于不同场景可参考 serverside-operations 概览维度服务端操作客户端操作执行位置服务器数据库用户浏览器/应用适用场景大型数据集、安全与数据完整性要求高、复杂业务逻辑实时交互、降低服务器负载、离线能力性能表现仅返回过滤后的结果加载更快、扩展性更好需先将全部数据拉取到本地再处理大数据集下可能出现性能问题服务端过滤的核心价值在于过滤条件在服务器端执行影响的是数据集中的全部记录而不是 Table 组件当前已加载的那一小部分数据。这一点也得到源码佐证——在 useTable.js 中当开启服务端模式时Table 底层使用的 TanStack Table 会切换为manualFiltering模式即过滤逻辑完全交由开发者通过查询在服务端处理前端不再对已加载数据做本地过滤。前置准备添加 Table 组件并填充数据在实现过滤之前先完成 Table 组件与数据源的准备工作从右侧组件库中拖拽一个Table组件到画布上。在底部查询面板中选择数据源并创建新查询。本指南以 ToolJet 内置的示例数据源Postgres为例使用如下查询获取数据SELECT * FROM public.sample_data_orders LIMIT 100将 Table 组件的Data属性值设置为{{queries.query_name.data}}让组件展示查询返回的数据。第一步开启 Server Side Filter 属性在 Table 组件的属性面板中找到Server Side Filter开关并将其启用。从源码可以确认该开关的实际行为在 widgets/table.js 中serverSideFilter被定义为一个clientServerSwitch类型的属性用于在客户端/服务端两种过滤模式间切换其默认值为{{false}}见 widgets/table.js并在 initSlice.js 中初始化。开启后Table 的useTableHook 会将该值映射为 TanStack Table 的manualFiltering: serverSideFilter见 useTable.js从而关闭前端自动过滤。第二步创建 RunJS 查询动态生成 SQL开启服务端过滤后Table 组件会把当前过滤器列表暴露为components.table1.filters变量。创建一个RunJS查询读取该变量并动态拼接出带过滤条件的 SQLconst filterData components.table1.filters; const createSQLQueries (filters) { let conditions ; filters.forEach(({ condition, value, column }, index) { const prefix index 0 ? WHERE : AND; switch (condition) { case contains: conditions ${prefix} ${column} ILIKE %${value}%; break; case doesNotContains: conditions ${prefix} ${column} NOT ILIKE %${value}%; break; case matches: case equals: conditions ${prefix} ${column} ${value}; break; case ne: conditions ${prefix} ${column} ! ${value}; break; case nl: conditions ${prefix} ${column} IS NULL; break; case isEmpty: conditions ${prefix} ${column} ; break; default: throw new Error(Unsupported condition: ${condition}); } }); const mainQuery SELECT * FROM public.sample_data_orders ${conditions}; return { mainQuery }; } return createSQLQueries(filterData);这段脚本的核心逻辑值得拆解遍历过滤器components.table1.filters是一个数组每个元素包含condition过滤条件类型、value过滤值、column目标列名三个字段条件拼接第一个条件以WHERE开头后续条件以AND连接条件类型映射脚本通过switch将过滤器的条件类型翻译为对应的 SQL 片段各类型含义如下condition 取值含义生成的 SQLcontains包含column ILIKE %value%doesNotContains不包含column NOT ILIKE %value%matches/equals等于column valuene不等于column ! valuenl为空NULLcolumn IS NULLisEmpty为空字符串column 注意示例脚本采用字符串插值方式拼接过滤值仅适用于演示与受信任的数据场景。若过滤值可能来自不可信输入建议在生产环境对列名与值做必要的转义或校验避免 SQL 注入风险。第三步为 RunJS 查询添加事件处理器RunJS 查询执行成功后需要触发数据查询重新取数。为 RunJS 查询添加如下事件处理器Event事件Query SuccessAction动作Run QueryQuery查询选择你的数据查询即第一步创建的 Postgres 查询第四步让数据查询使用动态 SQL编辑你的数据查询将 SQL 替换为引用 RunJS 查询输出结果的模板字符串{{queries.runjs1.data.mainQuery}}这里queries.runjs1.data.mainQuery即 RunJS 脚本返回对象中的mainQuery字段。ToolJet 的查询模板语法会在执行前将其解析为最终的 SQL 语句从而把过滤条件注入到数据库查询中。第五步将 Table 的过滤变化接入查询链路现在把 Table 组件的过滤行为与 RunJS 查询连接起来。为 Table 组件添加事件处理器Event事件Filter ChangedAction动作Run QueryQuery查询选择你的 RunJS 查询配置完成后每次过滤器发生变化都会依次触发Table 的Filter Changed事件 → 运行 RunJS 查询重新拼接 SQL→ RunJS 的Query Success事件 → 运行数据查询按新条件取数→ Table 的 Data 属性刷新。这条事件链正是服务端过滤的完整闭环。从源码看Filter Changed事件在 widgets/table.js 中被定义为 Table 组件的标准事件onFilterChanged同时组件暴露了filters这一可访问变量见 widgets/table.js开发者也可以通过组件方法setFilters/clearFilters见 widgets/table.js以编程方式设置或清空过滤器灵活驱动服务端过滤逻辑。第六步添加加载状态Loading State为了避免过滤执行期间界面无反馈可以给 Table 组件加上加载状态在 Table 组件属性面板中找到Additional Actions附加操作区域点击Loading State右侧的fx图标进入表达式编辑模式输入{{queries.getOrders.isLoading}}将getOrders替换为你实际的查询名称。这样当数据查询正在执行时Table 组件会展示加载状态过滤交互的反馈更清晰。实现原理小结从源码层面回看整个实现服务端过滤的机制可以归纳为三点模式切换serverSideFilter属性clientServerSwitch类型决定过滤是否由前端接管。开启后useTable.js 将 TanStack Table 置于manualFiltering模式前端不再执行本地过滤状态暴露过滤器的当前状态通过components.table1.filters暴露给应用包含condition、value、column字段供 RunJS 读取并翻译为 SQL事件驱动过滤条件变化触发Filter Changed事件widgets/table.js配合 RunJS 的Query Success事件形成过滤 → 拼 SQL → 重新取数的完整链路。最终的效果是当用户在 Table 组件上应用一个或多个过滤器时查询在服务器端执行过滤作用于数据集的全部记录而非仅限前端已加载的数据——这正是大规模数据集场景下保持查询准确性与性能的关键所在。同理搜索Search、排序Sort、分页Pagination 等服务端操作也可参照本文的事件链模式进行编排。【免费下载链接】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），仅供参考