# 图片

> 在 React 中从图片取色：上传、拖入或粘贴图片，提取主色调色板，并借助放大预览精确采样某个像素。

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

图片模式可以把上传的照片、logo 或截图变成一组调色板。拖入、粘贴或选择文件后，点击预览图即可采样单个像素。几乎透明的像素会被跳过，所以透明背景的 logo 返回的是 logo 本身的颜色，而不是空白背景。色块用的是 [SwatchGrid](https://chroma-panel.jscrate.dev/zh/react/components/swatch-grid)，采样由 `extractPalette` 完成，你也可以自己调用它，传入 `File`、`Blob` 或图片 URL。键盘用户可以聚焦图片，按 Enter 或空格键选取图片中心的颜色。

## 结构

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

<ChromaPanel
  modes={[imageMode]}
  imageOptions={{ maxColors: 12 }}
  modeProps={{ image: { sortBy: "luminance" } }}
/>;
```

采样器会先校验文件再处理，并在一个尺寸受限、经过缩小的画布上读取像素。默认情况下，文件大小上限为 20 MB，解码后的图片上限为 4000 万像素。关闭再重新打开选择器时，已加载的图片会保留；替换或移除图片时才会释放。

解码使用的是 `createImageBitmap`，如果需要支持旧版浏览器，请查看[图片采样的浏览器支持情况](https://chroma-panel.jscrate.dev/zh/react/handbook/browser-support)。

`imageOptions` 是一种简写，下面两种写法等价：

```tsx
<ChromaPanel imageOptions={{ maxColors: 12 }} />
<ChromaPanel modeProps={{ image: { extractOptions: { maxColors: 12 } } }} />
```

完整的安全与采样选项如下：

| Option            |    Default | 作用                              |
| ----------------- | ---------: | --------------------------------- |
| `maxColors`       |        `8` | `extractPalette` 返回的主色数量   |
| `size`            |      `100` | 采样画布的最长边                  |
| `alphaThreshold`  |      `128` | 采样时忽略透明像素的阈值          |
| `maxFileSize`     | `20971520` | 文件大小上限，单位为字节（20 MB） |
| `maxSourcePixels` | `40000000` | 解码后的尺寸上限（4000 万像素）   |
| `worker`          |          — | 可选的 worker 或 worker 工厂函数  |
| `signal`          |          — | 可选的取消信号                    |

`sortBy` 属于图片面板的选项，而不是提取选项。通过 `modeProps.image` 把它设为 `'population'`（默认）、`'luminance'` 或 `'hue'`。

采样耗时只有几毫秒，所以默认在主线程上运行。如果把 `size` 调得很大，就把它移到 worker 中。请在你自己的源码里构造 URL，这样打包工具才能解析它：

```ts
const url = new URL("chroma-panel/image-worker", import.meta.url);
const worker = new Worker(url, { type: "module" });

await extractPalette(file, { size: 400, worker });
```

这个 worker 是一个独立的[入口](https://chroma-panel.jscrate.dev/zh/react/utils/entry-points)。包里没有其他代码导入它，所以只有在你创建 worker 时才会加载。

## 演示

```tsx
"use client";

import { ChromaPanel } from "chroma-panel";

export default function ChromaPanelImageDemo() {
  return (
    <ChromaPanel
      defaultValue="#3366cc"
      modes={["image"]}
      showTitleBar={false}
      injectStyles={false}
    />
  );
}
```

## API 参考

```ts
function extractPalette(source: Blob | File | string, options?: ExtractOptions): Promise<ExtractResult>
```

Samples dominant colors from a validated image using a bounded, downscaled pixel surface.

```ts
function quantize(data: Uint8ClampedArray, maxColors: number, alphaThreshold?: number): QuantizedSwatch[]
```

The color quantizer behind extractPalette, for when you already have pixel data.

## 模式 id

`'image'`。把它加入 `modes` 就会显示这个标签页，标签页的顺序与它们在 `modes` 中的顺序一致。