Styimat

让CSS变量拥有预处理能力：嵌套语法、Lab/LCH色彩空间、Display P3广色域、智能数学计算，一份代码适配所有现代浏览器。

项目结构

├── bin
│   └── convert-styimat.js
├── dist
│   ├── styimat.js
│   ├── styimat.min.js
│   ├── styimat.min.mjs
│   └── styimat.mjs
├── esm    // ESModule文件的快捷导入方式
├── umd    // UMD文件的快捷导入方式
├── cli    // 命令行文件的快捷导入方式
└── package.json

安装方式

1. Git 克隆（推荐）

# 克隆主仓库
git clone https://gitee.com/wxy6987/styimat.git

# 进入项目目录
cd styimat

# 安装依赖
npm install

2. 直接下载 ZIP

3. NPM 安装

npm install styimat

4. CDN 引入

<!-- unpkg -->
<script src="https://unpkg.com/styimat"></script>

<!-- jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/styimat/styimat.min.js"></script>

5. ESModule使用

import styimat from 'https://unpkg.com/styimat/esm'
const css = `
  $primary: lab(54.7 77.9 80.1);
  .button { background-color: $primary; }
`;

const result = await styimat.convert(css);
console.log(result);

也可以按需导入

import { convert, apply } from 'https://unpkg.com/styimat/esm'
const css = `
  $primary: lab(54.7 77.9 80.1);
  .button { background-color: $primary; }
`;

const result = convert(css);
console.log(result);
apply();

特性

• Lab/LCH 颜色支持 - 将 Lab 和 LCH 颜色转换为 CSS 兼容的 RGB
• 广色域显示 - 自动检测并支持 Display P3 广色域显示器
• 变量系统 - 类似 Sass 的变量系统，支持作用域变量
• 嵌套规则 - 支持 Sass 风格的嵌套选择器
• 十六进制语法 - 支持 lab#LLAABB 和 lch#LLCCHHH 简洁语法
• 增强数学计算 - 支持 math() 函数和复杂数学表达式
• 轻量高效 - 无依赖，压缩后仅约 20KB
• 多种使用方式 - 浏览器、Node.js、命令行均可使用
• 灵活API - 支持函数调用、模板标签、对象配置等多种用法
• 现代ESModule导入 - 支持import按需导入

使用方法

JavaScript调用

1. 作为函数调用

// 方式1：直接传入CSS字符串
const css = await styimat(`
  $primary: lab(54.7 77.9 80.1);
  .button { color: $primary; }
`);

// 方式2：传入配置对象（返回函数本身）
styimat({
  enableP3: true,
  enableMath: true
});

// 方式3：无参数调用（自动处理页面中所有标记的<style>标签）
styimat();

2. 作为模板标签使用

// 基本模板标签用法
const css = await styimat`
  $primary: lab(54.7 77.9 80.1);
  $secondary: lch(44.7 67.9 210);
  
  .button {
    background: $primary;
    color: white;
    
    &:hover {
      background: $secondary;
    }
  }
`;

// 模板标签支持插值
const theme = 'dark';
const cssWithVars = await styimat`
  $primary: \${theme === 'dark' ? 'lab(30 40 50)' : 'lab(70 20 -10)'};
  
  body {
    background: $primary;
  }
`;

3. 对象方法调用

// 1. 转换CSS
const converted = await styimat.convert(cssString, config);

// 2. 应用到页面
const styleElement = styimat.apply(cssString, config);

// 3. 配置全局设置
styimat.config({
  enableP3: true,
  enableMath: true,
  indentSize: 2
});

// 4. 使用工具方法
const mathResult = styimat.math.evaluate('100px/2'); // "calc(100px / 2)"
const rgbColor = styimat.colorUtils.labToRGB(54.7, 77.9, 80.1);

4. HTMLElement新增方法

ele.cssVar(prop, value);   // 设置prop变量为value
ele.cssVar.prop = value;   // 设置prop变量为value
ele.cssVar[prop] = value;  // 设置prop变量为value
ele.cssVar(prop);          // 获取prop变量的值
ele.cssVar.prop;           // 获取prop变量的值
ele.cssVar[prop]           // 获取prop变量的值

5. 混合使用示例

// 先配置，然后使用模板标签
styimat.config({ enableP3: true });

