ColorArea 颜色区域

二维颜色选择器，允许用户从渐变区域中选择颜色

用法

1import { ColorArea } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3import { ColorArea } from "@lenso/ui";4
5export function ColorAreaBasic() {6  return (7    <ColorArea aria-label="Color area" defaultValue="rgb(116, 52, 255)">8      <ColorArea.Thumb />9    </ColorArea>10  );11}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

1import { ColorArea } from '@lenso/ui';2
3export default () => (4  <ColorArea>5    <ColorArea.Thumb />6  </ColorArea>7);

示例

带定位点

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. */3import { ColorArea } from "@lenso/ui";4export function ColorAreaWithDots() {5  return (6    <ColorArea aria-label="Color area" showDots defaultValue="hsl(200, 100%, 50%)">7      <ColorArea.Thumb />8    </ColorArea>9  );10}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

色彩空间与通道

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

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. Base UI owns the ordinary selects. */3import { ColorArea, parseColor } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6import { styles } from "../color-picker/source.stylex";7import { ColorDemoSelect } from "../color-picker/source";8type Space = "rgb" | "hsl" | "hsb";9type Channel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue";10const channelsBySpace: Record<Space, Channel[]> = {11  rgb: ["red", "green", "blue"],12  hsl: ["hue", "saturation", "lightness"],13  hsb: ["hue", "saturation", "brightness"],14};15export function ColorAreaSpaceAndChannels() {16  const [colorSpace, setColorSpace] = useState<Space>("hsb");17  const [color, setColor] = useState(() => parseColor("hsb(219, 58%, 93%)"));18  const [xChannel, setXChannel] = useState<Channel>("saturation");19  const [yChannel, setYChannel] = useState<Channel>("brightness");20  function changeSpace(space: Space) {21    setColorSpace(space);22    setXChannel(space === "rgb" ? "blue" : "saturation");23    setYChannel(space === "rgb" ? "green" : space === "hsl" ? "lightness" : "brightness");24  }25  const channels = channelsBySpace[colorSpace];26  return (27    <div {...stylex.props(styles.centeredColumn)}>28      <div {...stylex.props(styles.controls)}>29        <ColorDemoSelect30          label="Color Space"31          value={colorSpace}32          options={["rgb", "hsl", "hsb"]}33          onChange={changeSpace}34          width={128}35          uppercase36        />37        <ColorDemoSelect38          label="X Axis"39          value={xChannel}40          options={channels.filter((c) => c !== yChannel)}41          onChange={setXChannel}42          width={144}43        />44        <ColorDemoSelect45          label="Y Axis"46          value={yChannel}47          options={channels.filter((c) => c !== xChannel)}48          onChange={setYChannel}49          width={144}50        />51      </div>52      <ColorArea53        aria-label="Color area"54        colorSpace={colorSpace}55        value={color}56        xChannel={xChannel}57        yChannel={yChannel}58        onChange={setColor}59      >60        <ColorArea.Thumb />61      </ColorArea>62      <div {...stylex.props(styles.row)}>63        <div {...stylex.props(styles.preview)} style={{ backgroundColor: color.toString("css") }} />64        <code {...stylex.props(styles.code)}>{color.toString(colorSpace)}</code>65      </div>66    </div>67  );68}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

禁用

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. */3import { ColorArea } from "@lenso/ui";4export function ColorAreaDisabled() {5  return (6    <ColorArea aria-label="Color area" isDisabled defaultValue="hsl(200, 100%, 50%)">7      <ColorArea.Thumb />8    </ColorArea>9  );10}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

受控组件

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. */3import { ColorArea, ColorSwatch, parseColor } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6import { styles } from "../color-picker/source.stylex";7export function ColorAreaControlled() {8  const [color, setColor] = useState(parseColor("#9B80FF"));9  return (10    <div {...stylex.props(styles.column)}>11      <ColorArea12        aria-label="Color area"13        colorSpace="rgb"14        value={color}15        xChannel="red"16        yChannel="green"17        onChange={setColor}18      >19        <ColorArea.Thumb />20      </ColorArea>21      <div {...stylex.props(styles.row, styles.width300)}>22        <ColorSwatch color={color} size="md" />23        <p {...stylex.props(styles.muted)}>24          Current color: <span {...stylex.props(styles.medium)}>{color.toString("hex")}</span>25        </p>26      </div>27    </div>28  );29}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

渲染函数

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. Native RAC render state replaces DOM render interception. */3import { ColorArea } from "@lenso/ui";4export function RenderFunction() {5  return (6    <ColorArea aria-label="Color area" defaultValue="rgb(116, 52, 255)" data-custom="slider">7      {({ isDisabled }) => (8        <ColorArea.Thumb data-custom="thumb" data-disabled={isDisabled || undefined} />9      )}10    </ColorArea>11  );12}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** Adapted from HeroUI v3.2.6. Apache-2.0. */3import { ColorArea } from "@lenso/ui";4import { styles } from "../color-picker/source.stylex";5export function CustomStyles() {6  return (7    <ColorArea aria-label="Color area" xstyle={styles.areaCustom} defaultValue="rgb(116, 52, 255)">8      <ColorArea.Thumb xstyle={styles.areaThumb} />9    </ColorArea>10  );11}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

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

1@layer components {2  .color-area {3    @apply rounded-3xl;4  }5
6  .color-area__thumb {7    @apply size-5 border-4;8  }9}

样式参考

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

CSS 类

ColorArea 组件使用以下 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。

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 元素

ColorArea 颜色区域

用法

组件结构

示例

带定位点

色彩空间与通道

禁用

受控组件

渲染函数

自定义样式

Tailwind CSS

全局 CSS

样式参考

CSS 类

基础类 [!toc]

元素类 [!toc]

交互状态

API 参考

ColorArea

ColorArea.Thumb

相关组件