更新记录

2.0.1(2026-11-12) 下载此版本

  • chore: 调整目录结构

2.0.0(2026-08-18) 下载此版本

  • refactor: 清理 color.uts 中注释掉的历史代码(instanceof 检查、Map 实现版本、for/while 循环)
  • refactor: reversedNames 从实例属性改为模块级常量,避免每个 TinyColor 实例都重建颜色名称反向映射表
  • refactor: setAlpha 合并重载签名为单一 string | number 参数
  • refactor: 精简 format-input.uts 的 inputToRGB 中 any 类型为具体联合类型
  • fix: 修复 toString 的参数类型为 LimeColorFormats | null,override toString() 正确委托带参版本
  • fix: 修复 conversion.uts 中 numberInputToObject 位运算在大于 0x7FFFFFFF 的数值上溢出的问题,改用除法运算
  • fix: 删除 rgbToHsl/rgbToHsv switch 分支中的调试 console.log
  • chore: 删除空接口 LimeColor,从 LimeColorInput 联合类型中移除
  • chore: 删除未使用的 utssdk/unierror.uts
  • chore: 删除冗余的 utssdk 平台目录(app-android-o、app-js-o、index-o.uts)
  • chore: 删除测试桩文件 common/test.uts 和 components/lime-color/lime-color.vue
  • chore: 修复 readme 赞助图片 CDN 地址(testingcf.jsdelivr.net → cdn.jsdelivr.net)

0.0.7(2025-08-31) 下载此版本

  • chore: 更新文档
查看更多

平台兼容性

uni-app(4.72)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ √ √ √ - 5.0 √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
√ √ √ √ √ √ √ √ √ - √ √

uni-app x(4.74)

Chrome Safari Android iOS 鸿蒙 微信小程序
√ √ 5.0 √ √ √

name: lime-color 颜色工具 description: tinycolor 的 TypeScript 实现,提供颜色解析、格式转换、颜色调整、配色组合,以及 Ant Design 主题色阶生成。 tags:

  • color
  • 颜色
  • tinycolor
  • 转换
  • 色阶 plugin: lime-color category: API 插件 dependencies: []

lime-color 颜色工具

一个轻量的颜色工具库,API 与 tinycolor2 保持一致,提供颜色解析、格式转换、颜色调整与配色组合,并内置 Ant Design 的主题色阶生成算法。纯 TypeScript 实现,无平台条件编译,uni-app x 蒸汽模式(Vapor)、uni-app(Vue2 / Vue3)与各小程序均可直接使用。

安装方法

  1. 在 uni-app 插件市场中搜索并导入 lime-color
  2. 导入后可能需要重新编译项目
  3. 在页面或组件中按需引入使用

::: tip 注意🔔 lime-color 2.0 起改为纯 TypeScript 实现:不再使用 .uts 文件、#ifdef 平台分支与 // @ts-nocheck,实现全部落在 common/ 下的 .ts 文件,对外类型声明在 utssdk/interface.ts。包入口仍是 @/uni_modules/lime-color,无需改导入路径。 :::

代码演示

基础使用

import { tinyColor } from '@/uni_modules/lime-color'

// 解析颜色
const color = tinyColor('#1890ff')

// 转成其它格式
color.toHexString() // '#1890ff'
color.toRgbString() // 'rgb(24, 144, 255)'
color.toHslString() // 'hsl(209, 100%, 55%)'

// 调整后继续链式调用
color.lighten(10).toHexString() // '#4ba8ff'

颜色解析

tinyColor() 与 new TinyColor() 接受多种输入,无法解析时 isValid 为 false,颜色按黑色处理。

import { tinyColor } from '@/uni_modules/lime-color'

// 十六进制
tinyColor('#f00')      // #rgb
tinyColor('f00')       // 省略 # 也可以
tinyColor('#ff0000')   // #rrggbb
tinyColor('#ff000080') // #rrggbbaa,带透明度
tinyColor('ff0000')    // 省略 # 也可以

