ToolJet Button Group 组件完全指南：属性、事件、暴露变量与样式详解-平芜编程栈

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/ToolJet

Button 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.js（displayName: 'Button Group (Legacy)'）。旧版组件仍可继续使用，但新应用建议优先使用新版以获得更完整的校验、加载态与图标支持。本文以文档描述的新版组件为主，旧版差异会在对应小节说明。

组件源码位于 ButtonGroupV2.jsx，渲染时输出带有role="group"语义的容器，内部每个按钮通过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]}}等属性。

属性（Properties）

Button 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 组件渲染标题，并支持alignment（side/top）、direction（left/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等暴露方法的传参约定（数组入参），使用时应以新版行为为准。

事件（Events）

Button Group 暴露一个核心事件：

事件	说明
On click	用户点击按钮组中的任意按钮时触发

On click事件的触发时机在源码中有明确体现：无论单选还是多选，每次按钮点击都会调用fireEvent('onClick')（见 ButtonGroupV2.jsx 的handleButtonClick）。也就是说，每次点击都会触发事件，事件回调里可以通过components.buttongroup1.selected读取到点击后的最新选中值。

上图展示了在构建器中为 Button Group 配置事件的典型流程：添加On click事件后，关联一个 Action（这里为 Show Alert，Message 为 "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 文档明确指出：当前没有为按钮组实现用于控制或调节组件的 CSA（Component-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 时启用提交按钮）。

通用（General）

Tooltip（工具提示）

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}}即可。

样式（Styles）

Button Group 的样式面板可整体调整按钮组的观感。以下为文档列出的样式项（旧版组件样式）：

样式	说明	期望值
Background color	设置按钮组中按钮的背景色	取色器选色或输入 Hex 色值，如`#000000`
Text color	设置按钮组中按钮的文字颜色	取色器选色或输入 Hex 色值，如`#000000`
Visibility	控制组件可见/隐藏	`{{true}}`或`{{false}}`，默认`{{true}}`
Disable	禁用组件	`{{true}}`或`{{false}}`，默认`{{false}}`
Border radius	设置按钮圆角	`0`到`100`的数值
Selected text color	修改选中按钮的文字颜色	取色器选色或输入 Hex 色值，如`#000000`
Selected background color	修改选中按钮的背景颜色	取色器选色或输入 Hex 色值，如`#000000`
Box shadow	为组件框架添加阴影效果（X/Y 偏移、模糊、扩散半径与颜色）	形如`9px 11px 5px 5px #00000040`的值

禁用态在源码中的实现是：按钮透明度降至0.5、pointer-events: none、光标变为not-allowed，并同步设置aria-disabled（见 ButtonGroup.jsx 与 ButtonGroupV2.jsx）。选中态则通过selectedBackgroundColor/selectedTextColor覆盖默认背景与文字色。

新版组件的扩展样式

新版 Button Group（buttonGroupV2.js）在旧版样式基础上大幅扩展，按折叠面板组织为几组：

Label（标签）：labelColor（标签颜色）、labelFontSize（字号，默认 12）、alignment（side/top）、direction（left/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（容器）：padding（default/none，影响组件高度计算，源码中padding === 'none'时高度增加 4px，见 ButtonGroupV2.jsx）。

此外，新版组件还支持给每个按钮配置图标（icon字段，使用 ToolJet 内置 Tabler 图标名，如IconBolt、IconBulb、IconTag）以及单项禁用（disable）与默认选中（default）标记，这些通过"Options"折叠面板中的Mapped button（advanced 模式，使用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.text=='yes'&&'valid'}}）。校验失败时按钮组下方会以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控制提交按钮的可用性。
可访问性：组件渲染时带role="group"、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 与其他组件联动，即可快速搭建具备动态筛选、视图切换和表单校验能力的内部应用。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考