ToolJet Toggle Switch 组件完全指南：属性、事件、组件操作（CSA）、校验与样式定制

ToolJet Toggle Switch 组件完全指南：属性、事件、组件操作（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

Toggle Switch（开关）是 ToolJet 应用构建器中处理二元选择的基础组件，常用于功能开关、设置启停等场景。本文以 ToolJet 2.50.0-LTS 版本文档为骨架，结合仓库源码（组件配置与 React 实现、Cypress 测试）深入讲解该组件的属性配置、事件绑定、组件特定操作（CSA）、暴露变量、校验规则与样式定制，读完即可在表单与工作流中熟练使用开关并驱动动态行为。

组件定位与 V2/Legacy 版本说明

Toggle Switch 组件用于二元选择，例如打开/关闭某个功能、启用/禁用某项设置。从仓库的组件注册表 widgetConfig.js 可以看到，当前组件面板中存在两套开关配置：

• toggleSwitchV2Config：新版 Toggle Switch（ToggleSwitchV2），即本文档描述的对象；
• toggleswitchConfig：遗留版Toggle Switch (Legacy)（组件名ToggleSwitchLegacy），仅保留 Label、Default status、基础样式与onChange事件。

本文档中的信息提示（info 块）明确指出：如需遗留版 Toggle Switch 的配置，请参考 Legacy 文档（对应旧版 toggle-switch.md）。在源码层面，两版配置分别定义于 toggleswitchv2.js 与 toggleswitch.js，便于对照差异。

Properties（属性）

Data（数据）

属性	说明	期望值
Label	用作开关标签的文本。	字符串（例如Enable notifications）。
Default status	设置应用加载时开关的默认状态。	拨动开关，或点击fx动态设置值。

在源码 toggleswitchv2.js 中，label字段为code类型（校验 schema 为string），defaultValue字段为switch类型，其两个选项值分别是{{true}}（On）与{{false}}（Off），并校验 schema 为boolean。也就是说，默认状态不仅在画布上可拨动，也可以通过fx用表达式（如绑定另一个组件的值）动态决定。

渲染层如何消费属性

在 ToggleV2.jsx 中：

const defaultValue = properties.defaultValue ?? false; const [on, setOn] = useState(Boolean(defaultValue));

组件以Boolean(defaultValue)初始化内部状态on，当defaultValue变化时通过useEffect调用setInputValue同步更新（首次渲染跳过），从而支持运行时动态改写默认值。

Events（事件）

事件	说明
On change	当开关输入发生变化时触发。
On check（已弃用）	当开关被勾选时触发。
On uncheck（已弃用）	当开关被取消勾选时触发。

新版组件在事件配置中仅保留onChange（见 toggleswitchv2.js），On check与On uncheck标记为 deprecated。事件触发链路在 ToggleV2.jsx 中非常直观：

const handleToggleChange = () => { setOn(!on); fireEvent('onChange'); setUserInteracted(true); };

用户每次点击开关，除了翻转内部状态，还会调用fireEvent('onChange')触发事件处理器，同时通过setUserInteracted(true)标记"用户已交互"——这一标记是表单校验提示显示的前提。事件处理器中可配置 ToolJet 的全部Actions（如展示告警、运行查询、打开 URL 等），详细说明见 Action Reference。

Component Specific Actions（组件特定操作，CSA）

以下 Toggle Switch 的组件特定操作可在任意事件处理器中通过 CSA 控制：

操作	说明	访问方式
setChecked	使用组件特定操作改变开关状态。	使用 RunJS 查询（例如await components.toggleswitch1.setChecked(true)）或通过事件触发。
setValue	设置开关的值。	使用 RunJS 查询（例如await components.toggleswitch1.setValue(true)）或通过事件触发。
setLoading	切换开关的加载状态。	使用 RunJS 查询（例如await components.toggleswitch1.setLoading(true)）或通过事件触发。
setVisibility	改变开关的可见性。	使用 RunJS 查询（例如await components.toggleswitch1.setVisibility(true)）或通过事件触发。
setDisable	禁用或启用开关。	使用 RunJS 查询（例如await components.toggleswitch1.setDisable(true)）或通过事件触发。
toggle	切换开关当前状态。	使用 RunJS 查询（例如await components.toggleswitch1.toggle()）或通过事件触发。