const designSystem = await styimat`
  /* 设计系统变量 */
  $primary: lab#8CFF80;
  $secondary: lch#6CFF180;
  $spacing-unit: 1rem;
  
  /* 组件样式 */
  .btn {
    padding: $spacing-unit;
    background: $primary;
    
    &.secondary {
      background: $secondary;
    }
  }
`;

// 应用到页面
styimat.apply(designSystem);

命令行使用

# 基本用法
npx styimat input.css output.css

# 输出到 stdout
npx styimat input.css

# 使用管道
npx styimat < input.css > output.css
cat input.css | npx styimat > output.css

# 从 stdin 读取，输出到 stdout
npx styimat

# 全局安装后使用
npm install -g styimat
styimat input.css output.css

更多使用方法请 npx styimat -h

Styimat语法

1. 变量定义

变量定义要用$name: value;的格式，使用直接$name

/* 全局变量 */
$primary-color: lab(54.7 77.9 80.1);
$spacing: 1rem;
$font-family: 'Inter', sans-serif;

/* 局部变量（在规则块内） */
.container {
  $local-var: 20px;
  margin: $local-var;
      
  &::before {
   content: $$ctx;  // 获取元素属性ctx
  }
}

2. 配置头语法

变量定义要用@config name value的格式，写在css顶部

@config indent-size 4
@config auto-process-style-tags true
@config preserve-original true
@config enable-p3 false
@config root-selector :root
@config enable-nesting true
@config enable-math true

/* 然后写您的CSS代码 */
$primary-color: lab#32a852;
$spacing: math(16px*2+4px);

body {
  color: $primary-color;
  padding: $spacing;
  
  .container {
    margin: math($spacing/2);
  }
}

注意：配置头既支持驼峰命名也支持连字符命名，例如 indent-size 和 indentSize 效果相同。

3. 导入语法

导入文件要用@import url;的格式

@import yourcss.css;

/* 然后写您的CSS代码 */
$primary-color: lab#32a852;
$spacing: math(16px*2+4px);

body {
  color: $primary-color;
  padding: $spacing;
  
  .container {
    margin: math($spacing/2);
  }
}

4. 别名语法

别名定义要用@alias alias prop的格式，可以使用定义的别名来代替原生的属性名

@alias bg background-color;

/* 然后写您的CSS代码 */
$primary-color: lab#32a852;

body {
  bg: $primary-color;
}

5. 宏语法

更强大的替换，要用以下格式：

@macro name($param1, $param2, $param3: defaultvalue...) {
    /* macro body */
}

示例：

@macro grid($columns, $gap: 10px) {
  display: grid;
  grid-template-columns: repeat($columns, 1fr);
  gap: $gap;
}

.container {
  @grid: 3 20px;
}

6. Math计算语法

/* math() 函数 */
.element {
  width: math(100%/3);
  height: math(200px+30px);
  padding: math(2rem*1.5);
  margin: math((100vh-200px)/2);
}

/* 支持单位运算 */
.container {
  font-size: math(16px * 1.125); /* 18px */
  gap: math(24px + 1rem); /* 支持混合单位 */
}

7. Lab颜色语法

/* 标准 lab() 函数 */
.element {
  color: lab(54.7 77.9 80.1);
  background: lab(87.8 -79.3 80.8 / 0.5); /* 带透明度 */
}

/* 十六进制简写 */
.element {
  color: lab#8CFF80; /* L=8C, A=FF, B=80 */
}

8. LCH颜色语法

/* 标准 lch() 函数 */
.element {
  color: lch(54.7 78.9 38.5);
  background: lch(87.8 79.3 180 / 30%); /* 带透明度百分比 */
}

/* 十六进制简写 */
.element {
  color: lch#8CFF90; /* L=8C, C=FF, H=90 */
}

9. 嵌套规则

可以让写代码更简单，而且让代码可读性更高

/* Styimat 风格的嵌套 */
.container {
  padding: 1rem;

  .header {
    font-size: 2rem;
    
    .title {
      color: lab(20 40 60);
    }
  }
}

@media (min-width: 768px) {
  .container {
    padding: 2rem;
    
    .header {
      font-size: 3rem;
    }
  }
}

10. 嵌套变量

/* 变量可以引用其他变量 */
$base-color: lab(54.7 77.9 80.1);
$text-color: lch(20 30 270);
$border-color: $base-color;
$padding-large: math(2rem * 1.5);