// RGB / RGBA
tinyColor('rgb(255, 0, 0)')
tinyColor('rgb 255 0 0')          // 括号和逗号都可以省略
tinyColor('rgba(255, 0, 0, .5)')
tinyColor('rgb(100%, 50%, 0%)')   // 百分比通道

// 现代 CSS 语法(空格分隔 + 斜杠透明度)
tinyColor('rgb(0 0 0 / 50%)')          // rgba(0, 0, 0, 0.5)
tinyColor('hsl(270deg 60% 40% / 50%)') // rgba(102, 41, 163, 0.5)

// HSL / HSLA
tinyColor('hsl(0, 100%, 50%)')
tinyColor('hsla(0, 100%, 50%, .5)')
tinyColor('hsl 0 1.0 0.5')        // 1.0 按 100% 处理

// HSV / HSVA / HSB / HSBA
tinyColor('hsv(0, 100%, 100%)')
tinyColor('hsva(0, 100%, 100%, .5)')
tinyColor('hsb(210, 90%, 100%)')

// CSS 颜色名称
tinyColor('red')
tinyColor('RED')              // 大小写不敏感
tinyColor('blanchedalmond')
tinyColor('transparent')      // 完全透明

// 数字(按 0xRRGGBB 解释,不含透明度)
tinyColor(0xaabbcc)           // #aabbcc
tinyColor(0x0)                // #000000

// 对象
tinyColor({ r: 255, g: 0, b: 0 })
tinyColor({ r: 255, g: 0, b: 0, a: 0.5 })
tinyColor({ h: 210, s: 1, l: 0.5 })  // HSL
tinyColor({ h: 210, s: 1, v: 1 })    // HSV
tinyColor({ h: 210, s: 1, b: 1 })    // HSB

// 非法输入
const invalid = tinyColor('not a color')
invalid.isValid          // false
invalid.toHexString()    // '#000000'

颜色转换

const color = tinyColor('#1890ff')

// 对象
color.toRgb()                 // { r: 24, g: 144, b: 255, a: 1 }
color.toHsl()                 // { h: 208.83116883116884, s: 1, l: 0.5470588235294118, a: 1 }
color.toHsv()                 // { h: 209, s: 0.9058823529411765, v: 1, a: 1 }
color.toHsb()                 // { h: 209, s: 0.9058823529411765, b: 1, a: 1 }
color.toPercentageRgb()       // { r: '9%', g: '56%', b: '100%', a: 1 }

// 字符串
color.toRgbString()           // 'rgb(24, 144, 255)'
color.toHslString()           // 'hsl(209, 100%, 55%)'
color.toHsvString()           // 'hsv(209, 91%, 100%)'
color.toHsbString()           // 'hsb(209, 91%, 100%)'
color.toPercentageRgbString() // 'rgb(9%, 56%, 100%)'

// 十六进制
color.toHex()                 // '1890ff'
color.toHexString()           // '#1890ff'
color.toHexString(true)       // '#1890ff',无法简写时仍是 6 位
color.toHex8()                // '1890ffff'
color.toHex8String()          // '#1890ffff'
tinyColor('#ff0000').toHexString(true) // '#f00',可以简写
color.toHexShortString()      // 有透明度时输出 8 位,否则 6 位

// 名称与数字
tinyColor('red').toName()     // 'red'
tinyColor('#00ffff').toName() // 'aqua'(同名色值取第一个)
tinyColor('#123456').toName() // null,没有对应的颜色名称
tinyColor('#1890ff').toNumber() // 1609983(0x1890ff)

// 统一出口,等价于按 format 选择上面的方法
color.toString()              // '#1890ff'
color.toString('rgb')         // 'rgb(24, 144, 255)'
color.toString('hsl')         // 'hsl(209, 100%, 55%)'

颜色判断

tinyColor('red').getBrightness()  // 76.245,感知亮度 0-255
tinyColor('red').isDark()         // true
tinyColor('red').isLight()        // false
tinyColor('#1890ff').getLuminance() // 0.2736,相对亮度 0-1
tinyColor('#808080').isMonochrome() // true,灰色
tinyColor('red').equals('#f00')     // true

透明度

const color = tinyColor('rgba(24, 144, 255, 0.3)')

