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，并导出配置：

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。

{
  "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 属性将不生效。

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

// 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 配置项。

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

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

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

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

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 中导出一个数组：

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。

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

const resourcesDir = './resources';

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

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

// 生成后的 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

配置文件：

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

const resourcesDir = './resources';

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

生成的 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 下载到本地。

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

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

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

第三步：添加 scripts 并执行

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

{
  "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 配置功能；