滑块

用户从给定范围内选择值的输入。

import React from 'react';
import * as Slider from '@radix-ui/react-slider';
import './styles.css';

const SliderDemo = () => (
  <form>
    <Slider.Root className="SliderRoot" defaultValue={[50]} max={100} step={1}>
      <Slider.Track className="SliderTrack">
        <Slider.Range className="SliderRange" />
      </Slider.Track>
      <Slider.Thumb className="SliderThumb" aria-label="Volume" />
    </Slider.Root>
  </form>
);

export default SliderDemo;

功能

可以是受控或不受控的。

支持多个滑块。

支持滑块之间的最小值。

支持触摸或点击轨道以更新值。

支持从右到左方向。

完整的键盘导航。

安装

从命令行安装组件。

npm install @radix-ui/react-slider

结构

导入所有部分并将其组合在一起。

import * as Slider from '@radix-ui/react-slider';

export default () => (
  <Slider.Root>
    <Slider.Track>
      <Slider.Range />
    </Slider.Track>
    <Slider.Thumb />
  </Slider.Root>
);

API 参考

根

包含滑块的所有部分。当在 form 内使用时，它将为每个滑块渲染一个 input，以确保事件正确传播。

属性	类型	默认值
`asChild`	`布尔值`	`false`
`defaultValue`	`数字数组`	无默认值
`value`	`数字数组`	无默认值
`onValueChange`	`函数`	无默认值
`onValueCommit`	`函数`	无默认值
`name`	`字符串`	无默认值
`disabled`	`布尔值`	`false`
`orientation`	`枚举`	`"horizontal"`
`dir`	`枚举`	无默认值
`inverted`	`布尔值`	`false`
`min`	`数字`	`0`
`max`	`数字`	`100`
`step`	`数字`	`1`
`minStepsBetweenThumbs`	`数字`	`0`

数据属性	值
`[data-disabled]`	禁用时出现
`[data-orientation]`	`"vertical" \|"horizontal"`

轨道

包含 Slider.Range 的轨道。

属性	类型	默认值
`asChild`	`布尔值`	`false`

数据属性	值
`[data-disabled]`	禁用时出现
`[data-orientation]`	`"vertical" \|"horizontal"`

范围

范围部分。必须位于 Slider.Track 内。

属性	类型	默认值
`asChild`	`布尔值`	`false`

数据属性	值
`[data-disabled]`	禁用时出现
`[data-orientation]`	`"vertical" \|"horizontal"`

滑块

一个可拖动的滑块。您可以渲染多个滑块。

属性	类型	默认值
`asChild`	`布尔值`	`false`

数据属性	值
`[data-disabled]`	禁用时出现
`[data-orientation]`	`"vertical" \|"horizontal"`

示例

垂直方向

使用 orientation 属性创建垂直滑块。

// index.jsx
import * as Slider from '@radix-ui/react-slider';
import './styles.css';

export default () => (
  <Slider.Root
    className="SliderRoot"
    defaultValue={[50]}
    orientation="vertical"
  >
    <Slider.Track className="SliderTrack">
      <Slider.Range className="SliderRange" />
    </Slider.Track>
    <Slider.Thumb className="SliderThumb" />
  </Slider.Root>
);

/* styles.css */
.SliderRoot {
  position: relative;
  display: flex;
  align-items: center;
}
.SliderRoot[data-orientation='vertical'] {
  flex-direction: column;
  width: 20px;
  height: 100px;
}

.SliderTrack {
  position: relative;
  flex-grow: 1;
  background-color: grey;
}
.SliderTrack[data-orientation='vertical'] {
  width: 3px;
}

.SliderRange {
  position: absolute;
  background-color: black;
}
.SliderRange[data-orientation='vertical'] {
  width: 100%;
}

.SliderThumb {
  display: block;
  width: 20px;
  height: 20px;
  background-color: black;
}

创建范围

添加多个滑块和值以创建范围滑块。

import * as Slider from '@radix-ui/react-slider';

export default () => (
  <Slider.Root defaultValue={[25, 75]}>
    <Slider.Track>
      <Slider.Range />
    </Slider.Track>
    <Slider.Thumb />
    <Slider.Thumb />
  </Slider.Root>
);

定义步长

使用 step 属性增加步长间隔。

import * as Slider from '@radix-ui/react-slider';

export default () => (
  <Slider.Root defaultValue={[50]} step={10}>
    <Slider.Track>
      <Slider.Range />
    </Slider.Track>
    <Slider.Thumb />
  </Slider.Root>
);

防止滑块重叠

使用 minStepsBetweenThumbs 避免具有相同值的滑块。

import * as Slider from '@radix-ui/react-slider';

export default () => (
  <Slider.Root defaultValue={[25, 75]} step={10} minStepsBetweenThumbs={1}>
    <Slider.Track>
      <Slider.Range />
    </Slider.Track>
    <Slider.Thumb />
    <Slider.Thumb />
  </Slider.Root>
);

无障碍性

符合滑块 WAI-ARIA 设计模式.

键盘交互

键	描述
`箭头右`	根据`step` 值递增/递减 `orientation`.
`箭头左`	根据`step` 值递增/递减 `orientation`.
`箭头上`	将值增加`step` 数量。
`箭头下`	将值减少`step` 数量。
`PageUp`	将值增加一个较大的`step`。
`PageDown`	将值减少一个较大的`step`。
`Shift + 箭头上`	将值增加一个较大的`step`。
`Shift + 箭头下`	将值减少一个较大的`step`。
`Home`	将值设置为最小值。
`End`	将值设置为最大值。

自定义 API

通过将基本部分抽象到您自己的组件中来创建自己的 API。

抽象所有部分

此示例抽象了所有Slider 部分，因此它可以用作自闭合元素。

用法

import { Slider } from './your-slider';

export default () => <Slider defaultValue={[25]} />;

实现

// your-slider.jsx
import * as SliderPrimitive from '@radix-ui/react-slider';

export const Slider = React.forwardRef((props, forwardedRef) => {
  const value = props.value || props.defaultValue;

  return (
    <SliderPrimitive.Slider {...props} ref={forwardedRef}>
      <SliderPrimitive.Track>
        <SliderPrimitive.Range />
      </SliderPrimitive.Track>
      {value.map((_, i) => (
        <SliderPrimitive.Thumb key={i} />
      ))}
    </SliderPrimitive.Slider>
  );
});

注意事项

鼠标事件不会触发

由于在实现过程中遇到的限制，以下示例将无法按预期工作，并且onMouseDown 和onMouseUp 事件处理程序不会被触发

<Slider.Root
  onMouseDown={() => console.log('onMouseDown')}
  onMouseUp={() => console.log('onMouseUp')}
>
  …
</Slider.Root>

我们建议改用指针事件（例如，onPointerDown，onPointerUp）。无论上述限制，这些事件更适合跨平台/设备处理，因为它们会对所有指针输入类型（鼠标、触摸、笔等）触发。

上一个分隔符

下一个开关

在 GitHub 上编辑此页面。

概述

指南

组件

工具

滑块

功能

安装

结构