ToolJet Button Group 组件完全指南属性、事件、暴露变量与样式详解【免费下载链接】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/ToolJetButton Group按钮组是 ToolJet 低代码应用构建器中用于将一系列相关按钮排列在单行内的基础组件常被用来实现单选/多选的分段控制式交互。本文以 docs/docs/widgets/button-group.md 为核心结合仓库前端源码系统讲解其属性配置、事件绑定、暴露变量、通用设置与样式体系并展示如何在构建器App Builder中实际使用它。阅读对象正在使用 ToolJet App Builder 搭建内部工具、仪表盘或业务应用的开发者。读完本文你将掌握 Button Group 的完整配置方法、用表达式动态驱动其行为的方式以及如何通过事件与 Action 联动其他组件。组件概览Button Group 组件用于把一组彼此相关的按钮放在同一行展示例如视图切换表格/看板/日历、状态筛选全部/进行中/已完成、时间粒度切换日/周/月等场景。在 ToolJet 的组件分类中它属于表单类交互组件默认宽度为 12 列、高度为 80px见 buttonGroupV2.js 的defaultSize。从仓库源码看Button Group 的组件注册信息定义在 buttonGroupV2.js新版displayName: Button Group同时保留了一个旧版配置 buttonGroup.jsdisplayName: Button Group (Legacy)。旧版组件仍可继续使用但新应用建议优先使用新版以获得更完整的校验、加载态与图标支持。本文以文档描述的新版组件为主旧版差异会在对应小节说明。组件源码位于 ButtonGroupV2.jsx渲染时输出带有rolegroup语义的容器内部每个按钮通过data-cy属性暴露测试钩子buttongroup1-button-0之类方便 Cypress 等端到端测试定位相关测试用例可参考 componentsBasicHappypath.skip.js。上图展示了 Button Group 在 App Builder 中的典型形态左侧画布上是一个名为buttongroup1的按钮组包含 A、B、C 三个按钮A 为选中态右侧 Properties 面板中对应配置了values {{[1,2,3]}}、Labels {{[A,B,C]}}、Default selected {{[1]}}等属性。属性PropertiesButton Group 的属性决定了按钮组的内容、标签和初始状态。将组件拖入画布后点击组件并在右侧属性面板即可配置以下属性。属性说明期望值label设置按钮组的标题组标签任意字符串如Select the options或动态值{{queries.queryname.data.text}}values设置按钮组各按钮的值字符串/数字组成的数组如{{[1,2,3]}}Labels设置按钮组各按钮的显示文本字符串/数字组成的数组如{{[A,B,C]}}Default selected设置初始选中的按钮值数组如{{[1]}}表示默认选中第一个按钮Enable multiple selection开启/关闭多选模式布尔值{{true}}或{{false}}label按钮组标题label用于给整个按钮组一个说明性标题渲染为组件上方的标签文本。它可以是静态字符串也可以使用双花括号表达式动态计算例如{{queries.getUser.data.name}}。在源码中新版组件通过 Label 组件 渲染标题并支持alignmentside/top、directionleft/right、auto宽度、labelWidth、labelColor、labelFontSize等标签级样式配置而旧版组件ButtonGroup.jsx则简单地渲染一个p标签仅在 label 非空时显示。values按钮的值values数组定义了每个按钮对应的内部值它是按钮参与选中逻辑、事件回调与暴露变量的核心依据。它可以是数字数组{{[1,2,3]}}也可以是字符串数组{{[pending,completed]}}甚至是查询返回的数据{{queries.getStatuses.data}}。值得注意的源码细节旧版组件在useEffect中会将defaultSelected与values取交集defaultSelected.filter((item) values.includes(item))即默认选中值不在 values 中时会被自动过滤保证选中的一定是有效按钮见 ButtonGroup.jsx。新版组件则通过validOptionValues约束setSelected传入的值同样会过滤无效项见 ButtonGroupV2.jsx。Labels按钮的显示文本Labels数组定义每个按钮在界面上显示的文字。若其长度小于values长度源码会按索引将前几个 Label 覆盖到对应按钮上其余按钮回退显示 values 中的原始值若 Labels 长度大于等于 values则完全以 Labels 显示见 ButtonGroup.jsx。因此你完全可以做到值为 1、2、3显示为 A、B、C实现值与文案解耦。Default selected初始选中项Default selected决定应用运行时按钮组的初始选中状态。文档示例{{[1]}}表示默认选中值为1的那个按钮。需要注意它始终是一个数组——即使单选模式下也只取数组中的第一个有效值。旧版组件的setSelected逻辑里单选模式传入数组时会取filteredItems[0]作为唯一选中项见 ButtonGroup.jsx新版组件在单选模式下也只会保留第一个值见 ButtonGroupV2.jsx。Enable multiple selection多选开关开启后用户可以同时选中多个按钮点击已选中的按钮会将其从选中集合中移除再次点击取消选中点击未选中的按钮则追加进选中集合单选模式下点击新按钮会替换当前选中项再次点击当前选中按钮则取消选中。该开关在属性面板中是一个 Toggle值为布尔表达式。旧版组件在开启多选时setExposedVariable(selected, ...)写入的是用逗号拼接的字符串如1,2新版组件则始终写入数组见 ButtonGroup.jsx 与 ButtonGroupV2.jsx。在新版组件中多选还会影响clear、setSelected等暴露方法的传参约定数组入参使用时应以新版行为为准。事件EventsButton Group 暴露一个核心事件事件说明On click用户点击按钮组中的任意按钮时触发On click事件的触发时机在源码中有明确体现无论单选还是多选每次按钮点击都会调用fireEvent(onClick)见 ButtonGroupV2.jsx 的handleButtonClick。也就是说每次点击都会触发事件事件回调里可以通过components.buttongroup1.selected读取到点击后的最新选中值。上图展示了在构建器中为 Button Group 配置事件的典型流程添加On click事件后关联一个 Action这里为 Show AlertMessage 为 Hello world!Alert Type 为 Info。事件面板会列出当前组件已绑定的所有事件。ToolJet 的事件系统支持将事件连接到多种 Action如 Show Alert、Run Query、控制组件、跳转页面、发送邮件等。关于全部 Action 的详细说明参见文档 Actions 参考目录原文档中的 Action Reference 页面对应此目录。// 事件回调中读取点击后的选中值示例 {{ components.buttongroup1.selected }}典型用法On click 事件中执行 Run Query将{{components.buttongroup1.selected}}作为查询参数实现点击按钮 → 动态筛选表格数据的联动。组件专属动作Component Specific Actions / CSA旧版 Button Group 文档明确指出当前没有为按钮组实现用于控制或调节组件的 CSAComponent-Specific Actions。不过在新版组件中源码为组件暴露了一组可编程动作actions配置见 buttonGroupV2.js它们等价于其他组件的 CSA可在事件动作如 Run Query / Run JavaScript Code中通过components.buttongroup1.方法名(...)调用动作 handle说明参数setSelected以编程方式选中指定值selected值或值数组clear清空所有选中项无setDisable设置禁用状态disable布尔setLoading设置加载状态loading布尔setVisibility设置可见状态disable布尔其实现位于 ButtonGroupV2.jsx 的useEffect中setSelected会校验传入值是否存在于有效选项validOptionValues中非法值会被过滤clear将选中集合置空并触发校验setDisable/setLoading/setVisibility会同时更新内部状态并同步到暴露变量。// 示例在 JavaScript 代码中通过暴露方法控制按钮组 await components.buttongroup1.setSelected([1, 2]); // 选中值为 1 和 2 的按钮多选模式 await components.buttongroup1.clear(); // 清空选择 await components.buttongroup1.setDisable(true); // 禁用整个按钮组旧版组件仅暴露setSelected一个动作见 buttonGroup.js 的actions且其实现同样会过滤不在values中的值。暴露变量Exposed Variables变量说明访问方式selected保存当前选中的按钮值数组动态访问{{components.buttongroup1.selected[0]}}或{{components.buttongroup1.selected}}selected是 Button Group 最常用的暴露变量在事件回调、查询参数、其他组件的属性表达式中均可引用。例如// 单选场景取第一个选中值 {{ components.buttongroup1.selected[0] }} // 多选场景直接引用整个数组 {{ components.buttongroup1.selected }}旧版组件在多选时selected暴露的是逗号拼接的字符串如1,2见 ButtonGroup.jsx 的setExposedVariable(selected, copyDefaultActive.join(,))而新版组件始终暴露数组见 ButtonGroupV2.jsx并且额外暴露了以下状态变量变量说明isVisible组件当前是否可见isDisabled组件当前是否被禁用isLoading组件当前是否处于加载态isValid当前值是否通过校验这些变量由 ButtonGroupV2.jsx 通过setExposedVariable同步到components.buttongroup1.*可用于条件逻辑判断例如仅在{{components.buttongroup1.isValid}}为 true 时启用提交按钮。通用GeneralTooltip工具提示Tooltip 用于在用户将鼠标悬停在组件上时显示额外说明信息。在通用面板的 Tooltip 字段中填入字符串后悬停即可看到提示气泡。文档示例中为按钮组配置了Select an option的提示文本新版组件还支持通过tooltipFormat切换提示内容的渲染格式Plain text / Markdown / HTML默认plainText并可用表达式动态生成提示内容见 buttonGroupV2.js 的tooltip与tooltipFormat配置。Tooltip 字段支持双花括号表达式例如根据选中值动态提示{{当前选择 components.buttongroup1.selected.join(, )}}。设备适配Devices属性说明期望值Show on desktop控制组件在桌面视图中是否可见通过开关设置或点击fx动态配置逻辑表达式Show on mobile控制组件在移动视图中是否可见通过开关设置或点击fx动态配置逻辑表达式两个属性控制响应式可见性例如默认配置为桌面显示{{true}}、移动端隐藏{{false}}见 buttonGroupV2.js 的definition.others。若希望移动端也显示将其切换为{{true}}即可。样式StylesButton Group 的样式面板可整体调整按钮组的观感。以下为文档列出的样式项旧版组件样式样式说明期望值Background color设置按钮组中按钮的背景色取色器选色或输入 Hex 色值如#000000Text color设置按钮组中按钮的文字颜色取色器选色或输入 Hex 色值如#000000Visibility控制组件可见/隐藏{{true}}或{{false}}默认{{true}}Disable禁用组件{{true}}或{{false}}默认{{false}}Border radius设置按钮圆角0到100的数值Selected text color修改选中按钮的文字颜色取色器选色或输入 Hex 色值如#000000Selected background color修改选中按钮的背景颜色取色器选色或输入 Hex 色值如#000000Box shadow为组件框架添加阴影效果X/Y 偏移、模糊、扩散半径与颜色形如9px 11px 5px 5px #00000040的值禁用态在源码中的实现是按钮透明度降至0.5、pointer-events: none、光标变为not-allowed并同步设置aria-disabled见 ButtonGroup.jsx 与 ButtonGroupV2.jsx。选中态则通过selectedBackgroundColor/selectedTextColor覆盖默认背景与文字色。新版组件的扩展样式新版 Button GroupbuttonGroupV2.js在旧版样式基础上大幅扩展按折叠面板组织为几组Label标签labelColor标签颜色、labelFontSize字号默认 12、alignmentside/top、directionleft/right、auto宽度自适应默认开、labelWidth标签宽度滑块。Buttons按钮backgroundColor背景默认var(--cc-surface1-surface)、hoverBackgroundMode悬停背景 auto/manual默认 auto、hoverBackgroundColor、borderColor边框色、textColor文字色、textSize字号默认 14、fontWeight字重 normal/medium/bold/lighter/bolder、iconColor/selectedIconColor图标颜色、selectedBackgroundColor/selectedTextColor选中态、errTextColor校验错误文案颜色、borderRadius圆角默认 6、btnAlignment按钮组对齐 left/center/right、boxShadow默认0px 0px 0px 0px #00000040。Container容器paddingdefault/none影响组件高度计算源码中padding none时高度增加 4px见 ButtonGroupV2.jsx。此外新版组件还支持给每个按钮配置图标icon字段使用 ToolJet 内置 Tabler 图标名如IconBolt、IconBulb、IconTag以及单项禁用disable与默认选中default标记这些通过Options折叠面板中的Mapped buttonadvanced 模式使用schema数组或图形化options列表配置。schema 的默认值形如{{[{label:Button1,value:1,icon:IconBolt,iconVisibility:false,disable:false,default:true}, ...]}}校验与表单集成新版新版组件集成在表单校验体系中可在属性面板的 Validation 区域开启Make this field mandatory必填校验或编写Custom validation自定义规则placeholder 示例{{components.text2.textyesvalid}}。校验失败时按钮组下方会以errTextColor颜色显示错误文案且容器上会设置aria-invalid见 ButtonGroupV2.jsx 与 buttonGroupV2.js 的validation配置。将其放入 ToolJet 的 Form 容器内即可参与表单提交校验配合clear暴露方法实现表单重置时清空选择源码中通过useFormClear挂接 Form 的清除信号见 ButtonGroupV2.jsx。常见使用场景与最佳实践分段控制器Segmented Control用values{{[list,board,calendar]}}、Labels{{[列表,看板,日历]}}做视图切换On click 事件里根据{{components.buttongroup1.selected[0]}}切换表格组件的可见性或数据源。状态筛选按钮组 查询联动将selected作为查询参数传给后端例如{{components.buttongroup1.selected[0]}}作为status过滤条件。动态数据驱动values/Labels 直接绑定查询结果数组配合{{queries.getOptions.data}}实现运行时动态生成按钮。表单单选/多选开启必填校验后放入 Form 容器结合clear动作实现表单重置用isValid控制提交按钮的可用性。可访问性组件渲染时带rolegroup、aria-labelledby、aria-disabled、aria-invalid等 ARIA 属性便于无障碍工具识别也建议配合 Tooltip 给出操作提示。使用旧版还是新版新建应用请直接使用新版 Button Group更多样式、校验、加载态与图标能力若在旧应用中已使用 Legacy 版本且无需上述能力可保持现状迁移时注意selected变量从字符串到数组的行为差异。总结Button Group 是 ToolJet 中实现单选/多选分组交互的轻量组件。本文覆盖了其属性label/values/Labels/Default selected/多选开关、唯一事件 On click、暴露变量selected新版另有isVisible/isDisabled/isLoading/isValid、工具提示、设备适配与完整样式体系并对照源码 ButtonGroupV2.jsx 与组件配置 buttonGroupV2.js 解释了底层实现细节值过滤、多选拼接、校验联动等。配合事件 Action 与其他组件联动即可快速搭建具备动态筛选、视图切换和表单校验能力的内部应用。【免费下载链接】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），仅供参考