Segmented
在少量互斥视图或模式间切换。中文惯用名：分段控制器。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.segmented |
| 名称 | Segmented |
| 二级分类 | 数据展示（data-display） |
| 用途 | 在少量互斥视图或模式间切换 |
| 描述 | 中文惯用名：分段控制器。 |
预览
静态结构：Segmented 渲染 role="radiogroup" 的药丸容器（rounded-full 灰底 + p-1），选项为 role="radio" 的 pill 按钮；选中项高亮由独立的滑动指示块（data-slot="segmented-indicator"，absolute 白底圆角块 + shadow-sm）承载，切换时指示块经 left/width 过渡平滑滑向新选中项（motion-safe 生效，尊重减弱动态偏好），选中文字加粗、未选中弱化文字；选项可前置 Icon 白名单图标，选项级 disabled 或整体 disabled 半透明禁用。Form 集成同 Slider 模式：在 Form 内声明非空 name 即经 registerField 注册（携带 rules，value 作为字段初始值、优先于 Form initialValues），外层包 FieldShell 呈现 label 与校验错误，className / style 挂到 form-item 容器；独立渲染时 value 为受控值、onChange 传出选中项 value（DSL 语义值），className / style 挂控件本身。
DSL 结构
{
"type": "Segmented",
"props": {
"name": "period",
"value": "month",
"options": [
{
"label": "日",
"value": "day"
},
{
"label": "周",
"value": "week"
},
{
"label": "月",
"value": "month"
},
{
"label": "年",
"value": "year"
}
]
}
}何时用
何时使用
- 在少量（2-5 个）互斥视图、模式或维度间切换：列表 / 网格、日 / 周 / 月、全部 / 未读。
- 切换立即生效、只改变同区域内容的呈现方式，不切换页面上下文。
- Form 内作为单选字段（声明 name 即自动注册，参与校验与提交）。
何时不用
- 选项多、需承载复杂内容面板或路由语义（可分享、可深链的标签页）：使用 Tabs。
- 表单内长列表单选：使用 RadioGroup / Select；Segmented 选项需短文案平铺。
- 二元开关（开 / 关）：使用 Switch；多选：使用 Checkbox 组。
- 触发动作而非切换状态：使用 Button。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认（文本选项） | 药丸容器 + 文本 pill，选中白底浮起 | 视图 / 维度切换（如「列表 |
| 图标选项 | 选项前置 Icon 白名单图标 | 图标增强辨识的模式切换（如视图形态） |
| Form 表单项 | FieldShell 包裹：label + 控件 + 校验错误 | 表单内单选字段（声明 name 自动注册） |
| 受控 / 非受控 | value 受控或内部状态自管 | 独立渲染时与外部状态联动或自管 |
| 禁用态 | 整体或选项级半透明禁用 | 暂不可用的模式或权限受限选项 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明 name 即自动成为表单项 |
label | string | — | 表单项标签（仅 Form 内生效） |
rules | FieldRule[] | — | 校验规则（注册字段时携带） |
options | SegmentedOption[] | [] | 选项列表（可含表达式解析后的数组）；项结构 { label, value: string |
value | `string | number` | — |
disabled | boolean | false | 整体禁用；选项级禁用用 options 项的 disabled |
onChange | `(value: string | number) => void` | — |
className | string | — | 通用：根节点 class（Form 内为 form-item 容器，独立渲染时为控件本身） |
style | CSSProperties | — | 通用：根节点内联样式（同 className 的挂载规则） |
使用规范
- 选项控制在 2-5 个、label 为 1-4 字短文案；超出或需要内容面板 / 路由语义时改用 Tabs。
- value 与选项 value 严格同型（string | number 不混用），否则选中态匹配失败。
- Form 内使用必须声明非空 name；rules 随字段注册，value 作初始值且优先于 Form initialValues。
- 独立渲染受控场景：传 value 并在 onChange 回写；不传 value 时组件自管内部状态。
- 切换应立即反映到关联内容；切换代价高（重新拉取大量数据）的场景用 Tabs + 显式加载态更合适。
- 禁用整体用 disabled，个别选项不可用用选项级 disabled，并对禁用原因给出上下文提示。
正例
- ✓ 看板顶部：options「日 / 周 / 月」，onChange 切换图表统计维度，value 受控同步查询参数。
- ✓ Form 内「通知方式」：name="notify" + label + rules 必填，随表单校验提交。
- ✓ 视图切换：选项配 icon（list / grid 图标），纯展示切换无路由跳转。
反例
- ✕ 用 Segmented 做页面级标签导航或承载路由语义（应使用 Tabs）。
- ✕ 塞入 7、8 个长文案选项导致 pill 挤压换行（应改用 Select / RadioGroup）。
- ✕ 受控传入 value 却不处理 onChange 回写，或选项 value 字符串数字混用导致选中态丢失。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。