.element {
  color: $text-color;
  border: 1px solid $border-color;
  padding: $padding-large;
}

API文档

JavaScript API

const styimat = require('styimat');

// 转换 CSS
const cssPromise = styimat.convert(cssString, config);

// 应用到页面
styimat.apply(cssString, config);

// 配置全局设置
styimat.config({
  rootSelector: ':root',
  variablePrefix: '--',
  convertLabToRGB: true,
  convertLchToRGB: true,
  enableP3: true,
  enableMath: true,
  indentSize: 4,
  enableNesting: true,
  importBaseUrl: '',        // 导入基础URL
  importCache: true,        // 缓存导入文件
  importTimeout: 5000,      // 导入超时时间
  autoProcessStyleTags: true,
  styleTagAttribute: 'e',
  preserveOriginal: false
});

// 导入工具
styimat.imports.clearCache();            // 清除导入缓存
styimat.imports.setBaseUrl('/css/');     // 设置导入基础URL
styimat.imports.setCacheEnabled(false);  // 禁用导入缓存
styimat.imports.setTimeout(10000);       // 设置导入超时时间

// 定义插件
class compressPlugin extends styimat.Plugin {
    name = "compress";
    install() {
        // 下载时调用 (不必须)
    }
    
    destroy() {
        // 删除时调用 (不必须)
    }
    
    convert(css, config) {
        // 必须写，否则报错
        return css.replace(/[\n\s]/g, "");
    }
    
    methods = {
        parse(cssText){
            return this.convert(cssText);
        }
    }
}

// 设置插件
styimat.plugins.use(compressPlugin);

// 删除插件
styimat.plugins.remove("compress");

// 使用自定义方法
styimat.compress.parse("color: red;  background-color: blue;")

插件的定义标准

export defult class extends styimat.Plugin {
    name = "compress";
    install() {
        // 下载时调用
        // 在这里做初始化工作
    }
    
    destroy() {
        // 删除时调用
        // 记得清理
    }
    
    convert(css, config) {
        // 转换时调用，必须写
        return css.replace(/[\n\s]/g, "");
    }
    
    methods = {
        // 一些自定义方法
        parse(cssText){
            return this.convert(cssText);
        }
    }
}

// 导入时
import compressPlugin from "./plugins/compress.js";
styimat.use(compressPlugin);

