Slider

Slider 支持水平和垂直范围输入、内嵌图标、数值指示器及方向布局，并提供便于键盘操作的行为。

数值指示器以手动弹出层渲染，使其留在浏览器顶层，不会被父级溢出裁剪。其动画位置由 Slider CSS 变量和变换驱动；请勿在应用代码中覆盖动画使用的 --percent 路径。

数值量化

Slider 会原样保留外部传入的 value，包括步进刻度之间的值。这样，Slider 可以显示通过配套文本或数字输入框输入的更精确数值，而不会在未提示的情况下改动它。

通过 Slider 交互产生的值会按一致规则量化：

• 指针拖动和键盘方向键使用 step 网格。
• 启用滚轮输入后，鼠标滚轮使用 wheelStep 网格（若未提供则使用 step）；按住 Alt 时始终使用 step 网格。
• 网格从有效下限 max(min, lowerLimit) 开始。即使最后一个区间短于一个步长，也始终可以选择有效上限 min(max, upperLimit)。
• Home 和 End 键分别选择准确的有效下限和上限。

滚轮输入默认关闭。只有显式设置 wheel 才会启用：

<Slider v-model:value="value" :min="0" :max="100" :step="1" wheel :wheel-step="5" />

wheelStep 只控制已启用滚轮输入后的步长，不会自行启用滚轮。Slider 禁用或 wheel 为 false 时不会拦截滚轮事件，页面可正常滚动。

2

当前值：2

示例

默认

2

Value: 2

方向

ltr

2

rtl

2

垂直

ltr

2

rtl

2

尺寸

size 属性优先于子树和应用默认值，内置回退值为 medium。应用级尺寸通过 sliderDefaults.size 设置；子树可在 setup 中调用 provideSliderDefaults()。详见组件默认值。

standard

extra-small

2

small

2

medium

2

large

2

extra-large

2

expressive

extra-small

2

small

2

medium

2

large

2

extra-large

2

数值指示器位置

top

2

bottom

2

start

2

end

2

内嵌图标

brightness_6brightness_7

48

禁用

2

Slider 外观

应用和子树默认值可分别通过 sliderDefaults 与 provideSliderDefaults() 设置；字段包括 size、appearance、wheel 和 valueIndicator。默认值为 appearance: 'standard'、wheel: false 和 valueIndicator: true。实例属性优先于这些默认值。

appearance="standard" 是默认值：中性非活动轨道厚 4px，中等尺寸下圆形滑块为 16px，并有独立的 32px 命中区域。Extra-small 和 small 使用 14px 滑块；large 和 extra-large 分别使用 18px 和 20px。size 与 appearance 相互独立。焦点状态会显示清晰轮廓；悬停和按压会添加轻微光晕，但不会改变几何尺寸。

appearance="expressive" 保留原有的粗轨道和竖直手柄。内嵌图标仅支持 expressive 的 medium、large 和 extra-large 尺寸；standard 不显示图标。两种外观都支持停止标记、所有数值指示器位置、格式化、垂直方向、RTL、禁用状态、范围限制和步进量化。Standard 指示器更紧凑，并仍渲染在顶层弹出层中。:value-indicator="false" 仅隐藏视觉提示。

Standard 尺寸 Token 为 --md-slider-track-thickness、--md-slider-thumb-size 和 --md-slider-target-size。已有的 --md-slider-active-track-color、--md-slider-inactive-track-color、--md-slider-handle-color 和指示器颜色 Token 对两种外观都有效。命中区域应至少与滑块一样大。程序设置的值保持精确；Slider 交互会按步进网格吸附。配对数字输入框由调用方管理。

精确数字输入

Opacity

42.125

迁移旧默认选项

sliderSize 和 sliderAppearance 已移除且没有兼容别名。将它们分别迁移到 sliderDefaults.size 和 sliderDefaults.appearance。如需保留之前的外观，可在实例上设置 appearance="expressive"，或将应用级 sliderDefaults.appearance 设为 'expressive'。也可通过 provideSliderDefaults() 为子树设置默认值。外观与密度的搭配建议请参阅 样式指南。

