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 应用构建器中查询Query的“自定义参数Custom Parameters”能力展开讲解如何在查询面板中为查询定义可复用的变量、通过parameters.identifier语法在查询内部引用它们并借助事件系统在 REST API 成功后将响应数据动态注入 ToolJetDB 写入查询。读完本文你将掌握自定义参数的完整定义规则、作用域限制、UI 操作流程以及“数据源查询 事件联动 参数透传”的典型端到端实战方案并了解其底层前端实现原理。什么是查询自定义参数在 ToolJet 中查询Query是应用与数据交互的核心单元。当同一个查询需要在不同场景下携带不同输入例如不同用户、不同筛选条件、不同写入内容时直接修改查询本身的配置会破坏查询的复用性也会让维护变得困难。自定义参数Custom Parameters正是为了解决这一问题而设计它允许你在不修改查询主体逻辑的前提下为查询预先声明一组“占位变量”每个变量拥有一个名称Name和一个默认值Default value。查询执行时这些变量会以parameters.identifier的形式被求值并替换为实际传入的值。自定义参数的使用场景非常广泛在 ToolJetDB 中通过参数决定Create Row/Update Rows写入的字段值在 REST API 查询中通过参数动态拼接请求头、请求体或查询字符串在 RunJS / RunPy 代码中通过参数传入外部数据让同一段脚本以不同输入运行配合事件Events系统把上游查询的响应结果作为下游查询的参数值实现查询链式联动。该能力在官方查询面板文档中也有入口说明可参考 docs/docs/app-builder/query-panel.md 中 “Custom Parameters” 一节“Custom parameters provide a convenient method for passing variables to a query.”添加自定义参数操作步骤打开查询面板Query Panel选中你要添加自定义参数的查询在查询编辑器的顶部工具栏中找到Parameters区域点击或 Add按钮添加一个自定义参数为每个参数填写两项信息Name名称参数的唯一标识符用于在查询中引用Default value默认值一个常量字符串、数字或对象。命名规则与默认值约束源码依据从前端实现可以确认上述 UI 行为的细节约束。参数列表由 ParameterList.jsx 渲染每个参数项支持点击编辑改名、改默认值和删除新增、编辑表单由 ParameterForm.jsx 承载其中包含两条重要的校验规则命名必须是合法变量名源码使用正则/^[a-zA-Z_$][a-zA-Z0-9_$]*$/校验即名称只能以字母、下划线或$开头后续可包含字母、数字、下划线、$否则会提示Variable name invalid名称不可重复如果新名称与当前查询中已有参数同名otherParams.some((param) param.name name.trim())会提示Variable name exists并阻止提交。此外默认值输入框上方的信息提示Tooltip明确说明“Exposed values such as components, queries, globals etc are not supported in this field. Please use constant strings, numbers or objects.”——即默认值字段不支持组件、查询、全局变量等动态暴露值只能填写常量字符串、数字或对象。需要动态数据时应在引用位置查询字段本身使用{{ }}表达式而不是在参数默认值里塞表达式。从状态管理看参数被持久化在查询的options.parameters数组中。在 QueryManagerBody.jsx 中handleAddParameter、handleParameterChange、handleParameterRemove分别对应新增、编辑、删除三个动作均对options.parameters做不可变更新后写回查询配置同一文件还显示 Parameters 区域的渲染条件runjs、runpy、tooljetdb以及非默认类型的restapi查询均支持自定义参数。引用语法与作用域定义好参数后在查询中使用如下语法引用parameters.identifier例如定义了一个名为name的参数则查询中应书写parameters.name。需要注意参数只能在其被定义的查询内部使用不能跨查询引用这与查询间的数据传递方式不同——跨查询传递数据应使用queries.queryName引用或事件参数透传在查询配置中需要结合 ToolJet 的双大括号求值语法使用例如{{parameters.name}}让 ToolJet 在执行前对表达式求值。示例一使用自定义参数在 ToolJetDB 中创建行假设我们有一个 ToolJetDB 表包含以下列name、email和contact。下面使用自定义参数向表中写入一条新记录。第 1 步创建 ToolJetDB 查询新建一个 ToolJetDB 查询从数据源下拉框中选择目标表操作类型选择Create Row创建行。第 2 步添加自定义参数在 Parameters 区域添加以下三个参数参数 Name参数 Value默认值nameShubhemailshubhemail.comcontact4638563845第 3 步为查询列绑定参数将查询的列Column与对应参数绑定ColumnValuename{{parameters.name}}email{{parameters.email}}contact{{parameters.contact}}第 4 步执行查询点击执行Run按钮查询将以参数的值写入一行新记录到 ToolJetDB 表中。由于参数值是可以复用的变量后续只要修改参数默认值或在事件/其他调用处传入新值即可在不改动查询结构的情况下写入不同内容。示例二通过事件为查询提供参数值更强大的用法是让参数值来自事件运行时。下面的例子展示执行一个 REST API 查询在其成功onSuccess事件中触发一个 ToolJetDB 的 Create Row 查询并把 REST API 响应中的字段作为参数传入。第 1 步创建 REST API 查询新建一个 REST API 查询配置如下Method方法GETURLhttps://reqres.in/api/users?page2第 2 步添加成功事件为该 REST API 查询添加一个成功事件Success Event配置如下Name事件名onSuccessAction动作Run Query运行查询Query选择前面创建的Create Row查询Parameters你为Create Row查询添加的参数会自动出现在事件配置中逐一赋值即可| 参数名 | 值 | | ------ | -- | | name |{{queries.getSalesData.data.data[0].name}}—— 取响应数据第一条记录的name字段 | | email |{{queries.getSalesData.data.data[0].email}}—— 取响应数据第一条记录的email字段 | | contact |4638563845—— 演示用常量值 |第 3 步执行并观察结果运行 REST API 查询后观察 ToolJetDB 表——成功事件会触发 Create Row 查询使用事件中传入的参数值创建一条新记录。原理说明事件配置中“参数自动可用”的机制在前端有明确实现在 RunjsParamters.jsx 中事件处理器会从目标查询的options.parameters读取全部参数定义并逐一渲染输入框用户填写后写入事件对象的parameters字段const handleChange (value, param) { const newParams { ...event?.parameters, [param.name]: value }; handlerChanged(index, parameters, newParams); };也就是说参数定义在查询上一次性声明参数值在事件上每次触发可不同。这正是自定义参数能够实现“一个查询、多场景复用”的底层设计。在 RunJS / RunPy 查询中使用参数除了 ToolJetDB 与 REST APIJavaScript 查询RunJS同样支持自定义参数官方文档参见 docs/docs/data-sources/custom-js.md 的 “Parameters in Run JavaScript Code” 一节在 RunJS 查询编辑器中点击Parameters 按钮创建参数填写参数Name设置默认Value字符串、数字或对象在代码中使用parameters.name语法引用该参数。这样同一段 JavaScript 代码可以针对不同输入重复执行实现“代码不变、输入可变”的动态控制。例如创建一个名为newAlert的参数值为某个对象即可在代码中通过parameters.newAlert获取并展示。RunPy 查询的逻辑与之相同——参数声明与引用方式一致区别仅在于执行环境是 Python。注意事项与最佳实践基于文档说明与源码校验逻辑总结如下实践建议命名规范参数名必须是合法标识符/^[a-zA-Z_$][a-zA-Z0-9_$]*$/建议使用语义化的小驼峰命名如userName、pageSize便于在表达式中阅读默认值仅限常量默认值只支持常量字符串、数字或对象不要把组件引用、查询引用或全局变量写进默认值动态值一律在引用处通过{{ }}表达式传入作用域隔离参数只在定义它的查询内部有效。若需跨查询传值请使用事件参数如示例二或queries.queryName引用参数名唯一同一查询内参数名不可重复前端会在表单中直接拦截并提示Variable name exists结合事件实现链路将“参数声明”与“事件赋值”解耦让上游查询REST API / RunJS 等的成功或失败事件驱动下游查询并注入动态参数值这是构建多步骤数据流如“拉取数据 → 写入数据库”的推荐模式配合变换Transformation若需要对上游响应做二次加工再作为参数传入可在事件参数值中使用表达式或利用查询的 Transformation 阶段预处理数据使下游参数值更干净。延伸阅读docs/docs/app-builder/query-panel.md查询面板整体功能含 Custom Parameters 入口与预览、数据源切换等docs/docs/data-sources/custom-js.mdRunJS 查询中参数的使用与示例ParameterForm.jsx参数新增/编辑表单与命名校验实现ParameterList.jsx查询面板顶部 Parameters 列表渲染实现QueryManagerBody.jsx参数增删改的状态管理及支持参数的数据源类型判定RunjsParamters.jsx事件配置中参数自动渲染与赋值实现。【免费下载链接】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），仅供参考
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 应用构建器中查询Query的“自定义参数Custom Parameters”能力展开讲解如何在查询面板中为查询定义可复用的变量、通过parameters.identifier语法在查询内部引用它们并借助事件系统在 REST API 成功后将响应数据动态注入 ToolJetDB 写入查询。读完本文你将掌握自定义参数的完整定义规则、作用域限制、UI 操作流程以及“数据源查询 事件联动 参数透传”的典型端到端实战方案并了解其底层前端实现原理。什么是查询自定义参数在 ToolJet 中查询Query是应用与数据交互的核心单元。当同一个查询需要在不同场景下携带不同输入例如不同用户、不同筛选条件、不同写入内容时直接修改查询本身的配置会破坏查询的复用性也会让维护变得困难。自定义参数Custom Parameters正是为了解决这一问题而设计它允许你在不修改查询主体逻辑的前提下为查询预先声明一组“占位变量”每个变量拥有一个名称Name和一个默认值Default value。查询执行时这些变量会以parameters.identifier的形式被求值并替换为实际传入的值。自定义参数的使用场景非常广泛在 ToolJetDB 中通过参数决定Create Row/Update Rows写入的字段值在 REST API 查询中通过参数动态拼接请求头、请求体或查询字符串在 RunJS / RunPy 代码中通过参数传入外部数据让同一段脚本以不同输入运行配合事件Events系统把上游查询的响应结果作为下游查询的参数值实现查询链式联动。该能力在官方查询面板文档中也有入口说明可参考 docs/docs/app-builder/query-panel.md 中 “Custom Parameters” 一节“Custom parameters provide a convenient method for passing variables to a query.”添加自定义参数操作步骤打开查询面板Query Panel选中你要添加自定义参数的查询在查询编辑器的顶部工具栏中找到Parameters区域点击或 Add按钮添加一个自定义参数为每个参数填写两项信息Name名称参数的唯一标识符用于在查询中引用Default value默认值一个常量字符串、数字或对象。命名规则与默认值约束源码依据从前端实现可以确认上述 UI 行为的细节约束。参数列表由 ParameterList.jsx 渲染每个参数项支持点击编辑改名、改默认值和删除新增、编辑表单由 ParameterForm.jsx 承载其中包含两条重要的校验规则命名必须是合法变量名源码使用正则/^[a-zA-Z_$][a-zA-Z0-9_$]*$/校验即名称只能以字母、下划线或$开头后续可包含字母、数字、下划线、$否则会提示Variable name invalid名称不可重复如果新名称与当前查询中已有参数同名otherParams.some((param) param.name name.trim())会提示Variable name exists并阻止提交。此外默认值输入框上方的信息提示Tooltip明确说明“Exposed values such as components, queries, globals etc are not supported in this field. Please use constant strings, numbers or objects.”——即默认值字段不支持组件、查询、全局变量等动态暴露值只能填写常量字符串、数字或对象。需要动态数据时应在引用位置查询字段本身使用{{ }}表达式而不是在参数默认值里塞表达式。从状态管理看参数被持久化在查询的options.parameters数组中。在 QueryManagerBody.jsx 中handleAddParameter、handleParameterChange、handleParameterRemove分别对应新增、编辑、删除三个动作均对options.parameters做不可变更新后写回查询配置同一文件还显示 Parameters 区域的渲染条件runjs、runpy、tooljetdb以及非默认类型的restapi查询均支持自定义参数。引用语法与作用域定义好参数后在查询中使用如下语法引用parameters.identifier例如定义了一个名为name的参数则查询中应书写parameters.name。需要注意参数只能在其被定义的查询内部使用不能跨查询引用这与查询间的数据传递方式不同——跨查询传递数据应使用queries.queryName引用或事件参数透传在查询配置中需要结合 ToolJet 的双大括号求值语法使用例如{{parameters.name}}让 ToolJet 在执行前对表达式求值。示例一使用自定义参数在 ToolJetDB 中创建行假设我们有一个 ToolJetDB 表包含以下列name、email和contact。下面使用自定义参数向表中写入一条新记录。第 1 步创建 ToolJetDB 查询新建一个 ToolJetDB 查询从数据源下拉框中选择目标表操作类型选择Create Row创建行。第 2 步添加自定义参数在 Parameters 区域添加以下三个参数参数 Name参数 Value默认值nameShubhemailshubhemail.comcontact4638563845第 3 步为查询列绑定参数将查询的列Column与对应参数绑定ColumnValuename{{parameters.name}}email{{parameters.email}}contact{{parameters.contact}}第 4 步执行查询点击执行Run按钮查询将以参数的值写入一行新记录到 ToolJetDB 表中。由于参数值是可以复用的变量后续只要修改参数默认值或在事件/其他调用处传入新值即可在不改动查询结构的情况下写入不同内容。示例二通过事件为查询提供参数值更强大的用法是让参数值来自事件运行时。下面的例子展示执行一个 REST API 查询在其成功onSuccess事件中触发一个 ToolJetDB 的 Create Row 查询并把 REST API 响应中的字段作为参数传入。第 1 步创建 REST API 查询新建一个 REST API 查询配置如下Method方法GETURLhttps://reqres.in/api/users?page2第 2 步添加成功事件为该 REST API 查询添加一个成功事件Success Event配置如下Name事件名onSuccessAction动作Run Query运行查询Query选择前面创建的Create Row查询Parameters你为Create Row查询添加的参数会自动出现在事件配置中逐一赋值即可| 参数名 | 值 | | ------ | -- | | name |{{queries.getSalesData.data.data[0].name}}—— 取响应数据第一条记录的name字段 | | email |{{queries.getSalesData.data.data[0].email}}—— 取响应数据第一条记录的email字段 | | contact |4638563845—— 演示用常量值 |第 3 步执行并观察结果运行 REST API 查询后观察 ToolJetDB 表——成功事件会触发 Create Row 查询使用事件中传入的参数值创建一条新记录。原理说明事件配置中“参数自动可用”的机制在前端有明确实现在 RunjsParamters.jsx 中事件处理器会从目标查询的options.parameters读取全部参数定义并逐一渲染输入框用户填写后写入事件对象的parameters字段const handleChange (value, param) { const newParams { ...event?.parameters, [param.name]: value }; handlerChanged(index, parameters, newParams); };也就是说参数定义在查询上一次性声明参数值在事件上每次触发可不同。这正是自定义参数能够实现“一个查询、多场景复用”的底层设计。在 RunJS / RunPy 查询中使用参数除了 ToolJetDB 与 REST APIJavaScript 查询RunJS同样支持自定义参数官方文档参见 docs/docs/data-sources/custom-js.md 的 “Parameters in Run JavaScript Code” 一节在 RunJS 查询编辑器中点击Parameters 按钮创建参数填写参数Name设置默认Value字符串、数字或对象在代码中使用parameters.name语法引用该参数。这样同一段 JavaScript 代码可以针对不同输入重复执行实现“代码不变、输入可变”的动态控制。例如创建一个名为newAlert的参数值为某个对象即可在代码中通过parameters.newAlert获取并展示。RunPy 查询的逻辑与之相同——参数声明与引用方式一致区别仅在于执行环境是 Python。注意事项与最佳实践基于文档说明与源码校验逻辑总结如下实践建议命名规范参数名必须是合法标识符/^[a-zA-Z_$][a-zA-Z0-9_$]*$/建议使用语义化的小驼峰命名如userName、pageSize便于在表达式中阅读默认值仅限常量默认值只支持常量字符串、数字或对象不要把组件引用、查询引用或全局变量写进默认值动态值一律在引用处通过{{ }}表达式传入作用域隔离参数只在定义它的查询内部有效。若需跨查询传值请使用事件参数如示例二或queries.queryName引用参数名唯一同一查询内参数名不可重复前端会在表单中直接拦截并提示Variable name exists结合事件实现链路将“参数声明”与“事件赋值”解耦让上游查询REST API / RunJS 等的成功或失败事件驱动下游查询并注入动态参数值这是构建多步骤数据流如“拉取数据 → 写入数据库”的推荐模式配合变换Transformation若需要对上游响应做二次加工再作为参数传入可在事件参数值中使用表达式或利用查询的 Transformation 阶段预处理数据使下游参数值更干净。延伸阅读docs/docs/app-builder/query-panel.md查询面板整体功能含 Custom Parameters 入口与预览、数据源切换等docs/docs/data-sources/custom-js.mdRunJS 查询中参数的使用与示例ParameterForm.jsx参数新增/编辑表单与命名校验实现ParameterList.jsx查询面板顶部 Parameters 列表渲染实现QueryManagerBody.jsx参数增删改的状态管理及支持参数的数据源类型判定RunjsParamters.jsx事件配置中参数自动渲染与赋值实现。【免费下载链接】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），仅供参考
)
)
