# 品牌调色板

> 通过 palettes prop 在 React 颜色选择器中放入自己的品牌色块，也可以用 defaultPalettes 扩展内置色板，而不是整体替换。

Source: https://chroma-panel.jscrate.dev/zh/react/recipes/brand-palette
Last updated: 2026-09-21

如果用户只能从批准的品牌色中选择，而不是随便选一个颜色，就传入你自己的色块。给每个色块起个名字：搜索会用到它，屏幕阅读器也会朗读它。

```tsx
import { ChromaPanel, type ColorPalette } from "chroma-panel";
import "chroma-panel/style.css";

const BRAND: ColorPalette[] = [
  {
    name: "Core",
    colors: [
      { color: "#0b1b3a", name: "Ink" },
      { color: "#3366cc", name: "Signal" },
      { color: "#f5f7fb", name: "Paper" },
    ],
  },
  {
    name: "Status",
    colors: ["#2f9e44", "#f08c00", "#e03131"],
  },
];

export function BrandPicker() {
  return (
    <ChromaPanel
      modes={["palettes", "wheel"]}
      palettes={BRAND}
      defaultValue="#3366cc"
    />
  );
}
```

`modes` 中的第一个模式就是默认模式，所以把 `palettes` 放在最前面，面板打开时就会停在这个标签页上。从列表中去掉 `"wheel"`，品牌色就成了唯一的选色方式。

## 数据结构

`palettes` 接收一个 `ColorPalette[]`。每个调色板是一个分组，包含 `name` 和它的 `colors`：

```tsx
interface ColorPalette {
  name: string;
  colors: (string | { color: string; name?: string })[];
}
```

颜色可以写成字符串，也可以写成带 color 和 name 的对象，同一个分组里两种写法可以混用。字符串和 `value` 走的是同一个解析器，所以 `"#3366cc"`、`"rgb(51 102 204)"` 和 `"hsl(220 60% 50%)"` 都可以。

每个分组渲染为一个 [SwatchGrid](https://chroma-panel.jscrate.dev/zh/react/components/swatch-grid)，其中每个色块都是一个按钮。按钮的可访问名称取自 `name`，没有时就用颜色字符串。选中的色块带有 `aria-pressed`。

搜索会同时匹配颜色字符串和名称，不区分大小写。搜索后变空的分组不会出现在结果中。

## 扩展而不是替换

传入 `palettes` 会直接替换掉三个内置分组。如果想保留它们，并把自己的分组放在前面，就展开 `defaultPalettes()`：

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

<ChromaPanel
  modes={["palettes"]}
  palettes={[...BRAND, ...defaultPalettes()]}
/>;
```

`defaultPalettes()` 每次调用都会生成一个新数组，所以你可以对结果重新排序或过滤，不会影响面板的默认色板。

> **defaultPalettes 只从主入口导出**
>
> 它从 `chroma-panel` 导出，这个入口注册了全部五种模式。`chroma-panel/panel` 和
> `chroma-panel/palettes`
> 这两个入口不导出它。各入口分别包含哪些内容，请参阅[入口](https://chroma-panel.jscrate.dev/zh/react/utils/entry-points)。

## 只有调色板的选择器

有些产品里，批准的颜色就是选择器的全部。只传入一种模式，标签栏也就没有可切换的内容了：

```tsx
<ChromaPanel modes={["palettes"]} palettes={BRAND} showRecentColors={false} />
```

`showRecentColors={false}` 还会去掉底栏中的最近使用色块，否则用户可能通过它们选回已经不在列表里的颜色。

这里值得了解一下 `showAlpha` 不做什么：透明度滑块和透明度 (alpha) 输入框属于色轮和滑块模式，所以只有调色板的选择器无论如何都不会显示它们。该模式的 id、搜索框和内置分组，请参阅[调色板模式](https://chroma-panel.jscrate.dev/zh/react/modes/palettes)页面。