color.getAlpha()        // 0.3
color.setAlpha(0.5)     // 返回自身,可以链式调用
color.toRgbString()     // 'rgba(24, 144, 255, 0.5)'

// 计算叠加在背景上的实际颜色
tinyColor('rgba(24, 144, 255, 0.3)')
  .onBackground('#ffffff')
  .toHexString()        // '#badeff'

颜色调整

const color = tinyColor('#1890ff')

color.lighten(10).toHexString()     // '#4ba8ff',提高明度
color.brighten(10).toHexString()    // '#31a9ff',提高亮度(直接拉伸 RGB)
color.darken(10).toHexString()      // '#0076e4',降低明度
color.tint(20).toHexString()        // '#46a6ff',与白色混合
color.shade(20).toHexString()       // '#1373cc',与黑色混合
color.desaturate(20).toHexString()  // '#2f8fe8',降低饱和度
tinyColor('#8a8a8a').saturate(20).toHexString() // '#a17373',提高饱和度
color.greyscale().toHexString()     // '#8b8b8b',完全去色
color.spin(90).toHexString()        // '#fa18ff',旋转色相

// 与另一种颜色混合,amount 为 0-100
color.mix('#f5222d', 50).toHexString() // '#875996'

配色组合

const color = tinyColor('#f5222d')

// 补色
color.complement().toHexString() // '#22f5ea'

// 相邻色,可传生成数量与色轮分片数
color.analogous().map((c) => c.toHexString())
// ['#f5222d', '#f52281', '#f52257', '#f5222d', '#f54122', '#f56b22']

// 单色序列(同色相、同饱和度,明度递变)
color.monochromatic().map((c) => c.toHexString())
// ['#f5222d', '#200506', '#4b0a0e', '#751015', '#a0161d', '#ca1c25']

// 三色 / 四色 / n 色组合
color.triad().map((c) => c.toHexString())   // ['#f5222d', '#2df522', '#222df5']
color.tetrad().map((c) => c.toHexString())  // ['#f5222d', '#96f522', '#22f5ea', '#8022f5']
color.polyad(5).map((c) => c.toHexString())

// 分裂补色
color.splitcomplement().map((c) => c.toHexString())
// ['#f5222d', '#d6f522', '#2281f5']

主题色阶生成

generate() 使用 Ant Design 的色阶算法,由主色推导出 10 个色阶(5 个浅色 + 主色 + 4 个深色),可直接用于生成主题变量。

import { generate } from '@/uni_modules/lime-color'

// 与 Ant Design 官方色板一致
generate('#1890ff')
// ['#e6f7ff', '#bae7ff', '#91d5ff', '#69c0ff', '#40a9ff',
//  '#1890ff', '#096dd9', '#0050b3', '#003a8c', '#002766']

generate('#f5222d')
// ['#fff1f0', '#ffccc7', '#ffa39e', '#ff7875', '#ff4d4f',
//  '#f5222d', '#cf1322', '#a8071a', '#820014', '#5c0011']

// 暗色主题:与深色背景混合,默认背景 #141414
generate('#1890ff', { theme: 'dark' })
// ['#111d2c', '#112a45', '#15395b', '#164c7e', '#1765ad',
//  '#177ddc', '#3c9ae8', '#65b7f3', '#8dcff8', '#b7e3fa']

// 自定义暗色背景
generate('#1890ff', { theme: 'dark', backgroundColor: '#001529' })

配合 lime-style 生成主题变量:

import { generate } from '@/uni_modules/lime-color'
import type { LimeColorGenerateOptions } from '@/uni_modules/lime-color'

const levels = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900]
const colors = generate('#3283ff', { theme: 'dark' } as LimeColorGenerateOptions)

// colors[0] → primary50 … colors[9] → primary900,主色取 500
colors.forEach((color, index) => {
  console.log(`primary${levels[index]}: ${color}`)
})

API 文档

构造函数

方法 说明 参数 返回值
tinyColor(color, opts) 创建 TinyColor 实例 color: 颜色输入, opts: 选项 TinyColor 实例
new TinyColor(color, opts) 同上,也可以直接 new color: 颜色输入, opts: 选项 TinyColor 实例

