@sakitam-gis/sprite-cli 1.0.0

package/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 sakitam-fdd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/QUICK_START.md

@@ -0,0 +1,582 @@
+# 快速开始指南
+
+本文档将指导您快速上手 `@sakitam-gis/sprite-cli` - 一个现代化的雪碧图生成工具。
+
+## 📋 目录
+
+- [安装](#-安装)
+- [基本使用](#-基本使用)
+- [命令行选项](#-命令行选项)
+- [高级功能](#-高级功能)
+- [元数据支持](#-元数据支持)
+- [PNG 优化](#-png-优化)
+- [实际应用场景](#-实际应用场景)
+- [常见问题](#-常见问题)
+
+## 🎯 前置要求
+
+- Node.js >= 18.0.0
+- npm、pnpm 或 yarn 包管理器
+
+推荐使用 **pnpm** 以获得更好的性能和磁盘空间利用率。
+
+## 📦 安装
+
+### 方式 1: 全局安装（推荐）
+
+适用于命令行直接使用：
+
+```bash
+# npm
+npm install -g @sakitam-gis/sprite-cli
+
+# pnpm（推荐）
+pnpm add -g @sakitam-gis/sprite-cli
+
+# yarn
+yarn global add @sakitam-gis/sprite-cli
+```
+
+### 方式 2: 项目本地安装
+
+适用于在项目构建流程中使用：
+
+```bash
+# npm
+npm install --save-dev @sakitam-gis/sprite-cli
+
+# pnpm
+pnpm add -D @sakitam-gis/sprite-cli
+
+# yarn
+yarn add -D @sakitam-gis/sprite-cli
+```
+
+然后在 `package.json` 中添加脚本：
+
+```json
+{
+  "scripts": {
+    "build:sprites": "sprite-maker output/sprite icons/",
+    "build:sprites:retina": "sprite-maker output/sprite@2x icons/ --retina"
+  }
+}
+```
+
+### 方式 3: 使用 npx（无需安装）
+
+适用于临时使用或测试：
+
+```bash
+npx @sakitam-gis/sprite-cli output/sprite icons/
+```
+
+## 🚀 基本使用
+
+### 1. 准备图标文件
+
+创建一个目录，放入您的 SVG 或 PNG 图标文件：
+
+```
+icons/
+  ├── home.svg
+  ├── user.svg
+  ├── settings.svg
+  ├── logo.png
+  └── ...
+```
+
+**支持的文件格式：**
+- ✅ SVG（推荐）- 矢量图形，自动优化
+- ✅ PNG - 光栅图像
+
+### 2. 生成雪碧图
+
+最简单的用法：
+
+```bash
+sprite-maker output/sprite icons/
+```
+
+这将生成两个文件：
+- **`output/sprite.png`** - 合成的雪碧图图片
+- **`output/sprite.json`** - 布局和元数据信息
+
+### 3. 查看输出
+
+**sprite.json 示例：**
+
+```json
+{
+  "home": {
+    "width": 24,
+    "height": 24,
+    "x": 0,
+    "y": 0,
+    "pixelRatio": 1
+  },
+  "user": {
+    "width": 24,
+    "height": 24,
+    "x": 24,
+    "y": 0,
+    "pixelRatio": 1
+  }
+}
+```
+
+## 🔧 命令行选项
+
+### 完整语法
+
+```bash
+sprite-maker [output] [input] [options]
+```
+
+### 参数说明
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `output` | 输出文件路径（不含扩展名）或目录 | `sprites/icon` 或 `sprites/` |
+| `input` | 输入图标目录 | `icons/` |
+| `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` |
+
+## 🎨 高级功能
+
+### 1. Retina 显示屏支持
+
+为高 DPI 显示屏生成多种分辨率：
+
+```bash
+# 1x (标准)
+sprite-maker output/sprite icons/
+
+# 2x (Retina)
+sprite-maker output/sprite@2x icons/ --retina
+
+# 3x (超高清)
+sprite-maker output/sprite@3x icons/ --ratio=3
+```
+
+生成文件：
+```
+output/
+  ├── sprite.png      (1x)
+  ├── sprite.json
+  ├── sprite@2x.png   (2x)
+  ├── sprite@2x.json
+  ├── sprite@3x.png   (3x)
+  └── sprite@3x.json
+```
+
+**在 Web 应用中使用多分辨率雪碧图：**
+
+```css
+/* 标准屏幕 */
+.icon {
+  background-image: url('sprite.png');
+}
+
+/* Retina 屏幕 */
+@media (-webkit-min-device-pixel-ratio: 2),
+       (min-resolution: 192dpi) {
+  .icon {
+    background-image: url('sprite@2x.png');
+    background-size: 50%;  /* 重要：缩放到原始尺寸 */
+  }
+}
+```
+
+### 2. Unique 模式（去重）
+
+当多个图标指向相同的图像时，使用 unique 模式可以减小文件大小：
+
+```bash
+sprite-maker output/sprite icons/ --unique
+```
+
+**示例场景：**
+```
+icons/
+  ├── icon-a.svg   (内容相同)
+  ├── icon-b.svg   (内容相同)
+  └── icon-c.svg   (内容不同)
+```
+
+在 unique 模式下：
+- `icon-a` 和 `icon-b` 将指向同一个图像位置
+- 雪碧图文件更小
+- JSON 中仍包含所有图标的布局信息
+
+### 3. 自动目录创建
+
+输出目录不存在时会自动创建：
+
+```bash
+# 即使 output/sprites/ 不存在也会自动创建
+sprite-maker output/sprites/icon icons/
+```
+
+### 4. 默认文件名
+
+如果只指定目录作为输出路径，会自动生成默认文件名：
+
+```bash
+# 输出：sprites/sprite.png 和 sprites/sprite.json
+sprite-maker sprites/ icons/
+
+# 输出：sprites/sprite@2x.png 和 sprites/sprite@2x.json
+sprite-maker sprites/ icons/ --retina
+```
+
+## 📋 元数据支持
+
+本工具支持提取和处理 **Mapbox 9-patch 风格的元数据**，用于可拉伸图像和内容区域定义。
+
+### 在 SVG 中定义元数据
+
+使用特殊的 `id` 属性来标记元数据区域：
+
+```xml
+<svg width="24" height="24" xmlns="http://www.w3.org/2000/svg">
+  <!-- 主图标内容 -->
+  <rect width="24" height="24" fill="#333"/>
+  
+  <!-- 水平拉伸区域 (9-patch) -->
+  <path id="mapbox-stretch-x" d="M 8 0 L 16 0 L 16 24 L 8 24 Z" fill="none"/>
+  
+  <!-- 垂直拉伸区域 (9-patch) -->
+  <path id="mapbox-stretch-y" d="M 0 8 L 24 8 L 24 16 L 0 16 Z" fill="none"/>
+  
+  <!-- 内容区域 -->
+  <path id="mapbox-content" d="M 4 4 L 20 4 L 20 20 L 4 20 Z" fill="none"/>
+  
+  <!-- 文本占位符区域 -->
+  <path id="mapbox-text-placeholder" d="M 6 6 L 18 6 L 18 18 L 6 18 Z" fill="none"/>
+</svg>
+```
+
+### 元数据类型说明
+
+| ID 前缀 | 类型 | 说明 | 输出格式 |
+|---------|------|------|----------|
+| `mapbox-stretch-x` | 水平拉伸 | 定义水平方向可拉伸区域 | `[[x1, x2], ...]` |
+| `mapbox-stretch-y` | 垂直拉伸 | 定义垂直方向可拉伸区域 | `[[y1, y2], ...]` |
+| `mapbox-stretch` | 双向拉伸 | 同时定义水平和垂直拉伸 | 同时输出 X 和 Y |
+| `mapbox-content` | 内容区域 | 定义可放置内容的区域 | `[left, top, right, bottom]` |
+| `mapbox-text-placeholder` | 文本占位符 | 定义文本占位符区域 | `[left, top, right, bottom]` |
+
+### 输出的元数据格式
+
+生成的 JSON 文件将包含元数据：
+
+```json
+{
+  "button": {
+    "width": 24,
+    "height": 24,
+    "x": 0,
+    "y": 0,
+    "pixelRatio": 1,
+    "metadata": {
+      "stretchX": [[8, 16]],
+      "stretchY": [[8, 16]],
+      "content": [4, 4, 20, 20],
+      "placeholder": [6, 6, 18, 18]
+    }
+  }
+}
+```
+
+### 元数据的应用场景
+
+1. **可拉伸按钮** - 定义边框和中间可拉伸区域
+2. **9-patch 图像** - Android 风格的可缩放图像
+3. **弹性面板** - 可自适应内容的 UI 组件
+4. **文本框背景** - 带有文本占位符的输入框
+
+## 🗜️ 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. 组合使用
+
+结合多个选项获得最佳效果：
+
+```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
+```
+
+### 优化效果对比
+
+| 配置 | 文件大小 | 质量 | 适用场景 |
+|------|----------|------|----------|
+| 默认 | 100% | 优秀 | 通用 |
+| `--palette --colors=128` | ~60% | 良好 | 图标、简单图形 |
+| `--palette --colors=64` | ~40% | 中等 | 图标（不追求完美） |
+| `--quality=90` | ~110% | 极佳 | 需要高保真的场景 |
+
+## 💡 实际应用场景
+
+### 场景 1: Web 应用图标
+
+```bash
+# 生成多分辨率图标
+sprite-maker dist/icons/sprite icons/ --unique
+sprite-maker dist/icons/sprite@2x icons/ --retina --unique
+sprite-maker dist/icons/sprite@3x icons/ --ratio=3 --unique
+```
+
+**使用方式：**
+
+```html
+<!-- HTML -->
+<div class="icon icon-home"></div>
+```
+
+```css
+/* CSS */
+.icon {
+  display: inline-block;
+  background-image: url('/icons/sprite.png');
+  background-repeat: no-repeat;
+}
+
+@media (-webkit-min-device-pixel-ratio: 2) {
+  .icon {
+    background-image: url('/icons/sprite@2x.png');
+    background-size: 50%;
+  }
+}
+
+.icon-home {
+  width: 24px;
+  height: 24px;
+  background-position: 0px 0px;
+}
+```
+
+### 场景 2: Mapbox/MapLibre 地图样式
+
+```bash
+# 生成地图图标雪碧图
+sprite-maker map-styles/sprite map-icons/
+sprite-maker map-styles/sprite@2x map-icons/ --retina
+```
+
+**在地图样式中使用：**
+
+```json
+{
+  "sprite": "https://example.com/map-styles/sprite",
+  "layers": [
+    {
+      "id": "poi-labels",
+      "type": "symbol",
+      "layout": {
+        "icon-image": "marker",
+        "icon-size": 1
+      }
+    }
+  ]
+}
+```
+
+### 场景 3: 游戏精灵表
+
+```bash
+# 生成游戏角色精灵表（PNG 输入）
+sprite-maker game/sprites/characters characters/*.png --unique --palette
+```
+
+### 场景 4: 移动应用资源
+
+```bash
+# iOS 和 Android 多分辨率资源
+sprite-maker mobile/assets/icons@1x icons/ 
+sprite-maker mobile/assets/icons@2x icons/ --ratio=2
+sprite-maker mobile/assets/icons@3x icons/ --ratio=3
+```
+
+### 场景 5: 构建流程集成
+
+**package.json:**
+
+```json
+{
+  "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",
+    "watch:sprites": "chokidar 'assets/icons/**/*.svg' -c 'npm run build:sprites'"
+  }
+}
+```
+
+## ❓ 常见问题
+
+### Q1: 生成的 PNG 文件太大，如何优化？
+
+**A:** 使用优化选项：
+
+```bash
+sprite-maker output/sprite icons/ --palette --colors=128 --quality=80
+```
+
+### Q2: 支持哪些图像格式？
+
+**A:** 
+- ✅ SVG（推荐）- 矢量图形，自动优化
+- ✅ PNG - 光栅图像
+- ❌ JPEG、GIF、WebP - 不支持
+
+### Q3: 如何处理大量图标？
+
+**A:** 工具已针对性能优化：
+- 自动并发处理
+- SVG 缓存机制
+- 可处理 500+ 图标
+
+```bash
+# 大批量图标建议使用 unique 模式和优化
+sprite-maker output/sprite icons/ --unique --palette --colors=128
+```
+
+### Q4: unique 模式什么时候使用？
+
+**A:** 在以下情况使用：
+- 多个图标共享相同图像
+- 需要减小文件大小
+- 图标库有别名（如 `home` 和 `house` 指向同一图标）
+
+### Q5: 元数据没有被提取？
+
+**A:** 检查：
+1. SVG 中的 `id` 属性是否以 `mapbox-` 开头
+2. 路径（`<path>`）元素是否有有效的 `d` 属性
+3. 查看生成的 JSON 文件中的 `metadata` 字段
+
+### Q6: 如何在 CI/CD 中使用？
+
+**A:** 添加到构建脚本：
+
+```yaml
+# GitHub Actions 示例
+- name: Install sprite-cli
+  run: npm install -g @sakitam-gis/sprite-cli
+
+- name: Generate sprites
+  run: |
+    sprite-maker dist/sprite assets/icons/
+    sprite-maker dist/sprite@2x assets/icons/ --retina
+```
+
+### Q7: 输出目录不存在会报错吗？
+
+**A:** 不会，工具会自动创建输出目录。
+
+### Q8: 可以只生成 JSON 不生成 PNG 吗？
+
+**A:** 目前不支持，JSON 和 PNG 总是一起生成。
+
+### Q9: 支持自定义布局算法吗？
+
+**A:** 目前使用固定的 Shelf Best Height Fit 算法，空间利用率达 80-95%，无需自定义。
+
+### Q10: 如何调试生成错误？
+
+**A:** 
+1. 检查输入文件格式是否正确
+2. 确保 SVG 文件有明确的 `width` 和 `height` 或 `viewBox`
+3. 查看控制台输出的警告信息
+
+## 📚 相关资源
+
+- [README.md](./README.md) - 项目主文档
+- [CHANGELOG.md](./CHANGELOG.md) - 版本更新历史
+- [GitHub Issues](https://github.com/sakitam-gis/sprite-cli/issues) - 问题反馈
+- [NPM Package](https://www.npmjs.com/package/@sakitam-gis/sprite-cli) - NPM 主页
+
+## 🆘 获取帮助
+
+如果您遇到问题或有建议：
+
+1. 查看本文档的 [常见问题](#-常见问题) 部分
+2. 查看 [GitHub Issues](https://github.com/sakitam-gis/sprite-cli/issues) 中是否有类似问题
+3. 提交新的 [Issue](https://github.com/sakitam-gis/sprite-cli/issues/new)
+
+## 🎉 开始使用
+
+现在您已经了解了所有功能，开始生成您的第一个雪碧图吧！
+
+```bash
+# 快速开始
+sprite-maker output/sprite icons/
+```
+
+Happy sprite making! 🚀