用法

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

色相0°

组件结构

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

示例

禁用

色相200°

垂直方向

受控组件

色相200°

当前颜色：hsl(200, 100%, 50%)

HSL 通道

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

色相0°

饱和度100%

明度50%

当前颜色：hsl(0, 100%, 50%)

透明度通道

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

透明度50%

RGB 通道

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

红255

绿100

蓝50

当前颜色：rgb(255, 100, 50)

渲染函数

色相0°

自定义样式

Tailwind CSS

色相220°

全局 CSS

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

@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 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

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

基础类

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

状态类

.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。

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`	是否禁用