ToolJet Checkbox 组件完全指南：属性、事件、CSA 与源码实现解析-平芜编程栈

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 preference`）
Default 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 > 0，userInteracted被置为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：配置文件将其拆分为tooltipFormat（plainText / markdown / html 三选一）与tooltip文本字段两项，默认plainText，因此 tooltip 内容还支持 Markdown 与 HTML 渲染格式。

设备适配（Devices）

属性	说明
Show on desktop	桌面视图中显示组件
Show on mobile	移动视图中显示组件

两者均支持开关切换或fx动态表达式。从definition看默认值为showOnDesktop: {{true}}、showOnMobile: {{false}}，即新拖入的 Checkbox 默认只在桌面端可见，投放到移动端应用时需显式开启 Show on mobile。

样式（Styles）

Label 分组

样式属性	说明	配置方式
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 type="checkbox">），背景色随状态在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 回归测试