# ColorField

> ColorField 是 React 颜色选择器的文本输入框，支持 hex、rgb()、hsl() 和 hwb() 字符串，注册后还能输入 CSS 颜色名称。

Source: https://chroma-panel.jscrate.dev/zh/react/components/color-field
Last updated: 2026-09-21

`ColorField` 是选择器里用来输入或粘贴颜色的文本框。它可以当作十六进制颜色输入框使用，也能识别 `rgb()`、`hsl()` 和 `hwb()` 字符串；把 CSS 颜色名称注册为[命名颜色](https://chroma-panel.jscrate.dev/zh/react/utils/named-colors)之后，还能直接输入颜色名称。不管输入的是哪种格式，离开输入框后都会显示为十六进制。

只要文本能解析，颜色就会立即更新；输入框失去焦点或按下 Enter 时提交更改。文本无法解析时，输入框会带上 `aria-invalid`，离开时恢复为上一个有效颜色。[色轮模式](https://chroma-panel.jscrate.dev/zh/react/modes/wheel)和滑块模式的最下方都有一个这样的输入框。如果自定义模式需要让用户输入精确值，就可以用它。设置 `withAlpha` 后，透明度通道会以八位十六进制显示，例如 `#3366ccff`。

## 结构

```tsx
import { ColorField } from "chroma-panel";

<ColorField label="Hex" withAlpha />;
```

支持哪些格式，请参阅[解析](https://chroma-panel.jscrate.dev/zh/react/utils/parsing)。

> **只能在面板内使用**
>
> 内置模式就是由这些基础组件搭起来的。它通过 `usePanel()` 读取颜色，所以只能放在 `ChromaPanel` 里使用，通常用在[自定义模式](https://chroma-panel.jscrate.dev/zh/react/modes/custom)中。如果要在面板之外做颜色选择器，请使用[颜色 store 和相关 hook](https://chroma-panel.jscrate.dev/zh/react/utils/use-color-store)。

## API 参考

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `'Hex'` | The label beside the field. |
| `withAlpha` | `boolean` | `false` | Accept and show the alpha channel, so `#3366ccff` round-trips. |
| `className` | `string` | — | Class on the field. |

## 相关内容

- [解析](https://chroma-panel.jscrate.dev/zh/react/utils/parsing)：输入框支持的所有字符串格式
- [命名颜色](https://chroma-panel.jscrate.dev/zh/react/utils/named-colors)：让用户可以输入 `rebeccapurple` 这样的名称
- [序列化](https://chroma-panel.jscrate.dev/zh/react/utils/serializing)：把颜色转换成其他字符串格式
- [NumberField](https://chroma-panel.jscrate.dev/zh/react/components/number-field)：只输入一个通道，而不是整个颜色