更新记录
2.0.1(2026-11-12)
下载此版本
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)
下载此版本
查看更多
平台兼容性
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)与各小程序均可直接使用。
安装方法
- 在 uni-app 插件市场中搜索并导入
lime-color
- 导入后可能需要重新编译项目
- 在页面或组件中按需引入使用
::: 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) |
注意事项
- 格式会被继承:由
tinyColor('red') 派生出的颜色 format 仍是 name,toString() 会输出颜色名称而不一定是十六进制。例如 tinyColor('red').darken(100).toString() 返回 'black';需要十六进制时请显式调用 toHexString()。
- 同名色值取名:
aqua / cyan、gray / grey 这类同值颜色,toName() 返回最先出现的名称(aqua、gray),与 tinycolor 一致;没有对应名称时返回 null。
- 数字输入不含透明度:
tinyColor(0xff000080) 按 0xRRGGBB 解释,只取低 24 位,需要透明度请用字符串或对象。
- 取整误差:HSL / HSV 与 RGB 之间互转存在浮点误差,极端取值可能末位相差 1,属正常现象。
- 解析失败不抛错:无法识别时返回
isValid === false 的黑色实例,不会抛异常。
- 2.0 迁移:
.uts 文件与 #ifdef 平台分支已移除,实现改为 common/ 下的纯 TypeScript 文件,对外类型声明在 utssdk/interface.ts;包入口保持 index.ts 不变,实例方法、参数与返回值保持兼容,hsb() / hsba() 字符串形式与 clone() 的行为已修正。
文档链接
📚 详细文档请访问以下站点:
支持与赞赏
如果你觉得本插件解决了你的问题,可以考虑支持作者:
| 支付宝赞助 |
微信赞助 |
 |
 |