> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/slider.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Slider 滑动输入条

通过滑动选择数值或区间。


## 基础用法

通过滑块选择数值，并为控件提供关联字段名称。


音量

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/slider/basic.tsx"
import { Form, FormField, Slider } from '@ifhover/leaf-ui';

export function SliderBasic() {
  return (
    <Form layout="vertical">
      <FormField label="音量">
        <Slider name="volume" defaultValue={35} />
      </FormField>
    </Form>
  );
}
```

展开代码


## 示例

### 区间选择

`range` 使用 `[起点, 终点]` 二元数组，两个端点不能互相穿越。


预算范围

range.tsx

复制代码

```tsx lineNumbers file="../../src/examples/slider/range.tsx"
import { Form, FormField, Slider } from '@ifhover/leaf-ui';

export function SliderRange() {
  return (
    <Form layout="vertical">
      <FormField label="预算范围">
        <Slider aria-label="预算范围" name="budget" range defaultValue={[20, 70]} />
      </FormField>
    </Form>
  );
}
```

展开代码

### 离散刻度

`marks` 提供可点击的刻度。设置 `step={null}` 后，只能选择刻度中的值。


折扣

02560100

marks.tsx

复制代码

```tsx lineNumbers file="../../src/examples/slider/marks.tsx"
import { Form, FormField, Slider } from '@ifhover/leaf-ui';

export function SliderMarks() {
  return (
    <Form layout="vertical">
      <FormField label="折扣">
        <Slider
          defaultValue={25}
          step={null}
          marks={[
            { value: 0, label: '0' },
            { value: 25, label: '25' },
            { value: 60, label: '60' },
            { value: 100, label: '100' },
          ]}
        />
      </FormField>
    </Form>
  );
}
```

展开代码

### 只读与禁用

两者都禁止修改；需要仍参与表单提交时使用 `readOnly`。


只读

禁用

disabled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/slider/disabled.tsx"
import { Form, FormField, Slider } from '@ifhover/leaf-ui';

export function SliderDisabled() {
  return (
    <Form layout="vertical">
      <FormField label="只读">
        <Slider defaultValue={45} readOnly />
      </FormField>
      <FormField label="禁用">
        <Slider defaultValue={45} disabled />
      </FormField>
    </Form>
  );
}
```

展开代码

### 垂直布局

设置 `vertical`，沿垂直方向调整数值。


音量

vertical.tsx

复制代码

```tsx lineNumbers file="../../src/examples/slider/vertical.tsx"
import { Form, FormField, Slider } from '@ifhover/leaf-ui';

export function SliderVertical() {
  return (
    <Form layout="vertical">
      <FormField label="音量">
        <Slider vertical defaultValue={60} />
      </FormField>
    </Form>
  );
}
```

展开代码

[](#)
### 数值提示

悬停或聚焦滑块时显示 `tooltip`，可用 `formatter` 设置数值格式。


音量

tooltip.tsx

复制代码

```tsx lineNumbers file="../../src/examples/slider/tooltip.tsx"
import { Form, FormField, Slider } from '@ifhover/leaf-ui';

export function SliderTooltip() {
  return (
    <Form layout="vertical">
      <FormField label="音量">
        <Slider defaultValue={35} tooltip={{ formatter: (value) => `${value}%` }} />
      </FormField>
    </Form>
  );
}
```

展开代码

### 受控值与操作完成

`onChange` 随数值变化触发，单值返回数字，区间返回二元数组。`onChangeComplete` 在操作结束且数值发生过变化后触发，可用于保存最终值。重置受控字段时，应用需同步恢复 `value`。


音量

当前值：35

已确认：35

重置

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/slider/controlled.tsx"
import { Button, Flex, Form, FormField, Slider, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function SliderControlled() {
  const [value, setValue] = useState(35);
  const [completed, setCompleted] = useState(35);

  return (
    <Form
      layout="vertical"
      onReset={() => {
        setValue(35);
        setCompleted(35);
      }}
    >
      <FormField label="音量" help={`当前值：${value}`}>
        <Slider
          name="volume"
          value={value}
          onChange={setValue}
          onChangeComplete={(next) => {
            if (typeof next === 'number') setCompleted(next);
          }}
        />
      </FormField>
      <Text tone="muted" role="status">
        已确认：{completed}
      </Text>
      <Flex align="center">
        <Button type="reset" variant="outline">
          重置
        </Button>
      </Flex>
    </Form>
  );
}
```

展开代码

#### 表单与键盘

设置 `name` 可参与原生表单提交；区间以同一个字段名提交两个值，用 `FormData.getAll` 读取。非受控字段随表单重置恢复初始值，表单接入见 [Form](https://ifhover.github.io/leaf-ui/components/form.md)。

方向键按步长调整，Home / End 跳至边界；Shift + 方向键和 PageUp / PageDown 调整十个步长。离散模式按相邻刻度调整。


## API

### Slider API

配置单值或区间值、数值范围和滑动交互。

| 属性                 | 类型                                                                 | 默认值                        | 说明                                      |
| ------------------ | ------------------------------------------------------------------ | -------------------------- | --------------------------------------- |
| `min`              | `number`                                                           | `0`                        | 最小值，默认 0。                               |
| `max`              | `number`                                                           | `100`                      | 最大值，默认 100。                             |
| `step`             | `number \| null`                                                   | `1`                        | 每次调整的步长；null 时只允许选择 marks 中的值。          |
| `marks`            | `readonly `[`SliderMark`](#slidermark)`[]`                         | `[]`                       | 刻度列表                                    |
| `vertical`         | `boolean`                                                          | `false`                    | 使用垂直布局                                  |
| `showValue`        | `boolean`                                                          | `false`                    | 悬停或聚焦时在右上方显示数值，默认隐藏                     |
| `onChangeComplete` | `(value: number \| readonly [number, number]) => void`             | —                          | 操作结束且数值发生过变化后触发；单值返回数字，区间返回二元数组。        |
| `tooltip`          | `boolean \| { formatter?: (value: number) => ReactNode }`          | `false`                    | 显示滑块提示，可定制数值格式。                         |
| `range`            | `false \| true`                                                    | `false`                    | 区间选择                                    |
| `value`            | `number \| readonly [number, number]`                              | —                          | 受控数值。                                   |
| `defaultValue`     | `number \| readonly [number, number]`                              | `range ? [min, max] : min` | 非受控模式的初始数值；单值默认为 min，区间默认为 \[min, max]。 |
| `onChange`         | `((value: number) => void) \| ((value: [number, number]) => void)` | —                          | 数值变化，回调类型由 range 决定                     |
| `disabled`         | `boolean`                                                          | `false`                    | 禁用交互。                                   |
| `readOnly`         | `boolean`                                                          | `false`                    | 锁定业务值，禁止输入、选择、清除和删除。                    |
| `name`             | `string`                                                           | —                          | 原生 FormData 中的字段名。                      |
| `form`             | `string`                                                           | —                          | 关联的原生表单 ID。                             |

### SliderMark

在指定数值位置显示刻度与标签。

| 属性      | 类型          | 默认值 | 说明      |
| ------- | ----------- | --- | ------- |
| `value` | `number`    | 必填  | 刻度数值。   |
| `label` | `ReactNode` | —   | 刻度显示内容。 |
