ColorField 颜色输入框

用法

import { ColorField, parseColor } from '@heroui/react';

组件结构

import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';

export default () => (
  <ColorField>
    <Label />
    <ColorField.Group>
      <ColorField.Prefix>
        <ColorSwatch color="#000000" />
      </ColorField.Prefix>
      <ColorField.Input />
    </ColorField.Group>
    <Description />
    <FieldError />
  </ColorField>
)

ColorField 将标签、颜色输入、描述与错误合并为单个无障碍组件。

示例

变体

ColorField.Group 组件支持两种视觉变体：

• primary（默认）- 标准样式带阴影，适用于大多数场景
• secondary - 低强调变体无阴影，适用于 Surface 组件内

表面样式

在 Surface 组件内使用时，在 ColorField.Group 上使用 variant="secondary" 以应用适合 Surface 背景的低强调变体。

带描述

必填字段

禁用

宽度充满

表单校验

将 isInvalid 与 FieldError 一起使用以显示验证消息。

分量编辑

ColorField 支持通过设置 colorSpace 与 channel 属性编辑单个颜色通道（hue、saturation、lightness、red、green、blue、alpha）。

受控组件

控制值以与其他组件或状态管理同步。

表单示例

包含验证与提交处理的完整表单示例。

渲染函数

自定义样式

Tailwind CSS

全局 CSS

ColorField 默认样式较少。覆盖 .color-field 类以自定义容器样式。

@layer components {
  .color-field {
    @apply flex flex-col gap-1;

    &[data-invalid="true"],
    &[aria-invalid="true"] {
      [data-slot="description"] {
        @apply hidden;
      }
    }

    [data-slot="label"] {
      @apply w-fit;
    }

    [data-slot="description"] {
      @apply px-1;
    }
  }
}

样式参考

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

CSS 类

• .color-field – 最小样式的根容器（flex flex-col gap-1）

Note: 子组件（Label、Description、FieldError）有各自的 CSS 类与样式。请参阅各自文档了解自定义选项。ColorField.Group 样式见下方 API 参考。

交互状态

ColorField 根据状态自动管理以下 data 属性：

• Invalid：[data-invalid="true"] 或 [aria-invalid="true"] - 无效时自动隐藏 description slot
• Required：[data-required="true"] - isRequired 为 true 时应用
• Disabled：[data-disabled="true"] - isDisabled 为 true 时应用
• Focus Within：[data-focus-within="true"] - 任一子 input 聚焦时应用

API 参考

ColorField

ColorField 继承 React Aria ColorField 组件的所有属性。

Base Props

Value Props

Channel Props

Validation Props

State Props

Form Props

Accessibility Props

Composition Components

ColorField 与以下需单独导入并直接使用的组件配合：

• Label - 来自 @heroui/react 的字段标签组件
• ColorField.Group - 颜色输入组组件（见下方文档）
• ColorField.Input - ColorField.Group 内的 input 元素
• ColorField.Prefix / ColorField.Suffix - 输入组的前缀与后缀 slot
• ColorSwatch - 来自 @heroui/react 的颜色预览组件
• Description - 来自 @heroui/react 的帮助文本组件
• FieldError - 来自 @heroui/react 的验证错误消息

每个组件有各自的 props API。在 ColorField 内直接使用它们进行组合：

import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';

<ColorField
  isRequired
  isInvalid={hasError}
  value={color}
  onChange={setColor}
>
  <Label>Brand Color</Label>
  <ColorField.Group>
    <ColorField.Prefix>
      <ColorSwatch color={color?.toString("hex") || "#E4E4E7"} />
    </ColorField.Prefix>
    <ColorField.Input />
  </ColorField.Group>
  <Description>Select your brand's primary color.</Description>
  <FieldError>Please enter a valid color.</FieldError>
</ColorField>

Color Types

ColorField 使用 React Aria Components 的 Color 对象：

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

// Parse from hex string
const color = parseColor('#3B82F6');

// Get hex string from color
const hex = color.toString('hex'); // "#3b82f6"

// Get RGB values
const rgb = color.toString('rgb'); // "rgb(59, 130, 246)"

// Use in ColorField
<ColorField value={color} onChange={setColor}>
  {/* ... */}
</ColorField>

Render Props

对 className、style 或 children 使用 render props 时，可使用以下值：

ColorField.Group

ColorField.Group 接受 React Aria Group 组件的所有属性，以及以下属性：

ColorField.Input

ColorField.Input 接受 React Aria Input 组件的所有属性，以及以下属性：

ColorField.Prefix

ColorField.Prefix 接受标准 HTML div 属性：

ColorField.Suffix

ColorField.Suffix 接受标准 HTML div 属性：

ColorField.Group Styling

Customizing the component classes

基础类驱动每个实例。使用 @layer components 一次性覆盖。

@layer components {
  .color-input-group {
    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;

    &:hover,
    &[data-hovered="true"] {
      @apply bg-field-hover;
    }

    &[data-focus-within="true"],
    &:focus-within {
      @apply status-focused-field;
    }

    &[data-invalid="true"] {
      @apply status-invalid-field;
    }

    &[data-disabled="true"],
    &[aria-disabled="true"] {
      @apply status-disabled;
    }
  }

  .color-input-group__input {
    @apply flex flex-1 items-center rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

  .color-input-group__prefix,
  .color-input-group__suffix {
    @apply shrink-0 text-field-placeholder flex items-center;
  }
}

ColorField.Group CSS Classes

• .color-input-group – 根容器样式
• .color-input-group__input – Input 包装器样式
• .color-input-group__prefix – 前缀元素样式
• .color-input-group__suffix – 后缀元素样式

ColorField.Group Interactive States

• Hover：:hover 或 [data-hovered="true"]
• Focus Within：[data-focus-within="true"] 或 :focus-within
• Invalid：[data-invalid="true"]（与 aria-invalid 同步）
• Disabled：[data-disabled="true"] 或 [aria-disabled="true"]

相关组件