---
title: ColorArea 颜色区域
description: 二维颜色选择器，允许用户从渐变区域中选择颜色
links:
  rac: ColorArea
  source: color-area/color-area.tsx
  styles: color-area.css
  storybook: Components/Colors/ColorArea
  figma: true
---

## 用法

```tsx
import { ColorArea } from '@heroui/react';
```

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

## 组件结构

```tsx
import { ColorArea } from '@heroui/react';

export default () => (
  <ColorArea>
    <ColorArea.Thumb />
  </ColorArea>
);
```

## 示例

### 带定位点

<ComponentPreview
  name="color-area-with-dots"
/>

### 色彩空间与通道

使用 `colorSpace` 设置颜色空间（RGB、HSL、HSB），使用 `xChannel`/`yChannel` 自定义各轴显示的颜色通道。

<ComponentPreview
  name="color-area-space-and-channels"
/>

### 禁用

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

### 受控组件

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

### 渲染函数

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

## 自定义样式

### Tailwind CSS

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

### 全局 CSS

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

```css
@layer components {
  .color-area {
    @apply rounded-3xl;
  }

  .color-area__thumb {
    @apply size-5 border-4;
  }
}
```

## 样式参考

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

### CSS 类

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

#### 基础类 [!toc]
- `.color-area` - 渐变背景与内阴影的基础样式
- `.color-area--show-dots` - 添加点阵网格覆盖层以精确选色

#### 元素类 [!toc]
- `.color-area__thumb` - 可拖拽的滑块指示器

### 交互状态

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

- **Disabled**：`[data-disabled="true"]`
- **Focus**：`[data-focus-visible="true"]`
- **Dragging**：`[data-dragging="true"]`（仅 thumb）

## API 参考

### ColorArea

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

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `value` | `string \| Color` | - | 当前颜色值（受控） |
| `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） |
| `onChange` | `(color: Color) => void` | - | 拖拽过程中颜色变化时的回调 |
| `onChangeEnd` | `(color: Color) => void` | - | 用户停止拖拽时的回调 |
| `xChannel` | `ColorChannel` | `"saturation"` | 水平轴的颜色通道 |
| `yChannel` | `ColorChannel` | `"brightness"` | 垂直轴的颜色通道 |
| `colorSpace` | `ColorSpace` | - | 通道使用的颜色空间 |
| `isDisabled` | `boolean` | `false` | 是否禁用 |
| `showDots` | `boolean` | `false` | 是否显示点阵网格覆盖层 |
| `className` | `string` | - | 附加 CSS 类 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorAreaRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

### ColorArea.Thumb

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | 内联样式或 render props 函数 |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorThumbRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

## 相关组件

<RelatedComponents component="color-area" />