styimat 4.1.0 → 4.2.1

package/README.md

@@ -11,12 +11,12 @@
 
 ```
 ├── bin
-│   └── convert-styimat.js
+│   └── convert-styimat.js
 ├── dist
-│   ├── styimat.js
-│   ├── styimat.min.js
-│   ├── styimat.min.mjs
-│   └── styimat.mjs
+│   ├── styimat.js
+│   ├── styimat.min.js
+│   ├── styimat.min.mjs
+│   └── styimat.mjs
 ├── esm    // ESModule文件的快捷导入方式
 ├── umd    // UMD文件的快捷导入方式
 ├── cli    // 命令行文件的快捷导入方式
@@ -62,20 +62,20 @@ const css = `
   .button { background-color: $primary; }
 `;
 
-const result = styimat.convent(css);
+const result = styimat.convert(css);
 console.log(result);
 ```
 
 **也可以按需导入**
 
 ```javascript
-import { convent, apply } from 'https://unpkg.com/styimat/esm'
+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 = convent(css);
+const result = convert(css);
 console.log(result);
 apply();
 ```
@@ -87,106 +87,27 @@ apply();
 - **变量系统** - 类似 Sass 的变量系统，支持作用域变量
 - **嵌套规则** - 支持 Sass 风格的嵌套选择器
 - **十六进制语法** - 支持 `lab#LLAABB` 和 `lch#LLCCHHH` 简洁语法
-- **增强数学计算** - 支持 `math()`` 函数和复杂数学表达式
+- **增强数学计算** - 支持 `math()` 函数和复杂数学表达式
 - **轻量高效** - 无依赖，压缩后仅约 20KB
 - **多种使用方式** - 浏览器、Node.js、命令行均可使用
 - **灵活API** - 支持函数调用、模板标签、对象配置等多种用法
 - **现代ESModule导入** - 支持`import`按需导入
 
-## 快速开始
-
-### 浏览器中使用
-
-```html
-<!-- 在 HTML 中直接使用 -->
-<style e>
-  $primary-color: lab(54.7 77.9 80.1);
-  $spacing: 1rem;
-  
-  .button {
-    background-color: $primary-color;
-    padding: $spacing;
-    
-    &:hover {
-      background-color: lab(44.7 67.9 70.1);
-    }
-  }
-</style>
-
-<script src="https://cdn.jsdelivr.net/npm/styimat/styimat.min.js"></script>
-```
-
-### Node.js 中使用
-
-```javascript
-const styimat = require('styimat');
-
-const css = `
-  $primary: lab(54.7 77.9 80.1);
-  .button { background-color: $primary; }
-`;
-
-const result = styimat.convert(css);
-console.log(result);
-```
-
-### AMD中使用
-```javascript
-// scripts/main.js
-require.config({
-  paths: {
-    'styimat': 'https://cdn.jsdelivr.net/npm/styimat/styimat.min'
-  }
-});
-
-require(['styimat'], function(styimat) {
-  // 主应用代码
-  styimat.apply(`
-    $primary: lab(50 20 -10);
-    body { color: $primary; }
-  `);
-});
-```
-
-### 命令行使用
-
-```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`**
-
-## 高级用法
-
-**重要！如果用了import语法一定加上await，没用可以不加，但是加上了一直不错！**
+---
 
-### 1. 作为函数直接调用
+## 使用方法
 
-`styimat` 本身是一个可调用的函数，支持多种调用方式：
+### 一、JavaScript调用
 
+#### 1. 作为函数调用
 ```javascript
 // 方式1：直接传入CSS字符串
