@sakitam-gis/sprite-cli 1.0.3 → 1.0.4

package/QUICK_START.md

@@ -90,6 +90,24 @@ icons/
 - ✅ SVG（推荐）- 矢量图形，自动优化
 - ✅ PNG - 光栅图像
 
+<a id="svg-class-styles"></a>
+
+#### SVG 图标的 class 样式
+
+设计工具导出的 SVG 可以直接作为输入。例如，下图在雪碧图中显示红色填充和浅色描边。
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16">
+  <style>.st0 { fill: #FF0000; stroke: #F9F7F7; stroke-width: 2 }</style>
+  <path class="st0" d="M2 2h12v12H2z"/>
+</svg>
+```
+
+- CLI 和 Node.js API 在内存中补齐缺少的展示属性。元素上已有的同名属性和内联 `style` 优先。
+- 支持 `.st0`、`.st0, .st1` 以及一个元素带多个 class。匹配的类声明之间先比较 `!important`，再取样式表中靠后的声明。
+- 支持填充、描边、线宽与虚线、透明度、`color`、渐变色标和填充／裁剪规则。可通过 `fill: url(#gradientId)` 引用 SVG 内部渐变，也可写成 `url(#gradientId) hsl(120,100%,50%)` 指定引用失效时的备用色。半透明颜色支持 `rgba()`。
+- 预处理只展开内嵌样式表中顶层的简单类选择器（类名使用 ASCII 字母、数字、下划线或连字符）。后代选择器、复合选择器、伪类、条件规则、外部样式表及 CSS 变量均不在展开范围内。依赖这些写法的图标，建议在导出时把最终颜色写入元素属性。
+
 ### 2. 生成雪碧图
 
 最简单的用法：
@@ -148,9 +166,6 @@ sprite-maker [output] [input] [options]
 | `--retina` | 生成 2x 像素比率（等同于 --ratio=2） | boolean | `false` | `--retina` |
 | `--ratio=<n>` | 指定像素比率 | number | `1` | `--ratio=3` |
 | `--unique` | 去重模式，相同图像只存储一次 | boolean | `false` | `--unique` |
-| `--colors=<n>` | PNG 颜色数量（2-256） | number | `256` | `--colors=128` |
-| `--quality=<n>` | PNG 质量（0-100） | number | `80` | `--quality=90` |
-| `--palette` | 使用调色板模式压缩 PNG | boolean | `false` | `--palette` |
 | `--help, -h` | 显示帮助信息 | - | - | `--help` |
 
 ## 🎨 高级功能
@@ -309,77 +324,20 @@ sprite-maker sprites/ icons/ --retina
 
 ## 🗜️ PNG 优化
 
-本工具使用 **Sharp** 库对生成的 PNG 文件进行高级优化。
-
-### 优化选项
-
-#### 1. 颜色量化
-
-减少颜色数量以降低文件大小：
-
-```bash
-# 使用 128 色调色板（默认 256 色）
-sprite-maker output/sprite icons/ --colors=128
-```
-
-**推荐值：**
-- `256` - 最高质量（默认）
-- `128` - 高质量，文件较小
-- `64` - 中等质量，文件更小
-- `32` - 低质量，最小文件
-
-#### 2. 质量设置
-
-调整 PNG 压缩质量：
-
-```bash
-# 90% 质量（默认 80%）
-sprite-maker output/sprite icons/ --quality=90
-```
-
-**推荐值：**
-- `90-100` - 高质量，文件较大
-- `80-89` - 平衡质量和大小（推荐）
-- `60-79` - 较小文件，质量略降
-- `< 60` - 不推荐
-
-#### 3. 调色板模式
-
-启用调色板模式进一步压缩：
-
-```bash
-sprite-maker output/sprite icons/ --palette
-```
-
-**效果：**
-- ✅ 大幅减小文件大小（通常 30-50%）
-- ⚠️ 可能轻微影响颜色精度
-- ✅ 适用于图标和简单图形
-
-#### 4. 组合使用
+在 Node.js 中调用 `generateOptimizedImage` 可设置调色板、颜色数和质量。传入包含图像数据的布局（`format: false`），将返回的 PNG Buffer 写入文件。
 
-结合多个选项获得最佳效果：
+```js
+import { writeFile } from 'node:fs/promises';
+import {
+  getFilePaths, loadFile, generateLayout, generateOptimizedImage,
+} from '@sakitam-gis/sprite-cli';
 
-```bash
-# 最小文件大小（适用于图标）
-sprite-maker output/sprite icons/ --palette --colors=64 --quality=75
-
-# 高质量压缩（适用于复杂图形）
-sprite-maker output/sprite icons/ --colors=256 --quality=90
-
-# 平衡模式（推荐）
-sprite-maker output/sprite icons/ --palette --colors=128 --quality=80
+const imgs = await Promise.all((await getFilePaths('icons/')).map(loadFile));
+const layout = await generateLayout({ imgs, pixelRatio: 1, format: false });
+const png = await generateOptimizedImage(layout, { palette: true, colors: 128, quality: 80 });
+await writeFile('sprite.png', png);
 ```
 
-### 优化效果对比
-
-| 配置 | 文件大小 | 质量 | 适用场景 |
-|------|----------|------|----------|
-| 默认 | 100% | 优秀 | 通用 |
-| `--palette --colors=128` | ~60% | 良好 | 图标、简单图形 |
-| `--palette --colors=64` | ~40% | 中等 | 图标（不追求完美） |
-| `--quality=90` | ~110% | 极佳 | 需要高保真的场景 |
-
 ## 💡 实际应用场景
 
 ### 场景 1: Web 应用图标
@@ -450,7 +408,7 @@ sprite-maker map-styles/sprite@2x map-icons/ --retina
 
 ```bash
 # 生成游戏角色精灵表（PNG 输入）
-sprite-maker game/sprites/characters characters/*.png --unique --palette
+sprite-maker game/sprites/characters characters/ --unique
 ```
 
 ### 场景 4: 移动应用资源
@@ -471,8 +429,8 @@ sprite-maker mobile/assets/icons@3x icons/ --ratio=3
   "scripts": {
     "prebuild": "npm run build:sprites",
     "build:sprites": "npm run sprites:1x && npm run sprites:2x",
-    "sprites:1x": "sprite-maker public/sprites/icon assets/icons/ --palette --unique",
-    "sprites:2x": "sprite-maker public/sprites/icon@2x assets/icons/ --retina --palette --unique",
+    "sprites:1x": "sprite-maker public/sprites/icon assets/icons/ --unique",
+    "sprites:2x": "sprite-maker public/sprites/icon@2x assets/icons/ --retina --unique",
     "watch:sprites": "chokidar 'assets/icons/**/*.svg' -c 'npm run build:sprites'"
   }
 }
