[English](./README.md) | 简体中文
# @ray-js/image-color-picking
[](https://www.npmjs.com/package/@ray-js/image-color-picking) [](https://www.npmjs.com/package/@ray-js/image-color-picking)
> 识图取色
> 内部通过 canvas 获取图片像素颜色，然后通过聚合算法计算出出现较多次且相互之间不是非常接近的若干数量的颜色
## 安装
```sh
$ npm install @ray-js/image-color-picking
// 或者
$ yarn add @ray-js/image-color-picking
```
## 使用
### 基本使用
1. 引入 `ImageColorPicker` 组件，放置在页面上，因为组件内部是通过 canvas 获取颜色的，所以需要页面上有一个组件作为获取颜色的基础， id 默认需要传 `image-color-picking`。
2. 引入 `imageColorPicking` 方法，传入文件路径获取主要颜色, `pickNum` 属性可以控制提取的主要颜色数量。
3. `imageColorPickingDestroy` 方法可以在组件销毁时清除缓存队列
```tsx
import {
imageColorPicking,
ImageColorPicker,
chooseCropImageSync,
imageColorPickingDestroy,
} from '@ray-js/image-color-picking';
import React, { useEffect } from 'react';
import { View } from '@ray-js/ray';
const Demo = () => {
useEffect(() => {
return () => {
// 销毁组件缓存队列 v1.1.0版本支持
imageColorPickingDestroy();
};
}, []);
const run = async () => {
// 调用app能力选择本地手机图片路径
const path = await chooseCropImageSync();
// 取消了
if (typeof path !== 'string') return;
// 获取主要颜色
const colors = await imageColorPicking({
path,
pickNum: 8,
});
console.log(colors, '--获取到的颜色');
};
return (
<>
点击执行
);
};
```
### 自定义 id 和传入 base64 用法
1. 通过挂载在页面上的组件设置不同的 id 如：`my-custom`, 则在调用 `imageColorPicking` 方法时也需要传对应的 `selector` 属性 使方法可以获取到此组件实例
2. 通过 `readImgSync` 方法将手机内的图片路径转换成 base64 格式，然后使用 `imageColorPicking` 方法发送给组件内部运行并返回颜色。
```tsx
import {
imageColorPicking,
ImageColorPicker,
chooseCropImageSync,
readImgSync,
imageColorPickingDestroy,
} from '@ray-js/image-color-picking';
import React, { useEffect } from 'react';
import { View } from '@ray-js/ray';
const Demo = () => {
useEffect(() => {
return () => {
// 销毁组件缓存队列 v1.1.0版本支持
imageColorPickingDestroy();
};
}, []);
const run = async () => {
// 调用app能力选择图片
const path = await chooseCropImageSync();
// 取消了
if (typeof path !== 'string') return;
// 将手机内图片转化成base64
const fileBase64: string = await readImgSync(path);
// 获取主要颜色
const colors = await imageColorPicking({
base64: fileBase64,
// 自定义的id
selector: '#my-custom',
// 调亮颜色
isPrimary: false,
pickNum: 8,
// 禁用颜色排序
isSort: false,
});
console.log(colors, '--获取到的颜色');
};
return (
<>
点击执行
);
};
```
### 分割图片取色 `v1.1.0`
`splitImage` 参数可以将图片分块识别，默认传 true 时是 2 行 4 列
```tsx
import {
imageColorPicking,
ImageColorPicker,
chooseCropImageSync,
imageColorPickingDestroy,
} from '@ray-js/image-color-picking';
import React, { useEffect } from 'react';
import { View } from '@ray-js/ray';
const Demo = () => {
useEffect(() => {
return () => {
// 销毁组件缓存队列 v1.1.0版本支持
imageColorPickingDestroy();
};
}, []);
const run = async () => {
const path = await chooseCropImageSync();
// 取消了
if (typeof path !== 'string') return;
const colors = await imageColorPicking({
path,
splitImage: {
// 启用分割模式
cols: 10,
rows: 10,
},
});
console.log(colors, '--获取到的分割颜色');
};
return (
<>
点击执行
);
};
```
### 按需返回颜色 `v1.1.1`
`filterDuplicate` 参数可以过滤重复或相似的颜色。当设置为 `true` 时，只会返回不重复的颜色。例如，如果图片只有一个颜色，即使 `pickNum` 是 8，也只会返回 1 个颜色。
```tsx
import {
imageColorPicking,
ImageColorPicker,
chooseCropImageSync,
imageColorPickingDestroy,
} from '@ray-js/image-color-picking';
import React, { useEffect, useState } from 'react';
import { View } from '@ray-js/ray';
const Demo = () => {
const [colors, setColors] = useState([]);
useEffect(() => {
return () => {
// 销毁组件缓存队列
imageColorPickingDestroy();
};
}, []);
const run = async () => {
const path = await chooseCropImageSync();
// 取消了
if (typeof path !== 'string') return;
const result = await imageColorPicking({
path,
selector: '#my-custom2',
pickNum: 8,
// 过滤重复颜色
filterDuplicate: true,
});
setColors(result);
console.log(result, '--获取到的颜色');
};
return (
<>
点击执行
颜色数量：{colors.length}
{colors.map((item, index) => (
))}
);
};
```
## 方法和类型
| 参数 | 说明 | 类型 |
| --------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| ImageColorPicker | 获取图片资源颜色的配套组件，需要和`imageColorPicking`结合使用 | _ImgCanvasProps & { id: string }_ |
| imageColorPicking | 获取图片资源颜色的配套方法，需要和`ImageColorPicker`结合使用 | _(currOptions: ImageColorPickingOption = {}): Promise\_ |
| chooseCropImageSync | 获取手机内本地图片的方法，基于`chooseCropImage`实现，封装成 promise，并增加部分权限申请逻辑 | _(sourceType?: "album" \| "camera"): Promise\_ |
| chooseImageSync | 获取手机内本地图片的方法，基于`chooseImage`实现，封装成 promise，并增加部分权限申请逻辑 | _(sourceType?: "album" \| "camera"): Promise\_ |
| readImgSync | 读取本地手机图片资源转化成 base64 格式 | _(path: string): Promise\_ |
| imageColorPickingDestroy `v1.1.0` | 销毁组件缓存队列 | _(selector?: string): void_ |
### ImgCanvasProps
| 参数 | 说明 | 类型 | 默认值 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------- |
| path | 本地手机文件路径 | _string_ | `''` |
| canvasId | 自定义 canvas id | _string_ | `image-color-picking-canvas` |
| base64 | 图片 base64 字符串 | _string_ | - |
| pickNum | 提取的颜色数量 | _number_ | `5` |
| isPrimary | 是否保持原色，false 时，组件发现颜色过暗时会调亮内部的颜色 | _boolean_ | `true` |
| isSort `v1.1.0` | 是否对提取的颜色根据色值进行排序 | _boolean_ | `true` |
| filterDuplicate `v1.1.1` | 是否过滤重复的颜色，如果为 true，则只返回不重复的颜色（即使 pickNum 更大） | _boolean_ | `false` |
| splitImage `v1.1.0` | 是否分割图片识别颜色，传 true 时为默认的 2 行 4 列，会将图片划分为 8 块区域识别，也每个区域一个颜色；也可以自定义划分规则 | _boolean \| { cols: number; rows: number; }_ | - |
| onColorsChange | 颜色改变的回调 | _(colors: string[])=>void_ | - |
### ImageColorPickingOption
| 参数 | 说明 | 类型 | 默认值 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------- |
| selector | 组件的 id 需要加上`#`开头 | _string_ | `#image-color-picking` |
| path | 本地手机文件路径 | _string_ | - |
| canvasId | 自定义 canvas id，会自动根据 `selector` 属性加上 `-canvas` 后缀 | _string_ | `image-color-picking-canvas` |
| base64 | 图片 base64 字符串 | _string_ | - |
| pickNum | 提取的颜色数量 | _number_ | - |
| isPrimary | 是否保持原色，组件会默认调亮内部的颜色，关闭的话需要传入 true | _boolean_ | - |
| isSort `v1.1.0` | 是否对提取的颜色进行排序 | _boolean_ | `true` |
| filterDuplicate `v1.1.1` | 是否过滤重复的颜色，如果为 true，则只返回不重复的颜色（即使 pickNum 更大） | _boolean_ | `false` |
| splitImage `v1.1.0` | 是否分割图片识别颜色，传 true 时为默认的 2 行 4 列，会将图片划分为 8 块区域识别，也每个区域一个颜色；也可以自定义划分规则 | _boolean \| { cols: number; rows: number; }_ | - |
| context | 原生小程序方式使用时 传 this；ray 方式使用时 不需要传 | _any_ | - |