iconfontify

v1.4.4

Published

5 months ago

Best practices for generating Fonts from svg using webfont

Downloads

0High
0Medium
0Low

cx19940809

svg clip-path clean svgo icons iconfont

SVG to Icon Font Generator

一个专业的SVG图标转字体工具，支持自动清理、优化SVG文件并生成高质量的字体文件。

📋 目录

✨ 特性

🔧 智能SVG清理：自动移除背景、优化路径、保持图标比例
🎨 高质量字体生成：支持TTF格式，保持图标清晰度
📱 完整的Unicode映射：自动生成映射文件，支持多种使用方式
🎯 防变形优化：专门优化的SVGO配置，防止图标变形
🔄 自定义Unicode映射：支持通过JSON文件自定义图标的Unicode值
🚀 一键构建：Shell脚本自动化整个构建流程
📂 灵活的目录配置：支持自定义输入输出目录
🌐 HTML预览：可选生成交互式预览页面

📦 安装

环境要求

Node.js >= 14.0.0
npm 或 yarn

NPM包使用（推荐）

npx iconfontify

本地项目安装

npm install iconfontify --save-dev

全局安装

npm install -g iconfontify

安装后可以全局使用 iconfontify 命令。

🚀 快速开始

准备SVG文件

将您的SVG图标文件放入 icon/ 目录：

icon/
├── home.svg
├── user.svg
├── search.svg
└── ...

运行构建

# 使用NPM包（推荐）
npx iconfontify
   
# Windows用户使用Node.js版本
npx iconfontify --node
   
# 本地项目使用
./bin/build-icons.sh

查看输出

构建完成后，在 build/iconfont/ 目录下查看生成的文件：

build/iconfont/
├── icons.ttf          # 字体文件
├── icon-mapping.json  # Unicode映射
└── preview.html       # 预览页面（如果使用 -h 参数）

🛠 使用方法

基本用法

# NPM包使用（推荐）
npx iconfontify

# 生成HTML预览
npx iconfontify -h

# 自定义输入输出目录
npx iconfontify -i svg-icons -o dist/fonts

# Windows用户使用Node.js版本
npx iconfontify --node -h

# 本地项目直接使用
./bin/build-icons.sh -i custom-icons -o output -h

分步执行

您也可以单独运行各个步骤：

# 1. 清理SVG文件
node clean-icons.js

# 2. 生成字体文件
node generate-font.js

📋 命令行选项

| 选项 | 说明 | 默认值 | |------|------|--------| | -i <目录> | 指定输入目录 | icon | | -o <目录> | 指定输出目录 | build/iconfont | | -n <名称> | 指定字体名称 | iconfont | | --iconmap <文件> | 指定图标映射JSON文件路径 | 使用-o目录下的icon-mapping.json | | -h | 生成HTML+CSS预览文件 | 关闭 | | --node | 强制使用Node.js版本（Windows推荐） | 自动检测 | | --help | 显示帮助信息 | - | | --version | 显示版本信息 | - |

使用示例

# 基本构建
npx iconfontify

# 指定自定义目录
npx iconfontify -i svg-files -o fonts

# 指定字体名称
npx iconfontify -n myicons

# 使用自定义图标映射文件
npx iconfontify --iconmap icons.json

# 生成预览页面
npx iconfontify -h

# Windows用户推荐方式
npx iconfontify --node -i assets/icons -o dist/iconfont -h

# 完整自定义示例
npx iconfontify -i svg-icons -o dist/fonts -n myicons --iconmap icon-mapping.json -h

# 本地项目构建
./bin/build-icons.sh -i assets/icons -o dist/iconfont -h

📁 项目结构

svg2iconfont/
├── bin/
│   └── build-icons.sh       # 主构建脚本
├── icon/                    # SVG图标目录
│   ├── home.svg
│   ├── user.svg
│   └── ...
├── build/                   # 构建输出目录
│   └── iconfont/
│       ├── icons.ttf
│       ├── icon-mapping.json
│       └── preview.html
├── clean-icons.js           # SVG清理脚本
├── generate-font.js         # 字体生成脚本
├── package.json
└── README.md

⚙️ 配置说明

SVG清理配置

clean-icons.js 中的 SVGO 配置已优化，防止图标变形：

const svgoConfig = {
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeViewBox: false,        // 保持视图框
          convertShapeToPath: false,   // 禁用形状转路径
          collapseGroups: false,       // 禁用组合并
          mergePaths: false,           // 禁用路径合并
          convertTransform: false,     // 禁用变换转换
          cleanupNumericValues: {
            floatPrecision: 3          // 提高精度
          }
        }
      }
    }
    // ... 其他插件
  ]
};

字体生成配置

generate-font.js 中的字体生成参数：

const result = await webfont({
  files: 'icon/*.svg',
  fontName: 'icons',
  formats: ['ttf'],
  fontHeight: 1024,              // 标准字体高度
  descent: 200,                  // 基线对齐
  normalize: true,               // 标准化图标尺寸
  round: 10e12,                  // 高精度舍入
  centerHorizontally: true,      // 水平居中
  fixedWidth: false,             // 保持图标比例
  startUnicode: 0xE001,          // 起始Unicode码点
  // ... 其他配置
});

📤 输出文件

icons.ttf

字体文件，包含所有图标的字形定义。

icon-mapping.json

Unicode映射文件，格式如下：

