滑块

用户在给定范围内选择值的输入控件。

import * as React from "react";
import { Slider } from "radix-ui";
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 { Slider } from "radix-ui";

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

API 参考

根组件

包含滑块的所有部分。当在表单中使用时，它将为每个滑块手柄渲染一个 input 元素，以确保事件正确传播。

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

数据属性	值
`[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 { Slider } from "radix-ui";
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 { Slider } from "radix-ui";

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

定义步长

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

import { Slider } from "radix-ui";

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

防止滑块手柄重叠

使用 minStepsBetweenThumbs 避免具有相等值的滑块手柄。

import { Slider } from "radix-ui";

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 设计模式。

键盘交互

按键	描述
`ArrowRight`	根据 ... 增加/减少 `step` 值 `orientation`.
`ArrowLeft`	根据 ... 增加/减少 `step` 值 `orientation`.
`ArrowUp`	将值增加 `step` 量。
`ArrowDown`	将值减少 `step` 量。
`PageUp`	将值增加更大的 `step` 量。
`PageDown`	将值减少更大的 `step` 量。
`Shift + ArrowUp`	将值增加更大的 `step` 量。
`Shift + ArrowDown`	将值减少更大的 `step` 量。
`Home`	将值设置为最小值。
`End`	将值设置为最大值。

自定义 API

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

抽象所有部分

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

用法

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

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

实现

// your-slider.jsx
import { Slider as SliderPrimitive } from "radix-ui";

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 上编辑此页。

概述

指南

组件

实用工具

滑块

功能

用法

实现