node-create-sprite

一个基于 Node.js 生成雪碧图的工具，用于从指定文件夹中的图片（PNG、JPG、SVG）生成雪碧图（Sprite）、对应的 CSS 样式文件和 Mapbox GL 兼容的 JSON 配置文件。

特性

• 🎯 支持自定义输入目录、输出目录和文件名
• 📷 支持 PNG 和 JPG 图片格式
• 🎨 支持 SVG 文件转换为精灵图
• 📋 自动生成 CSS 样式文件，包含每个图片的定位信息
• 🗺️ 生成 Mapbox GL 兼容的 JSON 配置文件
• 🧹 可选择清空输出目录
• 💻 提供命令行工具，方便集成到开发流程中
• 👁️‍🗨️ 生成雪碧图预览页面，方便查看生成效果

注意事项

⚠️ 重要提示：当前版本的SVG转精灵图功能存在以下特点和限制：

跨平台兼容性处理

• 自动适配操作系统：工具会根据操作系统自动选择不同的SVG处理方式：
  • 在Windows系统上：默认使用不依赖mapnik的SVG处理方式，以避免mapnik库在Windows上的安装和兼容性问题
  • 在非Windows系统（如Linux、macOS）上：使用传统的依赖mapnik的SVG处理方式

功能限制

• 不支持含有内嵌图像（embedded image）的SVG文件。如果SVG文件中使用了<image>标签引用外部或内嵌的PNG/JPG图像，这些图像可能无法正确显示在生成的精灵图中。
• TODO：未来版本将改进SVG处理逻辑，解决内嵌图像支持问题。

安装

前提条件

• Node.js: 版本 16 或更高
• 包管理器: npm、yarn 或 pnpm

全局安装（推荐）

npm install -g node-create-sprite
# 或
pnpm add -g node-create-sprite

使用方法

作为命令行工具使用

全局安装后使用:

create-sprite -i <输入图片目录> -n <输出文件名> -o <输出目录> -c <是否清空输出目录>

本地使用:

# 先链接到全局
pnpm link --global

# 然后使用命令
create-sprite -i <输入图片目录> -n <输出文件名> -o <输出目录> -c <是否清空输出目录>

命令行参数

| 参数 | 简写 | 描述 | 必填 | 默认值 | |------|------|------|------|--------| | --input | -i | 输入图片所在的目录路径，默认支持 png、jpg、svg | 是 | - | | --name | -n | 输出文件名称 | 是 | sprite | | --output | -o | 输出目录，支持相对路径。如果不指定，默认使用输入目录 | 否 | 输入目录 | | --clean | -c | 是否清空输出目录，0 (不清空) 或 1 (清空) | 否 | 0 | | --format | -f | 图片源格式，可选值：png/jpg/svg | 否 | png | | --version | -v | 查看当前版本 | 否 | - | | --help | -h | 查看帮助信息 | 否 | - |

示例

基本使用

# 使用默认参数，输入目录为当前目录下的images，输出到同目录，文件名为sprite
create-sprite -i ./images -n sprite

# 自定义输出目录和是否清空
create-sprite -i ./icons -o ./dist -n my-sprite -c 1

# 生成SVG图标精灵图
create-sprite -i ./images -n svg-sprite -f svg

# 查看帮助信息
create-sprite --help

输出文件

执行后，工具会在指定的输出目录中生成以下文件：

1. [filename].png: 合并后的雪碧图
2. [filename].css: 对应的 CSS 样式文件，包含每个图片的选择器和定位信息
3. [filename].json: Mapbox GL 兼容的 JSON 配置文件

CSS 文件示例

.image1 {
  width: 32px;
  height: 32px;
  background-image: url('sprite.png');
  background-position: -0px -0px;
}

.image2 {
  width: 32px;
  height: 32px;
  background-image: url('sprite.png');
  background-position: -32px -0px;
}

平台兼容性说明

• Windows: 仅支持PNG/JPG格式的雪碧图生成
• macOS/Linux: 支持所有格式，包括PNG/JPG/SVG

注意事项

1. Node.js 版本要求: 必须使用 Node.js 16 或更高版本
2. 输入目录: 确保输入目录存在并且包含有效的图片文件
3. 输出目录: 如果输出目录不存在，工具会自动创建
4. 清空输出目录: 当输入目录和输出目录相同时，即使设置了 --clean 1，工具也不会清空输出目录，以避免误删除原始图片
5. 图片格式: PNG/JPG 格式功能可以直接使用

License

ISC