---
title: ColorSlider 颜色滑块
description: 颜色滑块允许用户调整颜色值的单个通道

links:
  rac: ColorSlider
  source: color-slider/color-slider.tsx
  styles: color-slider.css
  storybook: Components/Colors/ColorSlider
  figma: true
---

## 用法

```tsx
import { ColorSlider, Label } from '@heroui/react';
```

<ComponentPreview
  name="color-slider-basic"
/>

## 组件结构

```tsx
import { ColorSlider, Label } from '@heroui/react';

export default () => (
  <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)">
    <Label>Hue</Label>
    <ColorSlider.Output />
    <ColorSlider.Track>
      <ColorSlider.Thumb />
    </ColorSlider.Track>
  </ColorSlider>
)
```
## 示例

### 禁用

<ComponentPreview
  name="color-slider-disabled"
/>

### 垂直方向

<ComponentPreview
  name="color-slider-vertical"
/>

### 受控组件

<ComponentPreview
  name="color-slider-controlled"
/>

### HSL 通道

使用多个 ColorSlider 控制颜色值的不同通道。滑块可共享同一颜色值以构建完整颜色选择器。

<ComponentPreview
  name="color-slider-channels"
/>

### 透明度通道

Alpha 通道滑块显示透明棋盘格图案，帮助可视化透明度级别。

<ComponentPreview
  name="color-slider-alpha-channel"
/>

### RGB 通道

也可使用 RGB 颜色空间的红、绿、蓝通道。

<ComponentPreview
  name="color-slider-rgb-channels"
/>

### 渲染函数

<ComponentPreview
  name="color-slider-render-function"
/>

## 自定义样式

### Tailwind CSS

<ComponentPreview name="color-slider-custom-styles" />

### 全局 CSS

可使用 `@layer components` 指令自定义 ColorSlider 组件类。
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@layer components {
  .color-slider {
    @apply flex flex-col gap-2;
  }

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

  .color-slider__track {
    @apply relative h-5 w-full rounded-full;
  }

  .color-slider__thumb {
    @apply size-4 rounded-full border-3 border-white shadow-overlay;
  }
}
```

## 样式参考

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

ColorSlider 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)）：

#### 基础类 [!toc]
- `.color-slider` - 基础滑块容器
- `.color-slider__output` - 显示当前值的输出元素
- `.color-slider__track` - 带颜色渐变的轨道元素
- `.color-slider__thumb` - 显示当前颜色的滑块元素

#### 状态类 [!toc]
- `.color-slider[data-disabled="true"]` - 禁用滑块状态
- `.color-slider[data-orientation="vertical"]` - 垂直方向
- `.color-slider__thumb[data-dragging="true"]` - 滑块正在拖拽
- `.color-slider__thumb[data-focus-visible="true"]` - 滑块键盘聚焦
- `.color-slider__thumb[data-disabled="true"]` - 禁用滑块状态

### 交互状态

组件同时支持 CSS 伪类与 data 属性：

- **Hover**：滑块上的 `:hover` 或 `[data-hovered="true"]`
- **Focus**：滑块上的 `:focus-visible` 或 `[data-focus-visible="true"]`
- **Dragging**：滑块上的 `[data-dragging="true"]`
- **Disabled**：滑块或 thumb 上的 `:disabled` 或 `[data-disabled="true"]`

## API 参考

### ColorSlider

继承自 [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html)。

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `channel` | `ColorChannel` | - | 滑块操作的颜色通道（hue、saturation、lightness、brightness、alpha、red、green、blue） |
| `colorSpace` | `ColorSpace` | - | 颜色空间（hsl、hsb、rgb）。默认为值的颜色空间 |
| `value` | `string \| Color` | - | 当前颜色值（受控） |
| `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） |
| `onChange` | `(value: Color) => void` | - | 拖拽过程中值变化时的回调 |
| `onChangeEnd` | `(value: Color) => void` | - | 拖拽结束时的回调 |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 滑块方向 |
| `isDisabled` | `boolean` | - | 是否禁用 |
| `name` | `string` | - | 表单提交时 input 元素的名称 |
| `aria-label` | `string` | - | 滑块的无障碍标签 |
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `ReactNode \| RenderFunction` | - | 滑块内容或 render 函数 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSliderRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

### ColorSlider.Output

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `ReactNode \| RenderFunction` | - | 输出内容或 render 函数 |

### ColorSlider.Track

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `style` | `CSSProperties \| RenderFunction` | - | 内联样式或 render 函数 |
| `children` | `ReactNode \| RenderFunction` | - | 轨道内容或 render 函数 |

### ColorSlider.Thumb

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `style` | `CSSProperties \| RenderFunction` | - | 内联样式或 render 函数 |
| `children` | `ReactNode \| RenderFunction` | - | 滑块内容或 render 函数 |

### Render Props

使用 render 函数时，提供以下值：

| Prop | 类型 | 描述 |
|------|------|------|
| `state` | `ColorSliderState` | 颜色滑块的状态 |
| `color` | `Color` | 当前颜色值 |
| `orientation` | `"horizontal" \| "vertical"` | 滑块方向 |
| `isDisabled` | `boolean` | 是否禁用 |

## 无障碍

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

- 完整键盘导航支持（方向键、Home、End、Page Up/Down）
- 值变化的屏幕阅读器播报
- 正确的焦点管理
- 禁用状态支持
- 通过隐藏 input 元素集成 HTML 表单
- 支持 locale 感知值格式化的国际化

更多信息请参阅 [React Aria ColorSlider 文档](https://react-spectrum.adobe.com/react-aria/ColorSlider.html)。

## 相关组件

<RelatedComponents component="color-slider" />