滚轮输入默认关闭。如果需要单个 Slider 使用滚轮调整值，请显式添加 wheel，例如 <Slider wheel />；应用或子树默认值也可通过 sliderDefaults.wheel 或 provideSliderDefaults({ wheel: true }) 开启。仅设置 wheelStep 不会启用滚轮；未启用滚轮或 Slider 已禁用时，页面滚动行为不变。valueIndicator 默认开启，可通过 sliderDefaults.valueIndicator 设置应用默认值。

参考

结构

高亮显示

元素	部件	选择器
<div>	root	[data-scope="slider"][data-part="root"] left_click鼠标左键单击复制
<div>	track-active	[data-scope="slider"][data-part="track-active"] left_click鼠标左键单击复制
<div>	track-inactive	[data-scope="slider"][data-part="track-inactive"] left_click鼠标左键单击复制
<div>	handle	[data-scope="slider"][data-part="handle"] left_click鼠标左键单击复制
<div>	value-indicator条件显示	[data-scope="slider"][data-part="value-indicator"] left_click鼠标左键单击复制
<span>	value-indicator-text	[data-scope="slider"][data-part="value-indicator-text"] left_click鼠标左键单击复制

属性

名称	说明	默认值	控件
vertical可选	Whether the slider is vertical. boolean | undefined	false
direction可选	The direction of the slider. ltrrtl	"ltr"	checkltrrtl
min必填	The minimum value of the slider. number	-
max必填	The maximum value of the slider. number	-
step必填	The step value of the slider. number	-
wheel可选	Enable mouse-wheel value changes. Disabled by default to preserve page scrolling. boolean | undefined	-
wheelStep可选	The amount the value changes when wheel interaction is enabled. number | undefined	-
lowerLimit可选	The lower limit for the slider value. number | undefined	-
upperLimit可选	The upper limit for the slider value. number | undefined	-
appearance可选	Visual appearance, independent of size. standardexpressive	-	standardexpressive
size可选	The size of the slider. smalllargeextra-smallmediumextra-large	-	smalllargeextra-smallcheckmediumextra-large
startIcon可选	Name of the inset icon shown at the start side of the track. string | undefined	-
endIcon可选	Name of the inset icon shown at the end side of the track. string | undefined	-
disabled可选	- boolean | undefined	false
valueIndicator可选	- boolean | undefined	-	check
valueIndicatorPlacement可选	- startendbottomtop	-	startendbottomtop
formatter可选	- { valueToText: (value: number) => string; textToValue: (text?: string | undefined) => number | undefined; } | undefined	-	-
stopIndicators可选	- number[] | undefined	-
value必填	- number	-

事件1

名称	类型	说明
update:value	[value: number]	-

样式10

预览

Token	说明
--md-slider-track-thicknessSize 回退值0.25rem	Standard track thickness.
--md-slider-thumb-sizeSize 回退值1rem	Standard thumb diameter; size determines the fallback.
--md-slider-target-sizeSize 回退值2rem	Standard hit area, independent of thumb size.
--md-slider-active-track-colorColor 回退值var(--md-sys-color-primary)	Controls active track color.
--md-slider-inactive-track-colorColor 回退值var(--md-sys-color-primary-container)	Controls inactive track color.
--md-slider-handle-colorColor 回退值var(--md-sys-color-primary)	Controls handle color.
--md-slider-active-icon-colorColor 回退值var(--md-sys-color-on-primary)	Controls icon color on the active track.
--md-slider-inactive-icon-colorColor 回退值var(--md-sys-color-primary)	Controls icon color on the inactive track.
--md-slider-value-indicator-backgroundColor 回退值var(--md-sys-color-inverse-surface)	Controls value indicator container color.
--md-slider-value-indicator-colorColor 回退值var(--md-sys-color-inverse-on-surface)	Controls value indicator label color.