ToolJet 前端组件实战Toggle Switch开关组件的完整配置与源码级解析【免费下载链接】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 开源仓库中的 Toggle Switch 组件文档 为核心骨架结合仓库内真实的前端组件注册配置与 React 实现源码系统讲解 Toggle Switch 组件的属性配置、事件系统、组件专属动作CSA、暴露变量、校验规则、样式定制与设备适配。读完本文你将能够在 ToolJet 应用编辑器中熟练配置该开关组件并能通过 RunJS 查询与fx动态表达式对它进行编程式控制。说明ToolJet 同时提供新旧两代 Toggle Switch。本文讲解的是新版 Toggle Switch内部组件名ToggleSwitchV2旧版Legacy的配置文档见 toggle-switch.md两者在事件、校验与样式能力上有明显差异阅读时请勿混淆。组件定位何时使用 Toggle SwitchToggle Switch 组件用于二选一布尔输入场景例如打开/关闭某个功能、启用/禁用某项设置、切换明暗主题等。它与 Checkbox 的主要区别在于交互语义开关强调即时生效的切换动作适合表示当前某个状态的开与关。在仓库源码中该组件的注册元数据位于 frontend/src/AppBuilder/WidgetManager/widgets/toggleswitchv2.js其中name: ToggleSwitch、displayName: Toggle Switch——编辑器中展示的名称component: ToggleSwitchV2——实际渲染的 React 组件defaultSize: { width: 6, height: 30 }——拖入画布时的默认栅格尺寸。渲染实现位于 frontend/src/AppBuilder/Widgets/ToggleV2.jsx内部基于一个隐藏的input typecheckbox加自绘滑块实现这在后文源码解析中会展开说明。属性Properties数据Data属性说明期望值Label开关组件的标签文本。字符串如Enable notificationsDefault status应用加载时开关的默认状态。手动拨动开/关或点击fx动态设置值需要特别说明两点Label 支持动态表达式。在 toggleswitchv2.js 中label的类型是code校验 schema 为{ type: string }这意味着你可以填写{{components.textinput1.value}}之类的模板表达式让标签文本随其他组件状态联动。Default status 的本质是defaultValue。在源码中它被定义为switch类型、取值为布尔值选项为On{{true}}/ Off{{false}}默认值为{{false}}。它只在初次加载时生效——从 ToggleV2.jsx 可以看到组件用useState(Boolean(defaultValue))初始化内部状态当defaultValue属性后续变化时组件通过useEffect调用setInputValue(defaultValue)同步首次渲染除外因此它在运行时也可以被动态改写。事件Events事件说明On change开关输入状态发生变化时触发。On check已弃用开关被勾选时触发。On uncheck已弃用开关被取消勾选时触发。从源码实现看新版组件只注册了onChange一个事件见 toggleswitchv2.js 的events: { onChange: ... }On check / On uncheck是旧版保留的废弃事件。在 ToggleV2.jsx 中无论用户点击开关还是通过动作切换状态都会调用fireEvent(onChange)触发该事件你可以在事件处理器中接入展示告警、运行查询、更新变量等任意 ToolJet 动作。关于全部可用动作的详细说明可参考 动作参考文档。组件专属动作Component Specific ActionsCSA通过组件专属动作可以在任意事件处理器或 RunJS 查询中编程式控制开关组件动作说明如何访问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()或通过事件触发。从源码结构看toggleswitchv2.js 中实际注册了五个动作toggle、setValue、setVisibility、setDisable、setLoading其中setVisibility、setDisable、setLoading均接受一个布尔参数默认值{{false}}。文档中列出的setChecked在 v2 配置中并未单独注册编程式设置勾选状态请使用setValue例如await components.toggleswitch1.setValue(true)。对应的实现逻辑在 ToggleV2.jsxsetValue(value)内部调用setInputValue(value)同步更新 UI 状态、value暴露变量并重新执行校验toggle动作在每次调用时翻转on状态并触发onChange事件setVisibility、setDisable、setLoading除更新界面状态外还会同步更新对应的isVisible、isDisabled、isLoading暴露变量。典型用法示例RunJS 查询// 强制打开开关并触发校验 await components.toggleswitch1.setValue(true); // 提交期间禁用开关并显示加载态 await components.toggleswitch1.setDisable(true); await components.toggleswitch1.setLoading(true); // ...执行异步请求... await components.toggleswitch1.setLoading(false); await components.toggleswitch1.setDisable(false); // 一键翻转状态 await components.toggleswitch1.toggle();暴露变量Exposed Variables组件运行时会向应用上下文暴露以下变量可在任意 JS 表达式{{ }}或其他组件属性中引用变量说明如何访问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 中定义了这些变量的初始值value: false、label: Label、isMandatory: false、isVisible: true、isDisabled: false、isLoading: false。运行时ToggleV2.jsx 通过useEffect监听 label、isMandatory、isLoading、isVisible、isDisabled 等内部状态变化并同步更新暴露变量确保 UI 与表达式引用始终一致。一个常见的联动用法当开关打开时才显示某个输入框——{{components.toggleswitch1.value true}}把它填入输入框组件的Visibility属性的 fx 中即可实现条件显示。校验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)计算初始校验状态每次setInputValue无论是用户点击、CSA 调用还是默认值变化都会重新执行validate(value)并更新isValid暴露变量当userInteracted为真、组件可见且校验不通过时会在组件下方渲染红色错误信息data-cy为组件名-invalid-feedback样式取自 CSS 变量var(--cc-error-systemStatus)。需要说明的是Toggle Switch 的必填语义比较特殊布尔开关理论上总有值因此自定义校验通常是更实用的手段——例如上面示例中必须勾选才能继续的场景可以在提交按钮的 Disable 属性中配合使用{{components.toggleswitch1.value false}}附加操作Additional Actions动作说明配置选项Loading state显示加载动画常与 isLoading 属性配合表示进行中状态。打开/关闭开关或点击fx输入逻辑表达式动态配置。Visibility控制组件可见性。打开/关闭开关或点击fx输入逻辑表达式动态配置。Disable启用或禁用组件。打开/关闭开关或点击fx输入逻辑表达式动态配置。Tooltip悬停时显示额外提示信息。字符串如Are you a registered user?。对应源码中toggleswitchv2.js这四个属性均归属于additionalActions分组并且loadingState、visibility、disabledState为布尔开关默认值分别是{{false}}、{{true}}、{{false}}组件还额外提供了collapseWhenHidden隐藏时折叠占位选项默认{{false}}tooltip支持三种渲染格式plainText纯文本、markdown、html由tooltipFormat开关切换默认plainText。这是文档表格之外、但已在源码中实现的能力适合需要富文本提示的场景。在渲染层ToggleV2.jsx当loadingState为真时组件会用Loader替换标签与开关且此时disable也会被强制置为真见useState(properties.disabledState || properties.loadingState)避免加载过程中用户误操作。设备适配Devices属性说明期望值Show on desktop在桌面视图中显示组件。开关按钮设置或点击fx输入逻辑表达式动态配置。Show on mobile在移动视图中显示组件。开关按钮设置或点击fx输入逻辑表达式动态配置。源码中二者的默认值分别为{{true}}与{{false}}toggleswitchv2.js即默认只在桌面端显示。需要移动端展示时请记得在 Mobile 预览视图中开启该项。样式定制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对齐rightboxShadow阴影0px 0px 0px 0px #00000090padding内边距default渲染原理从 ToggleV2.jsx 可以看出开关本体是一个 28×18px 的圆角轨道borderRadius: 34px加一个 12×12px 的圆形滑块勾选时滑块通过translateX(12px)右移轨道背景色取styles.toggleSwitchColor未勾选时取styles.uncheckedColor边框使用styles.borderColor滑块颜色使用styles.handleColor切换过程带有 0.2s 的过渡动画。因此上述五类颜色直接影响的就是轨道的这三个视觉状态与滑块把手。源码级的完整数据流最后把整条链路串起来看Toggle Switch V2 在运行时遵循以下数据流初始化组件挂载时读取properties.defaultValue默认false初始化on状态并一次性通过setExposedVariables暴露value / label / isMandatory / isLoading / isVisible / isDisabled / isValid及全部 CSA 函数ToggleV2.jsx。用户交互点击开关 →toggleValue读取e.target.checked→ 更新value暴露变量 →fireEvent(onChange)→ 标记userInteracted→ 触发校验。编程控制RunJS 调用 CSA如setValue(true)→setInputValue→ 同步 UI、暴露变量与校验结果调用toggle→ 翻转状态并触发onChange。属性驱动编辑器里通过fx动态改defaultValue、disabledState、visibility、loadingState、label时组件内的useEffect会各自同步内部状态与暴露变量。表单联动组件接入 Form 的信号上下文支持提交时显示校验useShowValidationOnFormSubmit与表单清空时重置为 falseuseFormClear详见 ToggleV2.jsx。小结Toggle Switch V2 是 ToolJet 中实现布尔输入的标准组件通过 Label 与 Default status 完成基础配置On change 事件接入业务逻辑六类 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考