ToolJet Table 组件服务端搜索Server Side Search完整指南从 SQL 查询到事件链路【免费下载链接】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 Search。与客户端搜索不同服务端搜索把搜索条件交给数据库在服务器端执行搜索范围覆盖整个数据集而非仅当前已加载的行适用于数据量大、需要保证数据一致性与安全性的场景。读完本文你将掌握如何搭建基础查询与 Table 数据绑定、如何启用服务端搜索属性、如何编写带searchText变量的 SQL、如何用 Search 事件驱动查询执行以及如何通过 Loading State 提升交互体验。服务端搜索与客户端搜索的区别在开始配置之前先明确两者的边界。ToolJet 官方文档serverside-operations/overview.md对服务端操作server side operations与客户端操作client side operations做了如下界定服务端操作数据获取、过滤、排序、分页等任务在服务器数据库上执行充分利用服务器资源适合大数据集加载更快、扩展性更好同时有利于数据安全与完整性。客户端操作所有数据先一次性拉到浏览器再在本地完成过滤与排序。交互实时性高、服务器负载低但数据集较大时首屏加载与本地处理都会出现性能瓶颈。因此当你的表需要承载大型数据集、涉及复杂业务逻辑或对数据安全有要求时应优先考虑服务端操作ToolJet 的 Table 组件围绕搜索、排序、过滤、分页四类操作提供了完整的服务端支持详见 serverside-operations 目录。从源码看Table 组件的配置定义位于 frontend/src/AppBuilder/WidgetManager/widgets/table.js其中serverSideSearch属性被定义为clientServerSwitch类型即在 Client side 与 Server side 之间二选一serverSideSearch: { type: clientServerSwitch, displayName: Type, options: [ { displayName: Client side, value: clientSide }, { displayName: Server side, value: serverSide }, ], validation: { schema: { type: boolean }, defaultValue: false, }, },defaultValue: false表示默认使用客户端搜索切换为Server side后Table 内部将停止对已加载数据的本地过滤转而依赖暴露出的searchText变量把搜索词交给查询去处理。准备工作添加 Table 组件并绑定数据实现服务端搜索前先把 Table 组件放到画布并让它有数据可显示拖入组件从右侧组件库中把Table组件拖到画布上。创建数据查询点击底部的查询面板Query Panel选择一个数据源并新建查询。本指南使用 ToolJet 内置的示例数据源Postgres查询语句如下SELECT * FROM public.sample_data_orders LIMIT 100该查询即后续要配合搜索事件运行的getOrders查询的作用是从sample_data_orders表取回 100 行订单数据作为 Table 的初始数据源。仓库的示例应用模板 server/templates/sample_app_def.json 中同样内置了这条查询可以作为参考query: SELECT * FROM public.sample_data_orders\nLIMIT 100绑定 Data 属性选中 Table 组件在属性面板的Data属性中填入{{queries.getOrders.data}}getOrders换成你的实际查询名让表格展示查询返回的数据。完成这三步后Table 会渲染出 100 行示例订单数据接下来就可以配置服务端搜索。启用服务端搜索属性在属性面板中执行以下操作找到 Table 组件属性中的Server side Search位于 Search、Sort And Filter 相关分组内将该属性切换为Server side默认是 Client side。此时Table 组件不会再对已加载的 100 行数据做本地过滤搜索行为完全交由你在查询中实现的 SQL 逻辑负责。从源码层面看服务端搜索的开关在 frontend/src/AppBuilder/Widgets/NewTable/_components/TableContainer/TableContainer.jsx 中通过useTableStore读取const serverSideSearch useTableStore((state) state.getTableProperties(id)?.serverSideSearch, shallow);该值随后被传入useTable与列构建逻辑同时TableContainer.jsx 中有一段关键逻辑——当服务端搜索开启且搜索词非空时自动把分页重置到第一页useEffect(() { if (serverSideSearch globalFilter?.trim() ! ) { setPagination((prev) ({ ...prev, pageIndex: 0 })); } }, [globalFilter, serverSideSearch, setPagination]);这意味着每次发起新的搜索结果都会从第 1 页开始展示避免停留在旧搜索结果的页码上。属性面板中该开关的显示条件在 frontend/src/AppBuilder/RightSideBar/Inspector/Components/Table/Table.jsx 中由displaySearchBox推导保证只有启用搜索框时才展示该配置项。编写服务端搜索查询searchText 变量的用法启用服务端搜索后编辑刚才的查询把搜索条件写进 SQL。ToolJet 会把用户在 Table 搜索框中输入的内容实时暴露为组件变量{{components.table1.searchText}}table1换成你的 Table 组件名因此 SQL 可以这样写SELECT * FROM public.sample_data_orders WHERE city ILIKE %{{components.table1.searchText}}% OR country ILIKE %{{components.table1.searchText}}% OR state ILIKE %{{components.table1.searchText}}% LIMIT 100该查询在数据库端对city、country、state三个文本列做ILIKE模糊匹配从而在整个数据集上完成搜索而不是只搜索当前页的 100 行数据。要点如下ILIKE是 PostgreSQL 的大小写不敏感模糊匹配操作符配合%...%通配符实现包含式匹配{{components.table1.searchText}}中的table1必须替换为你实际的 Table 组件名用OR连接多个列即可扩展搜索范围例如再加customer_name、order_id等列保留LIMIT 100防止全表扫描结果过大配合分页使用效果更佳。searchText变量的来源可以从源码得到印证Table 组件的暴露变量定义在 frontend/src/AppBuilder/WidgetManager/widgets/table.js其中包含searchText: 这一初始值。在运行时TableExposedVariables.jsx 将搜索框的globalFilter状态同步为暴露变量// Expose search text useEffect(() { setExposedVariables({ searchText }); mounted fireEvent(onSearch); }, [searchText, setExposedVariables, fireEvent]);也就是说用户在搜索框每输入一个字符searchText都会更新并同时触发onSearch事件——这正是下一步要挂接事件处理器的原因。挂接事件处理器Search 事件 → Run Query仅有 SQL 还不够还需要让 Table 组件在每次搜索时主动执行该查询。做法是给 Table 组件添加一个事件处理器Event HandlerEvent事件SearchAction动作Run QueryQuery查询选择你编写了搜索 SQL 的那个查询如getOrders配置完成后每当用户在搜索框中输入内容searchText变化就会触发Search事件 → 执行Run Query动作 → 重新运行查询并携带最新的searchText参数 → 查询返回过滤后的数据并刷新 Table。这条链路在源码中的闭环如下用户在搜索框输入更新globalFilterTableExposedVariables.jsx 同步searchText暴露变量并调用fireEvent(onSearch)触发 Search 事件事件处理器执行 Run Query查询中的{{components.table1.searchText}}取到最新搜索词数据库执行带ILIKE条件的 SQL返回过滤结果Table 重新渲染同时如已开启分页重置到第 1 页。关于onSearch事件与fireEvent的调用还可参考 TableContainer 中buildTableColumn的调用buildTableColumn.js搜索框的globalFilter状态贯穿了列构建与事件触发全流程。添加 Loading State优化搜索反馈搜索是异步操作查询执行期间需要给用户明确的加载反馈。配置步骤如下打开 Table 组件属性面板中的Additional Actions附加操作区域点击Loading State旁边的fx图标在表达式输入框中填入{{queries.getOrders.isLoading}}getOrders替换为你的查询名。{{queries.getOrders.isLoading}}是查询的运行状态标志查询执行期间为true、执行结束后为false。绑定到 Loading State 后表格会在查询进行时显示加载指示器避免用户误以为搜索无响应。Table 组件的isLoading暴露变量同样定义在 table.js 的exposedVariables中初始值false属性面板中的loadingState属性默认值也为false。完整实现链路回顾至此ToolJet Table 组件的服务端搜索已完整实现。把整个流程串起来数据准备Table 组件绑定{{queries.getOrders.data}}初始展示 100 行订单数据开启服务端模式属性面板中把 Server side Search 切换为 Server side编写服务端 SQL用WHERE city/country/state ILIKE %{{components.table1.searchText}}%在数据库端完成全量数据搜索事件驱动刷新Search 事件 → Run Query 动作每次搜索自动重跑查询加载反馈Loading State 绑定{{queries.getOrders.isLoading}}查询期间显示加载状态。现在当用户在 Table 搜索框中输入内容时查询会在服务器端执行搜索范围覆盖整个数据集而非仅当前加载行这正是服务端搜索的核心价值。若要进一步优化可结合服务端排序sort.md、服务端过滤filter.md与服务端分页pagination.md构成完整的服务端操作体系相关实现均可在 frontend/src/AppBuilder/WidgetManager/widgets/table.js 的serverSidePagination、serverSideSort、serverSideFilter配置定义中看到它们的并列关系。【免费下载链接】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），仅供参考