@@ -482,11 +440,7 @@ sprite-maker mobile/assets/icons@3x icons/ --ratio=3
 
 ### Q1: 生成的 PNG 文件太大，如何优化？
 
-**A:** 使用优化选项：
-
-```bash
-sprite-maker output/sprite icons/ --palette --colors=128 --quality=80
-```
+使用 Node.js API 调整调色板颜色数和质量，示例见 [PNG 优化](#-png-优化)。
 
 ### Q2: 支持哪些图像格式？
 
@@ -503,8 +457,8 @@ sprite-maker output/sprite icons/ --palette --colors=128 --quality=80
 - 可处理 500+ 图标
 
 ```bash
-# 大批量图标建议使用 unique 模式和优化
-sprite-maker output/sprite icons/ --unique --palette --colors=128
+# 大批量图标建议使用 unique 模式
+sprite-maker output/sprite icons/ --unique
 ```
 
 ### Q4: unique 模式什么时候使用？

package/README.md

@@ -15,6 +15,7 @@
 
 ### 🎨 图像支持
 - ✅ **SVG 支持** - 原生支持矢量图形，自动优化
+- ✅ **SVG 类样式** - 自动读取内嵌 `<style>` 中的简单类规则，保留图标的填充和描边颜色。[支持范围与示例](./QUICK_START.md#svg-class-styles)
 - ✅ **PNG 支持** - 支持光栅图像输入
 - ✅ **多种像素比率** - 支持 1x、2x、3x 等 Retina 显示屏
 - ✅ **智能去重** - unique 模式，自动识别相同图像
@@ -114,16 +115,6 @@ sprite-maker output/sprite@3x icons/ --ratio=3    # 3x
 sprite-maker output/sprite icons/ --unique
 ```
 
-#### 5️⃣ PNG 优化选项
-
-```bash
-# 调色板模式（减小文件大小）
-sprite-maker output/sprite icons/ --palette --colors=128
-
-# 自定义质量
-sprite-maker output/sprite icons/ --quality=90
-```
-
 ## 📖 详细文档
 
 查看 [快速开始指南](./QUICK_START.md) 获取更多详细示例和高级用法。
@@ -135,9 +126,6 @@ sprite-maker output/sprite icons/ --quality=90
 | `--retina` | 生成 2x 像素比率（等同于 --ratio=2） | `false` |
 | `--ratio=<n>` | 指定像素比率（1x, 2x, 3x 等） | `1` |
 | `--unique` | 去重模式，相同图像只存储一次 | `false` |
-| `--colors=<n>` | PNG 颜色数量（2-256） | `256` |
-| `--quality=<n>` | PNG 质量（0-100） | `80` |
-| `--palette` | 使用调色板模式压缩 PNG | `false` |
 | `--help, -h` | 显示帮助信息 | - |
 
 ## 🛠️ 开发

package/dist/cli.js

@@ -110,7 +110,7 @@ var ShelfPack = class {
    * ```
    */
   pack(bins, options = {}) {
-    const binArray = [].concat(bins);
+    const binArray = Array.isArray(bins) ? bins : [bins];
     const results = [];
     for (let i = 0; i < binArray.length; i++) {
       const w = binArray[i].w || binArray[i].width;
@@ -416,8 +416,8 @@ async function extractMetadata(svg, pixelRatio = 1) {
         }
       ]
     });
-    const { DOMParser: DOMParser2 } = await import("@xmldom/xmldom");
-    const doc = new DOMParser2().parseFromString(optimized.data, "image/svg+xml");
+    const { DOMParser: DOMParser3 } = await import("@xmldom/xmldom");
+    const doc = new DOMParser3().parseFromString(optimized.data, "image/svg+xml");
     const metadata = {};
     const paths = doc.getElementsByTagName("path");
     for (let i = 0; i < paths.length; i++) {
@@ -454,7 +454,7 @@ async function extractMetadata(svg, pixelRatio = 1) {
           metadata.placeholder = [left, top, right, bottom];
         }
       } catch (err) {
-        console.warn(`Failed to compute bounds for ${id}: ${err}`);
+        console.warn(`Failed to compute bounds for ${id}: ${String(err)}`);
       }
     }
     if (metadata.stretchX) {
@@ -465,7 +465,7 @@ async function extractMetadata(svg, pixelRatio = 1) {
     }
     return metadata;
   } catch (err) {
-    console.error(`Failed to extract metadata: ${err}`);
+    console.error(`Failed to extract metadata: ${String(err)}`);
     return {};
   }
 }
