# NumberField

> NumberField 是 React 颜色选择器中单个颜色通道（如红色、色相或透明度）的数字输入框，可用来构建自定义选择器模式。

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

`NumberField` 是当前颜色某一个通道的数字输入框，适合已经知道确切数值的用户。在 React 颜色选择器的[滑块模式](https://chroma-panel.jscrate.dev/zh/react/modes/sliders)中，滑块下方那一排输入框就是它：根据所选的颜色模型，分别是 R、G、B，或 H、S、L，或 H、S、B。

和 [ChannelSlider](https://chroma-panel.jscrate.dev/zh/react/components/channel-slider) 一样，它编辑的是你指定的通道：`read` 从颜色中取出一个数值，`write` 把输入的数值合并回去。输入值超出 `min` 和 `max` 时，会先限制在这个范围内，再作用到颜色上。输入框只显示整数，输入时实时更新颜色，失去焦点时提交更改。在自定义模式中把它放在滑块旁边，用户就既能拖动，也能直接输入。

## 结构

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

<NumberField
  label="Hue"
  min={0}
  max={360}
  read={(c) => Math.round(c.h)}
  write={(h, c) => ({ ...c, h })}
/>;
```

> **只能在面板内使用**
>
> 内置模式就是由这些基础组件搭起来的。它通过 `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` (required) | `string` | — | Accessible name for the field. |
| `min` (required) | `number` | — | Lowest value accepted. |
| `max` (required) | `number` | — | Highest value accepted. |
| `step` | `number` | `1` | Arrow-key increment. |
| `read` (required) | `(color: Hsva) => number` | — | Pulls this channel's value out of the current color. |
| `write` (required) | `(value: number, current: Hsva) => Hsva` | — | Merges a typed value back into the color. |
| `className` | `string` | — | Class on the field. |

## 相关内容

- [ChannelSlider](https://chroma-panel.jscrate.dev/zh/react/components/channel-slider)：同样使用 `read` 和 `write` 的滑块
- [滑块模式](https://chroma-panel.jscrate.dev/zh/react/modes/sliders)：内置数字输入框所在的位置
- [ColorField](https://chroma-panel.jscrate.dev/zh/react/components/color-field)：把整个颜色作为一个字符串输入
- [转换](https://chroma-panel.jscrate.dev/zh/react/utils/converting)：从 HSVA 中读取 RGB 或 HSL 值