Slider 滑块

在给定范围内选择数值的输入控件。拖动滑块、点按轨道，或在聚焦时使用方向键。

基础用法

@Local volume: number = 50;

SSlider({ value: this.volume!!, max: 100, step: 1 })
SSlider({ defaultValue: 0.3, min: 0, max: 1, step: 0.05 })
SSlider({ defaultValue: 25, disabled: true })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

范围

两个永不交叉的滑块；拖动时显示数值气泡。

@Local price: number[] = [200, 800];

SSlider({ values: this.price!!, min: 0, max: 1000, step: 10, tooltip: 'active',
  formatValue: (v: number) => `$${v}` })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

刻度、标记与提示

SSlider({ defaultValue: 2, min: 0, max: 4, step: 1, ticks: true,
  marks: [0, 1, 2, 3, 4], formatValue: (v: number) => ['XS', 'S', 'M', 'L', 'XL'][v] })
SSlider({ defaultValue: 60, tooltip: 'always', formatValue: (v: number) => `${v}%` })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

纵向

orientation: 'vertical' 并指定长度；数值向上增长。

Row({ space: 32 }) {
  SSlider({ defaultValue: 40, orientation: 'vertical', length: 140 })
  SSlider({ defaultValues: [20, 70], orientation: 'vertical', length: 140, marks: [0, 50, 100] })
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

SSlider

shadcn-vue 的 Slider，自绘版本：h-1.5 rounded-full bg-muted 轨道，bg-primary 的选中区间，size-4 rounded-full border border-primary bg-background shadow-sm 的滑块，悬停或拖动时带有 ring-4 ring-ring/50。拖动滑块或点按轨道；获得焦点后方向键可步进。

变体：

• 区间：传入 values / defaultValues（两个数字）即为两个滑块（onValuesChange）；滑块不会交叉。
• ticks（每一步一个圆点）与 marks（轨道下方或旁边的带标签数值，通过 formatValue 格式化）。
• orientation: 'vertical'（数值向上增长；需要设置 length，默认 160vp）。
• 键盘：方向键按步进改变数值（区间模式下作用于最后触碰的滑块）。
• tooltip：'active' 在拖动 / 悬停 / 聚焦时在滑块上方显示数值，'always' 则始终显示。

属性	类型	默认值	说明
value!!	number | undefined	undefined	受控值（配合 !! 使用）。留空则为非受控。
defaultValue	number	0
values!!	number[] | undefined	undefined	受控的双滑块区间 [low, high]（配合 !! 使用）。
defaultValues	number[]	[]	非受控的初始区间；两个数字即开启区间模式。
min	number	0
max	number	100
step	number	1
disabled	boolean	false
orientation	SliderOrientation SliderOrientation = 'horizontal' | 'vertical'	'horizontal'
length	number	160	垂直滑块的长度，单位 vp。
ticks	boolean	false	每一步处显示一个圆点（最多 41 步）。
marks	number[]	[]	沿轨道显示的带标签数值。
tooltip	SliderTooltip SliderTooltip = 'none' | 'active' | 'always'	'none'
formatValue	(v: number) => string	(v: number): string => `${v}`	提示框与标记的文字。
label	string | undefined	undefined	无障碍名称。

事件	类型	默认值	说明
onValueChange	(v: number) => void	() => { }
onValueCommit	(v: number) => void	() => { }	拖动 / 点按 / 键盘操作结束时仅触发一次。
onValuesChange	(v: number[]) => void	() => { }
onValuesCommit	(v: number[]) => void	() => { }	区间模式：交互结束时仅触发一次。