Slider 滑动选择
Slider 在轨道上选一个数,或者两个数组成的范围。拖动手柄、点击轨道任意位置跳过去,或者聚焦手柄后用键盘调整。每个手柄都是 role="slider"。
演示
基础用法
用 aria-label 或 aria-labelledby 给滑动选择命名,名字会落到手柄上。
范围
range 增加第二个手柄,值变成 [start, end]。把一个手柄拖过另一个时两者会交换,所以值总是按从小到大返回。
标记
marks 在轨道上标出一些值。手柄除了按 step 吸附,也会吸附到标记上,所以步长为 10 时也能选到 37。
步长
step 设定取值的网格,从 min 开始算。小数步长也不会出现浮点误差。
只能选标记
step="mark" 时只能选 marks 里的值。
提示
手柄被悬停、通过键盘聚焦或拖动时,上方会显示当前值。formatTooltip 格式化显示内容,showTooltip 让它一直显示,tooltip={false} 关闭提示。
垂直
vertical 让轨道从下往上。默认高 200px,用 height 修改。
反向
reverse 把最小值放到另一端。
禁用
受控
传入 value 和 onUpdateValue 自己管理状态。拖动时每次变化都会调用 onUpdateValue。
无障碍
每个手柄都是可聚焦的 role="slider",带 aria-valuenow、aria-valuemin、aria-valuemax 和 aria-orientation。formatTooltip 返回字符串或数字时,它同时作为手柄的 aria-valuetext。滑动选择上的 aria-label、aria-labelledby 会用来命名手柄;范围模式下两个手柄会在 aria-label 后面加上语言包里的“起点”“终点”。
| 按键 | 作用 |
|---|---|
| 右 / 上 | 增加一步(右方向键跟随轨道,reverse 和从右到左的文字方向会翻转它) |
| 左 / 下 | 减少一步 |
| Page Up / Page Down | 增加或减少十步 |
| Home / End | 最小值或最大值 |
提示气泡只是重复当前值,对辅助技术隐藏。
Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
value | number | [number, number] | undefined | 受控时的当前值。 | 未发布 |
defaultValue | number | [number, number] | min,range 时为 [min, max] | 非受控时的初始值。 | 未发布 |
onUpdateValue | (value: number | [number, number]) => void | undefined | 滑动时以新值调用;范围总是从小到大。 | 未发布 |
range | boolean | false | 用两个手柄选择 [start, end]。 | 未发布 |
min | number | 0 | 最小值。 | 未发布 |
max | number | 100 | 最大值。 | 未发布 |
step | number | 'mark' | 1 | 取值网格;'mark' 时只能选 marks 里的值。 | 未发布 |
marks | Record<number, ReactNode> | undefined | 轨道上的标记,以值为键。 | 未发布 |
vertical | boolean | false | 从下往上。 | 未发布 |
reverse | boolean | false | 把最小值放到另一端。 | 未发布 |
disabled | boolean | false | 禁用。 | 未发布 |
keyboard | boolean | true | 允许用按键移动聚焦的手柄。 | 未发布 |
tooltip | boolean | true | 手柄被悬停、聚焦或拖动时显示当前值。 | 未发布 |
showTooltip | boolean | false | 一直显示提示。 | 未发布 |
formatTooltip | (value: number) => ReactNode | undefined | 格式化提示;字符串或数字同时作为 aria-valuetext。 | 未发布 |
Slider 也接受原生 div 属性和 ref。showTooltip 在 range 下也有效。提示是手柄里的气泡,而不是 Tooltip 弹层。通过 --r-slider-* token 调整轨道、填充和手柄的样式。