用法

import {
  ColorPicker,
  ColorArea,
  ColorSlider,
  ColorSwatch,
  ColorField,
  ColorSwatchPicker,
} from '@heroui/react';

组件结构

ColorPicker 是组合多个颜色组件的可组合组件：

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

export default () => (
  <ColorPicker defaultValue="#0485F7">
    <ColorPicker.Trigger>
      <ColorSwatch />
      <Label>Pick a color</Label>
    </ColorPicker.Trigger>
    <ColorPicker.Popover>
      <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">
        <ColorArea.Thumb />
      </ColorArea>
      <ColorSlider channel="hue" colorSpace="hsb">
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
    </ColorPicker.Popover>
  </ColorPicker>
);

示例

受控组件

已选：#325578

带色板

带输入字段

使用 ColorField 允许用户编辑单个颜色通道值，配合 Select 切换颜色空间。

带滑块

使用多个 ColorSlider 组件调整颜色值的各通道。

自定义样式

Tailwind CSS

全局 CSS

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

@layer components {
  .color-picker {
    @apply inline-flex;
  }

  .color-picker__trigger {
    @apply inline-flex items-center gap-4 rounded-lg;
  }

  .color-picker__popover {
    @apply p-4 rounded-xl;
  }
}

样式参考

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

CSS 类

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

基础类

.color-picker - 基础容器
.color-picker__trigger - 触发按钮
.color-picker__popover - 弹出层容器

交互状态

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

Focus：:focus-visible 或 [data-focus-visible="true"]
Disabled：:disabled 或 [data-disabled="true"]

API 参考

ColorPicker

继承自 React Aria ColorPicker。

Prop	类型	默认值	描述
`value`	`string \| Color`	-	当前颜色值（受控）
`defaultValue`	`string \| Color`	-	默认颜色值（非受控）
`onChange`	`(color: Color) => void`	-	颜色变化时的回调
`children`	`React.ReactNode`	-	颜色选择器内容（Trigger、Popover 等）
`className`	`string`	-	附加 CSS 类

ColorPicker.Trigger

Prop	类型	默认值	描述
`children`	`React.ReactNode \| ((renderProps) => React.ReactNode)`	-	触发器内容或 render prop
`className`	`string`	-	附加 CSS 类

ColorPicker.Popover

Prop	类型	默认值	描述
`placement`	`Placement`	`"bottom left"`	弹出层位置
`children`	`React.ReactNode`	-	弹出层内容
`className`	`string`	-	附加 CSS 类

Color

表示颜色值。完整 API 请参阅 React Aria Color。

Method	Description
`toString(format)`	将颜色转换为指定格式的字符串（hex、rgb、hsl、hsb、css）
`toFormat(format)`	将颜色转换为指定格式并返回新的 Color 对象
`getChannelValue(channel)`	返回指定通道的数值
`withChannelValue(channel, value)`	设置通道数值并返回新的 Color

parseColor

import { parseColor } from 'react-aria-components';

// Parse from string
const color = parseColor('#ff0000');
const hslColor = parseColor('hsl(0, 100%, 50%)');