滑块

¥Slider

用于用户在给定范围内选择值的输入框。

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

Can be controlled or uncontrolled.

Supports multiple thumbs.

Supports a minimum value between thumbs.

Supports touch or click on track to update value.

Supports Right to Left direction.

Full keyboard navigation.

安装

¥Installation

从命令行安装组件。

¥Install the component from your command line.

npm install @radix-ui/react-slider

结构

¥Anatomy

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

¥Import all parts and piece them together.

import { Slider } from "radix-ui";

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

API 参考

¥API Reference

根

¥Root

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

¥Contains all the parts of a slider. It will render an input for each thumb when used within a form to ensure events propagate correctly.

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]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

轨道

¥Track

包含 Slider.Range 的轨道。

¥The track that contains the Slider.Range.

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

Data attribute	Values
`[data-disabled]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

范围

¥Range

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

¥The range part. Must live inside Slider.Track.

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

Data attribute	Values
`[data-disabled]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

缩略图

¥Thumb

一个可拖动的缩略图。你可以渲染多个缩略图。

¥A draggable thumb. You can render multiple thumbs.

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

Data attribute	Values
`[data-disabled]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

示例

¥Examples

垂直方向

¥Vertical orientation

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

¥Use the orientation prop to create a vertical slider.

// 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;
}

创建范围

¥Create a range

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

¥Add multiple thumbs and values to create a range slider.

import { Slider } from "radix-ui";

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

定义步长

¥Define step size

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

¥Use the step prop to increase the stepping interval.

import { Slider } from "radix-ui";

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

防止缩略图重叠

¥Prevent thumb overlap

使用 minStepsBetweenThumbs 避免缩略图具有相同的值。

¥Use minStepsBetweenThumbs to avoid thumbs with equal values.

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>
);

可访问性

¥Accessibility

遵循滑块 WAI-ARIA 设计模式。

¥Adheres to the Slider WAI-ARIA design pattern.

键盘交互

¥Keyboard Interactions

Key	Description
`ArrowRight`	Increments/decrements by the `step` value depending on `orientation`.
`ArrowLeft`	Increments/decrements by the `step` value depending on `orientation`.
`ArrowUp`	Increases the value by the `step` amount.
`ArrowDown`	Decreases the value by the `step` amount.
`PageUp`	Increases the value by a larger `step`.
`PageDown`	Decreases the value by a larger `step`.
`Shift + ArrowUp`	Increases the value by a larger `step`.
`Shift + ArrowDown`	Decreases the value by a larger `step`.
`Home`	Sets the value to its minimum.
`End`	Sets the value to its maximum.

自定义 API

¥Custom APIs

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

¥Create your own API by abstracting the primitive parts into your own component.

抽象所有部分

¥Abstract all parts

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

¥This example abstracts all of the Slider parts so it can be used as a self closing element.

用法

¥Usage

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

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

实现

¥Implementation

// 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>
	);
});

注意事项

¥Caveats

鼠标事件未触发

¥Mouse events are not fired

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

¥Because of a limitation we faced during implementation, the following example won't work as expected and the onMouseDown and onMouseUp event handlers won't be fired:

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

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

¥We recommend using pointer events instead (eg. onPointerDown, onPointerUp). Regardless of the above limitation, these events are better suited for cross-platform/device handling as they are fired for all pointer input types (mouse, touch, pen, etc.).

Previous分隔符

Next切换

概览

指南

组件

实用工具

滑块