# React 教程

> 用 useState 构建 React 颜色选择器，分别处理实时变化和最终确认的变化，在表单中提交颜色值，并选择合适的选择器布局。

Source: https://chroma-panel.jscrate.dev/zh/react/overview/tutorial
Last updated: 2026-09-21

本指南用几行代码构建一个受控的 React 颜色选择器。你会把颜色值放在 `useState` 里，在用户拖动时更新预览，并在交互结束时保存最终的颜色。

## 安装

```bash
npm install chroma-panel
```

不需要 provider。组件会自行加载样式，所以装好包就可以直接渲染。

## 在 React 应用中添加颜色选择器

当选择器位于表单、设置页或工具栏中时，使用 `ColorInput`。它会渲染一个色块按钮，并在自适应的弹出层中打开面板。

```tsx
import { useState } from "react";
import { ColorInput } from "chroma-panel";

export function AccentColorPicker() {
  const [color, setColor] = useState("#3366cc");

  return (
    <ColorInput
      value={color}
      onChange={(next) => setColor(next.hex)}
      aria-label="Accent color"
    />
  );
}
```

传入 `value` 后，组件就是受控的。如果不需要把颜色值放进 React 状态，把 `value` 换成 `defaultValue`，并去掉 `onChange`。

## 处理 onChange，拖动结束后再保存

指针或键盘改变颜色的过程中，`onChange` 会一直运行，适合用来做实时预览。`onChangeComplete` 只在结束时运行一次，更适合用来写入存储、记录撤销历史、上报统计数据或发起网络请求。

```tsx
<ColorInput
  value={color}
  onChange={(next) => setColor(next.hex)}
  onChangeComplete={(next) => saveTheme({ accent: next.hex })}
/>
```

两个回调都会收到 hex、RGB、HSL、HSV、alpha 和 CSS 字符串等格式的值，你读取应用需要存储的那种格式即可。完整的事件模型见[受控与非受控](https://chroma-panel.jscrate.dev/zh/react/handbook/controlled)。

## 把选择器放在页面上

如果颜色选择器需要一直显示，使用 `ChromaPanel`。它就是去掉触发器和弹出层的同一个选择器。

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

<ChromaPanel
  value={color}
  onChange={(next) => setColor(next.hex)}
  modes={["wheel", "sliders", "palettes"]}
/>;
```

只传入当前任务需要的模式。比如设计工具可能需要滑块和图片取色，而主题设置可能只用得到一组事先审定过的调色板色块。

## 在表单中提交颜色

给 `ColorInput` 设置 `name`，它的值就会包含在 `FormData` 中。`required`、`disabled` 和 `form.reset()` 的效果与其他表单控件一样。

```tsx
<form action={saveProfile}>
  <label htmlFor="profile-color">Profile color</label>
  <ColorInput
    id="profile-color"
    name="profileColor"
    defaultValue="#3366cc"
    format="hex"
    required
  />
  <button type="submit">Save</button>
</form>
```

校验、重置行为以及 React Hook Form 的用法，请阅读[表单指南](https://chroma-panel.jscrate.dev/zh/react/handbook/forms)。

## 选择起点

- 需要弹出层或下拉式颜色选择器，使用 [ColorInput](https://chroma-panel.jscrate.dev/zh/react/components/color-input)。
- 需要内联面板，或者要在模态框里放颜色选择器，使用 [ChromaPanel](https://chroma-panel.jscrate.dev/zh/react/components/chroma-panel)。
- 凭视觉挑选颜色用[色轮](https://chroma-panel.jscrate.dev/zh/react/modes/wheel)；需要精确的 RGB、HSL、HSV 或不透明度数值，用[滑块](https://chroma-panel.jscrate.dev/zh/react/modes/sliders)。
- 品牌色用[调色板](https://chroma-panel.jscrate.dev/zh/react/modes/palettes)；要从上传的图片中取色，用[图片模式](https://chroma-panel.jscrate.dev/zh/react/modes/image)。
- 如果值是线性或径向渐变而不是单一颜色，使用 [GradientEditor](https://chroma-panel.jscrate.dev/zh/react/components/gradient-editor)。

框架相关的配置，请继续阅读 [Next.js](https://chroma-panel.jscrate.dev/zh/react/frameworks/next-js)、[Vite](https://chroma-panel.jscrate.dev/zh/react/frameworks/vite) 或 [Remix](https://chroma-panel.jscrate.dev/zh/react/frameworks/remix)。