配置选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | rootSelector | string | :root | CSS 变量定义的根选择器 | | variablePrefix | string | -- | CSS 变量前缀 | | preserveOriginal | boolean | false | 是否保留原始 <style e> 标签 | | indentSize | number | 4 | 嵌套规则的缩进大小 | | enableNesting | boolean | true | 是否启用嵌套规则 | | autoProcessStyleTags | boolean | true | 是否自动处理页面中的 style 标签 | | styleTagAttribute | string | e | 标识需要处理的 style 标签属性 | | convertLabToRGB | boolean | true | 是否转换 Lab 颜色为 RGB | | convertLchToRGB | boolean | true | 是否转换 LCH 颜色为 RGB | | enableP3 | boolean | true | 是否启用 Display P3 广色域支持 | | enableMath | boolean | true | 是否启用 math() 函数增强 | | importBaseUrl | string | | 导入的基础URL | |importCache| boolean |true| 是否缓存导入的文件 | |importTimeout| number |5000` | 导入超时时间（毫秒） |

十六进制颜色语法详解

Lab 十六进制格式：lab#LLAABB

Lab 颜色使用 lab# 前缀，后跟 6 个十六进制字符：

• 前 2 位：L（明度），范围 00-FF，映射到 0-100
• 中间 2 位：A（红绿轴），范围 00-FF，映射到 -192 到 192
• 后 2 位：B（黄蓝轴），范围 00-FF，映射到 -192 到 192

示例：lab#8CFF80 表示：

• L = 0x8C = 140 → 140/255 × 100 ≈ 55
• A = 0xFF = 255 → (255-128) × 1.5 ≈ 190.5
• B = 0x80 = 128 → (128-128) × 1.5 = 0

LCH 十六进制格式：lch#LLCCHHH

LCH 颜色使用 lch# 前缀，后跟 6 个字符（最后1-3位是十进制色相值）：

• 前 2 位：L（明度），范围 00-FF，映射到 0-100
• 中间 2 位：C（色度），范围 00-FF，映射到 0-150
• 后 1-3 位：H（色相），范围 0-100，映射到 0-360度

示例：lch#8CFF090 表示：

• L = 0x8C = 140 → 140/255 × 100 ≈ 55
• C = 0xFF = 255 → 255/255 × 150 = 150
• H = 090 → 090/100 × 360 = 324度

示例

完整示例

/* 定义颜色变量 */
$brand-primary: lab(54.7 77.9 80.1);
$brand-secondary: lch(44.7 67.9 210);
$text-primary: lch(20 30 270);
$spacing-unit: 1rem;
$border-radius: 0.5rem;

/* 使用变量和嵌套 */
.button {
  background-color: $brand-primary;
  color: white;
  padding: $spacing-unit math($spacing-unit * 2);
  border-radius: $border-radius;
  border: 2px solid lab(44.7 67.9 70.1);

  &:hover {
    background-color: lab(64.7 87.9 90.1);
    transform: translateY(-2px);
  }

  &.large {
    padding: math($spacing-unit * 1.5) math($spacing-unit * 3);
    font-size: math(1rem * 1.25);
  }
}

/* 媒体查询中的嵌套 */
.container {
  max-width: 1200px;
  margin: 0 auto;

  @media (max-width: 768px) {
    padding: 0 $spacing-unit;
    font-size: math(16px * 0.9);
  }
}

颜色混合示例

/* 使用十六进制语法创建调色板 */
$primary: lab#8CFF80;
$secondary: lch#8CFF18;
$accent: lch#6CFF27;

/* 创建变体 */
$primary-light: lab#B4FF0A;
$primary-dark: lab#64FF06;
$primary-transparent: lab(55 190 0 / 0.8);

.theme {
  --color-primary: var(--primary);
  --color-secondary: var(--secondary);
  --color-accent: var(--accent);

  .card {
    background: linear-gradient(135deg, $primary, $secondary);
    border: 1px solid $accent;
    width: math(100% / 3);
  }
}

Math() 函数高级示例

/* 复杂数学计算 */
.grid {
  --columns: 12;
  --gap: 1rem;
  
  .col-4 {
    width: math(calc(100% / var(--columns)) * 4);
  }
  
  .col-6 {
    width: math(calc(100% / var(--columns)) * 6 - var(--gap));
  }
}

.responsive {
  font-size: math(clamp(16px, 2vw + 8px, 24px));
  padding: math(max(1rem, 2vh));
}

.aspect-ratio {
  height: math(100vw / 16 * 9); /* 16:9 宽高比 */
}

浏览器兼容性

| 特性 | Chrome | Firefox | Safari | Edge | |------|--------|---------|---------|------| | CSS变量 | 49+ | 31+ | 9.1+ | 16+ | | Display P3 | 111+ | 113+ | 16.4+ | 111+ | | 嵌套规则 | 112+ | 117+ | 16.4+ | 112+ | | Lab/LCH颜色 | 通过转换 | 通过转换 | 通过转换 | 通过转换 |

注意：Styimat会自动为不支持的浏览器提供降级方案

常见问题

Q: 使用Styimat会影响页面加载性能吗？

A: Styimat非常轻量，压缩后仅约20KB。对于大多数项目，性能影响可以忽略不计。

Q: 如何从Sass/Less迁移到Styimat？

A: 大多数Sass/Less语法可以直接使用。主要区别是Styimat使用$前缀定义变量，且原生支持CSS变量。

Q: 生产环境中应该如何处理？

A: 建议在构建时使用命令行工具预处理CSS，而不是在浏览器中实时转换。

Git 仓库

• 主仓库: https://gitee.com/wxy6987/styimat
• ZIP 下载: https://gitee.com/wxy6987/styimat/repository/archive/main.zip
• Issues: 问题反馈
• Pull Requests: 贡献代码

贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
   

2. 切换到特性分支

git checkout -b feature/AmazingFeature

3. 提交更改

git commit -m 'Add some AmazingFeature'

4. 推送到分支

git push origin feature/AmazingFeature

5. 提交 Pull Request

许可证

MIT © 王小玗 2025

支持

如果发现 bug 或有功能建议，请在 Gitee Issues 中创建 Issue。

如果这个项目对你有帮助，请给个