更新记录

1.0.0（2026-10-09）

首个版本。

• 取主色与调色板（dominant），4bit 量化 + 相似色合并
• 取平均色（average），三端结果一致
• 区域取色（region），越界自动钳制
• 单像素取色（pixelAt），iOS 明确不支持并说明原因
• 配色方案（scheme），支持 vibrant / muted / analogous / complementary / monochrome 五种
• 色彩工具（纯 JS 全端可用）：rgb2hsl / hsl2rgb / readableTextColor
• 平台能力查询：supportsPalette() / supportsPixelAt() / suggestedCount()， 由原生层通过 __caps 显式回报，不靠 JS 条件编译反推
• 三端原生实现：
  • Android —— Bitmap.getPixels 批量读像素 + 4bit 量化统计
  • Harmony —— readPixelsSync 逐像素 + createPixelMapSizer 降采样
  • iOS —— CIAreaAverage 滤镜求区域均值（受类型库限制，无逐像素访问）

平台兼容性

uni-app(3.99)

其他

czg-imgcolor 图片取色

从图片提取主色、配色方案与像素值，返回可直接用的 HEX / RGB / HSL。

平台能力（重要）

iOS 拿不到逐像素数据，原因：

• CGDataProviderCopyData 未暴露
• CGContext 无像素访问器
• CIContext.render 需要 UnsafeMutableRawPointer，UTS 无法安全构造裸指针

iOS 只能用 CIAreaAverage 滤镜求区域均值 —— 平均色是精确的，但拿不到颜色分布。所以本插件在 iOS 上：

• dominant() 返回的 colors 长度就是 1，不编造调色板
• pixelAt() 明确报错并说明原因
• scheme() 由平均色的 HSL 数学推导（正确，但不反映图片真实配色）

要「真实的图片配色分布」，iOS 上请改用 Android / Harmony，或在后端算好再下发。

平台支持

能力查询

import {
  supportsPalette,     // 能否返回多色调色板
  supportsPixelAt,     // 能否单像素取色
  suggestedCount       // 建议取几个色（不支持调色板时返回 1）
} from '@/uni_modules/czg-imgcolor/index.js'

这三个函数由原生层回报能力，不由 JS 用条件编译反推 —— 条件编译在 Node / 小程序不生效，反推会得出错误结论。

API

dominant(path, count)

取主色与调色板。

const r = dominant('/path/photo.jpg', 5)
// {
//   primary: { hex:'#3A7BD5', int:3831253, r:58, g:123, b:213,
//              h:212.4, s:0.63, l:0.53, luminance:110.7, ratio:0.42, isDark:true },
//   colors: [ /* 最多 count 个 */ ]
// }

算法：缩放到长边 120px → 4bit 量化到 4096 格统计 → 按像素数降序 → 合并色相差 <12°、饱和度差 <0.12、明度差 <0.12 的相邻格（避免返回 5 个几乎一样的颜色）→ 透明像素不参与统计。

average(path)

取平均色（三端结果一致）。

average('/path/photo.jpg')
// { hex:'#7F5F3F', r:127, g:95, b:63, ... }

region(path, region)

区域取色。

region('/path/photo.jpg', { x: 0, y: 0, width: 100, height: 100 })

坐标单位像素，越界自动钳制。

pixelAt(path, x, y)

取单点像素色（iOS 不支持）。

pixelAt('/path/photo.jpg', 320, 240)

scheme(path, kind, count)

取配色方案。

scheme('/path/photo.jpg', 'analogous', 3)
// { primary: {...}, colors: [邻近色 × 3] }

色彩工具（纯 JS，无需原生，全端可用）

import { rgb2hsl, hsl2rgb, readableTextColor } from '@/uni_modules/czg-imgcolor/index.js'

rgb2hsl(255, 0, 0)          // { h: 0, s: 1, l: 0.5 }
hsl2rgb(210, 0.6, 0.4)      // { r: 51.1, g: 122.4, b: 204 }
readableTextColor('#1A237E')// '#FFFFFF'  自动判断配黑字还是白字
readableTextColor('#FFEB3B')// '#000000'

readableTextColor 用 BT.601 加权亮度，阈值 140。这是最实用的一个函数 —— 取完色直接决定文字颜色。

ColorInfo 字段

错误处理

隐私

全部处理在本机完成，不联网、不采集、不上传任何图片。

价格

普通授权版由 DCloud 对 uts 源码加密保护，运行时经云端解密编译；源码授权版提供完整 uts 源码，可自行修改与扩展，同样享受后续版本升级。

隐私说明

本插件全部图片处理在本机完成，不联网、不采集、不上传任何图片或数据。插件不主动读取相册与存储目录，输入完全由调用方通过参数传入。隐私声明详见 package.json 的 dcloudext.declaration。

更新日志

见 changelog.md

开源协议

MIT