@@ -483,7 +483,9 @@ function heightAndIdComparator(a, b) {
   return a.id.localeCompare(b.id);
 }
 function packImages(images) {
-  const sorted = [...images].sort(heightAndIdComparator);
+  const sorted = [...images].sort(
+    heightAndIdComparator
+  );
   const sprite = new ShelfPack(1, 1, { autoResize: true });
   sprite.pack(sorted, { inPlace: true });
   const packed = sorted.map((img) => ({
@@ -571,7 +573,7 @@ async function getImageDimensions(img, pixelRatio, useCache = true) {
         height: Math.ceil(height * pixelRatio)
       };
     } catch (err) {
-      throw new Error(`Failed to process SVG ${img.id}: ${err}`);
+      throw new Error(`Failed to process SVG ${img.id}: ${String(err)}`);
     }
   }
   return {
@@ -611,7 +613,7 @@ async function generateLayout(options) {
           const metadata = await extractMetadata(originalImg.svg, pixelRatio);
           Object.assign(layout[item.id], metadata);
         } catch (err) {
-          console.warn(`Failed to extract metadata for ${item.id}: ${err}`);
+          console.warn(`Failed to extract metadata for ${item.id}: ${String(err)}`);
         }
       }
     } else {
@@ -685,51 +687,145 @@ async function generateLayoutUnique(options) {
 import sharp from "sharp";
 import { createCanvas, loadImage as loadImage2 } from "@napi-rs/canvas";
 
+// src/core/svg-styles.ts
+import { DOMParser as DOMParser2, XMLSerializer } from "@xmldom/xmldom";
+import postcss from "postcss";
+var PRESENTATION = /* @__PURE__ */ new Set([
+  "fill",
+  "fill-opacity",
+  "fill-rule",
+  "stroke",
+  "stroke-width",
+  "stroke-opacity",
+  "stroke-linecap",
+  "stroke-linejoin",
+  "stroke-miterlimit",
+  "stroke-dasharray",
+  "stroke-dashoffset",
+  "opacity",
+  "color",
+  "stop-color",
+  "stop-opacity",
+  "clip-rule"
+]);
+function parseCss(css) {
+  try {
+    return postcss.parse(css);
+  } catch (error) {
+    if (error instanceof postcss.CssSyntaxError) return void 0;
+    throw error;
+  }
+}
+function select(target, prop, next) {
+  const prev = target.get(prop);
+  if (!prev || (next.important !== prev.important ? next.important : next.order >= prev.order)) {
+    target.set(prop, next);
+  }
+}
+function collectRules(doc) {
+  const byClass = /* @__PURE__ */ new Map();
+  let order = 0;
+  for (const style of Array.from(doc.getElementsByTagNameNS("*", "style"))) {
+    if (style.namespaceURI !== doc.documentElement.namespaceURI) continue;
+    const type = style.getAttribute("type")?.trim().toLowerCase();
+    const media = style.getAttribute("media")?.trim().toLowerCase();
+    if (type && type !== "text/css" || media && media !== "all") continue;
+    for (const rule of parseCss(style.textContent || "")?.nodes ?? []) {
+      if (rule.type !== "rule") continue;
+      const properties = /* @__PURE__ */ new Map();
+      for (const decl of rule.nodes) {
+        if (decl.type !== "decl") continue;
+        const prop = decl.prop.toLowerCase();
+        if (PRESENTATION.has(prop)) {
+          select(properties, prop, {
+            value: decl.value,
+            important: !!decl.important,
+            order: order++
+          });
+        }
+      }
+      for (const selector of new Set(rule.selectors)) {
+        if (!/^\.[\w-]+$/.test(selector)) continue;
+        const name = selector.slice(1);
+        const declarations = byClass.get(name) ?? /* @__PURE__ */ new Map();
+        for (const [prop, value] of properties) select(declarations, prop, value);
+        byClass.set(name, declarations);
+      }
+    }
+  }
+  return byClass;
+}
+function simplifyImportant(style) {
+  const winners = /* @__PURE__ */ new Map();
+  for (const decl of style.nodes) {
+    if (decl.type === "decl" && decl.important && PRESENTATION.has(decl.prop.toLowerCase())) {
+      winners.set(decl.prop.toLowerCase(), decl);
+    }
+  }
+  if (!winners.size) return false;
+  style.walkDecls((decl) => {
+    const winner = winners.get(decl.prop.toLowerCase());
+    if (winner === decl) decl.important = false;
+    else if (winner) decl.remove();
+  });
+  return true;
+}
+function inlineSvgClassStyles(svg) {
+  if (!/<(?:[^\s<>:]+:)?style[\s>]/.test(svg) && !/!\s*important/i.test(svg)) return svg;
+  const doc = new DOMParser2().parseFromString(svg, "image/svg+xml");
+  const byClass = collectRules(doc);
+  let changed = false;
+  for (const element of Array.from(doc.getElementsByTagName("*"))) {
+    if (element.namespaceURI !== doc.documentElement.namespaceURI) continue;
+    const properties = /* @__PURE__ */ new Map();
+    for (const name of new Set((element.getAttribute("class") || "").split(/\s+/))) {
+      for (const [prop, value] of byClass.get(name) ?? []) select(properties, prop, value);
+    }
+    const inline = element.getAttribute("style");
+    if (inline && (properties.size || inline.includes("!"))) {
+      const style = parseCss(inline);
+      if (!style) continue;
+      style.walkDecls((decl) => {
+        properties.delete(decl.prop.toLowerCase());
+      });
+      if (simplifyImportant(style)) {
+        element.setAttribute("style", style.toString());
+        changed = true;
+      }
+    }
+    for (const [prop, { value }] of properties) {
+      if (!element.hasAttribute(prop)) {
+        element.setAttribute(prop, value);
+        changed = true;
+      }
+    }
+  }
+  return changed ? new XMLSerializer().serializeToString(doc) : svg;
+}
+
 // src/core/colors.ts
 import { colord, extend } from "colord";
 import namesPlugin from "colord/plugins/names";
 extend([namesPlugin]);
-var COLOR_FUNC_RE = /(?:#[0-9a-fA-F]{3,8}|(?:hsl|rgb)a?\([^)]*\))/g;
-var COLOR_ATTR_RE = /\b(?:fill|stroke|stop-color|flood-color|color|lighting-color)\s*=\s*"([^"]*)"/gi;
-var STYLE_COLOR_PROP_RE = /(?:fill|stroke|stop-color|flood-color|color|lighting-color|background-color)\s*:\s*([^;"}{]+)/gi;
-function toHex(value) {
-  const c = colord(value);
-  if (!c.isValid()) return null;
-  const hex = c.toHex();
-  const rgba = c.toRgb();
-  return rgba.a === 1 ? hex.slice(0, 7) : hex;
+var COLOR_ATTR_RE = /\b(?:fill|stroke|stop-color|flood-color|color|lighting-color)\s*=\s*(["'])(.*?)\1/gi;
+var STYLE_COLOR_PROP_RE = /(?:fill|stroke|stop-color|flood-color|color|lighting-color|background-color)\s*:\s*([^;"'}{]+)/gi;
+function normalizePaint(value) {
+  const trimmed = value.trim();
+  const url = /^url\((?:"[^"]*"|'[^']*'|[^)]*)\)\s*/i.exec(trimmed)?.[0] ?? "";
+  const color = colord(trimmed.slice(url.length));
+  if (!color.isValid()) return value;
+  const normalized = color.toRgb().a === 1 ? color.toHex() : color.toRgbString();
+  return url + normalized;
 }
 function normalizeSvgColors(svgString) {
-  const lower = svgString.toLowerCase();
-  if (!lower.includes("hsl") && !lower.includes("rgb") && !lower.includes("color")) {
-    return svgString;
-  }
-  let result = svgString;
-  result = result.replace(COLOR_ATTR_RE, (fullMatch, attrValue) => {
-    const replaced = attrValue.replace(
-      COLOR_FUNC_RE,
-      (funcMatch) => toHex(funcMatch) || funcMatch
-    );
-    return fullMatch.replace(attrValue, replaced);
-  });
-  result = result.replace(STYLE_COLOR_PROP_RE, (fullMatch, colorValue) => {
-    const trimmed = colorValue.trim();
-    const hex = toHex(trimmed);
-    if (hex) {
-      return fullMatch.replace(colorValue, ` ${hex}`);
-    }
-    return fullMatch;
-  });
-  result = result.replace(COLOR_ATTR_RE, (fullMatch, attrValue) => {
-    const trimmed = attrValue.trim();
-    if (!trimmed || trimmed.startsWith("url(")) return fullMatch;
-    const hex = toHex(trimmed);
-    if (hex && hex !== trimmed.toLowerCase()) {
-      return fullMatch.replace(attrValue, hex);
-    }
-    return fullMatch;
-  });
-  return result;
+  if (!/(?:hsl|rgb|color|#[\da-f]{4}\b|#[\da-f]{8}\b)/i.test(svgString)) return svgString;
+  return svgString.replace(
+    STYLE_COLOR_PROP_RE,
+    (full, value) => full.replace(value, () => normalizePaint(value))
+  ).replace(
+    COLOR_ATTR_RE,
+    (full, quote, value) => full.replace(quote + value + quote, () => quote + normalizePaint(value) + quote)
+  );
 }
 
 // src/core/image.ts
@@ -739,7 +835,7 @@ async function renderImage(imageBuffer, isPNG, ctx, x, y, width, height) {
     if (isPNG) {
       src = imageBuffer;
     } else {
-      const svgString = normalizeSvgColors(imageBuffer.toString("utf8"));
+      const svgString = normalizeSvgColors(inlineSvgClassStyles(imageBuffer.toString("utf8")));
       const svgDataUrl = `data:image/svg+xml;base64,${Buffer.from(svgString).toString("base64")}`;
       src = svgDataUrl;
     }
@@ -776,7 +872,10 @@ async function generateImage(layout) {
   const ctx = canvas.getContext("2d");
   ctx.clearRect(0, 0, width, height);
   const renderPromises = [];
+  const rendered = /* @__PURE__ */ new Set();
   for (const [id, item] of Object.entries(layout)) {
+    if (rendered.has(item)) continue;
+    rendered.add(item);
     const svg = item.svg;
     const png = item.png;
     if (!svg && !png) {