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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/slider.md.

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
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} 后,只能选择刻度中的值。

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
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
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
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
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。

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

API

Slider API

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

属性类型默认值说明
minnumber0最小值,默认 0。
maxnumber100最大值,默认 100。
stepnumber | null1每次调整的步长;null 时只允许选择 marks 中的值。
marksreadonly SliderMark[][]刻度列表
verticalbooleanfalse使用垂直布局
showValuebooleanfalse悬停或聚焦时在右上方显示数值,默认隐藏
onChangeComplete(value: number | readonly [number, number]) => void—操作结束且数值发生过变化后触发;单值返回数字,区间返回二元数组。
tooltipboolean | { formatter?: (value: number) => ReactNode }false显示滑块提示,可定制数值格式。
rangefalse | truefalse区间选择
valuenumber | readonly [number, number]—受控数值。
defaultValuenumber | readonly [number, number]range ? [min, max] : min非受控模式的初始数值;单值默认为 min,区间默认为 [min, max]。
onChange((value: number) => void) | ((value: [number, number]) => void)—数值变化,回调类型由 range 决定
disabledbooleanfalse禁用交互。
readOnlybooleanfalse锁定业务值,禁止输入、选择、清除和删除。
namestring—原生 FormData 中的字段名。
formstring—关联的原生表单 ID。

SliderMark

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

属性类型默认值说明
valuenumber必填刻度数值。
labelReactNode—刻度显示内容。