opts 可选:

参数 说明 类型 默认值 可选值
format 指定输出格式,影响 toString() 的默认结果 string 沿用输入的格式 rgb、prgb、hex、hex3、hex4、hex6、hex8、name、hsl、hsb、hsv
gradientType 渐变类型,仅作透传保留 string - -

实例属性

属性 说明 类型
r / g / b RGB 通道,0-255 number
a 透明度,0-1 number
roundA 保留两位小数的透明度 number
isValid 是否解析成功 boolean
format 解析出的或指定的格式 string 或 undefined
originalInput 传入构造函数的原始输入 LimeColorInput

判断方法

方法 说明 返回值
getBrightness() 感知亮度(AERT 公式) 0-255
getLuminance() 相对亮度(WCAG 公式) 0-1
isDark() 感知亮度是否小于 128 boolean
isLight() 是否为亮色 boolean
isMonochrome() 是否为无彩色(饱和度 0) boolean
equals(color) 与另一个颜色的 rgba 是否相同 boolean

透明度方法

方法 说明 参数 返回值
getAlpha() 获取透明度 - 0-1
setAlpha(alpha) 设置透明度,返回自身 0-1 的数值或数字字符串 TinyColor 实例
onBackground(background) 计算叠加在背景上的实际颜色 背景色 TinyColor 实例

转换方法

