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/ToolJetToggle Switch开关是 ToolJet 应用构建器中处理二元选择的基础组件常用于功能开关、设置启停等场景。本文以 ToolJet 2.50.0-LTS 版本文档为骨架结合仓库源码组件配置与 React 实现、Cypress 测试深入讲解该组件的属性配置、事件绑定、组件特定操作CSA、暴露变量、校验规则与样式定制读完即可在表单与工作流中熟练使用开关并驱动动态行为。组件定位与 V2/Legacy 版本说明Toggle Switch 组件用于二元选择例如打开/关闭某个功能、启用/禁用某项设置。从仓库的组件注册表 widgetConfig.js 可以看到当前组件面板中存在两套开关配置toggleSwitchV2Config新版 Toggle SwitchToggleSwitchV2即本文档描述的对象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 为stringdefaultValue字段为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.jsOn 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.jsxsetValue: 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与isValidtoggle额外触发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.jsexposedVariables: { 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则会在表单清空时将开关重置为falseToggleV2.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 变量而非硬编码色值便于主题切换textColorvar(--cc-primary-text)标签文字颜色toggleSwitchColorvar(--cc-primary-brand)勾选色注释注明保留该键名以兼容旧数据uncheckedColorvar(--cc-surface3-surface)未勾选色borderColorvar(--cc-default-border)边框色handleColorvar(--cc-surface1-surface)圆钮色alignmentrightboxShadow0px 0px 0px 0px #00000090paddingdefault渲染层把样式直接映射到 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 typecheckbox透明铺底并带有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 态与配色。结合 CSAsetValue/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考