滑块

概述

用于在连续数值范围内选择一个或多个数值的滑块组件，支持水平/垂直方向、多滑块区间（range）模式、RTL 与反向（inverted）方向，以及完整的键盘操作。当数值属于有界数值范围、需要用户通过鼠标或键盘精确调节时使用；若为自由文本或数字输入，优先使用 SInputNumber。

用法

特性

🎚 modelValue / defaultValue — 基于 useControllableState 的受控与非受控双模式
🔢 单滑块或多滑块区间 — 向 modelValue 传入包含两个值的数组即可创建 range slider
⌨️ 完整键盘支持 — 方向键按 step 步进，PageUp/PageDown 与 Shift+方向键跳 10 步，Home/End 直达 min/max
↔ 通过 dir 支持 RTL 方向，inverted 可反转数值方向
📐 水平与垂直双方向，并反射 aria-orientation
📋 原生表单代理 — 隐藏输入（区间模式展开为 name[0]/name[1]）承载 name / required
🎨 通过 sliderVariants 提供 6 种尺寸 × 8 种颜色
🧩 trackProps / rangeProps / thumbProps 透传 + 默认插槽自定义滑块内容
📏 minStepsBetweenThumbs 与 thumbAlignment（contain / overflow）实现精细区间控制

演示

基础

100%

API

Aria 层

Slider

22 属性2 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	应用于根元素的额外类名。
color	ThemeColor	—	组件的主题颜色。
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<SliderUi>	—	该组件的按槽类重写。
trackProps	SliderTrackProps	—	转发给 track 元素的属性。
rangeProps	SliderRangeProps	—	转发给 range 元素的属性。
thumbProps	BaseProps	—	转发给 thumb 元素的属性。
modelValue	number[]	—	滑块的受控值。可作为 `v-model` 进行绑定。
defaultValue	number[]	—	滑块在未被控制时的初始值。
disabled	boolean	—	滑块是否被禁用。
orientation	DataOrientation	—	滑块的方向。
dir	Direction	—	滑块的阅读方向。
inverted	boolean	—	滑块值的方向是否被反转。
min	number	—	最小值。
max	number	—	最大值。
step	number	—	步进间隔。
minStepsBetweenThumbs	number	—	多个缩略图之间的最小允许间距。
thumbAlignment	SliderThumbAlignment	—	缩略图是否应保持在轨道边界内，还是允许超出边界。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:modelValue	number[]	当滑块值发生变化时调用的事件处理程序。
valueCommit	number[]	当滑块交互被提交时调用的事件处理程序。

SliderCompact

18 属性2 事件1 插槽

属性

属性名	类型	默认值	描述
trackProps	SliderTrackProps	—	转发给 track 元素的属性。
rangeProps	SliderRangeProps	—	转发给 range 元素的属性。
thumbProps	BaseProps	—	转发给 thumb 元素的属性。
modelValue	number[]	—	滑块的受控值。可作为 `v-model` 进行绑定。
defaultValue	number[]	—	滑块在未被控制时的初始值。
disabled	boolean	—	滑块是否被禁用。
orientation	DataOrientation	—	滑块的方向。
dir	Direction	—	滑块的阅读方向。
inverted	boolean	—	滑块值的方向是否被反转。
min	number	—	最小值。
max	number	—	最大值。
step	number	—	步进间隔。
minStepsBetweenThumbs	number	—	多个缩略图之间的最小允许间距。
thumbAlignment	SliderThumbAlignment	—	缩略图是否应保持在轨道边界内，还是允许超出边界。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:modelValue	number[]	当滑块值发生变化时调用的事件处理程序。
valueCommit	number[]	当滑块交互被提交时调用的事件处理程序。

插槽

插槽名	参数	描述
default	SliderCompactSlotProps	默认插槽的自定义内容。

SliderRange

2 属性

属性

属性名	类型	默认值	描述
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

SliderRoot

15 属性2 事件

属性