方法 说明 参数 返回值
toRgb() 转 RGB 对象 - RGBA 对象
toRgbString() 转 RGB 字符串 - string
toPercentageRgb() 转百分比 RGB 对象 - RGBAString 对象
toPercentageRgbString() 转百分比 RGB 字符串 - string
toHsl() 转 HSL 对象 - HSLA 对象
toHslString() 转 HSL 字符串 - string
toHsv() 转 HSV 对象 - HSVA 对象
toHsvString() 转 HSV 字符串 - string
toHsb() 转 HSB 对象 - HSBA 对象
toHsbString() 转 HSB 字符串 - string
toHex(allow3Char) 转十六进制(不带 #) allow3Char: 是否允许 3 位简写 string
toHexString(allow3Char) 转十六进制(带 #) allow3Char: 是否允许 3 位简写 string
toHex8(allow4Char) 转八位十六进制(不带 #) allow4Char: 是否允许 4 位简写 string
toHex8String(allow4Char) 转八位十六进制(带 #) allow4Char: 是否允许 4 位简写 string
toHexShortString(allowShortChar) 按透明度选择 3/6 位或 4/8 位 allowShortChar: 是否允许简写 string
toName() 转 CSS 颜色名称 - string 或 null
toNumber() 转 0xRRGGBB 数字 - number
toString(format) 按指定格式转字符串 format: 格式名称 string

调整方法

方法 说明 参数 返回值
lighten(amount) 提高明度,100 返回白色 0-100 TinyColor 实例
brighten(amount) 提高亮度(直接拉伸 RGB) 0-100 TinyColor 实例
darken(amount) 降低明度,100 返回黑色 0-100 TinyColor 实例
tint(amount) 与白色混合 0-100 TinyColor 实例
shade(amount) 与黑色混合 0-100 TinyColor 实例
desaturate(amount) 降低饱和度 0-100 TinyColor 实例
saturate(amount) 提高饱和度 0-100 TinyColor 实例
greyscale() 完全去色,等价于 desaturate(100) - TinyColor 实例
spin(amount) 旋转色相 -360 ~ 360 TinyColor 实例
mix(color, amount) 与另一种颜色混合 color: 颜色输入, amount: 0-100 TinyColor 实例

组合方法

方法 说明 参数 返回值
analogous(results, slices) 相邻色 results: 结果数量(含当前颜色,默认 6), slices: 分片数(默认 30) TinyColor[]
monochromatic(results) 单色序列 results: 数量(默认 6) TinyColor[]
splitcomplement() 分裂补色 - TinyColor[]
complement() 补色 - TinyColor 实例
triad() 三色组合,等价于 polyad(3) - TinyColor[]
tetrad() 四色组合,等价于 polyad(4) - TinyColor[]
polyad(n) n 色组合 n: 颜色数量 TinyColor[]

其他方法

方法 说明 参数 返回值
clone() 克隆当前颜色(按通道复制,不经过字符串) - TinyColor 实例

函数 API

函数 说明 参数 返回值
tinyColor(color, opts) 创建实例 color: 颜色输入, opts: 选项 TinyColor 实例
generate(color, opts) 生成 10 个主题色阶 color: 主色, opts: 生成选项 string[]

generate 的 opts:

参数 说明 类型 默认值 可选值
theme 主题,dark 时按暗色背景混合 string default default、dark
backgroundColor 暗色主题的底色 string #141414 任意颜色字符串

类型定义

所有类型都可以从包入口直接导入:

import type {
  RGB,
  RGBA,
  RGBAString,
  HSL,
  HSLA,
  HSV,
  HSVA,
  HSB,
  HSBA,
  LimeColorChannel,
  LimeColorFormats,
  LimeColorInfo,
  LimeColorOptions,
  LimeColorInput,
  LimeColorGenerateOptions,
} from '@/uni_modules/lime-color'
import type { TinyColor } from '@/uni_modules/lime-color'
类型 说明
LimeColorInput 所有可接受的颜色输入:字符串、数字、RGB(A)、HSL(A)、HSV(A)、HSB(A) 对象
LimeColorChannel 颜色通道,number 或 string(如 '100%')
LimeColorFormats 输出格式标识
LimeColorOptions 构造选项
LimeColorInfo RGB 解析结果,含 ok / format
LimeColorGenerateOptions generate() 的选项

支持的输入格式速查

形式 示例
十六进制 '#f00'、'f00'、'#ff0000'、'#ff000080'、'ff000080'
RGB / RGBA 'rgb(255, 0, 0)'、'rgb 255 0 0'、'rgba(255, 0, 0, .5)'、'rgb(100%, 50%, 0%)'
现代 CSS 语法 'rgb(0 0 0 / 50%)'、'hsl(270deg 60% 40% / 50%)'
HSL / HSLA 'hsl(0, 100%, 50%)'、'hsla(0, 100%, 50%, .5)'、'hsl 0 1.0 0.5'
HSV / HSVA / HSB / HSBA 'hsv(0, 100%, 100%)'、'hsva(0, 100%, 100%, .5)'、'hsb(210, 90%, 100%)'
颜色名称 'red'、'blanchedalmond'、'transparent'
数字 0xaabbcc(按 0xRRGGBB 解释)
对象 { r, g, b }、{ r, g, b, a }、{ h, s, l }、{ h, s, v }、{ h, s, b }
实例 tinyColor(colorInstance)

注意事项

  1. 格式会被继承:由 tinyColor('red') 派生出的颜色 format 仍是 name,toString() 会输出颜色名称而不一定是十六进制。例如 tinyColor('red').darken(100).toString() 返回 'black';需要十六进制时请显式调用 toHexString()。
  2. 同名色值取名:aqua / cyan、gray / grey 这类同值颜色,toName() 返回最先出现的名称(aqua、gray),与 tinycolor 一致;没有对应名称时返回 null。
  3. 数字输入不含透明度:tinyColor(0xff000080) 按 0xRRGGBB 解释,只取低 24 位,需要透明度请用字符串或对象。
  4. 取整误差:HSL / HSV 与 RGB 之间互转存在浮点误差,极端取值可能末位相差 1,属正常现象。
  5. 解析失败不抛错:无法识别时返回 isValid === false 的黑色实例,不会抛异常。
  6. 2.0 迁移:.uts 文件与 #ifdef 平台分支已移除,实现改为 common/ 下的纯 TypeScript 文件,对外类型声明在 utssdk/interface.ts;包入口保持 index.ts 不变,实例方法、参数与返回值保持兼容,hsb() / hsba() 字符串形式与 clone() 的行为已修正。

文档链接

📚 详细文档请访问以下站点:

支持与赞赏

如果你觉得本插件解决了你的问题,可以考虑支持作者:

支付宝赞助 微信赞助

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议