ToolJet 查询面板（Query Panel）完全指南：从查询创建、参数传递到事件联动

ToolJet 查询面板Query Panel完全指南从查询创建、参数传递到事件联动【免费下载链接】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/ToolJetToolJet 的 Query Panel查询面板位于应用构建器底部是连接数据源与界面组件的核心枢纽你可以在这里创建 API 请求、查询数据库、执行 JavaScript/Python 数据处理并通过事件系统把查询结果与组件行为串联起来。本文将基于 ToolJet v3.0.0-LTS 的官方文档与仓库源码系统讲解查询面板的两大区域Query Manager 与 Query Editor、查询的排序过滤与增删改、自定义参数、预览/运行机制、查询配置、变换Transformations、设置项与事件处理器帮助你完整掌握在 ToolJet 中构建数据驱动应用的关键技能。查询面板的整体结构查询面板位于 App Builder应用构建器的底部用于创建和管理与已连接**数据源data sources**交互的查询。它提供了执行 API 请求、查询数据库、以及通过 JavaScript 和 Python 应用变换transformations或进行数据操作的能力。从界面布局看查询面板由两个部分构成左侧的Query Manager查询管理器显示应用中已创建的全部查询列表负责查询的集中管理右侧的Query Editor查询编辑器用于配置当前选中的查询包括数据源、操作类型、参数、变换、设置与事件等。从源码结构看这一左右布局在前端由QueryPanel.jsx组合两个 memo 化的子组件实现QueryPanel.jsx 中通过MemoizedQueryDataPane左侧查询列表与MemoizedQueryManager右侧编辑器共同渲染面板高度支持拖拽调节高度范围被限制在视口高度的 4.5%94% 之间且高度/展开状态会持久化到localStorage的queryManagerPreferences中下次打开编辑器时自动恢复。Query Manager查询的创建与管理Query Manager 位于左侧罗列了应用中已创建的全部查询。其顶部的按钮用于添加新查询点击后会弹出菜单列出可从当前已连接数据源创建查询的所有选项。添加数据源本身有两种途径一是在查询面板中直接添加二是从左侧边栏进入Data Sources页面统一管理详见数据源总览。查询的排序与过滤在 Query Manager 顶部有排序/过滤按钮支持以下选项Filter过滤By Data source按数据源过滤Sort排序Name: A-Z按名称升序Name: Z-A按名称降序Type: A-Z按类型升序Type: Z-A按类型降序Last modified: oldest first最近修改最旧在前Last modified: newest first最近修改最新在前在排序/过滤按钮旁是搜索框可用于快速定位特定查询。源码层面排序与过滤逻辑集中在 FilterandSortPopup.jsx过滤面板会聚合当前查询实际引用到的数据源包括已连接数据源、全局数据源与示例数据源对于 runjs/runpy 这类无真实数据源 ID 的查询则归入静态数据源支持多选并显示选中数量角标排序选项则对应sortBycustom/name/kind/updated_at与sortOrderasc/desc的组合。搜索功能在 QueryDataPane.jsx 中使用 Fuse.js 模糊匹配查询名称threshold: 0.3支持输入部分名称即可命中。编辑、复制与删除查询将鼠标悬停在查询名称上会显示edit编辑、copy复制和 delete删除三个按钮编辑重命名当前查询复制复制duplicate当前选中的查询生成一个副本删除删除选中的查询。这些操作在前端由 QueryCardMenu.jsx 的菜单项驱动分别调用renameQuery、duplicateQuery与deleteDataQuery等 store 方法。Query Editor查询的配置与执行Query Editor 提供两种构建查询的方式通过低代码界面配置或手动输入查询文本。注意查询面板中的所有修改都会自动保存。这一自动保存特性在源码中有明确实现QueryPanel.jsx 订阅了 store 中queryPanel.selectedQuery的变化使用deep-object-diff对比前后查询对象排除后端维护的updated_at字段只要内容发生变化且不是单纯的重命名就会调用dataQuery.saveData(selectedQuery)持久化——重命名则交给独立的renameQuery流程处理避免重复保存。查询名称除了查询编辑器本身查询名称显示在查询面板顶部。点击名称即可进入编辑状态按需自定义查询名。查询名是应用内引用该查询结果的标识符例如组件属性中通过{{queries.queryName.data}}引用查询返回的数据。自定义参数Custom Parameters自定义参数提供了一种向查询传递变量的便捷方式。点击查询编辑器中 Parameters 标签旁的 Add按钮即可添加参数。每个参数需要指定Name参数的标识符Default value默认值可以是常量字符串、数字或对象。使用参数的语法在查询中使用parameters.identifier引用参数。需要注意参数只能在其被定义的查询内部使用无法跨查询访问。参数的解析机制在 queryPanelSlice.js 的runQuery中当调用方未显式传入参数时运行时会遍历dataQuery.options.parameters将每个参数的defaultValue通过resolveReferences解析后组装为参数对象与查询执行上下文getAllExposedValues暴露的组件、全局变量、变量等合并后参与查询体求值。同理QueryManager.jsx 在渲染编辑器时也会把参数解析后注入CodeHinterContext使代码提示Code Hinter能感知到parameters.xxx的存在。详细的参数实战教程含 ToolJetDB 创建行、通过事件传参等完整示例可参考使用自定义参数指南。在 Run JavaScript Code 中参数还支持跨查询传值例如在另一个 RunJS 查询中用queries.multiply.run({num1: 20, num2: 7})以自定义参数触发目标查询实现同一查询的多输入复用。预览PreviewPreview按钮用于预览查询返回的数据结果展示在查询面板底部的预览区域。该功能用于查询调试不会在应用中真正触发查询不会改动应用状态。数据预览支持Raw和JSON两种展示格式点击清空clear按钮可重置预览数据。从实现看预览走的是runQuery(..., shouldSetPreviewData true)路径运行前会展开预览面板并置 loading 状态结果返回后通过setPreviewData(finalData)写入预览区见 queryPanelSlice.js 的processQueryResults预览面板组件 Preview.jsx 会根据数据类型对象或原始值自动切换 JSON/字符串展示。运行RunRun按钮会真正触发查询使其与数据源交互并影响应用状态。这与Preview有本质区别通过 Run 触发查询行为等同于由应用内事件如按钮点击触发查询结果会写入queries暴露对象从而驱动绑定该查询数据的组件更新。这与变换教程中的说明一致使用 Run 按钮运行的查询会改变应用状态可通过左侧边栏的状态检查器State Inspector查看结果。查询配置Query ConfigurationQuery Configuration 用于设置从数据库生成响应所必需的关键值主要包括Data source数据源名称Operation要执行的操作类型例如List collections、Find one、Find many等。具体可用的配置项集合取决于数据源类型。例如 MongoDB 数据源会提供集合查询相关操作而 REST API 数据源则提供 Method、URL、Headers、Body 等 HTTP 配置。数据源Data Source数据源是所有查询的首要且默认的参数用于为查询选择合适的数据源。当连接了多个同类型数据源时可以通过下拉菜单轻松切换查询使用的数据源——这一点在数据源总览中也有说明在查询内部可以选择同一数据源类型下的不同连接。变换Transformation查询可以启用变换来修改查询结果。ToolJet 支持两种编程语言的变换JavaScript与Python。变换的两种语言示例假设查询返回了包含name字段的客户数据需拆出first_name和last_nameJavaScript// 返回值会被设置为 data原始数据在 rawData 中可用 return data.map((row) { return { ...row, first_name: row.name.split( )[0], last_name: row.name.split( )[1], }; });Pythonreturn list(map(lambda row: { **row, first_name: row[name].split( )[0], last_name: row[name].split( )[1], }, data))Python 变换中还支持引用 ToolJet 的全局变量例如给每条记录追加当前登录用户邮箱return list(map(lambda item: {**item, user: f{globals[currentUser][email]}}, data))变换后的数据同样可以通过预览查看原始数据始终保留在查询的rawData对象中。完整的变换说明与示例见变换TransformationsPython 侧的更多变换场景提取标题、按分类过滤、计算平均价格等见 Run Python Code 文档。从源码看变换由 Transformation.jsx 组件管理默认语言为javascript通过开关切换enableTransformation编辑器内提供 JavaScript/Python 双 Tab切换语言时写入transformationLanguage代码内容分别存入transformations.javascript/transformations.python。实际执行时queryPanelSlice.js 的processQueryResults检测到enableTransformation为真后调用runTransformation按所选语言执行变换代码并将返回值替换为查询的data若变换执行失败status failed则进入失败处理流程。设置Settings查询设置包含以下选项Run this query on application load?应用加载时运行此查询启用后每次应用加载都会执行该查询。源码中runQuery的isOnLoad参数即为此服务Request confirmation before running the query?运行前请求确认启用后运行查询前会弹出确认模态框要求选择Yes或No。对应实现中requestConfirmation解析为真时会把查询加入queryConfirmationList等待用户确认且支持自定义确认提示文案confirmationMessage见 queryPanelSlice.jsShow notification on success?成功时显示通知启用后查询成功触发时会显示成功 toast 通知并可自定义成功消息success message与通知时长秒。源码中默认时长为 5000msnotificationDuration * 1000 || 5000成功消息通过toast.success弹出。事件Events可以为查询添加事件处理器支持的事件有Query Success查询成功Query Failure查询失败事件处理器将动作与查询结果串联让应用运行更流畅。文档给出的示例场景如下场景你有两个查询——getTodos获取待办事项列表deleteTodos删除某个待办项事件处理器在deleteTodos上添加Query Success事件删除成功后运行getTodos。结果用户删除一个待办项事件处理器刷新待办列表展示待办数据的组件会更新为最新数据。事件处理器的更多说明包括条件执行等高级用法见组件事件处理器。在源码中runQuery会收集target data_query sourceId queryId的查询事件查询完成后根据成功/失败状态分发对应事件onEvent从而实现删除后自动刷新列表这类联动。总结查询面板是 ToolJet 应用构建中数据接入的核心入口左侧 Query Manager 负责查询的组织与检索排序、过滤、模糊搜索、重命名、复制、删除右侧 Query Editor 则承载查询的完整生命周期——从数据源与操作选择、自定义参数定义、变换编写到预览调试、正式运行、运行设置与成功/失败事件联动。理解这些能力并善用parameters.name传参、JavaScript/Python 变换与 Query Success/Failure 事件可以让你构建出数据链路清晰、组件联动顺畅的 ToolJet 应用。进一步阅读数据源总览 · 变换 Transformations · 使用自定义参数 · Run JavaScript Code · Run Python Code【免费下载链接】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），仅供参考