huecss

v1.2.2

Published

2 days ago

A powerful CSS variable preprocessor with nested selectors, Lab/LCH color spaces conversion and modern color features.

0High
0Medium
0Low

wxy6987

css preprocessor css-variables nested-css lab-color lch-color color-conversion hue color css-in-js

HueCSS - CSS 变量预处理与颜色转换库

HueCSS 是一个轻量级的 CSS 预处理工具，支持 CSS 变量预处理、嵌套选择器和现代颜色空间转换（Lab/LCH 到 RGB）。

特性

CSS 变量预处理：使用 $variable: value; 语法定义 CSS 变量
嵌套选择器：类似 Sass 的嵌套语法，支持 & 父选择器引用
颜色空间转换：自动将 lab() 和 lch() 颜色转换为 RGB
广色域支持：保留 Lab/LCH 颜色在支持 display-p3 的设备上显示更丰富的色彩
十六进制颜色格式：支持 lab# 和 lch# 十六进制语法
自动处理：可自动处理带有 e 属性的 style 标签
作用域变量：支持全局变量和选择器局部变量
轻量无依赖：纯 JavaScript 实现，无外部依赖
CDN 支持：通过 jsDelivr 和 UNPKG 快速引入
NPM 包：可通过 npm 安装，包含命令行工具

安装

浏览器使用

<!-- 通过 jsDelivr 引入 -->
<script src="https://cdn.jsdelivr.net/npm/huecss/huecss.min.js"></script>

<!-- 或通过 UNPKG 引入 -->
<script src="https://unpkg.com/huecss/huecss.min.js"></script>

NPM 安装

# 全局安装（命令行工具）
npm install -g huecss

# 或本地安装
npm install huecss

命令行工具

包中包含 huecss 命令，提供命令行转换功能：

# 1. 从标准输入读取，输出到标准输出
npx huecss < input.css

# 2. 使用管道
cat input.css | npx huecss

# 3. 从文件读取，输出到标准输出
npx huecss input.css

# 4. 从文件读取，输出到文件
npx huecss input.css output.css

快速开始

基本用法

<!DOCTYPE html>
<html>
<head>
    <!-- 添加 e 属性让 HueCSS 自动处理 -->
    <style e>
        /* 定义变量 */
        $primary-color: lab#ff8080;  /* Lab 十六进制格式 */
        $secondary-color: lch(70% 60 180);  /* LCH 格式 */
        $spacing: 1rem;
        
        /* 使用变量和嵌套 */
        .button {
            background-color: $primary-color;
            padding: $spacing calc($spacing * 2);
            
            &:hover {
                background-color: $secondary-color;
            }
            
            &.large {
                padding: calc($spacing * 1.5) calc($spacing * 3);
            }
        }
    </style>
</head>
<body>
    <button class="button">普通按钮</button>
    <button class="button large">大按钮</button>
    
    <script src="https://cdn.jsdelivr.net/npm/huecss/huecss.min.js"></script>
</body>
</html>

语法参考

变量定义

/* 全局变量（在 :root 中） */
$brand-color: #3498db;
$spacing-unit: 1rem;
$border-radius: 8px;

/* 选择器局部变量 */
.container {
    $local-padding: 20px;
    padding: $local-padding;
}

/* 使用变量 */
.element {
    color: $brand-color;
    margin: calc($spacing-unit * 2);
    border-radius: $border-radius;
}

还可以配合js

ele.cssVar.bgcolor = "red";   // ele.变量名 = 变量值
ele.cssVar.color              // ele.变量名，来获取变量值

注：ele是正常元素，已将cssVar添加到HTMLElement

嵌套规则

/* 嵌套语法 */
.navbar {
    background: #333;
    
    /* & 引用父选择器 */
    &.fixed {
        position: fixed;
    }
    
    /* 子元素 */
    .nav-item {
        color: white;
        
        &:hover {
            color: #3498db;
        }
    }
}

