# 为什么选择 Chroma Panel

> 需要多种取色方式、图片取色、表单支持和现代 CSS 颜色时，选这个 React 颜色选择器。也看看什么情况下更小的选择器更合适。

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

当一个 hex 输入框不够用时，就选 chroma-panel。它把色轮、精确滑块、调色板、图片取色、取色器和可直接用于表单的输入框放在同一套 API 后面。如果你只想要一个小巧的 hex 选择器，更小的库可能更合适。

## 它是最适合你应用的 React 颜色选择器吗？

这取决于具体需求。如果同一个界面需要多种取色方式，或者表单、图片取色、渐变和现代 CSS 颜色原本要靠几个不同的包来实现，就选 chroma-panel。如果你要的只是一个饱和度区域加一个 hex 输入框，选更小的选择器。[对比](https://chroma-panel.jscrate.dev/zh/react/overview/comparison)页列出了各项取舍和数据来源。

## 这些情况选它

- **用户需要不止一种取色方式。** 面板自带五种模式：色轮、滑块、调色板、图片和预设色，都放在一个标签栏里，用户可以随时切换。传入 `modes` 可以只显示其中一部分，顺序与你列出的一致。
- **你需要取色器。** 取色器是面板的一部分。只有在浏览器提供相应 API 时才会渲染这个按钮，所以你不用自己去隐藏它。要把取色器放在别处，使用 [`useEyedropper`](https://chroma-panel.jscrate.dev/zh/react/utils/use-eyedropper)，它提供一个 `supported` 标志和一个 `pick()` 方法。
- **你需要从图片中取色。** 用户拖入一张照片、一个 logo 或一张截图，[图片模式](https://chroma-panel.jscrate.dev/zh/react/modes/image)会把其中的主要颜色显示为色块。
- **颜色需要随表单一起提交。** `ColorInput` 接受 `name`，表现得和普通输入框一样：随表单提交，响应 `form.reset()`，并参与原生校验。详见[表单](https://chroma-panel.jscrate.dev/zh/react/handbook/forms)。
- **你需要预设色块。** 调色板模式通过 `palettes` 接收分组命名的色块，上方还有一个搜索框。预设色模式是一个 120 色的网格，可以用 `pencils` 替换。
- **你希望零运行时依赖，并且自带类型。** 本包没有 `dependencies`。`react` 和 `react-dom` 是 peer dependency，所以用的是你项目里的那一份，也不需要安装 `@types` 包。支持 React 16.14 及以上版本，包括 19。MIT 许可证。
- **颜色来回转换后不能失真。** 面板保存的是完整的 HSVA 值，而不是 hex 字符串，所以色相不会在极端值处丢失。

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

<ColorInput name="brand" defaultValue="#3366cc" format="rgba" required />;
```

## 这些情况选别的

- **你要的只是普通的 hex 选择器，而且在意那 4.9 kB。** react-colorful 更小，没有依赖，也自带类型。如果一个饱和度区域、一个色相滑块和一个 hex 输入框就够用，那就选它。
- **你想要现成的 Sketch 或 Photoshop 风格选择器。** react-color 自带 13 种。chroma-panel 只有一种外观，需要通过 CSS 自定义属性调整样式，而不是整体换掉。
- **你在开发 React Native 应用。** 不支持。组件渲染的是 DOM 元素，`react-dom` 是 peer dependency，弹出层也要通过 `createPortal` 渲染。
- **你需要一整套基于 canvas 的色彩管理方案。** 1.0 版本支持 OKLCH、OKLab、Lab、LCH 和 Display P3，但不会检查嵌入的 ICC 配置文件，也不能替代专门的图片编辑器。
- **你想要一个有多年下载记录的包。** 这个包还很新。它于 2026 年 9 月 14 日首次发布，当前版本是 1.0.1，所以 issue 历史、下载量、博客文章这些常见的参考信号还没有积累起来。

## 多出来的体积换来了什么

以下两个数字都是 gzip 后的体积，测量方式是在 Vite 生产构建中把 React 设为 external，统计增加的体积：

| 导入内容           | 应用增加的体积 |
| ------------------ | -------------- |
| 全部五种模式       | 23.1 kB        |
| 面板外壳加一种模式 | 15.0 kB        |

15.0 kB 是下限，包括面板外壳、颜色引擎、弹出层、文本输入框和一种模式。其余的体积来自另外四种模式。这就是在这里用它替代 react-colorful 的代价，换来的是带亮度滑块的色相轮、RGB/HSL/HSB 各通道滑块、可搜索的调色板、图片取色，以及 120 色的预设色网格。

这些不必全部引入。按[入口](https://chroma-panel.jscrate.dev/zh/react/utils/entry-points)中的做法，只导入面板外壳和你实际渲染的模式即可。单靠 tree shaking 删不掉某个模式，因为每种模式在其文件加载时都会自行注册，所以要减小体积，就得少导入几个入口。

> **以副作用方式导入模式**
>
> 要写 `import
> "chroma-panel/wheel"`，不要用具名导入，否则打包工具可能会把它删掉。

## 为什么要用 HSVA 保存状态

HSV 有两处会丢失信息：饱和度为零时，色相就不存在了；亮度为零时，色相和饱和度都不存在。用 RGB 或 hex 保存状态的选择器，每当有人把亮度拖到黑色再拖回来，都会碰到这个问题：选好的色相会变回红色。本包保存完整的 HSVA 值，每次改动都合并进去，而不是整体替换，所以你最初选的颜色，最后还能原样拿回来。[关于](https://chroma-panel.jscrate.dev/zh/react/overview/about)页说明了这个设计决定，同一套引擎也已导出，想在面板之外使用也可以。

## 下一步

- [快速开始](https://chroma-panel.jscrate.dev/zh/react/overview/quick-start)：安装并渲染一个选择器。
- [对比](https://chroma-panel.jscrate.dev/zh/react/overview/comparison)：四个库的各项数据，以及如何从 react-colorful 迁移。
- [常见问题](https://chroma-panel.jscrate.dev/zh/react/overview/faq)：简短的解答，包括打包体积、Next.js 和取色器支持。