组件 / 输入
分段控制
使用中性选中状态在同级视图之间切换。
结构
组成部分
- 01中性容器
- 02选中项
- 03未选项
- 04可见焦点环
预览
交互调整
使用中性色表示选中
当前：周 · 中性选中
当前 Token
component.segment.background.containercomponent.segment.background.selectedcomponent.segment.text.selectedcomponent.segment.height.md
<SegmentedControl aria-label="时间范围" size="md" options={ranges} />外观
视觉样式
- 仅中性
尺寸
规格
- 小 · 36px
- 中 · 44px
状态
交互状态
内容
使用规则
建议
- 使用浮起的中性表面表达选中。
- 选项保持同一层级和相近长度。
避免
- 不要使用强调色填充、文字或边框表达选中。
- 不要把分段控制用于多选。
Token
组件映射
| 名称 | 类型 | 浅色 | 深色 | 预览 |
|---|---|---|---|---|
component.segment.background.container分段控制容器 | color | oklch(0.95 0 255) | oklch(0.38 0.007 255) | |
component.segment.background.selected分段控制选中背景 | color | oklch(1 0 0) | oklch(0.29 0.003 255) | |
component.segment.background.selectedPressed分段控制选中项按下 | color | oklch(0.9 0.002 255) | oklch(0.47 0.01 255) | |
component.segment.background.hover分段控制悬停 | color | oklch(0.95 0 255) | oklch(0.38 0.007 255) | |
component.segment.background.pressed分段控制按下 | color | oklch(0.9 0.002 255) | oklch(0.47 0.01 255) | |
component.segment.text.selected分段控制选中文字 | color | oklch(0.2 0.001 255) | oklch(0.98 0 255) | |
component.segment.text.default分段控制默认文字 | color | oklch(0.47 0.01 255) | oklch(0.82 0.004 255) | |
component.segment.border.selected分段控制选中边框 | color | oklch(0.9 0.002 255) | oklch(0.38 0.007 255) | |
component.segment.shadow.selected分段控制选中层级 | shadow | 0 0 0 1px oklch(0 0 0 / 0.06), 0 2px 8px oklch(0 0 0 / 0.06) | 0 0 0 1px oklch(0 0 0 / 0.06), 0 2px 8px oklch(0 0 0 / 0.06) | Aa |
component.segment.radius分段控制圆角 | dimension | 0.625rem | 0.625rem | Aa |
component.segment.height.sm小型分段控制高度 | dimension | 2.25rem | 2.25rem | Aa |
component.segment.height.md中型分段控制高度 | dimension | 2.75rem | 2.75rem | Aa |
component.segment.opacity.disabled分段控制禁用透明度 | number | 0.5 | 0.5 | Aa |
component.segment.typography.size分段控制字号 | dimension | 0.875rem | 0.875rem | Aa |
component.segment.typography.weight分段控制字重 | fontWeight | 600 | 600 | Aa |
component.segment.typography.leading分段控制行高 | number | 1 | 1 | Aa |
component.segment.spacing.inset分段控制内距 | dimension | 0.25rem | 0.25rem | Aa |
component.segment.spacing.gap分段控制项目间距 | dimension | 0.25rem | 0.25rem | Aa |
component.segment.spacing.itemInline分段控制项目横向内距 | dimension | 0.75rem | 0.75rem | Aa |
component.segment.focus.width分段控制焦点环宽度 | dimension | 2px | 2px | Aa |
component.segment.motion.duration分段控制动效 | duration | 120ms | 120ms | Aa |
component.segment.motion.easing分段控制缓动 | cubicBezier | cubic-bezier(0.2, 0, 0, 1) | cubic-bezier(0.2, 0, 0, 1) | Aa |
无障碍
语义与键盘
无障碍
- 使用原生语义或完整实现对应 ARIA 模式。
- 提供可见焦点和不依赖颜色的状态提示。
键盘
- 方向键移动并选中相邻项目。
- Home 和 End 移到首项和末项。
- Tab 把整个组件作为一个停靠点。
属性与接口
公开接口
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
options | SegmentOption[] | 必填 | 选项列表。 |
value | string | — | 受控选中值。 |
defaultValue | string | 第一个可用项 | 非受控初始值。 |
onValueChange | (value) => void | — | 选中变化回调。 |
size | "sm" | "md" | md | 控件尺寸。 |
aria-label | string | 必填 | 分段控制名称。 |
<SegmentedControl aria-label="时间范围" options={ranges} defaultValue="week" />