ToggleGroup 切换组
Forms
智能自动检测
简介
ToggleGroup 组件是一组切换按钮，用于单选或多选场景。它常用于让用户选择互斥的布局样式（例如 Grid 与 List 视图切换器），或组合包容性的修饰项（例如粗体、斜体、下划线的文本格式化按钮）。
ToggleGroup 已在 Page Builder 中作为 toggleGroup 区块完整集成，内容编辑者与开发者可直接在 CMS 内轻松配置视觉选项、多选行为以及激活态配色方案。
用法
以下示例展示了内容编辑者如何绑定并组织交互式切换按钮。
1. 多选文本格式化工具栏
允许多个按钮同时被按下并处于激活态，非常适合多选功能开关或文本编辑器面板。
{
"type": "toggleGroup",
"multiple": true,
"defaultValue": ["bold"],
"items": [
{ "label": "B", "value": "bold" },
{ "label": "I", "value": "italic" },
{ "label": "U", "value": "underline" }
],
"interactive": true
}
2. 单选布局切换器（紫色主题）
演示单选模式，同一时刻仅有一个按钮可激活。激活项使用自定义的紫色主题 token 进行样式修饰。
{
"type": "toggleGroup",
"multiple": false,
"defaultValue": ["list"],
"items": [
{ "label": "Grid View", "value": "grid" },
{ "label": "List View", "value": "list" }
],
"colorPalette": "purple",
"interactive": true
}
3. 紧凑型垂直导航组
将切换选项按垂直方向排列，并使用紧凑的尺寸刻度。
{
"type": "toggleGroup",
"orientation": "vertical",
"defaultValue": ["dashboard"],
"items": [
{ "label": "Dashboard", "value": "dashboard" },
{ "label": "Settings", "value": "settings" }
],
"size": "sm",
"interactive": true
}
属性
| 属性 | CMS 字段类型 | 默认值 | 说明 / 可选项 |
|---|---|---|---|
多选 (multiple) | boolean | false | 允许同时切换激活多个按钮项。 |
初始激活值 (defaultValue) | list | [] | 表示以激活态开始的按钮选项的字符串值列表。 |
激活值 (value) | list | - | 表示当前激活选项的字符串值列表（受控）。 |
按钮项 (items) | list | [] | 切换按钮的有序集合。（参见下方切换项 schema）。 |
布局流向 (orientation) | select | "horizontal" | 切换选项的排列方式。 • 选项： "horizontal"、"vertical"。 |
视觉样式 (variant) | select | "outline" | 结构布局变体。 • 选项： "outline"、"ghost"。 |
尺寸刻度 (size) | select | "md" | 控制整体高度、内边距与文本缩放。 • 选项： "sm"、"md"、"lg"。 |
配色主题 (colorPalette) | select | "green" | 应用于激活按钮的视觉色彩强调。 • 选项： blue、green、red、purple、orange、amber、cyan、slate。 |
强制交互 (interactive) | boolean | true | 将组件作为交互式客户端岛屿进行水合，以协调对齐并处理键盘路由。 |
切换组项 Schema
items 数组中的每个条目都接受以下参数：
| 属性 | CMS 字段类型 | 必填 | 说明 |
|---|---|---|---|
显示文本 (label) | string | 是 | 渲染在切换按钮内部的标签文本。 |
唯一键 (value) | string | 是 | 引用该选项激活状态的关键标识符。 |
禁用 (disabled) | boolean | false | 禁用用户交互并淡化该按钮的样式。 |
开发者说明与无障碍
- WAI-ARIA 无障碍模式： 渲染出健壮的键盘可导航工具栏：
- 根容器接收
role="group"。 - 当
multiple为 true 时，单项渲染为role="checkbox"并带有aria-checked状态；否则渲染为role="radio"并带有aria-checked状态。
- 根容器接收
- 漫游焦点键盘导航： 支持原生焦点移动：
- 方向键（Right/Down 向前移动，Left/Up 向后移动）会根据所选
orientation轴自动在激活按钮间漫游焦点。 - Home 与 End 键可立即将焦点跳转到组内第一个与最后一个可用按钮。
- 方向键（Right/Down 向前移动，Left/Up 向后移动）会根据所选
- 表单关联： 切换选项无缝更新关联的 state 上下文，使父容器或表单钩子能够动态捕获变更。