---
title: "Slider 滑块"
description: "在区间内选择数值的滑块"
category: Form
status: beta
since: 0.3.4
tags: [slider, form, input]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
:::TuffDemoWrapper{demo="SliderSliderDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const value = ref(30)
  </script>

  <template>
    <TxSlider v-model="value" :min="0" :max="100" :step="1" />
  </template>
---
:::

### 显示数值
:::TuffDemoWrapper{demo="SliderSliderShowValueDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSlider v-model="value" :min="0" :max="100" :step="1" show-value />
  </template>
---
:::

### 格式化显示
`formatValue` 格式化右侧读数；未传 `tooltipFormatter` 时也用于 tooltip。
:::TuffDemoWrapper{demo="SliderSliderFormatValueDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSlider v-model="value" show-value :format-value="value => `${value}%`" />
  </template>
---
:::

### 禁用
:::TuffDemoWrapper{demo="SliderSliderDisabledDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSlider v-model="value" disabled show-value />
  </template>
---
:::

### 弹性 tooltip
`tooltipTilt` 让 tooltip 随指针速度与加速度倾斜、追尾，`tooltipJelly` 叠加果冻回弹。
:::TuffDemoWrapper{demo="SliderSliderElasticTooltipDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSlider
      v-model="value"
      show-value
      tooltip-tilt
      tooltip-jelly
      :tooltip-tilt-max-deg="22"
      :tooltip-offset-max-px="36"
      :tooltip-spring-stiffness="420"
      :tooltip-spring-damping="26"
      :tooltip-jelly-frequency="11"
      :tooltip-jelly-squash="0.32"
    />
  </template>
---
:::

### 最佳实践

- 连续或近似连续的数值用 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/`。

<TuffDocSourceLink />