更新记录

1.0.0（2025-08-01） 下载此版本

• Initial release

平台兼容性

uni-app x(4.64)

kux-chroma

一个强大的颜色操作库，提供了全面的颜色空间转换、调整、混合和分析功能。基于现代色彩科学理论实现，支持多种颜色模型和实用工具。

主要特性

• 🎨 ​多种颜色空间支持​：RGB, HSL, HSV, LAB, CMYK, XYZ, GL 等
• 🔁 ​颜色格式转换​：支持 HEX, RGB(A), HSL, HSV 等格式互转
• ✨ ​颜色调整功能​：亮度、饱和度调整，变暗/变亮，混色等
• 🤝 ​颜色混合模式​：支持乘/变暗/变亮/滤色/叠加等混合
• 📊 ​专业分析工具​：色温计算、对比度/色彩距离计算、色阶生成
• 📱 ​响应式设计​：提供完善的暗黑/明亮模式色阶生成
• 🌍 ​多平台支持​：适用于 Web 和跨平台应用开发

安装使用

下载插件

• 插件市场下载
  • 在插件市场搜索并导入 kux-chroma

• git 克隆

  • 控制台终端进入项目根目录执行 cd uni_modules

  • 当前目录执行

    git clone https://gitcode.com/uvuejs/kux-chroma.git
    git clone https://gitcode.com/uvuejs/kux-colors-helper.git

项目导入使用

import { useChroma, KuxChroma } from '@/uni_modules/kux-chroma';

快速开始

创建颜色对象

// 通过十六进制创建
const red = useChroma('#ff0000');

// 通过RGB值创建
const green = useChroma(0, 255, 0);

// 通过 CSS 颜色名称创建
const blue = useChroma('blue');

基本颜色操作

// 调整亮度
red.brighten(0.5) // 增加50%亮度
red.darken(0.3) // 减少30%亮度

// 调整饱和度
blue.saturate(0.5) // 增加50%饱和度
blue.desaturate(0.2) // 减少20%饱和度

// 转换为不同格式
red.hex(null) // 返回 '#ff0000'
blue.css('hsl') // 返回 'hsl(0, 100%, 50%)'

高级功能示例

色彩混合

// 简单混合
const mixed = KuxChroma.mix('#ff0000', '#00ff00', 0.3) // 30%红+70%绿

// 使用混合模式
const blended = KuxChroma.blend('red', 'blue', 'overlay')

专业色彩分析

// 计算对比度（WCAG 2.0）
const contrast = KuxChroma.contrast('#ffffff', '#000000') // 21
// 计算APCA对比度
const apcaContrast = KuxChroma.contrastAPCA('#333333', '#ffffff') // 0.9709390109083363
// 计算色温值
const temp = red.temperature() // 获取红色的开尔文色温值，1000

生成色阶

// 基于主色生成色阶
const scale = KuxChroma.palette('#00bc79', {
    mode: 'light', // 或 'dark'
    format: 'hex'
} as GenerateScaleOptions)
// scale将生成包含10个梯度的色阶数组，完全参考的 arco design palette算法实现

API概览

静态方法

实例方法

格式转换方法

类型定义

/**
 * interface.uts
 * uts插件接口定义文件，按规范定义接口文件可以在HBuilderX中更好的做到语法提示
 */
import { RGB } from '@/uni_modules/kux-colors-helper';

export type WCAGLevelOptions = {
    normal : number;
    large : number;
}

export type WCAG = {
    AA : WCAGLevelOptions;
    AAA : WCAGLevelOptions;
}

/**
 * 颜色和谐类型
 */
export type HarmonyType =
    | 'complementary'      // 互补色
    | 'analogous'          // 类似色
    | 'triadic'            // 三色组合
    | 'tetradic'           // 四色组合
    | 'split-complementary' // 分裂互补色
    | 'monochromatic'      // 单色组合
    | 'square'             // 方形组合
    | 'rectangle'          // 矩形组合
    | 'pentadic'           // 五色组合
    | 'hexadic'            // 六色组合
    | 'double-complementary'; // 双互补色组合

/**
 * 和谐色选项
 */
