滑块

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

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;

Features

可以是可控或不可控的。

支持多个滑块。

支持滑块之间的最小值。

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

支持从右到左的方向。

完整的键盘导航。

安装

从命令行安装组件。

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 参考

根节点

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

Prop	Type	Default
`asChild`	`boolean`	`false`
`defaultValue`	`number[]`	No default value
`value`	`number[]`	No default value
`onValueChange`	`function`	No default value
`onValueCommit`	`function`	No default value
`name`	`string`	No default value
`disabled`	`boolean`	`false`
`orientation`	`enum`	`"horizontal"`
`dir`	`enum`	No default value
`inverted`	`boolean`	`false`
`min`	`number`	`0`
`max`	`number`	`100`
`step`	`number`	`1`
`minStepsBetweenThumbs`	`number`	`0`
`form`	`string`	No default value

Data attribute	Values
`[data-disabled]`	禁用时存在
`[data-orientation]`	`"vertical" \| "horizontal"`

轨道

包含 Slider.Range 的轨道。

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`[data-disabled]`	禁用时存在
`[data-orientation]`	`"vertical" \| "horizontal"`

范围

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

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`[data-disabled]`	禁用时存在
`[data-orientation]`	`"vertical" \| "horizontal"`

滑块

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

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`[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 设计模式。

键盘交互

Key	Description
`ArrowRight`	根据 `orientation` 的值递增/递减 `step` 值。
`ArrowLeft`	根据 `orientation` 的值递增/递减 `step` 值。
`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）。尽管存在上述限制，但这些事件更适合跨平台/设备处理，因为它们适用于所有指针输入类型（鼠标、触摸、笔等）。

上一篇分隔符 Separator

下一篇开关 Switch

在 GitHub 上编辑此页面

概览 Overview

指南 Guides

组件 Components

通用工具 Utilities

滑块

Features

用法

实现