跳到正文

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

名称类型默认值说明版本
valuenumber | [number, number]undefined受控时的当前值。未发布
defaultValuenumber | [number, number]min,range 时为 [min, max]非受控时的初始值。未发布
onUpdateValue(value: number | [number, number]) => voidundefined滑动时以新值调用;范围总是从小到大。未发布
rangebooleanfalse用两个手柄选择 [start, end]。未发布
minnumber0最小值。未发布
maxnumber100最大值。未发布
stepnumber | 'mark'1取值网格;'mark' 时只能选 marks 里的值。未发布
marksRecord<number, ReactNode>undefined轨道上的标记,以值为键。未发布
verticalbooleanfalse从下往上。未发布
reversebooleanfalse把最小值放到另一端。未发布
disabledbooleanfalse禁用。未发布
keyboardbooleantrue允许用按键移动聚焦的手柄。未发布
tooltipbooleantrue手柄被悬停、聚焦或拖动时显示当前值。未发布
showTooltipbooleanfalse一直显示提示。未发布
formatTooltip(value: number) => ReactNodeundefined格式化提示;字符串或数字同时作为 aria-valuetext。未发布

Slider 也接受原生 div 属性和 ref。showTooltip 在 range 下也有效。提示是手柄里的气泡,而不是 Tooltip 弹层。通过 --r-slider-* token 调整轨道、填充和手柄的样式。