Slider 滑块更新

用法复制锚点链接

import { Slider } from '@heroui/react';

组件结构复制锚点链接

import { Slider, Label } from '@heroui/react';

export default () => (
  <Slider step={10}>
    <Label />
    <Slider.Output />
    <Slider.Track>
      <Slider.Fill />
      <Slider.Steps />
      <Slider.Thumb />
    </Slider.Track>
    <Slider.Marks>
      <Slider.Mark value={0} />
      <Slider.Mark value={50} />
      <Slider.Mark value={100} />
    </Slider.Marks>
  </Slider>
)

Slider.Steps 和 Slider.Marks 均为可选组件，可按需独立组合。

示例复制锚点链接

步进指示点复制锚点链接

将 Slider.Steps 放在 Slider.Track 内，即可根据 minValue、maxValue 和 step 在每个步进位置显示一个圆点。即使不显示圆点，step 也会控制数值的步进间隔。

圆点从 minValue 开始排列。如果 maxValue 不在步进位置上，则不会在该端点额外添加圆点。范围无效或所需圆点超过 1,000 个时，不渲染指示点。

刻度标签复制锚点链接

将 Slider.Marks 作为 Slider.Track 的同级元素紧随其后放置，并添加带有必填 value 的 Slider.Mark 子组件。每个标签根据对应数值定位，因此标签可以不等距排列，也不必与步进位置一致。

通过子内容自定义标签。未提供子内容时，标签会使用 Slider 的区域设置和 formatOptions 格式化数值。超出范围或数值非有限的标签不会渲染。刻度标签仅用于展示，不会改变数值或步进吸附行为。

步进指示点与刻度标签复制锚点链接

圆点和标签可以独立组合。步进支持小数；此示例使用 step={0.1}，并在 0、0.5 和 1 处显示标签。

带指示点与标签的范围滑块复制锚点链接

单个滑块控制点下，从最小值到当前选中值之间的圆点和标签会获得 data-filled="true"。范围滑块中，仅第一个和最后一个控制点之间的圆点和标签会获得该属性，包含两个端点。

垂直指示点与标签复制锚点链接

圆点和标签会自动适配 orientation="vertical"。请为垂直滑块提供具有明确高度的容器。水平方向的指示点和标签也会根据区域设置适配从右到左的排列方向。

禁用复制锚点链接

范围滑块结构复制锚点链接

import { Slider, Label } from '@heroui/react';

export default () => (
  <Slider defaultValue={[25, 75]}>
    <Label />
    <Slider.Output />
    <Slider.Track>
      {({state}) => (
        <>
          <Slider.Fill />
          {state.values.map((_, i) => (
            <Slider.Thumb key={i} index={i} />
          ))}
        </>
      )}
    </Slider.Track>
  </Slider>
)

垂直方向复制锚点链接

范围选择复制锚点链接

受控数值复制锚点链接

使用 value 和 onChange 控制数值。

自定义数值格式复制锚点链接

使用 formatOptions 格式化显示的数值。此示例将数值格式化为美元。

自定义输出展示复制锚点链接

自定义 Slider.Output，控制已选数值的展示方式。

渲染函数复制锚点链接

自定义样式复制锚点链接

Tailwind CSS复制锚点链接

全局 CSS复制锚点链接

若要自定义组件类，可使用 @layer components 指令。了解更多。

@layer components {
  .slider {
    @apply gap-2;
  }

  .slider__output {
    @apply text-sm text-muted;
  }

  .slider__track {
    @apply relative h-2 w-full rounded-full bg-surface-secondary;
  }

  .slider__fill {
    @apply absolute h-full rounded-full bg-accent;
  }

  .slider__thumb {
    @apply size-4 rounded-full bg-accent border-2 border-background;
  }
}

样式参考复制锚点链接

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类复制锚点链接

Slider 组件使用以下 CSS 类（查看源码样式）：

基础类复制锚点链接

• .slider - Slider 根容器
• .slider__output - 显示当前值的输出元素
• .slider__track - 包含填充、可选步进指示点与滑块控制点的轨道元素
• .slider__fill - 显示已选范围的填充元素
• .slider__thumb - 单个滑块控制点
• .slider__steps - 轨道内的装饰性步进指示点容器
• .slider__step - 单个步进指示点
• .slider__marks - 位于轨道之后的刻度标签容器
• .slider__mark - 根据数值定位的单个标签

状态类复制锚点链接

• .slider[data-disabled="true"] - 禁用状态
• .slider[data-orientation="vertical"] - 纵向方向
• .slider__thumb[data-dragging="true"] - 滑块正在拖动
• .slider__thumb[data-focus-visible="true"] - 滑块键盘聚焦
• .slider__thumb[data-disabled="true"] - 滑块禁用状态
• .slider__track[data-fill-start="true"] - 填充从起点开始
• .slider__track[data-fill-end="true"] - 填充在终点结束
• .slider__step[data-filled="true"] - 步进指示点位于已选区间内
• .slider__mark[data-filled="true"] - 刻度标签位于已选区间内

指示点与标签的数据属性复制锚点链接

交互状态复制锚点链接

该组件同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：

• 悬停：滑块上的 :hover 或 [data-hovered="true"]
• 聚焦：滑块上的 :focus-visible 或 [data-focus-visible="true"]
• 拖动：滑块上的 [data-dragging="true"]
• 禁用：Slider 或滑块上的 :disabled 或 [data-disabled="true"]

API 参考复制锚点链接

Slider复制锚点链接

Slider.Output复制锚点链接

Slider.Track复制锚点链接

Slider.Fill复制锚点链接

Slider.Thumb复制锚点链接

Slider.Steps复制锚点链接

在 Slider.Track 内根据根组件的范围和步进值渲染装饰性圆点。自动生成子元素，支持标准 DOM 属性和 ref。

Slider.Marks复制锚点链接

包含 Slider.Mark 子组件。直接放置在 Slider 内，位于 Slider.Track 之后。支持标准 DOM 属性和 ref。

Slider.Mark复制锚点链接

在 Slider.Marks 内根据数值定位的标签。支持标准 DOM 属性和 ref。

RenderProps复制锚点链接

对 Slider.Output 或 Slider.Track 使用渲染函数时，会提供以下值：

无障碍复制锚点链接

Slider 组件实现 ARIA slider 模式，并提供：

• 完整的键盘导航支持（方向键、Home、End、Page Up/Down）
• 数值变化时的屏幕阅读器播报
• 合理的焦点管理
• 禁用状态支持
• 通过隐藏 input 元素与 HTML 表单集成
• 结合区域设置进行数值格式化的国际化支持
• 从右到左（RTL）语言支持
• 步进圆点仅用于装饰，对辅助技术隐藏，且不会增加 Tab 停靠点
• 刻度标签保留为可读文本，不会替代 Slider 的无障碍标签或数值播报

更多信息见 React Aria Slider 文档。

相关组件复制锚点链接