-const css1 = await styimat(`
+const css = await styimat(`
   $primary: lab(54.7 77.9 80.1);
   .button { color: $primary; }
 `);
 
-// 方式2：传入配置对象（返回函数本身，可以链式调用）
+// 方式2：传入配置对象（返回函数本身）
 styimat({
   enableP3: true,
   enableMath: true,
@@ -197,10 +118,7 @@ styimat({
 styimat();
 ```
 
-### 2. 作为模板标签使用
-
-`styimat` 可以作为ES6模板字符串的标签函数，提供更简洁的语法：
-
+#### 2. 作为模板标签使用
 ```javascript
 // 基本模板标签用法
 const css = await styimat`
@@ -220,33 +138,18 @@ const css = await styimat`
 // 模板标签支持插值
 const theme = 'dark';
 const cssWithVars = await styimat`
-  $primary: ${theme === 'dark' ? 'lab(30 40 50)' : 'lab(70 20 -10)'};
+  $primary: \${theme === 'dark' ? 'lab(30 40 50)' : 'lab(70 20 -10)'};
   
   body {
     background: $primary;
   }
 `;
-
-// 复杂的插值示例
-const spacing = 1.5;
-const cssComplex = await styimat`
-  $base-spacing: ${spacing}rem;
-  $large-spacing: math(${spacing} * 2);
-  
-  .container {
-    padding: $base-spacing;
-    margin: $large-spacing;
-  }
-`;
 ```
 
-### 3. 作为对象方法调用
-
-除了函数调用，`styimat` 还提供了对象方法：
-
+#### 3. 对象方法调用
 ```javascript
 // 1. 转换CSS
-const converted =  await styimat.convert(cssString, config);
+const converted = await styimat.convert(cssString, config);
 
 // 2. 应用到页面
 const styleElement = styimat.apply(cssString, config);
@@ -263,9 +166,7 @@ const mathResult = styimat.math.evaluate('100px / 2'); // "50px"
 const rgbColor = styimat.colorUtils.labToRGB(54.7, 77.9, 80.1);
 ```
 
-### 4. HTMLElement的新方法
-HTMLElement由此库新增了`cssVar`属性，可以设置、获取css变量
-
+#### 4. HTMLElement新增方法
 ```javascript
 ele.cssVar(prop, value);   // 设置prop变量为value
 ele.cssVar.prop = value;   // 设置prop变量为value
@@ -275,8 +176,7 @@ ele.cssVar.prop;           // 获取prop变量的值
 ele.cssVar[prop]           // 获取prop变量的值
 ```
 
-### 4. 混合使用示例
-
+#### 5. 混合使用示例
 ```javascript
 // 先配置，然后使用模板标签
 styimat.config({ enableP3: true });
@@ -302,10 +202,32 @@ const designSystem = await styimat`
 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. 变量定义
 ```css
 /* 全局变量 */
 $primary-color: lab(54.7 77.9 80.1);
@@ -323,12 +245,16 @@ $font-family: 'Inter', sans-serif;
 }
 ```
 
-### 导入语法
-
-#### 您可以在CSS文件的开头使用导入文件来导入其他css文件，应该以`@import开头`：
-
+#### 2. 配置头语法
 ```css
-@import yourcss.css;
+#indent-size 4
+#auto-process-style-tags true
+#preserve-original true
+#enable-p3 false
+#root-selector :root
+#enable-nesting true
+#enable-math true
+#math-precision 8
 
 /* 然后写您的CSS代码 */
 $primary-color: lab#32a852;
@@ -344,59 +270,52 @@ body {
 }
 ```
 
-#### 还可以使用style语法:
-```html
-<!--这样就自动处理好了-->
-<style src="head.css" e></style>
-```
-
-### 别名语法
-
-#### 您可以在CSS文件的开头使用别名来让css属性名更简单，应该以`@alias开头`：
+**注意**：配置头既支持驼峰命名也支持连字符命名，例如 `indent-size` 和 `indentSize` 效果相同。
 
+#### 3. 导入语法
 ```css
-@alias bg background-color;
+@import yourcss.css;
 
 /* 然后写您的CSS代码 */
 $primary-color: lab#32a852;
+$spacing: math(16px * 2 + 4px);
 
 body {
-  bg: $primary-color;
+  color: $primary-color;
+  padding: $spacing;
+  
+  .container {
+    margin: math($spacing / 2);
+  }
 }
 ```
 
-### 配置头语法
-
-您可以在CSS文件的开头使用配置头来设置预处理选项，配置行以 `#` 开头：
-
+#### 4. 别名语法
 ```css
-#indent-size 4
-#auto-process-style-tags true
-#preserve-original true
-#enable-p3 false
-#root-selector :root
-#enable-nesting true
-#enable-math true
-#math-precision 8
+@alias bg background-color;
 
 /* 然后写您的CSS代码 */
 $primary-color: lab#32a852;
-$spacing: math(16px * 2 + 4px);
 
 body {
-  color: $primary-color;
-  padding: $spacing;
-  
-  .container {
-    margin: math($spacing / 2);
-  }
+  bg: $primary-color;
 }
 ```
 
-**注意**：配置头既支持驼峰命名也支持连字符命名，例如 `indent-size` 和 `indentSize` 效果相同。
+#### 5. 宏语法
+```css
+@macro grid($columns, $gap: 10px) {
+  display: grid;
+  grid-template-columns: repeat($columns, 1fr);
+  gap: $gap;
+}
 
-### Math 计算语法
+.container {
+  @grid(3, 20px);
+}
+```
 
+#### 6. Math计算语法
 ```css
 /* math() 函数 */
 .element {
@@ -413,8 +332,7 @@ body {
 }
 ```
 
-### Lab 颜色语法
-
+#### 7. Lab颜色语法
 ```css
 /* 标准 lab() 函数 */
 .element {
@@ -428,8 +346,7 @@ body {
 }
 ```
 
-### LCH 颜色语法
-
+#### 8. LCH颜色语法
 ```css
 /* 标准 lch() 函数 */
 .element {
@@ -443,32 +360,7 @@ body {
 }
 ```
 
-## 十六进制颜色语法详解
-
-### 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度
-
-### 嵌套规则
-
+#### 9. 嵌套规则
 ```css
 /* Sass 风格的嵌套 */
 .container {
@@ -494,8 +386,7 @@ LCH 颜色使用 `lch#`` 前缀，后跟 6 个字符（最后1-3位是十进制
 }
 ```
 
-### 嵌套变量
-
+#### 10. 嵌套变量
 ```css
 /* 变量可以引用其他变量 */
 $base-color: lab(54.7 77.9 80.1);
