# styimat

**Repository Path**: wxy6987/styimat

## Basic Information

- **Project Name**: styimat
- **Description**: 一个高效的CSS变量预处理库，支持Lab/LCH颜色空间自动转换、嵌套选择器和Display P3广色域，让现代CSS开发更简洁强大。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://gitee.com/wxy6987/styimat#readme
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-17
- **Last Updated**: 2026-01-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: CSS, styimat, color, css-in-js, color-conversion

## README

# Styimat
[![Stars](https://img.shields.io/badge/dynamic/json?label=Stars&query=%24.stargazers_count&url=https%3A%2F%2Fgitee.com%2Fapi%2Fv5%2Frepos%2Fwxy6987%2Fstyimat&color=FFD700&style=yellow)](https://gitee.com/wxy6987/styimat/stargazers)
[![Forks](https://img.shields.io/badge/dynamic/json?label=Forks&query=%24.forks_count&url=https%3A%2F%2Fgitee.com%2Fapi%2Fv5%2Frepos%2Fwxy6987%2Fstyimat&color=red)](https://gitee.com/wxy6987/styimat/members)
[![version](https://img.shields.io/npm/v/styimat.svg?color=brightgreen)](https://www.npmjs.com/package/styimat)
[![license](https://img.shields.io/npm/l/styimat.svg?color=lightgrey)](LICENSE)
[![npm 下载量](https://img.shields.io/npm/dt/styimat?label=download&color=blue)](https://www.npmjs.com/package/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 克隆（推荐）
```bash
# 克隆主仓库
git clone https://gitee.com/wxy6987/styimat.git

# 进入项目目录
cd styimat

# 安装依赖
npm install
```

### 2. 直接下载 ZIP
[![下载ZIP压缩包](https://img.shields.io/badge/下载ZIP压缩包-007BFF?style=for-the-badge&logo=data:image/svg%2bxml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c3ZnIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDQ4IDQ4IiBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik02IDQyLjAwODNINDIiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSI0IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48cGF0aCBkPSJNMzMgMjNMMjQgMzJMMTUgMjMiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSI0IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48cGF0aCBkPSJNMjMuOTkxNyA2VjMyIiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iNCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8%2bPC9zdmc%2b&logoColor=white)](https://gitee.com/wxy6987/styimat/repository/archive/main.zip)

### 3. NPM 安装
```bash
npm install styimat
```

### 4. CDN 引入
```html
<!-- unpkg -->
<script src="https://unpkg.com/styimat"></script>

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

### 5. ESModule使用
```javascript
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);
```

**也可以按需导入**

```javascript
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. 作为函数调用
```javascript
// 方式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. 作为模板标签使用
```javascript
// 基本模板标签用法
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. 对象方法调用
```javascript
// 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新增方法
```javascript
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. 混合使用示例
```javascript
// 先配置，然后使用模板标签
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);
```

### 命令行使用

```bash
# 基本用法
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`

```css
/* 全局变量 */
$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顶部

```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;`的格式

```css
@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`的格式，可以使用定义的别名来代替原生的属性名

```css
@alias bg background-color;

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

body {
  bg: $primary-color;
}
```

### 5. 宏语法

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

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

示例：

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

.container {
  @grid: 3 20px;
}
```

### 6. Math计算语法
```css
/* 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颜色语法
```css
/* 标准 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颜色语法
```css
/* 标准 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. 嵌套规则

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

```css
/* 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. 嵌套变量
```css
/* 变量可以引用其他变量 */
$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

```javascript
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;")
```

### 插件的定义标准

```javascript
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度

---

## 示例

### 完整示例
```css
/* 定义颜色变量 */
$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);
  }
}
```

### 颜色混合示例
```css
/* 使用十六进制语法创建调色板 */
$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() 函数高级示例
```css
/* 复杂数学计算 */
.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](https://gitee.com/wxy6987/styimat)
- **ZIP 下载**: [https://gitee.com/wxy6987/styimat/repository/archive/main.zip](https://gitee.com/wxy6987/styimat/repository/archive/main.zip)
- **Issues**: [问题反馈](https://gitee.com/wxy6987/styimat/issues)
- **Pull Requests**: [贡献代码](https://gitee.com/wxy6987/styimat/pulls)

## 贡献指南

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

1. **Fork 本仓库**  
[![Fork me on Gitee](https://gitee.com/wxy6987/styimat/widgets/widget_2.svg)](https://gitee.com/wxy6987/styimat/members)

2. **切换到特性分支**
```bash
git checkout -b feature/AmazingFeature
```
3. **提交更改**  
```bash
git commit -m 'Add some AmazingFeature'
```
4. **推送到分支**  
```bash
git push origin feature/AmazingFeature
```
5. **提交 Pull Request**

## 许可证

MIT © 王小玗 2025

## 支持

如果发现 bug 或有功能建议，请在 [Gitee Issues](https://gitee.com/wxy6987/styimat/issues) 中创建 Issue。

---

**如果这个项目对你有帮助，请给个 
[![Stars](https://img.shields.io/badge/dynamic/json?label=Stars&query=%24.stargazers_count&url=https%3A%2F%2Fgitee.com%2Fapi%2Fv5%2Frepos%2Fwxy6987%2Fstyimat&color=FFD700&style=yellow)](https://gitee.com/wxy6987/styimat/stargazers)**