Slider

滑动条组件允许用户在一个范围内选择一个或多个数值。

安装

The above command is for individual installation only. You may skip this step if @heroui/react is already installed globally.

导入

用法

禁用状态

尺寸

圆角

颜色

垂直滑动条

通过使用 orientation="vertical" 属性可以改变滑动条的方向。

显示步进标记

可以使用 showSteps 属性在每个步进点上显示小圆点标记。

带刻度标记

可以使用 marks 属性在每个步进点上显示标签。

范围滑动条

如果向 value 属性或 defaultValue 属性传递一个数值数组，滑动条将变为范围滑动条。

填充偏移量

fillOffset 属性允许设置填充应从何处开始。

带提示框

showTooltip 属性允许在用户悬停或拖动滑块时显示带有当前滑块值的提示框。

注意： 您可以通过向 Slider 组件传递 tooltipProps 来更改提示框的任何属性。

带轮廓

通过传递 showOutline 属性可以为滑块的滑块拇指添加小轮廓。

起始与结束内容

Slider 组件提供 startContent 和 endContent 属性，允许您向滑动条的开头和结尾添加任何 ReactNode。

数值格式化

默认情况下，数值格式化为百分比，但可以通过使用 formatOptions 属性指定不同的格式来修改。formatOptions 与 Intl.NumberFormat 的 option 参数兼容，并根据当前区域设置应用。

注意： 使用 tooltipValueFormatOptions 属性来格式化提示框中的值。

也可以使用 getValue 属性来格式化数值。

隐藏数值

默认显示 Slider 的数值，但可以通过传递 hideValue 属性来隐藏。

隐藏滑块拇指

默认显示 Slider 的滑块拇指，但可以通过传递 hideThumb 属性来隐藏。

受控模式

您可以通过传递 value 和 onChange 属性来控制滑动条。

如果您只想在用户停止拖动滑块拇指时捕获滑动条的值，可以使用 onChangeEnd 属性。

受控范围滑动条

您也可以通过使用 value 和 onChange 属性中的数值数组来控制范围滑动条。

自定义滑块拇指

Slider 组件提供了一个 renderThumb 属性，允许您以任何方式自定义滑块拇指。

自定义范围滑块拇指

您也可以使用 renderThumb 属性来自定义范围滑动条的滑块拇指。index 属性会告诉您正在渲染的是哪个拇指。

自定义标签

Slider 组件提供了一个 renderLabel 属性，允许您以任何方式自定义标签。

自定义数值显示

Slider 组件提供了一个 renderValue 属性，允许您自定义数值标签元素。

自定义提示框内容

您可以使用 getTooltipValue 属性，通过从函数返回字符串或数字来自定义提示框中显示的内容。返回数字时，可以利用现有的 tooltipValueFormatOptions 属性进行额外的格式化。

如果设置了 tooltipProps.content，它将优先于 getTooltipValue 生成的值。

禁用滑块拇指缩放动画

如果您想禁用滑块拇指的缩放动画，可以传递 disableThumbScale 属性。

插槽 (Slots)

• base: 基础插槽，包含所有其他插槽和元素。它是主要的容器。
• labelWrapper: Slider 标签和数值的容器。它对这两个元素进行对齐并确保布局一致。
• label: 用于显示 Slider 标签的专用插槽。
• value: 显示 Slider 的当前数值。位于 labelWrapper 内。
• step: 表示 Slider 上的单个步进或间隔。
• mark: 表示沿着 Slider 的特定值或间隔。
• trackWrapper: 滑动条轨道的容器，确保其对齐和定位一致。
• track: Slider 的基础条形轨道，滑块拇指沿其移动。
• filler: 所选值的视觉表示，从起点到当前滑块拇指位置填充轨道。
• thumb: 交互元素，用户可沿轨道拖动以选择 Slider 上的值。
• startContent: 用于在 Slider 开头添加额外内容或图标的插槽。
• endContent: 用于在 Slider 结尾添加额外内容或图标的插槽。

自定义样式

您可以通过向组件插槽传递自定义的 Tailwind CSS 类来定制 Slider 组件。

数据属性 (Data Attributes)

Slider 具有以下属性：

• data-hover: 当滑动条被悬停时。基于 useHover
• data-orientation: 滑动条的方向。基于 orientation 属性。

Thumbs (滑块拇指) 具有以下属性，这些属性由 renderThumb 属性返回：

• data-dragging: 当滑块拇指被拖动时。
• data-focus-visible: 当滑块拇指获得焦点时。基于 useFocusVisible
• data-hover: 当滑块拇指被悬停时。基于 useHover
• data-pressed: 当滑块拇指被按压时。基于 usePress

无障碍性 (Accessibility)

• 支持单个或多个滑块拇指。
• 通过 useMove 钩子支持鼠标、触摸和键盘操作。
• 支持多点触控，可同时拖动多个滑块拇指或多个滑动条。
• 按压轨道会将最近的滑块拇指移动到该位置。
• 支持使用方向键以及 Page Up/Down、Home 和 End 键。
• 支持水平和垂直方向。
• 支持自定义最小值、最大值和步进值，并处理舍入错误。
• 支持禁用整个滑动条或单个滑块拇指。
• 在拖动时阻止文本选择。
• 通过 ARIA 作为一组滑动条元素暴露给辅助技术。
• 滑块拇指使用隐藏的原生输入元素以支持触摸屏阅读器。
• 支持为整个滑动条和单个滑块拇指添加标签。
• 支持使用 <output> 元素显示当前滑块拇指的值。
• 国际化的数字格式化为百分比或数值。
• 支持在 RTL（从右到左）语言环境下的镜像显示。

API

Slider 属性 (Props)

Slider 函数 (Functions)

Slider 事件 (Events)

类型 (Types)

Slider 值 (Slider Value)

Slider 步进标记 (Slider Step Marks)