@@ -510,7 +401,9 @@ $padding-large: math(2rem * 1.5);
 }
 ```
 
-## API 文档
+---
+
+## API文档
 
 ### JavaScript API
 
@@ -532,7 +425,7 @@ styimat.config({
   enableP3: true,
   enableMath: true,
   mathPrecision: 6,
-  indentSize: 2,
+  indentSize: 4,
   enableNesting: true,
   importBaseUrl: '',        // 导入基础URL
   importCache: true,        // 缓存导入文件
@@ -566,8 +459,8 @@ styimat.imports.setTimeout(10000);       // 设置导入超时时间
 | 选项 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
 | `rootSelector` | string | `:root` | CSS 变量定义的根选择器 |
-| `variablePrefix` | string | `--`` | CSS 变量前缀 |
-| `preserveOriginal` | boolean | `false` | 是否保留原始 `<style e>`` 标签 |
+| `variablePrefix` | string | `--` | CSS 变量前缀 |
+| `preserveOriginal` | boolean | `false` | 是否保留原始 `<style e>` 标签 |
 | `indentSize` | number | `4` | 嵌套规则的缩进大小 |
 | `enableNesting` | boolean | `true` | 是否启用嵌套规则 |
 | `autoProcessStyleTags` | boolean | `true` | 是否自动处理页面中的 style 标签 |
@@ -575,16 +468,43 @@ styimat.imports.setTimeout(10000);       // 设置导入超时时间
 | `convertLabToRGB` | boolean | `true` | 是否转换 Lab 颜色为 RGB |
 | `convertLchToRGB` | boolean | `true` | 是否转换 LCH 颜色为 RGB |
 | `enableP3` | boolean | `true` | 是否启用 Display P3 广色域支持 |
-| `enableMath` | boolean | `true` | 是否启用 `math()`` 函数增强 |
+| `enableMath` | boolean | `true` | 是否启用 `math()` 函数增强 |
 | `mathPrecision` | number | `6` | 数学计算的精度 |
-| `importBaseUrl` | string | `` | 导入的基础URL |
+| `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);
@@ -625,7 +545,6 @@ $border-radius: 0.5rem;
 ```
 
 ### 颜色混合示例
-
 ```css
 /* 使用十六进制语法创建调色板 */
 $primary: lab#8CFF80;
@@ -651,7 +570,6 @@ $primary-transparent: lab(55 190 0 / 0.8);
 ```
 
 ### Math() 函数高级示例
-
 ```css
 /* 复杂数学计算 */
 .grid {
@@ -677,6 +595,30 @@ $primary-transparent: lab(55 190 0 / 0.8);
 }
 ```
 
+## 浏览器兼容性
+
+| 特性 | 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)