源码中的 CSA 实现

组件的操作句柄定义在配置的actions数组中（toggleswitchv2.js），运行时被注入为暴露变量中的异步函数（ToggleV2.jsx）：

setValue: async function (value) { setInputValue(value); setUserInteracted(true); }, setVisibility: async function (state) { setVisibility(!!state); setExposedVariable('isVisible', !!state); }, setDisable: async function (disable) { setDisable(!!disable); setExposedVariable('isDisabled', !!disable); }, setLoading: async function (loading) { setLoading(!!loading); setExposedVariable('isLoading', !!loading); }, toggle: async function () { setInputValue(!on); fireEvent('onChange'); setUserInteracted(true); },

其中setValue走setInputValue，会同步更新校验状态并刷新暴露变量value与isValid；toggle额外触发onChange事件，方便在脚本中模拟用户点击行为。从源码结构看，setChecked与setValue在功能上等价，均可通过 RunJS 或事件处理器驱动开关状态。

Exposed Variables（暴露变量）

变量	说明	访问方式
value	开关勾选时为布尔值true，未勾选时为false。	动态访问（例如{{components.toggleswitch1.value}}）。
label	开关的文本标签。	动态访问（例如{{components.toggleswitch1.label}}）。
isValid	表示开关状态是否有效。	动态访问（例如{{components.toggleswitch1.isValid}}）。
isMandatory	表示开关是否为必填。	动态访问（例如{{components.toggleswitch1.isMandatory}}）。
isLoading	表示开关是否处于加载状态。	动态访问（例如{{components.toggleswitch1.isLoading}}）。
isVisible	表示开关是否可见。	动态访问（例如{{components.toggleswitch1.isVisible}}）。
isDisabled	表示开关是否被禁用。	动态访问（例如{{components.toggleswitch1.isDisabled}}）。

暴露变量的初始值在配置中声明（toggleswitchv2.js）：

exposedVariables: { value: false, label: 'Label', isMandatory: false, isVisible: true, isDisabled: false, isLoading: false, }

每次用户交互或 CSA 调用后，组件通过setExposedVariable/setExposedVariables同步这些值（ToggleV2.jsx），因此在 RunJS、查询参数或其它组件的{{...}}表达式中可以实时读取开关的最新状态。

Validation（校验）

校验选项	说明	期望值
Make this field mandatory	若未输入任何值，则显示"Field cannot be empty"消息。	启用/禁用开关，或点击fx并输入逻辑表达式动态配置。
Custom validation	为特定条件指定校验错误消息。	逻辑表达式（例如{{components.toggleswitch1.value === false &&"Value needs to be checked"}}）。

自定义校验中如需使用正则表达式，可套用以下格式：

格式：{{(<regexPattern>.test(<value>)) ? '' : 'Error message';}}

示例：{{(/^\d{1,10}$/.test(components.textinput1.value)) ? '' : 'Error message';}}

校验的运行时行为

从渲染实现看（ToggleV2.jsx），组件通过validate(on)计算{ isValid, validationError }校验状态；仅当userInteracted && visibility && !isValid同时成立时，才会在开关下方渲染错误提示（data-cy形如toggleswitch1-invalid-feedback），错误文案颜色使用错误状态变量var(--cc-error-systemStatus)。此外，开关作为表单字段时，useShowValidationOnFormSubmit会在表单提交时触发校验显示，useFormClear则会在表单清空时将开关重置为false（ToggleV2.jsx）。

Additional Actions（附加操作）

操作	说明	配置选项
Loading state	启用加载微调器，常与isLoading配合表示处理中。	启用/禁用开关，或点击fx并输入逻辑表达式动态配置。
Visibility	控制组件可见性。	启用/禁用开关，或点击fx并输入逻辑表达式动态配置。
Disable	启用或禁用组件。	启用/禁用开关，或点击fx并输入逻辑表达式动态配置。
Tooltip	悬停时提供附加信息。	字符串（例如Are you a registered user?）。

新版组件还在"附加操作"区提供了Collapse when hidden（隐藏时折叠）与Tooltip 格式两个细节选项：tooltipFormat支持plainText/markdown/html三种渲染格式（默认plainText），配置见 toggleswitchv2.js。

