ToolJet 动态表单构建指南基于验证与条件实现智能交互表单【免费下载链接】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 应用构建器App Builder为背景讲解如何仅通过组件属性面板中的验证Validation与条件Condition配置快速构建具备动态显隐、实时校验和联动禁用能力的交互式表单。你将掌握 Form 组件与输入类组件Star Rating、Text Input、Number Input、Button的组合用法、fx表达式与正则校验的编写方式以及components.form1.children.*组件引用链和isValid暴露变量的底层工作机制并可直接在 ToolJet 画布上复现本教程的完整示例。1. 创建表单 UI在 ToolJet 应用构建器中从左侧组件库将Form组件拖拽到画布再在其内部放入以下输入组件并按下表设置各组件名称Component Name与标签Label组件Component组件名称Component Name标签LabelStar Ratingstarrating1How satisfied are you with our service?Text Inputtextinput1What specific issues did you encounter?Text Inputtextinput2EmailNumber Inputnumberinput1ContactButtonbutton1Submit组件名称是后续所有联动表达式的基础——ToolJet 通过components.formName.children.componentName的引用链访问表单内部任意子组件及其暴露变量因此建议为每个组件设置语义化、易记忆的名称例如本示例中的starrating1、textinput1等。放置完成后画布上的表单即具备上图所示的结构一个满意度星级评分、一个问题描述输入框、一个邮箱输入框、一个联系方式数字输入框以及一个提交按钮。2. 添加验证与条件本教程的核心在于通过组件属性面板中的三类配置——可见性条件Visibility、自定义验证Custom Validation与必填开关Make this field mandatory让表单具备“智能响应”能力。2.1 基于星级评分的动态显隐Visibility 条件选中textinput1问题描述输入框在右侧属性面板中找到Visibility可见性属性点击其旁的fx图标切换到表达式编辑模式输入以下代码{{components.form1.children.starrating1.value4}}该表达式的作用是当 Star Rating 组件starrating1的当前值value小于 4 时表达式结果为truetextinput1显示当评分达到 4 或 5 时表达式结果为falsetextinput1自动隐藏。这样便实现了“低评分时才追问具体问题”的动态表单逻辑。2.2 邮箱格式的自定义验证Custom Validation选中textinput2邮箱输入框在属性面板中找到Custom Validation自定义验证属性点击fx并输入以下正则表达式校验代码{{/^[a-zA-Z0-9._%-][a-zA-Z0-9.-]\.[a-zA-Z]{2,}$/.test(components.form1.children.textinput2.value) ? : Invalid email}}这段表达式使用 JavaScript 正则字面量对邮箱输入做格式测试^[a-zA-Z0-9._%-]匹配邮箱本地部分后跟[a-zA-Z0-9.-]匹配域名\.[a-zA-Z]{2,}$要求顶级域名至少两位字母。当test()返回true格式合法时表达式返回空字符串表示无错误否则返回提示文本Invalid email该文本会直接显示在输入框下方作为校验错误信息。自定义验证采用“返回空字符串即通过、返回非空字符串即错误提示”的约定因此你可以用任意 JavaScript 表达式组合出更复杂的校验规则例如长度限制、自定义域名白名单等。2.3 必填字段校验Make this field mandatory选中numberinput1联系方式数字输入框在属性面板中打开Make this field mandatory设为必填字段开关。开启后当该组件被留空时表单会显示必填校验错误提示用户补充该字段。从源码实现看必填校验是输入类组件验证体系的一部分在 frontend/src/AppBuilder/Widgets/BaseComponents/hooks/useInput.js 中isMandatory validation?.mandatory ?? false决定了组件是否要求非空而每一次值变更都会调用validate函数重新计算校验状态并通过setExposedVariable(isValid, validationStatus?.isValid)将结果同步到组件的isValid暴露变量供外部表达式引用。2.4 基于整体校验结果禁用提交按钮最后让button1提交按钮在邮箱格式非法、星级未评分或联系方式为空时处于禁用状态。在按钮组件的Visibility可见性条件中点击fx输入{{!components.form1.children.textinput2.isValid || !components.form1.children.starrating1.value || !components.form1.children.numberinput1.value}}这里用逻辑或||组合三个校验条件任一条件为真true时整个表达式结果为true按钮即被禁用!components.form1.children.textinput2.isValid邮箱输入框的isValid暴露变量为false正则校验未通过时取反后为true!components.form1.children.starrating1.value星级评分值为空0或未选择时取反为true!components.form1.children.numberinput1.value联系方式为空时取反为true。只有当三项全部通过时表达式才为false按钮保持可用从而保证提交的数据完整有效。这正是 ToolJet “组件暴露变量 表达式引用” 联动机制的典型用法isValid是输入类组件Text Input、Number Input 等通过 useInput.js 暴露出的实时校验结果任何属性可见性、禁用、文本内容等都能通过fx表达式读取它。3. 测试表单功能配置完成后进入预览模式按以下步骤验证各项联动是否按预期工作。3.1 验证星级评分驱动的显隐逻辑当 Star Rating 的评分低于 4 时textinput1问题描述输入框应正常显示当评分达到 4 或 5 时textinput1应自动隐藏3.2 验证邮箱与联系方式的错误提示及按钮禁用输入不符合格式的邮箱如abc或usersite这类缺少合法顶级域名的内容以及空的联系方式观察textinput2下方是否出现Invalid email错误提示、numberinput1是否出现必填错误同时确认button1处于禁用状态当所有字段通过校验后button1应恢复可用状态可以正常点击提交。4. 深入理解验证的底层实现原理4.1 输入类组件的统一验证管线ToolJet 的输入类组件Text Input、Number Input、Currency Input、Phone Input 等共用一套基于useInputHook 的验证管线。在 useInput.js 中Hook 接收validation与validate参数后组件挂载时即调用validate(value)初始化校验状态L58用户每次输入触发handleChange → setInputValue内部再次调用validateRef.current(value)并同步isValid暴露变量L240-L246校验状态validationStatus由{ isValid, validationError }构成isMandatory决定是否强制必填L66-L67校验错误默认在失焦handleBlur设置showValidationError trueL281-L286或表单提交时展示。因此属性面板中通过fx填写的自定义验证表达式实际会编译为该组件的validate函数与必填mandatory校验一起决定isValid暴露变量的最终值。4.2 Form 组件的子组件聚合与整体校验Form 组件本身也会聚合所有子组件的校验结果。在 frontend/src/AppBuilder/Widgets/Form/Form.jsx 中表单通过Object.values(effectiveChildrenData).every((item) item?.isValid ! false)判断整体是否有效同时 Form 组件维护了children暴露变量L337-L339这正是教程中components.form1.children.starrating1、components.form1.children.textinput2引用链的数据来源——每个子组件的value、isValid等暴露变量都会被汇集到form1.children对象下供父级及外部表达式统一访问。4.3 校验配置在定义结构中的落位在表单编辑器的高级配置中字段校验信息如正则被持久化在组件定义的validation字段下。相关工具代码 FormUtils.js 展示了value?.validation?.regex如何在字段配置与组件定义之间同步印证了validation.regex、validation.mandatory等配置项是动态表单校验体系的正式组成部分。5. 进阶将动态逻辑扩展到多页表单本教程的验证与条件组合可以无缝迁移到更复杂的场景。例如在 Form 组件中再加入Tabs组件将表单拆分为多个页签步骤页每个页签内放置各自的输入组件并沿用同样的表达式引用链通过components.form1.children.tabs1.children.stepComponent.children.inputName.isValid引用多层级下的校验结果ToolJet 的children引用链支持逐级嵌套在每个步骤页的提交/下一步按钮上复用“条件禁用”表达式确保用户完成当前步骤的必填与格式校验后才能继续在表单最终提交按钮上聚合所有页签内子组件的isValid实现整体校验后放行提交。掌握本指南中的三类核心配置——Visibility 条件、Custom Validation 自定义验证、mandatory 必填开关配合components.*.children.*引用链与isValid暴露变量即可在 ToolJet 中构建任意复杂度的动态、多步骤交互表单。【免费下载链接】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），仅供参考