Cody Icons

用于将 SVG 图标打包生成 codyicon.*（字体文件、CSS、预览页、SVG sprite 等）的内部图标库。

安装

在业务项目中安装：

npm i @aini_ai_cody/icons

项目结构

cody_icon/
├── src/
│   ├── icons/           # 基础图标（单色，会被打包成字体）
│   ├── cody_icons/      # Cody 专属图标（彩色 SVG，cody- 开头）
│   ├── svg_icons/       # 其他 SVG 图标素材（不参与构建）
│   └── template/
│       ├── mapping.json       # 基础图标的 codepoint 映射
│       ├── cody_mapping.json  # Cody 图标的 codepoint 映射
│       ├── metadata.json      # 基础图标元数据
│       ├── cody.json          # Cody 图标元数据
│       ├── styles.hbs         # CSS 模板
│       └── preview.hbs        # 预览页模板
├── dist/                # 构建产物
└── icon_test/           # 测试目录（不提交到仓库）

本地构建

安装依赖：

npm install

构建：

npm run build

构建流程：

1. clean - 清理 dist 目录
2. svgo - 优化 src/icons/ 下的 SVG
3. fonts - 使用 fantasticon 生成字体文件
4. merge-cody - 合并 cody_mapping.json 到 mapping.json
5. cody-sprite - 生成 cody 图标的 SVG sprite
6. export-to-ts - 导出 TypeScript 类型
7. export-to-csv - 导出 CSV
8. embed-metadata - 嵌入元数据
9. sprite - 生成完整的 SVG sprite
10. cody-colored - 处理彩色 cody 图标

添加图标

添加基础图标（单色字体图标）

1. 将 SVG 文件放入 src/icons/ 目录（文件名与图标名一致，如 my-icon.svg）

2. 在 src/template/mapping.json 中添加 codepoint 映射：

{
  "60543": ["my-icon", "my-icon-alias"]
}

注意：codepoint 必须是唯一的数字，建议从现有最大值递增

3. 在 src/template/metadata.json 中添加元数据（推荐）：

{
  "my-icon": {
    "tags": ["custom", "example"],
    "category": "action",
    "description": "My custom icon"
  }
}

4. 执行 npm run build

添加 Cody 专属图标（彩色 SVG）

Cody 开头的图标统一放在 src/cody_icons/ 目录，文件名必须以 cody- 开头。

1. 将 SVG 文件放入 src/cody_icons/ 目录，例如：cody-my-feature.svg

2. 在 src/template/cody.json 中添加元数据（推荐）：

{
  "cody-my-feature": {
    "tags": ["feature", "custom"],
    "category": "cody",
    "description": "My feature icon",
    "render": "svg"
  }
}

3. 执行 npm run build

注意：Cody 彩色图标不需要在 cody_mapping.json 中添加记录！构建脚本会自动扫描 src/cody_icons/ 目录下的所有 SVG 文件。cody_mapping.json 仅用于需要打包成字体的图标。

图标规范

• 基础图标：单色 SVG，16x16 或 24x24，路径使用 currentColor
• Cody 图标：可以是彩色 SVG，支持多种颜色，文件名必须以 cody- 开头

使用方式

使用 CSS 类名（基础图标）

<i class="codyicon codyicon-add"></i>

使用 CSS 类名（Cody 彩色图标）

<!-- 彩色模式（保留原始颜色） -->
<i class="codyicon cody-new"></i>

<!-- 单色模式（跟随 CSS color） -->
<i class="codyicon cody-mono cody-new" style="color: red;"></i>

使用 SVG Sprite

<!-- 基础图标 -->
<svg>
  <use xlink:href="codyicon.svg#add" />
</svg>

<!-- Cody 图标 -->
<svg>
  <use xlink:href="cody-icons.svg#cody-new" />
</svg>

构建产物

• dist/codyicon.ttf - 字体文件
• dist/codyicon.css - CSS 样式（包含字体图标和 cody 彩色图标）
• dist/codyicon.svg - 基础图标 SVG sprite
• dist/cody-icons.svg - Cody 图标 SVG sprite
• dist/cody_icons/ - Cody 彩色图标 SVG 文件
• dist/mapping.json - 完整的 codepoint 映射
• dist/metadata.json - 完整的元数据
• dist/codyicon.html - 图标预览页
• dist/codyiconsLibrary.ts - TypeScript 类型定义
• dist/codyicon.csv - CSV 格式导出

版本管理

# 补丁版本
npm run version:patch

# 次版本
npm run version:minor

# 主版本
npm run version:major

# 提交并打标签
npm run version:tag

# 提交、打标签并推送
npm run version:push