npm package: @polyv/icons-cli
Description: 本工具是保利威前端团队内部工具，用于生成项目中独有的图标组件。
Latest version: 1.7.0

# PolyvIcon 保利威图标库脚手架

本工具是保利威前端团队内部工具，用于生成项目中独有的图标组件。

## 使用指南

### 第一步：安装

```
npm install @polyv/icons-cli -D

// 如果你的项目是使用 vue2.x，请安装 @polyv/icons-vue
npm install @polyv/icons-vue -S

// 如果你的项目是使用 vue3.x，请安装 @polyv/icons-vue-next
npm install @polyv/icons-vue-next -S

// 如果你的项目是使用 js，请安装 @polyv/icons-svg
npm install @polyv/icons-svg -S
```

### 第二步：配置文件

在项目跟目录下创建脚手架配置文件 `polyv-icon.config.js`，并导出配置：

```js
const { defineConfig } = require('@polyv/icons-cli');

module.exports = defineConfig({
  // svg 文件目录，默认：resources
  resourcesDir: './resources',
  // 输出目录，默认：dist
  outDir: './src/icon-components',
  // 图标库类型，默认：svg，请根据类型安装对应的图标库
  libraryType: 'vue-next',
});
```

项目结构：

```
|- src
|- resources
|    |- close.svg
|    └─ add.svg
|- package.json
└─ polyv-icon.config.js
```

### 第三步：添加 scripts 并执行

在 package.json 的 scripts 中添加命令 `polyv-icon generate`。

```json
{
  "scripts": {
    "generate-icon": "polyv-icon generate"
  }
}
```

执行命令：

```
npm run generate-icon
```

## 配置选项

| 配置名 | 说明 | 类型 | 默认 |
| - | - | - | - |
| resourcesDir | svg 文件目录 | `string` | `'resources'` |
| outDir | 输出目录 | `string` | `'dist'` |
| libraryType | 图标库类型，注意需要安装相应的图标 npm 库 | `'svg' \| 'vue' \| 'vue-next'` | `'svg'` |
| iconComponentDirName | 图标组件目录名称 | `string` | `'icons'` |
| iconComponentExtension | 图标组件的扩展名 | `string` | svg - `.ts`, vue - `.ts`, vue-next - `.tsx` |
| iconMap | 是否创建 map 文件，如果为 `string` 类型，则为文件输出地址，如：`'./dist/map.ts'` | `boolean \| string` | `true` |
| mapExportPrefix | map 文件中导出的图标组件名是否带有前缀 | `string` | - |
| convertColorRelations | 颜色转换关系，详细请见：高级 - 颜色转换关系 | `Partial<ConvertColorRelations>` | {} |
| convertColorMode | 颜色转换模式 | `'relation' \| 'all' \| 'origin'` | `'relation'` |
| categoryJson | 是否创建分类 json 文件，如果为 `string` 类型，则为文件输出地址，如：`./dist/category-icon.json` | `boolean \| string` | `false` |
| categoryMatchs | 图标分类名匹配对象，仅在创建 categoryJson 时使用 | `Record<string, string>` | `{}` |
| demoHtml | 是否创建 demo.html | `boolean \| string` | `false` |
| libraryName | 图标库的名称，用于设置 demoHtml 的页面标题 | `string` | `'PolyvIconLibrary'` |
| endOfLine | 换行符 | `'auto' \| 'lf' \| 'crlf' \| 'cr'` | `'auto'` |

## 高级

### 颜色转换模式

图标模式 convertColorMode 共 2 种：

- `relation`：关系转换模式（默认），根据 `convertColorRelations` 颜色转换关系进行颜色转换，如果你的需要用到填充、双色、四色的图标类型，那么你需要使用 `relation` 的转换模式。
- `all`：全转换模式，设置该模式后，转换脚本会将 **所有颜色** 统一转换成外部描边色（outStrokeColor），注意该模式生成的图标仅支持线性 outline 的图标类型。
- `origin`：保留原始颜色模式，设置该模式后，生成的图标组件会保留图标的所有颜色，此时图标组件的 `color`、`type` 属性将不生效。

如果你的项目中一部分需要多色图标，其余的图标不需要区分颜色，那么建议配置文件使用数组方式：

```js
// polyv-icon.config.js
module.exports = [
  {
    resourcesDir: 'icon-1',
    outDir: 'src/icon-components-1',
    convertColorMode: 'all',
  },
  {
    resourcesDir: 'icon-2',
    outDir: 'src/icon-components-2',
    convertColorRelations: {
      outStrokeColor: ['#999', '#ccc'],
      outFillColor: 'none',
      innerStrokeColor: 'none',
      innerFillColor: 'none',
    },
  },
];
```

### 颜色转换关系

如果设计师提供设计稿图标中有不一样的主题色，那么可以根据主题色的配置去转换图标中的颜色配置，该配置可以设置 `convertColorRelations` 配置项。

脚手架中默认配置了颜色转换关系：

