更新记录

1.1.0（2025-09-27） 下载此版本

• [新增] 智能转换 API，支持自动格式识别
• [新增] 新增通用转换器 convertColor
• [新增] 新增批量转换功能 convertColors
• [新增] 新增颜色标准化功能 normalizeColor
• [优化] 性能优化和错误处理改进

1.0.0（2025-09-26） 下载此版本

• 颜色格式检测与验证
• HEX ↔ RGB ↔ HSL ↔ HSB 相互转换
• 命名颜色支持（70+ 常用颜色）
• 颜色亮度调整（lighten/darken）
• 饱和度调整（saturate）
• 颜色混合（mix）
• 补色生成（complement）
• 主题配色方案生成
• 对比度计算
• 无障碍性检查（AA/AAA 标准）

平台兼容性

uni-app(3.6.5)

smart-color-utils

一个功能强大的颜色工具库，支持多种颜色格式转换、颜色操作和无障碍性检查。

特性

• 多格式支持: 支持 HEX、RGB、RGBA、HSL、HSLA、HSB 和命名颜色
• 格式转换: 各种颜色格式之间的相互转换
• 智能转换: 自动识别颜色格式并转换到目标格式
• 颜色操作: 调亮、调暗、饱和度调整、颜色混合等
• 主题生成: 基于基础颜色生成完整的配色方案
• 无障碍性: WCAG 标准的对比度检查
• TypeScript: 完整的 TypeScript 类型支持

安装

# 通过 HBuilderX 插件市场安装
# 或者直接将 smart-color-utils 文件夹放入 uni_modules 目录

使用方法

基础导入

import {
  toHex,
  toRgb,
  convertColor,
  lighten,
  darken,
  generateColorTheme,
} from '@/uni_modules/smart-color-utils';

智能转换

这些 API 可以自动识别输入的颜色格式，无需手动判断类型：

import { toHex, toRgb, toHsl, convertColor, normalizeColor } from '@/uni_modules/smart-color-utils';

// 智能转换到十六进制
toHex('red'); // '#ff0000'
toHex('rgb(255, 0, 0)'); // '#ff0000'
toHex('hsl(0, 100%, 50%)'); // '#ff0000'
toHex('#f00'); // '#ff0000'

// 智能转换到RGB
toRgb('#ff0000'); // 'rgb(255, 0, 0)'
toRgb('red'); // 'rgb(255, 0, 0)'
toRgb('hsl(0, 100%, 50%)'); // 'rgb(255, 0, 0)'
toRgb('#ff0000', 0.5); // 'rgba(255, 0, 0, 0.5)'

// 智能转换到HSL
toHsl('#ff0000'); // 'hsl(0, 100%, 50%)'
toHsl('red'); // 'hsl(0, 100%, 50%)'
toHsl('rgb(255, 0, 0)'); // 'hsl(0, 100%, 50%)'

// 通用转换器
convertColor('#ff0000', 'rgb'); // 'rgb(255, 0, 0)'
convertColor('red', 'hsl'); // 'hsl(0, 100%, 50%)'
convertColor('rgb(255, 0, 0)', 'hex'); // '#ff0000'
convertColor('#ff0000', 'rgba', { alpha: 0.5 }); // 'rgba(255, 0, 0, 0.5)'

// 颜色标准化
normalizeColor('#f00');
/*
{
  hex: '#ff0000',
  rgb: 'rgb(255, 0, 0)',
  hsl: 'hsl(0, 100%, 50%)',
  hsb: [0, 100, 100],
  name: 'red',
  original: '#f00',
  type: 'hex'
}
*/

// 批量转换
convertColors(['#ff0000', 'green', 'rgb(0, 0, 255)'], 'hex');
// ['#ff0000', '#008000', '#0000ff']

颜色格式检测与验证

import { detectType, isValidColor } from '@/uni_modules/smart-color-utils';

// 检测颜色类型
detectType('#ff0000'); // 'hex'
detectType('rgb(255,0,0)'); // 'rgb'
detectType('red'); // 'named'

// 验证颜色是否有效
isValidColor('#ff0000'); // true
isValidColor('invalid'); // false

传统格式转换

如果你需要更精确的控制，仍然可以使用传统的转换函数：

import {
  hexToRgb,
  rgbToHex,
  hexToHsl,
  hslToHex,
  namedColorToHex,
} from '@/uni_modules/smart-color-utils';

// HEX 转 RGB
hexToRgb('#ff0000'); // 'rgb(255, 0, 0)'
hexToRgb('#ff0000', 0.5); // 'rgba(255, 0, 0, 0.5)'

// RGB 转 HEX
rgbToHex(255, 0, 0); // '#ff0000'

// HEX 转 HSL
hexToHsl('#ff0000'); // [0, 100, 50]

// HSL 转 HEX
hslToHex(0, 100, 50); // '#ff0000'

// 命名颜色转 HEX
namedColorToHex('red'); // '#ff0000'

颜色操作

import { lighten, darken, saturate, mix, complement } from '@/uni_modules/smart-color-utils';

// 调亮颜色（支持任意格式输入）
lighten('#ff0000', 20); // 调亮 20%
lighten('red', 20); // 支持命名颜色
lighten('rgb(255, 0, 0)', 20); // 支持RGB格式

// 调暗颜色
darken('#ff0000', 20); // 调暗 20%

// 调整饱和度
saturate('#ff0000', 30); // 增加饱和度 30%
saturate('#ff0000', -30); // 降低饱和度 30%

// 混合颜色
mix('#ff0000', '#0000ff', 0.5); // 红色和蓝色各占 50%
mix('red', 'blue', 0.3); // 支持命名颜色

// 生成补色
complement('#ff0000'); // '#00ffff'
complement('red'); // 支持命名颜色

主题生成

import { generateColorTheme } from '@/uni_modules/smart-color-utils';

// 支持任意格式的基础颜色
const theme1 = generateColorTheme('#3B82F6');
const theme2 = generateColorTheme('blue');
const theme3 = generateColorTheme('rgb(59, 130, 246)');

console.log(theme1);
/*
{
  primary: '#3B82F6',
  primaryLight: '#60A5FA',
  primaryDark: '#1D4ED8',
  secondary: '#10B981',
  accent: '#F59E0B',
  complement: '#F6823B',
  neutral: '#6B7280',
  success: '#10B981',
  warning: '#F59E0B',
  error: '#EF4444',
  info: '#3B82F6'
}
*/

亮度和对比度

import { getLuminance, getContrast, isAccessible } from '@/uni_modules/smart-color-utils';

// 获取颜色亮度 (0-1) - 支持任意格式
getLuminance('#ffffff'); // 1
getLuminance('white'); // 1
getLuminance('rgb(0, 0, 0)'); // 0

// 计算对比度 (1-21) - 支持任意格式
getContrast('#000000', '#ffffff'); // 21
getContrast('black', 'white'); // 21

// 检查无障碍性
isAccessible('#000000', '#ffffff', 'AA', 'normal'); // true
isAccessible('black', 'white', 'AAA', 'large'); // true

API 参考

智能转换

类型定义

type ColorType = 'hex' | 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'named' | 'unknown';
type RgbTuple = [number, number, number];
type HsbTuple = [number, number, number];
type HslTuple = [number, number, number];

检测与验证

传统格式转换

颜色操作

主题与无障碍

注意事项

1. 所有颜色输入都会进行格式验证，无效格式会抛出错误
2. RGB 值范围为 0-255
3. HSL/HSB 中的 H 值范围为 0-360，S 和 L/B 值范围为 0-100
4. 透明度值范围为 0-1
5. 对比度计算基于 WCAG 2.1 标准