export type HarmonyOptions = {
    count ?: number;
    angle ?: number;
    distance ?: number;
}

export type CreateHarmonyResult = {
    name: string;
    colors: RGB[];
}

export type ColorFormat = 'hex' | 'rgb' | 'rgba' | 'hsl' | 'hsv' | 'lab' | 'cmyk';

// export type GenerateScaleOptions = {
//  mode?: 'light' | 'dark'; // 色彩模式
//  format?: ColorFormat; // 输出格式
//  index?: number; // 索引位置
//  list?: boolean; // 是否返回列表
// }

// #ifndef APP-HARMONY
export type GenerateScaleOptions = {
    mode?: 'light' | 'dark'; // 色彩模式
    format?: ColorFormat; // 输出格式
    index?: number; // 索引位置
    list?: boolean; // 是否返回列表
}
// #endif

// #ifdef APP-HARMONY
export interface GenerateScaleOptions {
    mode?: 'light' | 'dark'; // 色彩模式
    format?: ColorFormat; // 输出格式
    index?: number; // 索引位置
    list?: boolean; // 是否返回列表
}
// #endif

export interface IKuxChroma {
    /**
     * 获取和设置颜色的不透明度
     * 
     * @example
     * ```typescript
     * chroma('red').alpha(0.5) // #ff000080
     * chroma('rgba(255, 0, 0, 0.35)').alpha() // 0.35
     * ```
     */
    alpha(): number;
    alpha(a: number): IKuxChroma;
    alpha(a ?: number) : number | IKuxChroma
    /**
     * 降低颜色明度，默认降低程度为1
     * 
     * @example
     * ```typescript
     * chroma('hotpink').darken() // #c93384
     * chroma('hotpink').darken(2) // #930058
     * chroma('hotpink').darken(2.6) // #74003f
     * ```
     */
    // darken() : IKuxChroma;
    darken(value?: number): IKuxChroma;
    /**
     * 提高颜色明度，默认增加程度为1
     * 
     * @example
     * ```typescript
     * chroma('hotpink').lighten() // #ff9ce6
     * chroma('hotpink').lighten(2) // #ffd1ff
     * chroma('hotpink').lighten(3) // #ffffff
     * ```
     */
    // brighten(): IKuxChroma;
    brighten(value?: number): IKuxChroma;
    /**
     * 调整颜色的饱和度，默认调整程度为1
     * 
     * @example
     * ```typescript
     * chroma('slategray').saturate() // #4b83ae
     * chroma('slategray').saturate(2) // #0087cd
     * chroma('slategray').saturate(3) // #008bec
     * ```
     */
    saturate(): IKuxChroma;
    saturate(value?: number): IKuxChroma;
    /**
     * 与saturate功能相似但方向相反（降低饱和度）
     * 
     * @example
     * ```typescript
     * chroma('hotpink').desaturate() // #e77dae
     * chroma('hotpink').desaturate(2) // #cd8ca8
     * chroma('hotpink').desaturate(3) // #b199a3
     * ```
     */
    desaturate(): IKuxChroma;
    desaturate(value?: number): IKuxChroma;
    /**
     * 将当前颜色与目标颜色混合。混合比例是0到1之间的值。
     * 功能类似chroma.mix但第一个参数已被预设。
     * 可通过format参数调整输出颜色格式
     * 
     * @example
     * ```typescript
     * chroma('hotpink').mix('blue') // #b44add
     * chroma('hotpink').mix('blue', 0.25) // #dd5bc9
     * chroma('hotpink').mix('blue', 0.75, 'lab') // 
     * ```
     */
    // mix(targetColor: any): IKuxChroma;
    // mix(targetColor: any, ratio: number): IKuxChroma;
    mix(targetColor: any, ratio?: number, format?: string): IKuxChroma;
    /**
     * 生成色彩的暗部变化。相当于与黑色混合的语法糖
     * 
     * @example
     * ```typescript
     * chroma('hotpink').shade(0.25) // #dd5b9c
     * chroma('hotpink').shade(0.5) // #b44a7f
     * chroma('hotpink').shade(0.75) // #80355a
     * ```
     */
    shade(ratio?: number, mode?: string): IKuxChroma;
    /**
     * 生成色彩的亮部变化。相当于与白色混合的语法糖
     * 
     * @example
     * ```typescript
     * chroma('hotpink').tint(0.25) // #ff9dc9
     * chroma('hotpink').tint(0.5) // #ffc3dd
     * chroma('hotpink').tint(0.75) // #ffe3ee
     * ```
     */
    tint(ratio?: number, mode?: string): IKuxChroma;
    /**
     * 修改单个通道值并返回新的色彩对象。
     * 支持使用相对变化值（如*0.5）
     * 
     * @example
     * ```typescript
     * chroma('skyblue').set('hsl.h', 0) // #eb8787
     * chroma('orangered').set('lab.l', '*0.5') // #a10000
     * chroma('hotpink').set('hsl.l', 0.25, 'hsl') // #80355a
     * ```
     */
    set(channel: string, value: number | string): IKuxChroma;
    /**
     * 获取单个通道的值
     * 
     * @example
     * ```typescript
     * chroma('orangered').get('lab.l') // 57.582
     * chroma('orangered').get('hsl.l') // 0.5
     * chroma('orangered').get('rgb.g') // 69
     * ```
     */
    get(channel: string): number;
    /**
     * 相对亮度，遵循[WCAG标准定义]。
     * 归一化为0（最暗黑）到1（最亮白）
     */
    // luminance(): number;
    /**
     * 设置颜色亮度。源颜色将与黑色或白色进行插值调整，
     * 直到找到正确的亮度值，默认使用RGB颜色空间
     */
    // luminance(value: number, mode?: string): IKuxChroma;
    luminance(value?: number, mode?: string) : number | IKuxChroma
    /**
     * 获取颜色的十六进制字符串。
     * 默认模式"auto"会根据透明度决定是否包含alpha通道。
     * 如果不需要alpha通道，可明确设置为"rgb"模式
     * 
     * @example
     * ```typescript
     * chroma('red').hex() // "#ff0000"
     * chroma('rgba(255, 0, 0, 0.35)').hex() // "#ff0000"
     * chroma('red').hex('rgb') // "#ff0000"
     * chroma('rgba(255, 0, 0, 0.35)').hex('rgb') // "#ff0000"
     * chroma('rgba(255, 0, 0, 0.35)').hex('argb') // "#ff000033"
     * ```
     */
    // hex(): string;
    hex(mode?: "auto" | "rgb" | "rgba" | "argb"): string;
    /**
     * 返回颜色名称。如果颜色不存在，则返回十六进制RGB字符串
     * 
     * @example
     * ```typescript
     * chroma('#ffa500').name() // orange
     * chroma('#ffa505').name() // #ffa505
     * ```
     */
    name(): string;
    /**
     * 返回可用作CSS颜色定义的字符串，
     * 默认使用rgb模式
     * 
     * @example
     * ```typescript
     * chroma('red').css() // "rgb(255, 0, 0)"
     * chroma('rgba(255, 0, 0, 0.35)').css() // "rgba(255, 0, 0, 0.35)"
     * ```
     */
    css(mode?: string): string;
    /**
     * 返回红、绿、蓝分量组成的数组（0-255范围）。
     * 默认四舍五入为整数，传false可保留原始浮点数
     * 
     * @example
     * ```typescript
     * chroma('orange').rgb() // [255,165,0]
     * chroma('orange').darken().rgb() // [198,118,0]
     * chroma('orange').darken().rgb(false) // [198.05,118.11,0]
     * ```
     */
    rgb(round: boolean | null): number[];
    // rgb(): number[];
    /**
     * 类似rgb()，但在返回数组中包含alpha通道
     * 
     * @example
     * ```typescript
     * chroma('rgba(255, 0, 0, 0.35)').rgba() // [255,0,0,0.35]
     * chroma('rgba(255, 0, 0, 0.35)').darken().rgba() // [198,118,0,0.35]
     * chroma('rgba(255, 0, 0, 0.35)').darken().rgba(false) // [198.05,118.11,0,0.35]
     * ```
     */
    rgba(): number[];
    rgba(round?: boolean): number[];
    /**
     * 返回色相、饱和度、明度组成的数组：
     * - 色相: 0-360°
     * - 饱和度/明度: 0-1
     * 注意：无色调颜色（黑白灰）的色相为NaN
     * 
     * @example
     * ```typescript
     * chroma('orange').hsl() // [38.82,1,0.5,1]
     * chroma('white').hsl() // [NaN,0,1,1]
     * ```
     */
    hsl(): number[];
    /**
     * 返回色相、饱和度、亮度组成的数组：
     * - 色相: 0-360°
     * - 饱和度/亮度: 0-1
     * 注意：无色调颜色（黑白灰）的色相为NaN
     * 
     * @example
     * ```typescript
     * chroma('orange').hsv() // [38.82,1,1,1]
     * chroma('white').hsv() // [NaN,0,0,1]
     * ```
     */
    hsv(): number[];
    /**
     * 返回LAB颜色空间的L、a、b分量组成的数组。
     * 注意：无色调颜色（黑白灰）的L值为0
     * 
     * @example
     * ```typescript
     * chroma('orange').lab() // [74.94,23.93,78.95]
     * ```
     */
    lab(): number[];
    /**
     * 返回CMYK颜色空间的青、品、黄、黑分量（0-1范围）
     * 
     * @example
     * ```typescript
     * chroma('orange').cmyk() // [0,0.35,1,0]
     * ```
     */
    cmyk(): number[];
    /**
     * 返回颜色的十六进制 RGB 数字表示。
     *
     * @example
     * ```typescript
     * chroma('#000000').num() // 0
     * chroma('#0000ff').num() // 255
     * chroma('#00ff00').num() // 65280
     * chroma('#ff0000').num() // 16711680
     * ```
     */
    num(): number;
    /**
     * 估计给定颜色的温度（开尔文）。这对来自色温梯度的颜色最为有意义。
     *
     * @example
     * ```typescript
     * chroma('#ff3300').temperature() // 1000
     * chroma('#ff8a13').temperature() // 2000
     * chroma('#ffe3cd').temperature() // 4999
     * chroma('#cbdbff').temperature() // 10115
     * ```
     */
    temperature(): number;
    /**
     * 类似 RGB，但通道的范围是 `[0..1]`，而不是 `[0..255]`。
     *
     * @example
     * ```typescript
     * chroma('#33cc00').gl() // [0.2,0.8,0,1]
     * ```
     */
    gl(): number[];
    /**
     * 测试颜色是否被裁剪。
     * 来自 CIELab 色彩空间的颜色可能会被裁剪到 RGB 通道范围 [0..255]。
     * 超出该范围的颜色可能存在于自然界中，但在 RGB 显示器上无法显示（例如紫外线）。
     *
     * @example
     * ```typescript
     * chroma.hcl(50, 40, 20).clipped() // true
     * ```
     */
    // clipped(): boolean;
}

