# ToggleGroup 切换组
单选/多选互斥的按钮组：单选组用 radio 语义、多选组用 checkbox 语义，键盘方向键与 Home/End 导航，受控 `value`。支持尺寸档、纵向、贴合形态、项图标、强制选中、多选上限、满宽均分、选中色与校验态。
## 何时用 ToggleGroup，何时用 ButtonGroup
- **oas-toggle-group（本组件）**：**状态选择**——`value` 受控的「选中状态集合」，radio/checkbox 语义（`aria-checked`）、单选/多选、roving 键盘、mandatory / max-count / status 等表单能力。适合视图切换、筛选条件、富文本样式开关等状态机场景。
- **oas-button-group**：**动作编排**——组内按钮各自触发动作（`oas-click`），无选中状态语义；它也保留了 `value` / `multiple` 的选值形态，新代码的状态选择场景推荐使用 toggle-group（ARIA 语义与键盘模型更完整）。
## 单选
不设 `multiple` 时为单选（`role="radiogroup"` + `radio`），`value` 为字符串，同一时刻只有一项按下。
当前：day
## 多选
设置 `multiple` 后为多选（`role="group"` + `checkbox`），`value` 为 JSON 数组字符串。
当前：[]
## 禁用
项级 `disabled: true` 禁选；禁用项不参与键盘导航。
## 受控选中（value）
`value` 为受控通道：单选为字符串、多选为 JSON 数组字符串；外部设置属性即时反映到选中态（组内点击也会回写该属性）。以下用按钮外部驱动选中：
单选：日
单选：月
多选：斜体+下划线
预设 `value="week"` / `value='["bold"]'` 使两个组初始即带选中态；按钮外部写入 `value` 属性后选中态即时切换。
## 子元素声明式通道
除 `items` JSON 外，可用 `` 子元素声明式书写选项（`items` 属性*显式设置时优先*，未设置时解析子元素收敛到同一渲染路径）。默认插槽文本为 label，属性对齐 `ToggleItem` 字段：`value` / `disabled` / `icon` / `aria-label`。子元素增删、属性与文本变化会自动重渲染（MutationObserver）；单选/多选（`multiple`）语义与 items 通道完全一致。
日
周
月（禁用）
加粗
斜体
下划线
动态追加一项
## 尺寸档（size）
`size` 三档 `small` / `medium`（默认）/ `large`，控高与字号对齐全局 token；未显式设置时就近读取 config-provider 的 `size` 注入（全局密度联动）。表格行内用 small、筛选条用 large：
## 图标与纯图标项（icon / icon-only）
`items` 项加 `icon` 字段（或子元素 `icon` 属性）在文字前渲染图标（`@oas-ui/icons` 注册表图标名）。**无 label 的图标项自动进入纯图标形态**（等宽正方形），可访问名兜底取图标名，建议用 `ariaLabel` 字段提供更准确的名称；有 label 的项也可用 `ariaLabel` 覆盖可访问名（如富文本的「B」读作「加粗」）。
富文本工具栏是经典场景——字样样式用多选、对齐方式用单选：
B
I
U
S
左对齐
居中
右对齐
样式: bold | 对齐: left
## 纵向排布（vertical）
`vertical` 布尔属性切换为纵向组（同步 `aria-orientation="vertical"`），与纯图标组合是视图切换的经典形态：
视图：list
右侧为 `attached` 纵向贴合形态。长选项组纵向排布（带文字）同理：`vertical` + 普通 items 即可。
## 贴合形态（attached）
默认**分离**（按钮间有 gap、各自圆角，维持现状）；`attached` 布尔属性开启**贴合**——间距归零、相邻边框合并为 1px、仅组两端保留圆角（横向左右合并、纵向上下合并，逻辑属性适配 RTL）。hover / 聚焦 / 选中项自动浮于邻项之上，边框不被压线：
## 组级形态（variant）
`variant` 组级形态透传各切换项（对齐 `oas-button` 的 variant 体系）：`solid`（默认，描边容器、选中实底）/ `outlined`（透明底描边，选中主色描边 + 淡底着色）/ `filled`（浅底无描边，选中实底）/ `text`（无框无底，选中淡底 + 主色文字）。非法值静默回落 `solid`；与 `attached` / `vertical` / `color` / `status` 正交（status 语义色优先）。视图切换、富文本样式组适合 `attached + solid`，筛选面板适合 `filled` 或 `outlined`：
对齐: []
## 满宽均分（spread）
`spread` 布尔属性使组占满父容器宽度、选项等宽均分（移动端操作栏 / 筛选条形态）；纵向组同样占满宽度：
## 强制选中（mandatory）
- `mandatory`（布尔）：**多选最后一项不可取消**（点击/键盘拦截，不派发事件）；单选为 radio 语义天然不可全空，无感保持。
- `mandatory="force"`：蕴含上述拦截，并在**空态时自动选第一个非禁用项**——初始无 value、value 被清空、value 指向不存在的项、选项动态变化后落空，都会自动兜底。向导流（日/周/月必须选一个）零宿主代码：
统计周期（force，初始未设 value）：
导出格式（多选 mandatory，至少保留一项）：
周期: day | 格式: pdf
注意：`force` 的自动兜底**只回写 `value` 属性、不派发 `oas-change`**（非用户交互；value 属性即受控真相源），宿主监听属性变化或读取 value 即可。
## 多选上限（max-count）
`max-count`（仅 `multiple` 生效）限制最多选中数：**达上限后未选项置灰**（与禁用同视觉，`aria-disabled` 同步），点击/键盘拦截并派发 `oas-exceed-limit`（`detail: { value, max }`）；**已选项仍可取消**，取消后未选项恢复可选。非法值 / `0` / 负数视为无上限；单选模式不生效：
已选 1 / 2
## 选中色（color）
`color` 按 ui-spec 统一协议解析：任意 CSS 色值（`#0e7490` / `rgb(...)`，实底文字色按亮度自动取黑/白）优先；11 预设名（`magenta / red / volcano / orange / gold / lime / green / cyan / blue / geekblue / purple`）解析为 `--oas-preset-*` token（明暗主题自适应）；缺省主色。主题级批量定制走 CSS 变量 `--oas-toggle-color` / `--oas-toggle-on-color`：
## 表单校验（status）
`status` 三态 `success` / `warning` / `error`：未选项边框着语义色、选中项整块着色、focus ring 同步染色；`error` 联动宿主 `aria-invalid`（宿主自设 `aria-invalid="true"` 等效 error 视觉）。提交校验场景：
接收渠道：
保存
请至少选择一种接收渠道
## 事件
点击或键盘切换派发 `oas-change`，单选 `detail: { value: string }`，多选 `detail: { value: string[] }`。
oas-change: { value: "left" }
## API
### oas-toggle-group
#### 属性
| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `aria-label` | 组可访问名（宿主覆盖；缺省走 locale 兜底） | — | — |
| `attached` | 贴合形态：邻接项共享边线、首尾圆角（默认分离） | — | — |
| `color` | 选中色：预设名或任意 CSS 色值（自动算文字色） | `string` | — |
| `disabled` | 禁用整个切换组（自身显式禁用，或经 config-provider 全局禁用注入继承） | `boolean` | — |
| `items` | 选项 JSON（property 赋值单向反射 attribute） | `ToggleItem[] \| string` | `[]` |
| `mandatory` | 强制选中：布尔=唯一选中项不可取消；`force`=空态自动选首个非禁用项（向导流零代码） | — | — |
| `max-count` | 多选上限：达上限未选项置灰并派 oas-exceed-limit，已选项仍可取消 | `string` | — |
| `multiple` | 多选模式（checkbox 语义） | `boolean` | — |
| `size` | 尺寸档位 `small` / `medium`（默认）/ `large` | `string` | `medium` |
| `spread` | 满宽等分（对齐 button-group 的 spread） | — | — |
| `status` | 校验态：`error` / `warning` / `success`（未选项边框色 + 选中项整块着色） | `string` | — |
| `value` | 当前值：单选为字符串；多选为 JSON 数组字符串 | `string \| string[]` | `[]` |
| `variant` | 组级形态透传各切换项（对齐 button variant 体系）：`solid`（默认，描边容器、选中实底）/ `outlined`（透明底描边，选中主色描边 + 淡底）/ `filled`（浅底无描边，选中实底）/ `text`（无框无底，选中淡底 + 主色文字）；非法值静默回落 solid；与 attached/vertical 正交 | `string` | — |
| `vertical` | 纵向排列（联动 aria-orientation 与轴向键） | `boolean` | — |
#### Property（JS property；是否写回 attribute 见各行说明）
| Property | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `value` | 当前值：单选取选中值字符串，`multiple` 时取选中值数组 | `string \| string[]` | — |
#### 事件
| 事件 | 说明 |
| --- | --- |
| `oas-change` | 切换，`detail: { value: string \| string[] }` |
| `oas-exceed-limit` | 达 max-count 上限后的越界选择尝试，`detail: { value, max }` |
#### CSS 变量
| CSS 变量 | 默认值 |
| --- | --- |
| `--oas-toggle-color` | `var(--oas-color-primary)` |
| `--oas-toggle-on-color` | `var(--oas-color-text-on-primary)` |
| `--oas-toggle-tint-text` | `var(--oas-color-primary-text)` |
### oas-toggle-item
#### 属性
| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `aria-label` | 该项可访问名（纯图标项必填语义；缺省由图标名派生） | — | — |
| `disabled` | 禁用该项（点击不可选，方向键跳过） | — | — |
| `icon` | 图标（oas-icon 图标名）；label 可省（纯图标项） | — | — |
| `value` | 选项值（子元素声明式通道的数据载体字段） | — | — |
#### 插槽
| 名称 | 说明 |
| --- | --- |
| 默认 | 按钮文案（默认插槽文本） |
`ToggleItem` 字段：
| 字段 | 说明 | 类型 |
| ---------- | ------------ | --------- |
| `label` | 按钮文案（icon-only 项可省略） | `string` |
| `value` | 值（随事件回传） | `string` |
| `disabled` | 禁用该项 | `boolean` |
| `icon` | 前置图标（`@oas-ui/icons` 注册表图标名）；无 label 时进入纯图标形态 | `string` |
| `ariaLabel` | 项级可访问名称覆盖（缺省：label 文本；icon-only 时兜底图标名） | `string` |
键盘：单选模式方向键移动并选中（radio 组惯例）；多选模式方向键移动焦点（roving tabindex）、Space/Enter 切换；Home/End 直达首/末可用项（跳过禁用项）。容器 `role="radiogroup"` / `role="group"` + `aria-label`（宿主 `aria-label` 属性覆盖 locale 兜底），选中项 `aria-checked`；`vertical` 同步 `aria-orientation="vertical"`。