unocss-preset-alias-colors

English Document

一个轻量的 UnoCSS 预设插件，为你的设计系统启用语义化的颜色别名。将自定义的颜色名称（如 primary 或 brand）映射到实际的颜色标记，让你的工具类更具语义且易于维护。

特性

• 语义化颜色映射：创建直观的别名，如 primary → blue、brand → indigo
• 模式感知匹配：与颜色色阶（-500）、变体（dark:）和透明度修饰符（/50）无缝协作
• 内置校验：当映射的颜色在主题中不存在时发出警告，避免运行时意外
• 性能优化：首次访问时缓存源颜色，最小化开销
• 零配置：开箱即用，支持任何 UnoCSS 预设，特别是 preset-wind

安装

任选常用的包管理器：

pnpm add -D unocss-preset-alias-colors
# 或者
yarn add -D unocss-preset-alias-colors
# 或者
npm install -D unocss-preset-alias-colors

快速上手

在 UnoCSS 配置中注册预设并定义颜色别名：

import { defineConfig, presetWind } from 'unocss';
import presetAliasColors from 'unocss-preset-alias-colors';

export default defineConfig({
  presets: [
    presetWind(),
    presetAliasColors({
      colors: {
        primary: 'blue',
        secondary: 'purple',
        danger: 'red',
      },
    }),
  ],
});

然后在标记中使用语义化名称：

<!-- 这些类名会自动解析为其映射的颜色 -->
<button class="bg-primary-500 hover:bg-primary-600 text-white">
  主要按钮
</button>

<div class="text-secondary dark:text-secondary-300">
  主题文本
</div>

<span class="border-danger/50">
  危险徽章
</span>

实际使用场景

设计系统标记

在项目中保持一致的设计语言：

presetAliasColors({
  colors: {
    // 品牌颜色
    brand: 'indigo',
    accent: 'teal',

    // 语义颜色
    success: 'green',
    warning: 'yellow',
    error: 'red',
    info: 'blue',

    // UI 颜色
    surface: 'slate',
    muted: 'gray',
  },
});

多品牌应用

无需重写标记即可切换配色方案：

// 浅色主题配置
presetAliasColors({
  colors: {
    text: 'gray',
    background: 'white',
  },
});

// 深色主题配置
presetAliasColors({
  colors: {
    text: 'slate',
    background: 'zinc',
  },
});

框架组件库

将实现细节从组件 API 中抽象出来：

// 组件作者编写语义名称
<Card className="bg-card border-card-border">
  <Text className="text-card-foreground">内容</Text>
</Card>

// 下游用户配置实际颜色
presetAliasColors({
  colors: {
    card: 'white',
    'card-border': 'gray',
    'card-foreground': 'slate',
  },
});

配置

colors

类型：Record<string, string>

别名名称到 UnoCSS 主题中实际颜色键的映射。

presetAliasColors({
  colors: {
    // 别名名称 → 主题颜色键
    primary: 'blue',      // 将 `bg-primary-500` 映射为 `bg-blue-500`
    brand: 'indigo',      // 将 `text-brand` 映射为 `text-indigo`
    highlight: 'yellow',  // 将 `border-highlight/50` 映射为 `border-yellow/50`
  },
});

重要提示：预设使用 -{alias} 模式执行精确的标记替换，后跟：

• 连字符（-）用于颜色色阶：bg-primary-500
• 斜杠（/）用于透明度：text-primary/50
• 冒号（:）用于变体：dark:bg-primary
• 字符串结尾用于基础颜色：bg-primary

这确保了 primary-button 不会意外匹配 primary 别名。

工作原理

预设注册一个 UnoCSS 变体来拦截类名生成：

1. 模式检测：扫描类名中配置的 -{alias} 模式
2. 标记替换：将匹配的别名替换为其映射的颜色键
3. 验证：检查映射的颜色是否在主题中存在（如果未找到则发出警告）
4. 类名生成：UnoCSS 使用转换后的类名继续处理

输入：  bg-primary-500 hover:text-secondary/80
         ↓
替换：  bg-blue-500 hover:text-purple/80
         ↓
输出：  生成带有实际颜色值的 CSS

验证与警告

当你将别名映射到主题中不存在的颜色时：

presetAliasColors({
  colors: {
    primary: 'nonexistent-color', // ⚠️ 主题中不存在
  },
});

预设将会：

• 仍然使用映射后的名称生成类
• 在控制台打印警告，显示可用的颜色
• 帮助你尽早发现配置错误

警告输出示例：

[warn] Color nonexistent-color is not in the source colors: red, blue, green, ...

TypeScript 支持

预设完全类型化，并导出 TypeScript 定义：

import presetAliasColors from 'unocss-preset-alias-colors';
import type { AliasOptions } from 'unocss-preset-alias-colors';

// 类型安全的配置
const options: AliasOptions = {
  colors: {
    primary: 'blue',
    secondary: 'purple',
  },
};

export default defineConfig({
  presets: [presetAliasColors(options)],
});

分发形式

包提供多种构建输出以适应不同环境：

• ES 模块：从 unocss-preset-alias-colors 导入（推荐）
• CommonJS：使用 require('unocss-preset-alias-colors') 适用于 Node.js
• 类型定义：在 unocss-preset-alias-colors 中捆绑 .d.ts 文件

所有构建产物都经过优化且支持 tree-shaking。

常见模式

组件作用域颜色

presetAliasColors({
  colors: {
    // 按钮变体
    'btn-primary': 'blue',
    'btn-secondary': 'gray',

    // 卡片元素
    'card-bg': 'white',
    'card-border': 'gray',
  },
});

基于状态的颜色

presetAliasColors({
  colors: {
    'state-idle': 'gray',
    'state-pending': 'yellow',
    'state-success': 'green',
    'state-error': 'red',
  },
});

许可证

MIT