结语

kux 不生产代码，只做代码的搬运工，致力于提供uts 的 js 生态轮子实现，欢迎各位大佬在插件市场搜索使用 kux 生态插件：https://ext.dcloud.net.cn/search?q=kux

友情推荐

• TMUI4.0：包含了核心的uts插件基类.和uvue组件库
• UxFrame 低代码高性能UI框架：低代码高性能UI框架
• GVIM即时通讯模版：GVIM即时通讯模版，基于uni-app x开发的一款即时通讯模版
• t-uvue-ui：T-UVUE-UI是基于UNI-APP X开发的前端UI框架
• uXui: graceUI作者的免费开源组件库
• wx-ui 基于uni-app x开发的高性能混合UI库：基于uni-app x开发的高性能混合UI库，集成 uts api 和 uts component，提供了一套完整、高效且易于使用的UI组件和API，让您以更少的时间成本，轻松完成高性能应用开发。
• firstui-uvue：FirstUI（unix）组件库，一款适配 uni-app x 的轻量、简洁、高效、全面的移动端组件库。
• easyXUI 不仅仅是UI 更是为UniApp X设计的电商模板库：easyX 不仅仅是UI库，更是一个轻量、可定制的UniAPP X电商业务模板库，可作为官方组件库的补充,始终坚持简单好用、易上手