Slider 滑块 | Tuff Docs

用法

基础

示例加载中...

显示数值

示例加载中...

格式化显示

formatValue 格式化右侧读数；未传 tooltipFormatter 时也用于 tooltip。

示例加载中...

禁用

示例加载中...

tooltipTilt 让 tooltip 随指针速度与加速度倾斜、追尾，tooltipJelly 叠加果冻回弹。

示例加载中...

最佳实践

连续或近似连续的数值用 Slider；每个停靠点有独立语义时用 TxSegmentedSlider。
单位写在相邻文案或 formatValue / tooltipFormatter 中，不要塞进 modelValue。
拖动期间保持 min、max、step 稳定，否则拖钮会跳动。
倾斜与果冻动效用于探索式调参界面，不用于高密度表单。
改胶囊尺寸用 --tx-slider-surface-width / --tx-slider-surface-size，不要单独覆盖 --tx-slider-thumb-size；不要拖钮时先设 thumbSurface=false 再将其归零。

API 参考

属性

属性名	类型	默认值	说明
`modelValue`	`number`	`0`	当前值；显示时夹在 `min..max` 内。
`min`	`number`	`0`	最小值。
`max`	`number`	`100`	最大值。
`step`	`number`	`1`	步长。
`disabled`	`boolean`	`false`	禁用滑块并隐藏 tooltip。
`active`	`boolean`	`true`	`false` 时暂停观测、全局追踪与动效，值与 `disabled` 不变。
`ariaLabel`	`string`	-	可访问名称，写在原生 range 输入上而非外层包装。
`ariaLabelledby`	`string`	-	为 range 输入命名的可见元素 id。
`showValue`	`boolean`	`false`	在右侧显示当前值。
`formatValue`	`(value: number) => string`	-	格式化右侧读数。
`thumbSurface`	`boolean`	`true`	常驻胶囊拖钮，材质与形变同 Radio 指示器；`false` 为扁平圆钮。
`thumbVariant`	`'solid' \| 'blur' \| 'glass'`	`'blur'`	胶囊本体：`solid` 实心，`blur` 薄底并模糊下方轨道，`glass` 按住时折射。
`showTooltip`	`boolean`	`true`	满足触发条件时显示 tooltip。
`tooltipTrigger`	`'drag' \| 'hover' \| 'always'`	`'drag'`	tooltip 的触发方式。
`tooltipFormatter`	`(value: number) => string`	-	tooltip 文本格式化。
`tooltipPlacement`	`'top' \| 'bottom'`	`'top'`	tooltip 位于拖钮上方或下方。
`tooltipTilt`	`boolean`	`false`	启用随速度倾斜、偏移、挤压与扭曲的 tooltip 动效。
`tooltipTiltMaxDeg`	`number`	`18`	最大倾斜角度。
`tooltipOffsetMaxPx`	`number`	`28`	最大水平偏移。
`tooltipAccelBoost`	`number`	`0.65`	加速度对动效强度的加成。
`tooltipSpringStiffness`	`number`	`320`	跟随、偏移与倾斜的弹簧刚度。
`tooltipSpringDamping`	`number`	`24`	跟随、偏移与倾斜的弹簧阻尼。
`tooltipMotion`	`'blur' \| 'fade' \| 'none'`	`'blur'`	显示 / 隐藏动效；`none` 不包过渡。
`tooltipMotionDuration`	`number`	`160`	显示 / 隐藏动效时长（ms），负值按 0 处理。
`tooltipMotionBlurPx`	`number`	`10`	`blur` 动效的模糊半径（px），负值按 0 处理。
`tooltipDistortSkewDeg`	`number`	`8`	移动时扭曲（skew）的最大角度。
`tooltipJelly`	`boolean`	`true`	在倾斜之上叠加由加速度触发的果冻回弹。
`tooltipJellyFrequency`	`number`	`8.5`	回弹频率（Hz）。
`tooltipJellyDecay`	`number`	`10`	回弹衰减，越大越快停。
`tooltipJellyRotateDeg`	`number`	`10`	回弹的最大旋转角度。
`tooltipJellySkewDeg`	`number`	`12`	回弹的最大扭曲角度。
`tooltipJellySquash`	`number`	`0.16`	回弹的挤压强度。
`tooltipJellyTriggerAccel`	`number`	`2800`	触发回弹的加速度阈值。

事件

事件名	参数	说明
`update:modelValue`	`number`	原生 `input` 时以夹取后的值触发。
`change`	`number`	原生 `change` 时触发。

概述

默认的 thumbSurface 下，原生 thumb 退化为与胶囊等宽的命中区；键盘焦点环画在胶囊上，拖拽引起的聚焦除外。
active=false、KeepAlive 失活与卸载都会停止帧任务、移除全局 pointer 监听并断开尺寸观察；恢复后按当前布局重新观测。
减弱动效偏好即时生效：按住期间切换也会停止形变，原生输入与静态读数保留。

技术实现

拖钮形变与 Radio 指示器共用 packages/tuffex/packages/utils/animation/jelly.ts 的果冻数学。
不开放插槽：tooltip、拖钮、轨道与读数由内部渲染，以保持指针计算与 tooltip 变换同步。
源码：packages/tuffex/packages/components/src/slider/。

查看源码

packages/tuffex/packages/components/src/slider/index.ts