ToolJet Radio Button 组件详解动态选项、校验与组件特定动作的完整实战指南【免费下载链接】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 官方文档中的 Radio Button 组件文档为主体覆盖其选项配置静态/动态、动态选项加载态、组件特定动作CSA、暴露变量、事件、校验规则、额外动作及样式属性并结合仓库源码组件默认定义与 React 实现说明每个属性的默认值与底层生效机制帮助你在 ToolJet 应用构建中完成单选场景的完整配置。1. Radio Button 组件的核心定位Radio button组件用于从一组互斥的选项中收集用户的单一选择对应 ToolJet 构建器中的RadioButton组件描述为 Select one from multiple choices。它的组件注册与默认定义位于 radioButtonV2.jsReact 实现位于 RadioButtonV2.jsx。组件默认渲染尺寸来自配置中的defaultSize宽 12、高 43 的构建器网格单位并在画布上渲染为roleradiogroup的原生typeradio输入集合天然具备单选互斥语义与可访问性属性aria-busy、aria-disabled、aria-required、aria-invalid。2. DataLabel 属性属性说明期望值Label显示在组件上的标签文本字符串例如Select an option从源码定义看label是一个code类型属性即支持 fx 动态表达式默认值为Select见 radioButtonV2.js 中properties.label与definition.properties.label。标签内容会作为暴露变量components.radiobutton1.label对外可读也可在 JSX 绑定中直接引用。3. Options静态选项与动态选项Options区域允许向单选字段添加选项。有两种配置模式对应源码中的advanced属性在 Inspector 中显示为 Dynamic options 开关手动添加关闭Dynamic options点击Add new option逐条添加选项动态生成开启Dynamic options此时 Inspector 中会显示Schema代码输入框源码中schema属性通过conditionallyRender: { key: advanced, value: true }条件渲染可用 JS 表达式传入选项数组。3.1 动态选项的两种写法写法一传入对象数组并逐项指定字段{{ [{label: option1, value: 1, disable: false, visible: true, default: true}, {label: option2, value: 2, disable: false, visible: true}, {label: option3, value: 3, disable: false, visible: true}] }}写法二结合 Table 组件选中行传入带默认值的选项{{ queries.getEmployees.data.map(option ({ label: option.firstname, value: option.firstname, disable: false, visible: true, default: option.firstname components.table1.selectedRow.firstname })) }}选项对象的每个字段含义可由源码印证RadioButtonV2.jsx 中的selectOptions计算逻辑字段作用源码行为label选项显示文本经getSafeRenderableValue渲染为文本value选项值选中时写入value暴露变量参与checkedValue option.value判断disable是否禁用该选项映射为isDisabled禁用时该单选输入不可交互visible是否渲染该选项visible ?? true过滤false时该选项不渲染default初始选中项findDefaultItem会查找default true visible true的第一项作为初始值需要注意两点实现细节其一default只在首个满足default: true且visible: true的选项上生效多个选项同时标记default不会都选中其二组件对schema/options的 JSON 字符串变化有useEffect监听动态表达式求值结果变化时会重新计算默认选中项。组件默认定义中内置了 3 个示例选项option1/option2/option3其中 option2 的value: 2且default: true与默认value定义{{2}}保持一致见 radioButtonV2.js 的definition段。3.2 选项布局Layout源码中layout属性提供三种排布方式默认row取值效果row横向排列水平方向溢出时可滚动overflow: auto hiddencolumn纵向排列垂直方向溢出时可滚动overflow: hidden autowrap横向排列并自动换行flexWrap: wrap组件高度自适应内容height: max-content3.3 Options loading state选项加载态Options loading stateoptionsLoadingState布尔值默认false用于为动态生成的选项添加加载指示。它既可直接切换开关也可点击fx输入逻辑表达式动态控制。渲染逻辑上isLoading || optionsLoadingState任一为真时选项区域会被一个居中的Loader旋转图标替换RadioButtonV2.jsx 第 256 行附近的条件渲染适配合并查询执行中 → 选项渲染的动态场景。4. 组件特定动作CSA以下动作可通过 RunJS 查询或事件触发来控制组件动作说明访问方式clear()清空当前选中项RunJS 查询如await components.radiobutton1.clear()或事件触发setVisibility()设置组件可见性如await components.radiobutton1.setVisibility(false)或事件触发setLoading()设置组件加载态如await components.radiobutton1.setLoading(true)或事件触发setDisable()禁用组件如await components.radiobutton1.setDisable(true)或事件触发selectOption()选中指定选项如await components.radiobutton1.selectOption(2)或事件触发deselectOption()取消当前选中项如await components.radiobutton1.deselectOption()或事件触发这些动作与源码实现一一对应RadioButtonV2.jsx 通过setExposedVariables暴露selectOption、deselectOption、setVisibility、setDisable、setLoading等异步函数其中selectOption(value)内部会归一化参数若传入带value字段的对象则取其value更新value暴露变量、重新执行校验并触发onSelectionChange事件deselectOption等价于选中null。clear()属于 ToolJet 对输入类组件的通用控制动作可参考 control-component.md 中的动作参考。同时radioButtonV2.js的actions数组也在事件配置面板中注册了 Select option、Deselect option、Set visibility、Set loading、Set disable 五种事件动作可在事件编排中直接选择。5. 暴露变量Exposed Variables变量说明访问方式label单选按钮的标签名{{components.radiobutton1.label}}value用户选中的值{{components.radiobutton1.value}}options所有选项的数组{{components.radiobutton1.options}}取具体项如{{components.radiobutton1.options[0].label}}isValid输入是否通过校验{{components.radiobutton1.isValid}}isMandatory字段是否必填{{components.radiobutton1.isMandatory}}isLoading组件是否处于加载态{{components.radiobutton1.isLoading}}isVisible组件是否可见{{components.radiobutton1.isVisible}}isDisabled组件是否被禁用{{components.radiobutton1.isDisabled}}源码印证组件在useEffect中持续把label、options仅保留{label, value}两个字段、isValid、isMandatory、isLoading、isVisible、isDisabled同步为暴露变量RadioButtonV2.jsx 第 110–158 行因此即使属性由 fx 表达式动态变化这些变量也会随之刷新可安全用于其他组件的绑定表达式。6. 事件Events事件说明On select用户选中某个选项时触发源码中该事件名为onSelectionChange在配置中显示为 On select。它不仅由用户点击触发——当通过selectOption()/deselectOption()程序化改变选中项时同样会fireEvent(onSelectionChange)这意味着程序化改值也能驱动下游事件链如选中后立即执行某个 RunJS 查询。7. 校验Validation校验项说明期望值Make this field mandatory未选择任何选项时显示 Field cannot be empty 消息切换开关或点击fx输入逻辑表达式动态配置Custom validation针对特定条件指定校验错误消息逻辑表达式例如{{!components.radiobutton1.value Please select an option}}实现上mandatory默认falsecustomRule是code类型属性占位示例为{{components.text2.textyesvalid}}。组件用validate(checkedValue)计算isValid与validationError选中项变化时会重新求值校验失败时错误文案以红色小字显示在组件下方源码第 322–333 行的错误提示容器仅在组件可见且isValid为 false 时渲染。aria-required与aria-invalid也会同步必填与校验状态供无障碍读屏使用。8. 额外动作Additional Actions动作说明配置选项Loading state启用加载旋转指示器常配合isLoading使用以表示进度可切换或动态设置开关切换或fx动态配置Visibility控制组件可见性可切换或动态设置开关切换或fx动态配置Disable启用/禁用组件可切换或动态设置开关切换或fx动态配置Tooltip悬停时提供附加信息字符串例如Select an option.补充源码细节loadingState、visibility默认truedisabledState默认为false属性定义中的defaultValue与实际definition值不同以组件落地定义definition.properties为准。此外源码还注册了collapseWhenHidden隐藏时收起默认false与tooltipFormatTooltip 格式支持 Plain text / Markdown / HTML 三种默认plainText可在 Inspector 的 additional actions 区域配合使用。9. 设备适配Devices属性说明Show on desktop在桌面视图中显示组件。开关切换或fx动态配置Show on mobile在移动视图中显示组件。开关切换或fx动态配置默认定义中showOnDesktop: {{true}}、showOnMobile: {{false}}即新建组件默认只在桌面端显示。10. 样式配置Label / Switch / ContainerLabel 区域属性说明Color设置标签颜色。选择颜色或点击fx输入代码返回 Hex 颜色码Alignment设置标签与输入字段的位置关系。切换side/top或点击fx返回对齐值Width设置输入字段宽度。保留Auto width使用标准宽度取消后通过滑块或fx数值表达式调整源码对应labelColor默认var(--cc-primary-text)labelFontSize默认12alignment默认side还支持direction左/右对齐切换宽度由autoAuto width默认开启labelWidth滑块 widthTypeOf the Component / Of the Field默认ofComponent共同控制。Switch 区域单选项圆点的配色属性说明Border选项圆点边框颜色。选择颜色或fx返回 Hex 色值Checked background选中项背景色。选择颜色或fx返回 Hex 色值Unchecked background未选中项背景色。选择颜色或fx返回 Hex 色值Handle color选中项内部填充色。选择颜色或fx返回 Hex 色值Text选项文本颜色源码默认值分别为borderColor: var(--cc-default-border)、switchOnBackgroundColor: var(--cc-primary-brand)、switchOffBackgroundColor: var(--cc-surface1-surface)、handleColor: var(--cc-surface1-surface)、optionsTextColor: var(--cc-primary-text)均为主题变量随深色模式自动适配被禁用的选项会忽略这些配色统一显示为禁用色var(--surfaces-surface-03)与var(--icons-default)。Container 区域Padding通过启用Default选项保持标准内边距另有None选项源码中padding默认default不支持 fx 动态配置。11. 实践要点小结选项数据优先使用动态模式Schema表达式可从queries、components、clientUser等上下文中派生且default字段可基于 Table 选中行等状态实现预选程序化控制用 CSAselectOption/deselectOption/setVisibility/setLoading/setDisable/clear程序化改值同样会触发 On select 事件可驱动事件链动态选项异步生成期间打开Options loading state避免空选项闪烁校验组合使用 mandatory 与 custom validationisValid暴露变量可用于控制提交按钮的启用状态若选项较多将Layout设为wrap或column利用组件自带的溢出滚动与换行能力。以上属性、默认值与行为均可在 radio-button.md、radioButtonV2.js 与 RadioButtonV2.jsx 中核对。【免费下载链接】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），仅供参考