Slider 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

通过拖动选择单个数值或数值区间，支持水平、垂直、步进与填充式展示，适合范围和参数调整。

使用选择

用于连续值或范围调整。离散选项切换用 Segmented / Select；明确 minValue、maxValue、step 和可访问名称。

• bind:value 使用数值表示单滑块，数组表示双滑块范围；边界属性为 minValue / maxValue。

• step 控制步长，ariaLabel 提供名称；显式 Text as="label" 替换默认标签。

• solid／soft 的缺省条形标题随 LocaleProvider 切换；显式 title（含空字符串）、ariaLabel、数值及显式 label 保持原样。标题不替代可访问名称。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Slider, Text } from '@snowui-design-system/components';</script> <div style="width: 20rem; max-width: 100%; display: flex; flex-direction: column; gap: var(--gap-6);">    <Slider value={69} variant="soft" title="Volume" showLabel ariaLabel="Volume" />    <Slider value={88} variant="soft" title="Music" showLabel ariaLabel="Music volume" />    <Slider value={75} variant="soft" title="Notifications" step={25} showSteps showLabel ariaLabel="Notification volume" /></div>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

布局模型

主布局模型：复合管理布局。

• 轨道、填充条与拖动块规则复用 Progress：默认粗细 4px、轨道 Black4、填充 Primary、全圆角。

• 拖动块固定为 20px × 14px，默认背景为 Static White/80%，含 0.5px 白色 Inside Stroke（inset shadow）与 blur(2px) 背景模糊；drop shadow 保持 0 1px 2px rgba(0, 0, 0, 0.4) 不变。

• 鼠标常态隐藏拖动块；hover、focus-visible、拖动中显示；触控设备常驻显示。

• label 采用默认内置模式，默认不显示；showLabel=true 时自动生成 Text，并显示对应拖动块的实时值。普通及纵向 Range 自动生成两个 Text；水平 solid / soft Range 生成一个完整百分比范围（如 85%–100%）。

• 内置标题与 label 默认使用 Text lines={1}，排版为 12px / 16px；同类型内置实例统一通过 parts.Text 配置。显式 <Text as="label"> 内容保持原样并替换内置 label。

• 水平 label 位于拖动块上方，纵向 label 位于拖动块左侧，默认间距均为 2px；label 只在 hover 时显示。

• Range Slider 使用两个直系 as="label" 内容时，按顺序分别跟随起点和终点拖动块。

• solid / soft 是 Workshop 14458:37835 的两种 32px 条形变体：水平容器默认高 32px、圆角 8px，填充区域扩展为完整高度且左右两端均保留圆角；title 是左侧内置标题，缺省随 locale 使用“文本”／“Text”，不属于 label。

• solid 为高对比样式：填充默认 Primary，覆盖区域的 title、数值 label 与指示器使用 Static White/100%；未覆盖文字使用 Black/100%。

• soft 为主题自适应的低对比样式：填充默认 Black/10%，title、数值 label 与指示器均以 Black/100% 为基色，随亮色 / 暗色主题 token 变化。

• 两种条形变体的右侧数值均复用其他变体的 label 协议：默认不显示，showLabel=true 时生成实时百分比，继续支持 parts.Text 与显式 label。数值 label 常态通过独立 opacity: 0.4 显示，hover、focus 或拖动时提升到 opacity: 0.8。

• title 与数值 label 使用与 Slider 等宽、分界绑定 --snowui-slider-end 的文字背景裁切；分界可穿过单个字形并随点击、拖动连续移动。solid 在覆盖区域切换为白色；soft 覆盖前后均保持 Black/100%。

• 水平条形标题与数值使用独立单行预算，首选间距 --gap-1 且至少4 CSS px。标题可收缩并悬停访问全文，数值优先按自然宽度显示；原生 range 的值、键盘及表单语义保留。默认／纵向浮动 label 的2px轨道注释间距不变。

• 独立文字预算下，渐变画布使用 CSS inline-size 容器单位保持与完整 Slider 等宽，而非分别按文字区域缩放。缺少容器单位的浏览器退化为主题背景上的清晰静态文字，不显示逐字分色；该能力缺失路径尚未在旧浏览器实测。

• 条形变体的拖动块改为“可拖动”指示器，位于填充右缘内侧 4px；值为 0 时位于 Slider 左边框内侧 4px。鼠标常态隐藏，hover、focus 或拖动时以中心点为动效中心渐显、短变长、细变粗，退出时执行反向动效；时序与 easing 引用 generic Frame preset。

• thickness 同时控制条形变体的整体高度；default 仍为 4px，solid / soft 默认 32px。

• solid / soft + showSteps 使用固定 Black/10% 的 2px 圆点，只渲染内部刻度，不显示 0% / 100% 端点；圆点不响应 hover，也不随填充覆盖范围改变颜色。条形变体当前只定义水平布局，纵向 Slider 继续使用 default 视觉。

关键字

gap 沿用 Frame 关键字，但在 Slider 中用于覆盖 label 与拖动块间距。数字仍使用 Frame gap 倍率语义；默认值为 2px。

示例

<script lang="ts">  let value = $state(12);  let range = $state([3, 12]);</script> <Slider bind:value showLabel /> <Slider bind:value={range} showLabel ariaLabel={["最小值", "最大值"]} /> <div style="height: 120px;">  <Slider orientation="vertical" bind:value /></div> <Slider value={60} step={10} showSteps /> <Slider value={60}>  <Text as="label">60%</Text></Slider> <Slider value={74} variant="solid" title="Text" showLabel /> <Slider value={0} step={25} showSteps showLabel variant="solid" /> <Slider value={0} variant="solid" title="Volume" thickness={40} showLabel /> <Slider value={74} variant="soft" title="Text" showLabel />