/* 编译为 */
.navbar { background: #333; }
.navbar.fixed { position: fixed; }
.navbar .nav-item { color: white; }
.navbar .nav-item:hover { color: #3498db; }

@规则使用（必须用在最外层）

/* 关键帧动画必须在最外层定义 */
@keyframes rainbow {
    0% { 
        filter: hue-rotate(0deg); 
    }
    100% {
        filter: hue-rotate(360deg); 
    }
}

/* 媒体查询必须在最外层定义 */
@media (min-width: 768px) {
    .element {
        width: 50%;
    }
    
    .container {
        max-width: 1200px;
    }
}

/* 变量定义通常放在 :root 中 */
:root {
    $primary-color: lab(60% 20 -30);
    $animation-duration: 3s;
}

.element {
    animation: rainbow $animation-duration infinite linear;
    background: $primary-color;
    
    /* 嵌套内部不能再定义 @规则 */
    /* 错误示例：
    .inner {
        @keyframes slide { ... }  /* 错误！@规则不能嵌套 */
    } */
}

现代颜色空间支持

HueCSS 会自动检测设备是否支持 display-p3 广色域，并为支持的设备提供更丰富的色彩：

/* 输入 CSS */
.element {
    color: lab(60% 20 -30);
    background: lch(70% 60 180);
}

/* 输出 CSS（支持 display-p3 的设备） */
.element {
    color: lab(60% 20 -30);
    color: color(display-p3 0.482 0.655 0.824); /* 自动添加 fallback */
    background: lch(70% 60 180);
    background: color(display-p3 0.337 0.718 0.761);
}

/* 输出 CSS（不支持 display-p3 的设备） */
.element {
    color: rgb(123, 167, 210);
    background: rgb(86, 183, 194);
}

输出格式规范

HueCSS 输出的 CSS 代码非常规整，格式统一：

/* 输入 */
.button {
    $color: lab#ff8080;
    background: $color;
    padding: 1rem;
    
    &:hover {
        background: lch(70% 60 180);
    }
}

/* 输出 */
.button {
    background: rgb(255, 128, 128);
    padding: 1rem;
}

.button:hover {
    background: rgb(86, 183, 194);
}

/* 在支持 display-p3 的设备上 */
.button {
    background: rgb(255, 128, 128);
    background: color(display-p3 1 0.5 0.5);
    padding: 1rem;
}

.button:hover {
    background: rgb(86, 183, 194);
    background: color(display-p3 0.337 0.718 0.761);
}

JavaScript API

// 在模块化环境中
import huecss from 'huecss';
// 或
const huecss = require('huecss');

// 1. 直接转换 CSS 字符串
const css = `
    $primary: lab(60% 20 -30);
    $radius: 8px;
    
    .card {
        border-radius: $radius;
        background: $primary;
        
        &:hover {
            background: lab(70% 30 -20);
        }
    }
`;

const converted = huecss.convert(css);
console.log(converted);

// 2. 应用到页面
huecss.apply(css);

// 3. 配置选项
huecss.config({
    rootSelector: ':root',
    variablePrefix: '--',
    preserveOriginal: true,
    convertLabToRGB: true,
    convertLchToRGB: true,
    enableNesting: true,
    enableDisplayP3: true,
    prettyOutput: true  // 启用美化输出（默认已启用）
});

// 4. 颜色工具
const rgb = huecss.colorUtils.labToRGB(60, 20, -30);
console.log(rgb); // { r: 123, g: 167, b: 210 }

const hexLabRGB = huecss.colorUtils.parseHexLab('lab#ff8080');
console.log(hexLabRGB);

颜色格式

1. Lab 颜色

/* CSS 标准格式 */
.element {
    color: lab(60% 20 -30);
    color: lab(60 20 -30 / 0.5); /* 带透明度 */
}

/* 十六进制格式 */
.element {
    color: lab#ff8080;  /* L=ff, a=80, b=80 */
}

2. LCH 颜色

/* CSS 标准格式 */
.element {
    color: lch(70% 60 180);
    color: lch(70% 60 180deg / 0.8);
}

/* 十六进制格式 */
.element {
    color: lch#ff8040;  /* L=ff, C=80, H=40 */
}

3. 颜色转换

所有 Lab 和 LCH 颜色都会自动转换为 RGB 格式，并为支持 display-p3 的设备添加广色域版本：

/* 输入 */
.element { 
    color: lab(60% 20 -30); 
    animation: rainbow 3s infinite;
}

/* 输出（支持 display-p3） */
.element { 
    color: rgb(123, 167, 210);
    color: color(display-p3 0.482 0.655 0.824);
    animation: rainbow 3s infinite;
}

配置选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | rootSelector | string | :root | 根选择器名称 | | variablePrefix | string | -- | CSS 变量前缀 | | preserveOriginal | boolean | false | 是否保留原始 style 标签 | | indentSize | number | 2 | 缩进大小（空格数） | | enableNesting | boolean | true | 是否启用嵌套规则 | | autoProcessStyleTags | boolean | true | 是否自动处理 style 标签 | | styleTagAttribute | string | e | 识别 style 标签的属性 | | convertLabToRGB | boolean | true | 是否转换 Lab 颜色 | | convertLchToRGB | boolean | true | 是否转换 LCH 颜色 | | enableDisplayP3 | boolean | true | 是否添加 display-p3 颜色支持 | | prettyOutput | boolean | true | 是否美化输出格式 |

颜色工具 API

// 直接转换
const rgb1 = huecss.colorUtils.labToRGB(60, 20, -30);
const rgb2 = huecss.colorUtils.lchToRGB(70, 60, 180);

// 解析十六进制格式
const rgb3 = huecss.colorUtils.parseHexLab('lab#ff8080');
const rgb4 = huecss.colorUtils.parseHexLch('lch#ff8040');

// 通用颜色解析
const rgb5 = huecss.colorUtils.parseColor('lab(60% 20 -30)');
const rgb6 = huecss.colorUtils.parseColor('lch#ff8040');
const rgb7 = huecss.colorUtils.parseColor('#3498db'); // 支持传统格式

// LCH 转 Lab
const lab = huecss.colorUtils.lchToLab(70, 60, 180);

// 检测 display-p3 支持
const supportsP3 = huecss.colorUtils.supportsDisplayP3();

高级用法

作用域变量

/* 全局变量 */
$global-color: #333;

.component {
    /* 局部变量 - 只在这个选择器内有效 */
    $local-size: 200px;
    width: $local-size;
    
    /* 可以访问全局变量 */
    color: $global-color;
    
    .child {
        /* 不能访问父级的局部变量 */
        /* width: $local-size; */  /* 错误！ */
        
        /* 可以有自己的局部变量 */
        $child-padding: 10px;
        padding: $child-padding;
    }
}

.other-component {
    /* 不能访问其他组件的局部变量 */
    /* width: $local-size; */  /* 错误！ */
}

颜色空间计算

/* 使用 Lab 颜色进行主题设计 */
:root {
    $primary-lightness: 60%;
    $primary-a: 20;
    $primary-b: -30;
    
    $primary: lab($primary-lightness $primary-a $primary-b);
    $primary-dark: lab(calc($primary-lightness - 10%) $primary-a $primary-b);
    $primary-light: lab(calc($primary-lightness + 20%) $primary-a $primary-b);
}

.button {
    background: $primary;
    
    &:hover {
        background: $primary-dark;
    }
    
    &:active {
        background: $primary-light;
    }
}

浏览器兼容性

Chrome 58+
Firefox 52+
Safari 10.1+
Edge 16+
Node.js 12+

注意：display-p3 颜色空间支持需要：

Safari 15.4+
Chrome 111+
Edge 111+
Firefox 113+

性能注意事项

颜色转换在构建时完成，不影响运行时性能
嵌套解析会增加初始解析时间，但对最终 CSS 性能无影响
建议在生产环境中使用预处理的 CSS，而不是运行时处理
display-p3 检测只在支持时添加额外颜色声明

常见问题

1. 为什么我的变量没有生效？

确保变量在使用前已定义，并且使用 $ 符号引用。

2. Lab/LCH 颜色转换不准确？

转换使用标准的 CIELab 到 sRGB 算法。确保输入值在有效范围内：

Lab L: 0-100 或 0%-100%
Lab a/b: 约 -128 到 128
LCH C: ≥0
LCH H: 0-360

3. @规则可以嵌套吗？

不可以。HueCSS 要求所有 @ 规则（如 @keyframes, @media, @import）必须在最外层定义，不能嵌套在选择器内部。

4. 输出格式能自定义吗？

是的，可以通过配置 indentSize 调整缩进大小，但整体格式是固定的：

选择器 {
  属性名: 属性值;
  属性名: 属性值;
}

5. 如何在 Vue/React 中使用？

// React 示例
import huecss from 'huecss';
import { useEffect } from 'react';

const MyComponent = () => {
    const css = `
        @keyframes rainbow {
            0% { filter: hue-rotate(0deg); }
            100% { filter: hue-rotate(360deg); }
        }
        
        $color: lab(60% 20 -30);
        .my-class { 
            color: $color;
            animation: rainbow 3s infinite linear;
        }
    `;
    
    useEffect(() => {
        huecss.apply(css);
    }, []);
    
    return <div className="my-class">Hello</div>;
};

6. 为什么 display-p3 颜色在某些设备上不显示？

display-p3 是广色域标准，需要显示器硬件支持。HueCSS 会自动检测并回退到标准 sRGB。

许可证

MIT License

支持

如有问题或建议，请发送邮件至 [email protected]