需要留意的是，Loading state置为true时，渲染层会同时把disable状态置为真（properties.disabledState || properties.loadingState），并以Loader微调器替代开关本体、内容居中显示（ToggleV2.jsx），避免加载期间用户误操作。

Devices（设备可见性）

Show on desktop

使组件在桌面端视图可见。可通过开关按钮设置，或点击fx输入逻辑表达式动态配置。

Show on mobile

使组件在移动端视图可见。可通过开关按钮设置，或点击fx输入逻辑表达式动态配置。

配置层中showOnDesktop/showOnMobile均为toggle类型，默认值分别为{{true}}与{{false}}（toggleswitchv2.js），即默认在桌面端显示、移动端隐藏。

Styles（样式）

Label（标签）

标签属性	说明	配置选项
Text color	设置组件标签的颜色。	选择颜色，或点击fx输入以编程方式返回 Hex 颜色代码的代码。
Alignment	设置标签与输入框的位置。	点击开关选项，或点击fx输入以编程方式返回对齐值（left或right）的代码。

Switch（开关）

标签属性	说明	配置选项
Border color	设置开关的颜色。	选择颜色，或点击fx输入以编程方式返回 Hex 颜色代码的代码。
Checked color	设置开关勾选时的颜色。	选择颜色，或点击fx输入以编程方式返回 Hex 颜色代码的代码。
Unchecked color	设置开关未勾选时的颜色。	选择颜色，或点击fx输入以编程方式返回 Hex 颜色代码的代码。
Handle color	设置开关内部圆钮的颜色。	选择颜色，或点击fx输入以编程方式返回 Hex 颜色代码的代码。
Box shadow	设置组件的盒阴影属性。	选择盒阴影颜色并调整相关属性，或使用fx以编程方式设置。

默认样式值与渲染细节

样式默认值定义于 toggleswitchv2.js，均使用设计令牌（CSS 变量）而非硬编码色值，便于主题切换：

• textColor：var(--cc-primary-text)（标签文字颜色）
• toggleSwitchColor：var(--cc-primary-brand)（勾选色，注释注明保留该键名以兼容旧数据）
• uncheckedColor：var(--cc-surface3-surface)（未勾选色）
• borderColor：var(--cc-default-border)（边框色）
• handleColor：var(--cc-surface1-surface)（圆钮色）
• alignment：right
• boxShadow：0px 0px 0px 0px #00000090
• padding：default

渲染层把样式直接映射到 DOM 内联样式（ToggleV2.jsx）：滑轨宽 28px、高 18px，圆钮直径 12px，勾选时通过translateX(12px)平移，背景色与圆钮位移动画均为0.2s过渡，从而形成平滑的开合效果。alignment为right时容器使用flex-row-reverse，实现标签在左、开关在右的经典布局。

底层实现与测试佐证

组件注册：toggleSwitchV2Config从 widgets/index.js 导出，经 widgetConfig.js 注册进 Select inputs 分组；默认画布尺寸为宽 6、高 30（配置栅格单位），组件描述为 "User-controlled on-off switch"。

辅助渲染：开关外层使用OverflowTooltip包裹标签以支持长文本省略；必填标记为标签后方的红色*（颜色变量var(--cc-error-systemStatus)）；基础<input type="checkbox">透明铺底，并带有aria-disabled、aria-hidden、aria-required、aria-invalid等无障碍属性（ToggleV2.jsx）。

测试验证：仓库的 Cypress 测试用例（如 toggleSwitch.skip.js）覆盖了开关组件的命名编辑、暴露变量校验（通过 Inspector 打开并核对toggleswitch1的暴露值）以及 CSA 操作验证；测试常量 common.js 中toggleswitch1与Toggle Switch即组件在画布上的默认实例名与面板显示名。

小结：把开关接入真实业务

一个完整的开关用法通常包含四步：在画布放置 Toggle Switch 并设置Label与Default status；在On change事件中绑定查询或动作；通过{{components.toggleswitch1.value}}在查询参数、RunJS 或其它组件中读取状态；最后按需配置必填校验、Loading 态与配色。结合 CSA（setValue/toggle/setDisable等），即可实现"开关控制面板、开关联动表单、开关切换工作流"等常见内部工具场景。

【免费下载链接】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