{
  "home": {
    "unicode": 57345,
    "hex": "\\E001",
    "codePoint": "U+E001"
  },
  "user": {
    "unicode": 57346,
    "hex": "\\E002", 
    "codePoint": "U+E002"
  }
}

preview.html（使用 -h 参数时生成）

交互式预览页面，包含：

所有图标的可视化展示
点击复制CSS类名功能
Unicode信息显示
使用指南

💻 使用示例

HTML中使用

<!DOCTYPE html>
<html>
<head>
  <style>
    @font-face {
      font-family: 'iconfont';
      src: url('icons.ttf') format('truetype');
    }
    
    .icon {
      font-family: 'iconfont';
      font-style: normal;
    }
  </style>
</head>
<body>
  <!-- 直接使用Unicode -->
  <span class="icon">&#xE001;</span>
  
  <!-- 通过CSS类（需要额外CSS定义） -->
  <i class="icon-home"></i>
</body>
</html>

CSS定义

@font-face {
  font-family: 'iconfont';
  src: url('icons.ttf') format('truetype');
  font-weight: normal;
  font-style: normal;
}

[class^="icon-"], [class*=" icon-"] {
  font-family: 'iconfont' !important;
  speak: never;
  font-style: normal;
  font-weight: normal;
  line-height: 1;
  -webkit-font-smoothing: antialiased;
}

.icon-home:before { content: "\E001"; }
.icon-user:before { content: "\E002"; }
/* ... 更多图标 */

JavaScript中使用

// 加载映射文件
fetch('icon-mapping.json')
  .then(response => response.json())
  .then(mapping => {
    // 获取图标的Unicode值
    const homeIcon = String.fromCharCode(mapping.home.unicode);
    console.log(homeIcon); // 显示图标字符
  });

🔄 自定义Unicode映射

图标映射文件格式

您可以通过 --iconmap 参数指定一个JSON文件来自定义图标的Unicode值：

{
  "home": {
    "unicode": "\\E001"
  },
  "user": {
    "unicode": "\\E002"
  },
  "settings": {
    "unicode": "\\E003"
  }
}

使用自定义映射

# 使用自定义图标映射文件
npx iconfontify --iconmap my-icons.json

# 结合其他参数使用
npx iconfontify -i svg-icons -o dist/fonts --iconmap icon-mapping.json -h

映射规则

文件名匹配：SVG文件名必须与JSON中的key完全一致（不包含.svg扩展名）
Unicode格式：支持字符串格式的Unicode值，如 "\\E001"
默认行为：如果图标在映射文件中找不到，将使用自动分配的Unicode值
优先级：自定义映射的Unicode值会覆盖自动分配的值

应用场景

保持Unicode一致性：在更新图标库时保持现有代码的兼容性
特定Unicode分配：为特定图标分配特定的Unicode码点
版本控制：确保不同版本的图标字体使用相同的Unicode值

🔧 故障排除

常见问题

Q: npx iconfontify 报错"系统找不到指定的路径" A: 这是Windows环境下的bash路径问题，请使用 npx iconfontify --node

Q: 图标显示为方块或乱码 A: 检查字体文件是否正确加载，确认@font-face路径正确。

Q: 图标变形或比例异常 A: SVG文件可能包含复杂的变换或嵌套结构，请检查原始SVG文件。

Q: 构建失败 A: 确保Node.js版本 >= 14，依赖已正确安装。

Q: 找不到SVG文件 A: 检查输入目录是否存在且包含.svg文件。

Q: Windows用户bash环境问题 A: 推荐使用 --node 参数，或安装Git for Windows获得bash环境。

Q: 自定义Unicode映射不生效 A: 检查SVG文件名是否与JSON中的key完全一致，确保JSON格式正确。

Q: 图标映射文件读取失败 A: 检查文件路径是否正确，确保JSON文件格式有效。

调试方法

检查Node.js环境
```
node --version
npm --version
```
验证依赖安装
```
npm list webfont svgo
```

手动执行步骤

node clean-icons.js
node generate-font.js

查看详细输出
```
DEBUG=* ./bin/build-icons.sh
```

🔨 开发说明

修改SVG清理规则

编辑 clean-icons.js 中的 svgoConfig 对象：

const svgoConfig = {
  plugins: [
    // 添加或修改插件配置
    {
      name: 'your-plugin',
      params: {
        // 插件参数
      }
    }
  ]
};

自定义字体生成参数

编辑 generate-font.js 中的 webfont 配置：

const result = await webfont({
  // 修改配置参数
  fontHeight: 2048,    // 改变字体高度
  formats: ['ttf', 'woff2'],  // 添加更多格式
  // ... 其他参数
});

扩展输出格式

可以修改 generate-font.js 以支持更多输出格式：

WOFF/WOFF2: 网页字体格式
EOT: IE兼容格式
SVG: SVG字体格式

添加CSS生成

可以在 generate-font.js 中添加CSS文件生成逻辑：

// 生成CSS规则
const cssRules = Object.entries(iconMapping).map(([name, data]) => 
  `.icon-${name}:before { content: "${data.hex}"; }`
);

const cssContent = `
@font-face {
  font-family: 'iconfont';
  src: url('icons.ttf') format('truetype');
}

${cssRules.join('\n')}
`;

fs.writeFileSync(path.join(outputDir, 'icons.css'), cssContent);

📄 许可证

ISC License

🤝 贡献

欢迎提交Issue和Pull Request！

版本: 1.0.0