ToolJet Checkbox 组件完全指南属性、事件、CSA 与源码实现解析【免费下载链接】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 3.0.0-LTS 文档中的 Checkbox 组件参考为核心覆盖 Checkbox 组件的数据属性、事件、组件特定动作CSA、暴露变量、验证规则、附加动作、设备适配与全部样式配置项并结合 组件渲染源码 与 组件配置文件 剖析每个行为背后的实际实现机制读完后可在 App Builder 中完整配置 Checkbox 组件并理解其事件触发链、状态同步原理与验证渲染时机。组件定位与默认配置Checkbox 组件允许用户进行二元选择勾选 / 取消勾选是 ToolJet 中构建表单、偏好设置与确认交互的基础组件。其组件注册定义在 checkbox.js 中组件名称Checkbox描述为Single checkbox toggle渲染实现指向 Checkbox.jsx默认画布尺寸width: 6、height: 30配置项defaultSize。从源码结构看新建组件时各字段会获得definition中定义的初始值例如visibility: {{true}}、defaultValue: {{false}}、disabledState: {{false}}、loadingState: {{false}}、alignment: right、boxShadow: 0px 0px 0px 0px #00000090。样式默认值使用主题 CSS 变量如textColor: var(--cc-primary-text)、checkboxColor: var(--cc-primary-brand)、uncheckedColor: var(--cc-surface1-surface)、borderColor: var(--cc-default-border)这保证组件在未手动改色时自动跟随应用主题。数据属性Data文档中 Data 分组的两个属性如下属性说明期望值Label复选框的标签文本字符串如Select payment preferenceDefault status应用加载时的默认状态切换 on/off 开关或点击fx动态设置对应源码实现有两个值得注意的细节Label 即暴露变量。组件通过setExposedVariable(label, label)将标签文本实时同步到components.checkbox1.label因此 RunJS 中可以直接读取动态修改后的标签内容。Default status 支持动态表达式。配置中该字段定义为type: switch显示名Default state取值为{{true}}/{{false}}也可点击 fx 写入逻辑表达式。渲染层用properties.defaultValue ?? false作为初始值并在defaultValue变化时通过useEffect把新的默认值同步到内部checked状态与暴露变量——也就是说当动态表达式在其他地方改变了默认值时复选框状态会跟随刷新首次渲染除外避免初始化时误触发。事件Events事件说明On change复选框输入值发生任何变化时触发On check已弃用复选框被勾选时触发On uncheck已弃用复选框被取消勾选时触发从 Checkbox.jsx 的事件分发逻辑看onChange是唯一推荐事件它同时覆盖勾选与取消两个方向。onCheck/onUnCheck仍然保留并触发但配置文件中已明确标注Deprecated建议在新应用中将逻辑统一迁移到On change在回调中根据{{components.checkbox1.value}}判断当前是勾选还是取消。事件触发点共有三处均可验证触发关系用户点击复选框handleToggleChange先触发onChange再按结果触发onCheck或onUnCheck程序化设置CSA 的setChecked/setValue内部执行setCheckedAndNotify同样会触发对应的onCheck/onUnCheck程序化翻转toggle动作执行后触发onChange。提示完整的事件语义可参考官方文档中的 Action Reference 章节位于 docs/docs/actions/ 目录。组件特定动作CSA文档列出的 6 个 CSA 均可通过 RunJS 查询或在事件面板中触发动作说明访问方式setChecked改变复选框勾选状态await components.checkbox1.setChecked(true)setValue设置复选框值await components.checkbox1.setValue(true)setLoading切换加载状态await components.checkbox1.setLoading(true)setVisibility改变可见性await components.checkbox1.setVisibility(true)setDisable禁用/启用组件await components.checkbox1.setDisable(true)toggle翻转当前状态await components.checkbox1.toggle()源码中这些动作集中在组件挂载时通过setExposedVariables一次性注册Checkbox.jsx关键实现行为setValue与setChecked实际指向同一个setCheckedAndNotify函数设置值后若为true触发onCheck否则触发onUnCheck——程序化改值也会驱动事件链setLoading/setVisibility/setDisable接收布尔值后会做!!归一化同时同步更新对应的暴露变量isLoading/isVisible/isDisabled保证脚本与 UI 状态一致toggle执行setInputValue(!checked)并触发onChange与用户手动点击等效配置文件中setChecked的显示名为Set checked (Deprecated)与文档中弃用提示保持一致setValue是其推荐替代。暴露变量Exposed Variables变量说明访问方式value勾选为true未勾选为false{{components.checkbox1.value}}label复选框标签文本{{components.checkbox1.label}}isValid当前状态是否通过验证{{components.checkbox1.isValid}}isMandatory是否为必填字段{{components.checkbox1.isMandatory}}isLoading是否处于加载状态{{components.checkbox1.isLoading}}isVisible是否可见{{components.checkbox1.isVisible}}isDisabled是否被禁用{{components.checkbox1.isDisabled}}value的更新发生在setInputValue中任何状态变化用户点击、CSA 设置、toggle都会同步写入value与isValid暴露变量。E2E 测试用例 checkbox.cy.js 正是在 Inspector 面板中断言这些暴露变量的默认值value: false、isVisible: true、isValid: true、label: Label等以及 6 个动作函数均为Function类型可作为变量清单的官方验证依据。验证Validation验证选项说明期望值Make this field mandatory未输入值时显示 Field cannot be empty 提示启用/禁用开关或点击fx动态设置Custom validation针对特定条件指定验证错误信息逻辑表达式如{{components.checkbox1.value false Value needs to be checked}}在Custom Validation中嵌入正则的写法格式{{(regexPattern.test(value)) ? : Error message;}}示例{{(/^\d{1,10}$/.test(components.textinput1.value)) ? : Error message;}}表达式返回空字符串表示通过返回非空字符串则作为错误信息展示。从源码结构看验证错误的展示时机有两层控制用户交互门槛错误文本仅在!isValid visibility userInteracted三个条件同时成立时渲染。即用户尚未操作过时不立即报错避免空表单被红色提示刷屏表单提交信号组件通过 FormSignalContext 中的useShowValidationOnFormSubmit监听表单提交计数父级 Form 提交一次后submitAttemptCount 0userInteracted被置为true此时必填未勾选的 Checkbox 会自动显示错误。这解释了为什么把 Checkbox 放进 Form 中提交时验证信息会“延迟”到提交后才出现。此外useFormClear会在 Form 触发clearForm时将复选框重置为未勾选状态实现表单一键清空。当isMandatory为真时标签旁还会渲染红色星号*并设置aria-required供辅助技术识别。附加动作Additional Actions动作说明配置方式Loading state启用加载指示器常与isLoading配合表示进度开关切换或fx动态设置Visibility控制组件可见性开关切换或fx动态设置Disable禁用/启用组件开关切换或fx动态设置Tooltip悬停时提供补充说明字符串如Are you a registered user?实现层的行为细节Loading state加载期间复选框与标签整体被替换为一个 16px 的 Loader 指示器aria-busy{loading}且初始disable值被设为disabledState || loadingState——加载中的复选框默认不可交互这在等待后端返回初始值的场景下可防止误操作Visibility通过外层容器的display: visibility ? flex : none控制隐藏同时设置aria-hidden组件占位行为可结合Collapse when hidden开关默认关闭进一步控制Disable通过data-disabled属性与aria-disabled呈现禁用态下点击不会改变值Tooltip配置文件将其拆分为tooltipFormatplainText / markdown / html 三选一与tooltip文本字段两项默认plainText因此 tooltip 内容还支持 Markdown 与 HTML 渲染格式。设备适配Devices属性说明Show on desktop桌面视图中显示组件Show on mobile移动视图中显示组件两者均支持开关切换或fx动态表达式。从definition看默认值为showOnDesktop: {{true}}、showOnMobile: {{false}}即新拖入的 Checkbox 默认只在桌面端可见投放到移动端应用时需显式开启 Show on mobile。样式StylesLabel 分组样式属性说明配置方式Text color设置标签颜色选择颜色或fx返回 Hex 颜色代码Alignment设置标签与输入框的位置关系选择left/right或fx返回对齐值渲染逻辑中alignment left时容器切换为flex-row-reverse标签在左、方框在右默认的right则是方框在左、标签在右标签使用 14px 字号、400 字重并由OverflowTooltip处理超长文本截断提示。Switch 分组复选框本体样式属性说明配置方式Border color复选框边框颜色选择颜色或fx返回 Hex 值Checked color勾选状态下的方框背景色选择颜色或fx返回 Hex 值Unchecked color未勾选状态下的方框背景色选择颜色或fx返回 Hex 值Handle color勾选符号对勾颜色选择颜色或fx返回 Hex 值Box shadow组件盒阴影选择阴影颜色与参数或fx设置从源码结构看方框本体是固定 18×18px、5px 圆角的自绘div内部隐藏原生input typecheckbox背景色随状态在checkboxColor选中与uncheckedColor未选中之间切换对勾为 14×14px 的内联 SVG其描边颜色即handleColor。默认边框色为var(--cc-default-border)当borderColor恰好是默认值#CCD1D5时勾选态会把边框处理为透明以避免双重描边。配置文件里该分组还提供Padding选项default/none默认default文档未单独列出但同样可通过 fx 动态控制。可访问性与测试验证组件为原生 input 设置了完整的 ARIA 属性aria-disabled、aria-busy、aria-required、aria-hidden、aria-invalid并让标签通过label htmlFor与输入框关联屏幕阅读器可正确播报勾选状态与必填性。回归验证方面checkbox.cy.js 以 E2E 方式覆盖了拖拽创建组件后在 Inspector 中断言全部暴露变量与 6 个 CSA 函数、On Change事件触发、以及通过按钮触发Set visibility/Set disable/Set checked/Toggle/Set loading后断言data-disabled属性、be.checked状态与 loader 可见性与上文各章节的行为描述一一对应。参考文件索引文件作用docs/versioned_docs/version-3.0.0-LTS/widgets/checkbox.md本文对应的官方组件参考文档frontend/src/AppBuilder/WidgetManager/widgets/checkbox.js属性、事件、CSA、样式与默认值注册配置frontend/src/AppBuilder/Widgets/Checkbox.jsx组件渲染、事件分发与状态同步实现frontend/src/AppBuilder/Widgets/Form/FormSignalContext.tsx表单提交/清空信号控制验证展示时机cypress-tests/cypress/e2e/happyPath/appbuilder/commonTestcases/newSuits/componentsBasics/checkbox.cy.js组件行为 E2E 回归测试【免费下载链接】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），仅供参考