更新记录

1.0.1（2026-01-06） 下载此版本

上传示例图片

1.0.0（2026-01-06） 下载此版本

1.0.0

平台兼容性

uni-app(4.87)

wen-color 使用文档

一款基于八叉树颜色量化算法的图片主题色提取与渐变生成工具，适用于 uni-app H5 等支持 DOM/canvas 的运行环境。

1. 功能简介

• 从图片中自动提取多组主题色（默认 5 个）
• 支持过滤接近黑白、透明区域，提取视觉主色
• 基于提取结果自动生成线性/径向 CSS 渐变字符串
• 可配合 uni.chooseImage 做成可视化配色工具（示例见下）

2. 安装与引入

2.1 在 HBuilderX 插件市场安装

1. 在 HBuilderX 中打开项目
2. 打开「插件市场」搜索 wen-color
3. 点击安装/导入到当前项目

4. 确保项目目录下存在：

   • uni_modules/wen-color/
   • uni_modules/wen-color/js_sdk/color-extractor.js

2.2 代码中引入

在需要用到的页面或模块中引入：

import ColorExtractor from '@/uni_modules/wen-color/js_sdk/color-extractor.js';

路径以实际项目别名为准，如果没有配置 @，可以改用相对路径：

import ColorExtractor from '../../uni_modules/wen-color/js_sdk/color-extractor.js';

3. 快速上手示例

以下示例演示一个最小使用场景：选择图片 → 提取主题色 → 生成 CSS 渐变。

<template>
  <view class="container">
    <button @click="chooseImage">选择图片</button>

    <image v-if="imagePath" :src="imagePath" mode="widthFix" />

    <view v-if="colors.length">
      <view v-for="(c, i) in colors" :key="i" :style="{ backgroundColor: c }">
        {{ c }}
      </view>
    </view>

    <view v-if="gradient" :style="{ backgroundImage: gradient, height: '100rpx' }" />
  </view>
</template>

<script>
import ColorExtractor from '@/uni_modules/wen-color/js_sdk/color-extractor.js';

export default {
  data() {
    return {
      imagePath: '',
      colors: [],
      gradient: ''
    };
  },

  methods: {
    async chooseImage() {
      uni.chooseImage({
        count: 1,
        sizeType: ['compressed'],
        sourceType: ['album', 'camera'],
        success: async (res) => {
          this.imagePath = res.tempFilePaths[0];
          await this.extractColors();
        }
      });
    },

    async extractColors() {
      if (!this.imagePath) return;

      const extractor = new ColorExtractor({
        paletteSize: 5,
        quality: 10
      });

      // 提取主题色
      const colors = await extractor.extractFromImage(this.imagePath);
      this.colors = colors;

      // 生成线性渐变
      this.gradient = extractor.generateGradient(colors, 'linear', 90);
    }
  }
};
</script>

4. 与示例页面配合使用

仓库中 pages/index/index.vue 已经集成了更完整的示例，包括：

• 图片选择与预览
• 点击色块复制十六进制颜色值
• 切换渐变类型（linear / radial）
• 调整线性渐变角度（滑块）
• 一键复制生成的 CSS 渐变代码

可以参考该页面，将对应逻辑裁剪/迁移到自己的业务页面。

5. API 说明

5.1 构造函数

const extractor = new ColorExtractor(options?);

options 可选参数

• paletteSize：number，提取的颜色数量
  • 默认：5
• quality：number，采样质量/步长（值越大，采样越稀疏，提取速度越快、精度略低）
  • 默认：10
• maxColors：number，八叉树允许的最大颜色节点数量
  • 默认：256

5.2 extractFromImage(imagePath)

const colors = await extractor.extractFromImage(imagePath);
// colors: ['#ffcc00', '#3366ff', ...]

• 参数

  • imagePath: string
  • 本地图片路径（例如 uni.chooseImage 返回的 tempFilePaths[0]）
  • 或有 CORS 允许的网络图片地址（H5）

• 返回值

  • Promise<string[]>
  • 颜色数组，元素为十六进制颜色字符串（如：#RRGGBB）

• 注意事项

  • 内部通过 canvas + Image 对图片进行采样与颜色量化，需在支持 DOM 的平台上使用（例如 H5）
  • 对高度透明、接近纯黑/纯白的像素会自动过滤

5.3 generateGradient(colors, type?, angle?)

const gradient = extractor.generateGradient(colors, 'linear', 135);
// gradient 形如：'linear-gradient(135deg, #667eea 0%, #764ba2 100%)'

• 参数

  • colors: string[]
  • 颜色数组（例如 extractFromImage 的返回值）
  • type?: 'linear' | 'radial'
  • 渐变类型
  • 默认：'linear'
  • angle?: number
  • 渐变角度，0–360，仅在线性渐变下生效
  • 默认：90

• 返回值

  • string
  • CSS 渐变字符串，可直接用在 background 或 backgroundImage 中

• 行为说明

  • 若 colors 为空，会返回一组默认渐变：
    linear-gradient(90deg, #667eea 0%, #764ba2 100%)
  • 若 colors 只有一个颜色，会自动生成深浅过渡的渐变
  • 多个颜色时会均匀分布在 0%–100% 区间

6. 使用建议与注意事项

• 尽量使用尺寸适中、色彩比较丰富的图片，以获得更好的主题色效果
• 如果提取结果不理想，可以调整：
  • paletteSize（增减返回颜色数量）
  • quality（减小数值以获得更精细采样）
• 远程图片在 H5 中需要服务端开启 CORS，否则可能出现跨域导致无法读取像素
• 当前实现依赖 document.createElement('canvas') 和 Image，在不支持 DOM 的小程序平台上请谨慎使用或自行包装兼容逻辑

7. 运行环境要求

根据 uni_modules/wen-color/package.json，建议环境为：

• HBuilderX：^3.1.0
• uni-app / uni-app-x：^3.1.0

其他版本如能正常运行，也可按需自行测试。

8. 许可证

本组件为开源免费使用，如需二次封装或商用，可在保留版权声明的前提下自由使用。