ProComponents, templates & AI tooling
HeroUI
27.7k
快速开始
组件
发布说明
迁移

ColorArea 颜色区域

二维颜色选择器，用户可在渐变区域内选取颜色。

FigmaStorybookReact Aria源代码样式源代码

引入

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

用法

import {ColorArea} from "@heroui/react";

export function ColorAreaBasic() {
  return (
    <ColorArea defaultValue="rgb(116, 52, 255)">
      <ColorArea.Thumb />
    </ColorArea>
  );
}

组件结构

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

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

显示点阵

import {ColorArea} from "@heroui/react";

export function ColorAreaWithDots() {
  return (
    <ColorArea showDots defaultValue="hsl(200, 100%, 50%)">
      <ColorArea.Thumb />
    </ColorArea>
  );
}

受控

Current color: #9B80FF

"use client";

import type {Color} from "@heroui/react";

import {ColorArea, ColorSwatch, parseColor} from "@heroui/react";

颜色空间与通道

使用 colorSpace 设置颜色空间（RGB、HSL、HSB），并通过 xChannel / yChannel prop 自定义横纵轴展示的颜色通道。

Color Space
X Axis
Y Axis
hsb(219, 58%, 93%)
"use client";

import type {ColorSpace, Key} from "@heroui/react";

import {ColorArea, Label, ListBox, Select, parseColor} from "@heroui/react";

禁用

import {ColorArea} from "@heroui/react";

export function ColorAreaDisabled() {
  return (
    <ColorArea isDisabled defaultValue="hsl(200, 100%, 50%)">
      <ColorArea.Thumb />
    </ColorArea>
  );
}

自定义渲染函数

"use client";

import {ColorArea} from "@heroui/react";

export function CustomRenderFunction() {

样式

传入 Tailwind CSS 类

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

function CustomColorArea() {
  return (
    <ColorArea className="max-w-72 rounded-3xl">
      <ColorArea.Thumb />
    </ColorArea>
  );
}

自定义组件类

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

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

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

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

CSS 类

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

基础类

  • .color-area - 基础样式，含渐变背景与内阴影
  • .color-area--show-dots - 叠加点阵网格，便于精确取色

元素类

  • .color-area__thumb - 可拖动的 thumb 指示器

交互状态

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

  • 禁用：[data-disabled="true"]
  • 聚焦：[data-focus-visible="true"]
  • 拖拽：[data-dragging="true"]（仅 thumb）

API 参考

ColorArea Props

继承自 React Aria ColorArea。

Prop类型默认值描述
valuestring | Color-当前颜色值（受控）。
defaultValuestring | Color-默认颜色值（非受控）。
onChange(color: Color) => void-拖拽过程中颜色变化时调用的事件处理函数。
onChangeEnd(color: Color) => void-用户结束拖拽时调用的事件处理函数。
xChannelColorChannel"saturation"水平轴对应的颜色通道。
yChannelColorChannel"brightness"垂直轴对应的颜色通道。
colorSpaceColorSpace-通道所在的颜色空间。
isDisabledbooleanfalse是否禁用 ColorArea。
showDotsbooleanfalse是否显示点阵网格叠加层。
classNamestring-额外的 Tailwind CSS 类。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorAreaRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

ColorArea.Thumb Props

Prop类型默认值描述
classNamestring-额外的 Tailwind CSS 类。
styleCSSProperties | ((renderProps) => CSSProperties)-行内样式或渲染函数。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorThumbRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

CloseButton 关闭按钮

用于关闭对话框、模态框或收起内容的按钮组件。

ColorField 颜色输入框

基于 React Aria ColorField 的颜色输入字段，包含标签、说明与校验能力。

本页目录

引入用法组件结构显示点阵受控颜色空间与通道禁用自定义渲染函数样式传入 Tailwind CSS 类自定义组件类CSS 类基础类元素类交互状态API 参考ColorArea PropsColorArea.Thumb Props