ToolJet 查询自定义参数（Custom Parameters）使用指南：从添加、语法到事件驱动传参实战

ToolJet 查询自定义参数Custom Parameters使用指南从添加、语法到事件驱动传参实战【免费下载链接】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 查询面板提供的变量机制让你可以在不改动查询本身内容的前提下把易变的值常量字符串、数字、对象抽离出来按需替换。本文基于 ToolJet 2.50.0-LTS 版本的官方文档与前端源码完整讲解自定义参数的添加方式、parameters.identifier调用语法、作用域限制并结合 ToolJetDB 建行、事件驱动传参、RunJS 跨查询调用等真实场景给出可复制的实战步骤帮助你在内部工具与仪表盘开发中写出更灵活、更易维护的查询。一、什么是查询自定义参数在 ToolJet 的查询面板Query Panel中每个查询除了本身的请求体、SQL 语句或代码外还带有一个独立的Parameters参数区域。在这里声明的参数相当于为该查询预定义的变量占位符使用时只需在查询内容里以parameters.name的形式引用即可在不修改查询主体的情况下注入不同输入。这套机制的核心价值在于复用同一查询同一份 ToolJetDB 操作、REST API 请求或 RunJS 代码可以通过传入不同参数值执行多次无需复制查询解耦易变数据诸如用户输入、接口响应字段、常量配置等不再硬编码进查询内容而是收敛到参数区统一管理支持事件驱动传参当查询由按钮点击、其他查询成功等事件触发时可以在事件处理器中为参数动态赋值实现查询间的数据流转。需要说明的是参数默认值只支持常量字符串、数字或对象对象即 JSON 字面量这一点在前端源码中有明确约束。前端参数表单 ParameterForm.jsx 中Value 字段的 Tooltip 明确提示Exposed values such as components, queries, globals etc are not supported in this field. Please use constant strings, numbers or objects.也就是说组件值、查询结果、全局变量这类运行时暴露值不能直接写进默认值字段动态值应通过事件传参或查询内部表达式如{{parameters.x}}与组件引用组合来注入。二、添加自定义参数2.1 操作步骤打开底部查询面板选中你要添加参数的目标查询在查询编辑器顶部工具栏找到Parameters区域点击Add按钮新增一个参数为每个参数填写两项内容Name名称参数的标识符在查询中以parameters.name引用Default value默认值常量字符串、数字或对象。2.2 名称与默认值的源码级约束在底层实现中参数表单 ParameterForm.jsx 对名称做了两重校验合法标识符校验名称必须匹配正则/^[a-zA-Z_$][a-zA-Z0-9_$]*$/即以字母、下划线或$开头后续只能包含字母、数字、下划线、$否则提示Variable name invalid。这保证了parameters.xxx在 JS 表达式求值中是一个合法的变量路径重名校验同一查询内不允许存在重名参数提示Variable name exists且校验是实时的输入非法名称时表单不会提交。已添加的参数在顶部栏以胶囊pill形式展示点击可编辑点击胶囊右侧的移除按钮可删除当参数过多超出容器宽度时多余参数会收进N弹出层中展示见 ParameterList.jsx 的宽度计算逻辑。三、调用语法与作用域在查询内容中使用自定义参数的语法为parameters.identifier例如在 SQL 查询中SELECT * FROM allUsers WHERE id {{parameters.id}}在 RunJS 代码中return parameters.num1 * parameters.num2;作用域限制参数只能在其被定义的同一个查询内使用不能跨查询引用其他查询的参数。跨查询传递参数的正确做法有两种通过事件在触发时给目标查询的参数赋值见第五节通过queries.queryName.run({ 参数名: 值 })在代码中调用目标查询并传参见第六节。参数的解析发生在查询执行阶段。在查询执行切片 queryPanelSlice.js 中可以看到当本次执行没有外部传入参数时前端会遍历dataQuery.options?.parameters对每个参数的defaultValue调用resolveReferences(parameter.defaultValue, undefined)进行表达式解析组装成{ [parameter.name]: value }形式的参数对象再与当前应用状态合并为queryState用于后续查询变量getQueryVariables与表达式如{{parameters.x}}的求值。四、示例一在 ToolJetDB 中使用自定义参数创建行假设我们有一张 ToolJetDB 表包含name、email、contact三列下面用自定义参数向表中插入一行。第 1 步创建查询并选择操作新建一个 ToolJetDB 查询在下拉框中选中目标表操作类型选择Create Row创建行。第 2 步添加参数在查询顶部工具栏的 Parameters 区域依次添加三个参数NameDefault valuenameShubhemailshubhemail.comcontact4638563845第 3 步在列值中使用参数在 Create Row 的列映射中把各列的值填为对应参数引用ColumnValuename{{parameters.name}}email{{parameters.email}}contact{{parameters.contact}}第 4 步执行查询点击Run执行ToolJetDB 中即会新增一行三个字段的值分别来自name、email、contact三个参数。之后只需修改参数区的默认值或在事件中传入新值无需改动列映射即可插入不同数据。五、示例二通过事件为查询提供自定义参数自定义参数最常见的动态用法是在事件处理器中把前一个查询的响应数据注入到后续查询的参数里。下面演示执行一个 REST API 查询成功onSuccess后自动执行 ToolJetDB 的 Create Row 查询用接口响应数据建行。第 1 步创建 REST API 查询方法MethodGETURLhttps://reqres.in/api/users?page2第 2 步为 REST API 查询添加 onSuccess 事件在查询的Events中新增事件事件名称NameonSuccess动作ActionRun Query目标查询QueryCreate Row即上一节创建的 ToolJetDB 查询此时Create Row 查询中已添加的参数会自动出现在事件处理器的参数配置区为它们分别赋值name{{queries.getSalesData.data.data[0].name}}—— 取 REST 响应数据中第一条记录的name字段email{{queries.getSalesData.data.data[0].email}}—— 取第一条记录的email字段contact4638563845—— 演示用常量值。第 3 步触发并观察结果执行 REST API 查询成功回调触发 Create Row 查询ToolJetDB 表中即出现一条由接口数据与常量组合而成的新记录。从源码角度看事件处理器在执行Run Query动作时会读取目标查询query?.options?.parameters将其规约为{ 参数名: 表达式 }的映射并随事件下发见 EventManager.jsx随后查询执行流程收到这份userSuppliedParameters在 queryPanelSlice.js 中优先采用事件传入的参数值仅在未传入时才回退到默认值从而实现了事件驱动覆盖默认值的效果。六、在 RunJS 查询中使用参数含跨查询传参自定义参数同样适用于Run JavaScript Code查询详见 RunJS 文档。每个参数同样只需 Name 与默认值代码内以parameters.name引用。示例alert 展示参数值alert(parameters.newAlert)示例调用其他查询并传递参数创建 RunJS 查询multiply添加参数num1 10、num2 2代码如下return parameters.num1 * parameters.num2;创建另一个 RunJS 查询callMultiply代码中调用multiply并传入自定义参数值queries.multiply.run({num1: 20, num2: 7})执行callMultiply后multiply查询会以num120、num27执行并返回140。这正是同一查询、不同输入复用模式在 RunJS 中的体现其底层由executeMultilineJS接收参数对象并在执行时把参数合入上下文供代码访问见 queryPanelSlice.js。七、最佳实践与注意事项默认值保持简单默认值只接受常量字符串、数字、对象组件值、查询数据、全局变量请放在查询表达式或事件传参中注入避免依赖不成立的默认值。命名遵循 JS 标识符规范使用camelCase命名参数如minimumVotes、newAlert避免空格与特殊字符便于在表达式与代码中直接引用。参数作用域是查询级的不要把参数设计为跨查询共享需要共享的数据优先通过事件或queries.x.run({...})显式传递。与查询变量的配合自定义参数是变量声明查询内的{{parameters.x}}是变量引用两者配合使用才能生效。SQL 场景下可在 WHERE 子句中引用参数实现条件过滤例如 创建查询文档 中的SELECT * FROM allUsers WHERE id {{parameters.id}}。事件驱动是动态传参的主路径当参数值来自接口响应或组件状态时优先在事件的 Run Query 动作中赋值执行优先级高于默认值源码中userSuppliedParameters优先于options.parameters默认值解析。八、相关资源查询面板整体说明app-builder/query-panel.md参数 UI 实现ParameterList.jsx、ParameterForm.jsx、ParameterDetails.jsx参数解析与执行逻辑queryPanelSlice.jsRunJS 参数用法data-sources/custom-js.md查询创建与 SQL 参数示例app-builder/walkthrough/create-queries.md掌握自定义参数后你的查询将摆脱一处改动处处复制的困境静态常量收敛到参数区动态值通过事件注入同一查询可被任意场景复用——这正是低代码构建中保持应用可维护性的关键实践。【免费下载链接】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），仅供参考