# 常见问题

> React 颜色选择器与 Next.js、Tailwind、shadcn/ui、表单、TypeScript、渐变、现代 CSS 颜色和图片配合使用时的解答。

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

配置或行为不清楚时，先看这里。每个回答都链接到对应的指南，里面有代码和完整的 API 说明。

## 如何在 Next.js 中使用颜色选择器？

安装后直接导入即可。App Router、Remix 和其他服务端渲染方案都不需要特殊处理。所有需要浏览器环境的文件都已标记 `'use client'`，所以你不必为了导入它而标记自己的文件，也没有代码会在模块顶层读取 `window`。如果希望水合之前的标记也带有样式，请在根布局中导入 `chroma-panel/style.css`，并传入 `injectStyles={false}`。详细说明见[服务端渲染](https://chroma-panel.jscrate.dev/zh/react/handbook/server-rendering)。

## 能和 Tailwind CSS 一起用吗？

可以。通过 `classNames` prop 传入工具类，面板的每个部分对应一个键，例如 `root`、`trigger`、`swatch` 或 `slider`。本包的样式放在 `@layer chroma-panel` 中，所以在 Tailwind v4 里需要你自己声明图层顺序：在 preflight 之后、utilities 之前导入 `chroma-panel/style.css`，你的类名就会优先生效。颜色和尺寸都是 `--cp-*` CSS 变量。[使用 Tailwind 样式](https://chroma-panel.jscrate.dev/zh/react/handbook/tailwind)给出了具体的导入写法。

## 能在 shadcn/ui 项目中使用吗？

可以，作为独立组件使用。chroma-panel 并不是基于 shadcn/ui 或 Radix 构建的。它和其他包一样从 npm 安装，不需要 provider。放进 shadcn/ui 项目，和放进任何 Tailwind 应用没有区别：通过 `classNames` 传入你的类名，再设置 `--cp-*` 变量，让颜色和圆角与你的主题一致。面板会跟随系统配色方案，所以如果你的应用通过类名切换深色模式，请传入 `theme="dark"` 或 `theme="light"` 保持一致。可运行的代码见 [shadcn/ui 集成](https://chroma-panel.jscrate.dev/zh/react/integrations/shadcn-ui)，所有 CSS 变量见[主题指南](https://chroma-panel.jscrate.dev/zh/react/handbook/theming)。

## 能和 Material UI 或 React Aria 一起用吗？

可以。如果可以让 `ColorInput` 自己管理弹出层，直接渲染它即可。如果希望由 Material UI 或 React Aria 控制浮层，就把内联的 `ChromaPanel` 放进该库的 Popover 或 Dialog 中。这样可以避免嵌套两套焦点管理。详见 [Material UI](https://chroma-panel.jscrate.dev/zh/react/integrations/material-ui) 和 [React Aria](https://chroma-panel.jscrate.dev/zh/react/integrations/react-aria) 指南。

## 如何获取 hex 值？

从变化结果中读取。`onChange` 和 `onChangeComplete` 收到的都是一个同时包含所有格式的对象，其中有 `hex`、`rgba`、`hsva` 和 `css`，与你把 `format` 设成什么无关。

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

<ColorInput onChangeComplete={(color) => save(color.hex)} />;
```

`hex` 的每个通道会取整到 8 位，所以如果颜色必须原样恢复，请存储 `hsva`。`ColorChangeResult` 的所有字段见 [TypeScript](https://chroma-panel.jscrate.dev/zh/react/handbook/typescript)。

## 如何在表单中使用？

使用 `ColorInput` 并给它设置 `name`。它会像原生输入框一样随表单提交，在 `form.reset()` 时恢复为 `defaultValue`，并支持用 `required` 做原生校验。提交的字符串格式由 `format` prop 决定，所以需要 `rgba()` 的表单可以直接拿到这种格式。如果你自己渲染错误信息，请传入 `validationBehavior="aria"`。如果颜色值由你自己控制，重置也需要你自己处理。[表单](https://chroma-panel.jscrate.dev/zh/react/handbook/forms)中有可运行的示例。

## 哪些浏览器支持取色器？

取色器使用浏览器的 `EyeDropper` API，目前只有 Chrome、Edge 等 Chromium 系浏览器支持。`showEyedropper` 默认为 `true`，但只有在 API 存在时才会渲染按钮，所以在其他浏览器中不会出错，只是不渲染这个按钮。如果你自己做触发器，请在渲染前检查 `useEyedropper().supported`。详见[浏览器支持](https://chroma-panel.jscrate.dev/zh/react/handbook/browser-support)和 [useEyedropper](https://chroma-panel.jscrate.dev/zh/react/utils/use-eyedropper)。

## 它是用 TypeScript 编写的吗？

是的。本包为 ESM 和 CommonJS 都提供了自带的类型声明，所以无需安装 `@types` 包。每个变化处理函数都会收到带类型的 `ColorChangeResult`，prop 接口 `ChromaPanelProps` 和 `ColorInputProps` 也已导出，方便你扩展。`Hsva`、`Rgba`、`ColorFormat` 和 `ModeId` 等类型同样已导出。[TypeScript](https://chroma-panel.jscrate.dev/zh/react/handbook/typescript) 演示了如何为处理函数添加类型。

## 打包体积有多大？

导入包含全部五种模式的 `chroma-panel`，会给应用增加 23.1 kB（gzip）。只导入面板外壳和一种模式，增加 15.0 kB。两个数字都是在 Vite 生产构建中把 React 设为 external 后测得的增量。本包没有依赖，`react` 和 `react-dom` 是 peer dependency，所以用的是你应用中已有的那一份。如何只导入需要的模式，见[入口](https://chroma-panel.jscrate.dev/zh/react/utils/entry-points)。

## 这个颜色选择器支持无障碍访问吗？

支持，而且不需要额外配置。每一条颜色轴都是真实的 `<input type="range">`，所以键盘和屏幕阅读器支持都来自浏览器。方向键逐步调整，Page Up 和 Page Down 调整幅度更大，Home 和 End 直接跳到两端。数值以文字形式朗读，弹出层会锁定焦点，按 Escape 关闭，并把焦点交还给触发器。减少动态效果和强制颜色模式也都已处理。详细说明见[无障碍功能](https://chroma-panel.jscrate.dev/zh/react/overview/accessibility)。

## 支持哪些 React 版本？

React 16.14 及以上版本，包括 17、18 和 19。`react` 和 `react-dom` 是 peer dependency，不会打包进来。之所以需要 React DOM，是因为弹出层通过 `createPortal` 渲染。ESM 和 CommonJS 两种构建都已包含。包括浏览器和服务端渲染在内的完整兼容性表格，见[关于](https://chroma-panel.jscrate.dev/zh/react/overview/about#compatibility)页。

## 能从图片中取色吗？

可以。图片是五种内置模式之一。把图片拖进去，或点击选择文件，它就会提取图片的主要颜色供你挑选。你还可以在图片上移动鼠标查看放大预览，并点击某个像素精确取色。在开始有限度的取样之前，会先检查文件和图片尺寸。传入 `imageOptions={{ maxColors: 12 }}` 可以限制颜色数量。要在自己的界面中对图片取样，调用 `extractPalette`。详见[图片模式](https://chroma-panel.jscrate.dev/zh/react/modes/image)。

## 支持渐变和 OKLCH 吗？

支持。`GradientEditor` 位于单独的 `chroma-panel/gradient` 入口，负责处理线性和径向渐变。颜色引擎通过 `chroma-panel/color` 解析和转换 OKLCH、OKLab、Lab、LCH、sRGB 和 Display P3。除非你主动导入，否则这些功能不会进入纯色选择器的打包结果。详见 [GradientEditor](https://chroma-panel.jscrate.dev/zh/react/components/gradient-editor) 和 [CSS Color 4](https://chroma-panel.jscrate.dev/zh/react/utils/css-color-4)。