属性名	类型	默认值	描述
modelValue	number[]	—	滑块的受控值。可作为 `v-model` 进行绑定。
defaultValue	number[]	—	滑块在未被控制时的初始值。
disabled	boolean	—	滑块是否被禁用。
orientation	DataOrientation	—	滑块的方向。
dir	Direction	—	滑块的阅读方向。
inverted	boolean	—	滑块值的方向是否被反转。
min	number	—	最小值。
max	number	—	最大值。
step	number	—	步进间隔。
minStepsBetweenThumbs	number	—	多个缩略图之间的最小允许间距。
thumbAlignment	SliderThumbAlignment	—	缩略图是否应保持在轨道边界内，还是允许超出边界。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:modelValue	number[]	当滑块值发生变化时调用的事件处理程序。
valueCommit	number[]	当滑块交互被提交时调用的事件处理程序。

SliderThumb

3 属性

属性

属性名	类型	默认值	描述
index	number	—	当前滑块值数组中的拇指索引。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

SliderTrack

2 属性

属性

属性名	类型	默认值	描述
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

注意事项

架构与行业对标

VeanUI 由 Aria 层 SliderRoot（useControllableState + 值规范化 + VisuallyHiddenInput 表单代理）→ SliderTrack（指针拖拽，pointer-move/up/cancel 挂载在 document）→ SliderRange（滑块间的百分比跨度）→ SliderThumb（role="slider" + aria-valuemin/max/now + aria-orientation，聚焦派生步进）组成。SliderCompact 负责 root + track + range + thumbs 的组合与滑块迭代；UI 层 SSlider 仅通过 sliderVariants 计算变体类并经 provideSliderUi 注入 ui 映射。

能力	VeanUI	Ant Design `Slider`	Element Plus `Slider`	Mantine `Slider`	Naive UI `Slider`	shadcn `Slider`
Aria/styled 分离	✅	—	—	—	—	✅
受控/非受控	✅	✅	✅	✅	✅	✅
区间（多滑块）	✅	✅	✅	✅	✅	✅
垂直方向	✅	✅	✅	✅	✅	✅
反向 / RTL	✅	✅	✅	✅	✅	✅
键盘导航（方向键/Home/End/Page）	✅	✅	✅	✅	✅	✅
`minStepsBetweenThumbs`	✅	—	—	—	—	✅
表单代理 / `name` 提交	✅	✅	✅	✅	✅	✅
axe 零违规	✅	—	—	—	—	—
marks 刻度标记	➕	✅	✅	✅	✅	—
拖拽时数值气泡 tooltip	➕	✅	✅	✅	✅	—
数字输入框联动	➕	✅	—	—	—	—

使用注意

单滑块没有默认可访问名称——请通过 thumbProps 传入 aria-label（区间模式自动回退到本地化的"最小值"/"最大值"标签）。
滑块默认在轨道内（contain）；thumbAlignment="overflow" 可让滑块超出轨道边界。
表单代理仅在根元素含 form 类且设置了 name 时渲染；需配合原生 <form> 或 SForm 使用。
PageUp/PageDown 与 Shift+方向键按 step 的 10 倍步进；minStepsBetweenThumbs 可阻止滑块互相跨越。

常见问题

如何创建区间滑块（range slider）？

向 modelValue（或 defaultValue）传入包含两个值的数组，例如 [20, 80]。组件渲染两个滑块，valueCommit 同时发出两个值。两个滑块分别标记为"最小值"/“最大值”（已本地化），除非通过 thumbProps['aria-label'] 覆盖。

如何限制两个滑块的最小间距？

设置 minStepsBetweenThumbs 为滑块之间的最小步数——当间距低于该阈值时，步进或拖拽操作会被拒绝。

如何在滑块上方显示当前值？

使用默认插槽，它会为每个滑块提供 { index, value, modelValue } 参数，可渲染自定义内容。内置 tooltip 属于排期待增强项。

支持哪些键盘快捷键？

方向键按 step 步进，PageUp/PageDown 与 Shift+方向键跳 10 步，Home/End 直达 min/max。方向键跟随 dir 与 inverted（RTL 翻转水平方向键；inverted 反转数值方向）。

快速跳转

同分类组件

滑块

概述

用法

特性

演示

基础

API