跳到主要内容

Slider 滑块Slider · RangeSlider

在一个范围里大致选一个值（音量、亮度、缩放），或用 RangeSlider 选一段区间（价格、年龄）。需要精确数字时用 NumberInput，或者两者并排。

基本用法

默认 0–100、步长 1。拖动或键盘聚焦时在滑块上方显示数值气泡。

步长与刻度

档位不超过 12 个时可以用 ticks 显示刻度点，滑块用弹簧吸附到刻度；显示刻度时不显示数值气泡。format 决定数值怎么显示，同时用作读屏文字。

5 档，带刻度
步长 25

无极

step="any" 不吸附到任何刻度，值是连续的小数；显示时默认取整，用 digits 指定小数位。键盘一步是范围的百分之一。

保留两位小数

禁用

受控用法

onChange 在拖动过程中连续触发；onChangeEnd 在松手或每次按键之后触发一次，适合发请求。

实时值 40 · 松手后保存的值 40

区间滑块

RangeSlider 的值是 [下限, 上限]。按在轨道上会移动离得近的那个滑块；两个滑块不能交叉，minDistance 规定它们至少隔多远。

非受控

受控

¥200 – ¥600

规格

滑块
轨道 6 · 滑块 42 × 28 宽胶囊 · 1px 描边
按住
滑块 1.12× · 数值气泡 bouncy 弹出
落位
弹簧落位（分档 / 点击 / 键盘）；连续型拖动时直接跟手
无极
step="any" · 不吸附刻度，显示值取整
键盘
← → 步进 · PageUp / PageDown 走范围的十分之一 · Home / End

API

Slider

属性类型默认值说明
valuenumber—当前值（受控）。
defaultValuenumbermin初始值（非受控）。
onChange(value: number) => void—值变化时触发，拖动过程中连续触发。
onChangeEnd(value: number) => void—一次操作结束时触发：松手，或每次按键之后。
minnumber0最小值。
maxnumber100最大值。
stepnumber | 'any'1步长；'any' 为无极。
ticksboolean—显示刻度点，只在不超过 12 档时生效；此时不显示气泡。
bubblebooleantrue拖动或键盘聚焦时显示数值气泡。
format(value: number) => string—数值的显示方式，同时用作 aria-valuetext。
digitsnumber—显示的小数位；无极滑块默认取整。
disabledboolean—禁用。
namestring—表单字段名：多渲染一个隐藏 input。

RangeSlider

属性类型默认值说明
value[number, number]—[下限, 上限]（受控）。
defaultValue[number, number][min, max]初始值（非受控）。
onChange / onChangeEnd(value: [number, number]) => void—同 Slider，参数是区间。
minDistancenumber0两个滑块之间至少隔多远；0 表示可以重合，不能交叉。
thumbLabels[string, string]['最小值', '最大值']两个滑块各自的可读名称。
namestring—表单字段名：渲染两个同名的隐藏 input。
min / max / step / bubble / format / digits / disabled——同 Slider。不支持 ticks。

无障碍

  • Slider 的根节点是 role="slider"，带 aria-valuemin / aria-valuemax / aria-valuenow / aria-valuetext（取 format 的结果）。
  • RangeSlider 的根节点是 role="group"，里面两个滑块各自可聚焦，名称取 thumbLabels；它们的取值范围会随对方实时收窄。
  • ← ↓ 减一步，→ ↑ 加一步；PageUp / PageDown 走一大步（范围的十分之一，不小于一步）；Home / End 到两端。
  • 必须有可读名称：放进带 label 的 Field（走 aria-labelledby），或给 aria-label。
  • 数值气泡是装饰（aria-hidden）。需要一直看得到当前值时，请在旁边另外显示。
  • 禁用时为 aria-disabled 并离开 Tab 顺序。