```js
/**
 * 默认的颜色转换关系
 */
const defaultConvertColorRelations: ConvertColorRelations = {
  outStrokeColor: '#333',
  outFillColor: '#2F88FF',
  innerStrokeColor: '#FFF',
  innerFillColor: '#43CCF8',
};
```

例子：设计师提供的图标均为线性图标且颜色为 #999 和 #ccc，那么配置文件可以只配置 `outStrokeColor` 选项：

> 脚手架内部会将颜色配置合并，为了避免意外转换了其他不需要的颜色，建议将其他颜色设置为 none。

```js
const { defineConfig } = require('@polyv/icons-cli');

module.exports = defineConfig({
  convertColorRelations: {
    outStrokeColor: ['#999', '#ccc'],
    outFillColor: 'none',
    innerStrokeColor: 'none',
    innerFillColor: 'none',
  },
});
```

### 配置文件支持数组类型导出

如果你想同时构建出 vue 和 svg 方式的图标组件，那么你可以在 `polyv-icon.config.js` 中导出一个数组：

```js
const { defineConfig } = require('@polyv/icons-cli');

const resourcesDir = './resources';

module.exports = defineConfig([
  {
    resourcesDir,
    outDir: './src/svg-icon-components/',
    libraryType: 'svg',
  },
  {
    resourcesDir,
    outDir: './src/vue-icon-components/',
    libraryType: 'vue',
  },
]);
```

> 注意，这时候你的项目需要同时安装 `@polyv/icons-svg` 和 `@polyv/icons-vue`。

### map 文件添加导出前缀

如果你想让 map 文件导出时添加前缀避免与项目中的组件重名，那么你可以设置 `mapExportPrefix`。

```js
const { defineConfig } = require('@polyv/icons-cli');

const resourcesDir = './resources';

module.exports = defineConfig({
  // ...
  mapExportPrefix: 'Icon',
});
```

这时候脚手架生成的 map 文件将会带有 `Icon` 前缀导出组件：

```js
// 生成后的 map 文件

export { default as IconClose } from './icons/close';
export { default as IconSearch } from './icons/search';
```

### 生成 demo.html

你可以在配置文件中谁在 `demoHtml: true` 来生成图标浏览页面，生成后可双击文件本地查看项目中的图标。

### 生成 json 文件

如果你想生成图标组件的 json 文件，那么你可以传入 `categoryJson: true`，脚手架会根据 svg 文件的上一级文件目录名作为类型。

你也可以传入 `categoryMatchs` 来匹配各类型的中文名。

例如你的 `resources` 文件目录结构：

```
└─ resources
    |- Symbol
    |    └─ search.svg
    └─ Direction
         |- down.svg
         └─ up.svg
```

配置文件：

```js
const { defineConfig } = require('@polyv/icons-cli');

const resourcesDir = './resources';

module.exports = defineConfig({
  // ...
  categoryJson: true,
  categoryMatchs: {
    Symbol: '符号类',
    Direction: '方向类',
  },
});
```

生成的 json 文件

```json
[
  {
    "category": "Symbol",
    "categoryCN": "符号类",
    "icons": [
      {
        "category": "Symbol",
        "name": "搜索",
        "lineName": "search",
        "lowerName": "search",
        "upperName": "Search"
      }
    ]
  },
  {
    "category": "Direction",
    "categoryCN": "方向类",
    "icons": [
      {
        "category": "Direction",
        "name": "下",
        "lineName": "down",
        "lowerName": "down",
        "upperName": "Down"
      },
      {
        "category": "Direction",
        "name": "上",
        "lineName": "up",
        "lowerName": "up",
        "upperName": "Up"
      }
    ]
  }
]
```

## 迁移 iconfont 项目

脚手架提供脚本抓取 iconfont 项目中的 svg 文件到本地，使用方式如下：

### 第一步：通过 Network 下载 detail.json

打开 Iconfont 项目，并开启浏览器控制台 Network，双击打开 detail.json 请求，将打开后到 json 下载到本地。

![获取 detail.json](https://playertest.polyv.net/player2/library/polyv-icon-library/doc-image/icon-library-1.png)

![detail.json](https://playertest.polyv.net/player2/library/polyv-icon-library/doc-image/icon-library-2.png)

### 第二步：项目根目录新建 convert-iconfont 文件夹

在项目根目录中新建 `convert-iconfont` 文件夹，并将 detail.json 放入该文件夹中。

```
|- convert-iconfont
|    └─ detail.json
└─ package.json
```

### 第三步：添加 scripts 并执行

在 package.json 的 scripts 中添加命令 `polyv-icon convert-iconfont`。

```json
{
  "scripts": {
    "convert-iconfont": "polyv-icon convert-iconfont"
  }
}
```

执行命令：

```
npm run convert-iconfont
```

## 更新日志

### `v1.4.0`

- [新增] 新增 `convertColorMode` 模式：`origin` 保留原始颜色模式；

### `v1.3.0`

- [新增] 新增 `endOfLine` 换行符配置；

### `v1.2.0`

- 无其他更改

### `v1.1.0`

- [删除] 删除 `stroke-width` 配置功能；