xicon-cli

A command-line interface for managing icons. 管理图标组件的命令行工具。 可同时拉取 iconfont/figma 图标到本地，生成组件。

注：1.x 版本改为 esm 的方式，后续功能变更也将仅在 1.x 以上的版本实现，请尽快进行版本的升级。 1.x 新增功能点：

• 新增图标类型 multiple 多色图标，通过 css 变量实现多色图标配置及变色
• 新增输出格式 min
• 新增两种输入类型，svg 目录、json 文件
• 支持 figma 文档链接中的 node-id 参数，可配置只读取一个页面内的图标数据
• 默认模板加入可访问性相关的参数：role / aria-label / focusable / aria-hidden 等

特性

• 🎊 支持固定色、单色可配置、多色可配置等图标类型
• ⚙️ 配置灵活，同一项目内可配多个不同配置，根据需求灵活使用
• 🎉 可单独拉取 iconfont 或 figma 的图标，也可两者同时拉取
• 🎯 多种输出类型可选，且可任意配置
• 🌈 可自定义组件格式化方式
• 🚀 可设置过滤函数，过滤不需要的图标
• 📚 提供前后图标数据差异对比，方便跟踪变化
• 🤖 提供图标集成组件模板、预览页模板

安装依赖

npm install -D xicon-cli
yarn add -D xicon-cli

使用

初始化配置文件

xicon init

在当前目录生成 xicon.config.ts 配置文件。具体配置详见下方配置参数说明
参考：配置文件模板 注：配置参数可传入对象或者数组。

拉取图标

# configFile: 可传入配置文件，不传则默认取当前根目录下的xicon.config.ts 配置文件
xicon build [configFile]

使用图标

• 输出的 type 为 component 时

<template>
  <div>
    <IconArrowLeft style="font-size: 50px; color: red" />
    <icon-more style="font-size: 50px; color: red" />

    <!-- format=bg|img时 -->
    <IconArrowLeft size="50px" color="#2254f4" />
  </div>
</template>

<script lang="ts">
import { IconArrowLeft, IconMore } from "@/icons";

export default {
  components: {
    IconArrowLeft,
    IconMore,
  },
};
</script>

• 输出的 type 为 symbol 时

// 入口文件main.js
import { createApp } from "vue";
import App from "./App.vue";
import "./svg-icon/svg-icon"; // 输出的svg-icon.js文件
import SvgIcon from "./svg-icon/svg-icon.vue"; // 输出的svg-icon.vue文件

const app = createApp(App);
app.component(SvgIcon.name, SvgIcon); // 全局注册图标组件
app.mount("#app");

<template>
  <div>
    <svg-icon name="success-static" style="font-size: 50px; color: #2254f4" />
    <svg-icon name="error-fill" :style="{ fontSize: 50, color: '#2254f4' }" />
    <svg-icon name="edit" :style="{ fontSize: 50, color: '#2254f4' }" />
    <svg-icon name="add" :style="{ fontSize: 50, color: '#2254f4' }" />
  </div>
</template>

• 多色图标

<template>
  <div>
    <IconAddCircleMultiple class="demo-icon" />
  </div>
</template>

<script lang="ts">
import { IconAddCircleMultiple } from "@/icons";

export default {
  components: {
    IconAddCircleMultiple,
  },
};
</script>

<style>
.demo-icon {
  --primary-color: #2254f4;
  --abc-color: red;
  --abc2-color: green;
}

.demo-icon:hover {
  --primary-color: #000;
  --abc-color: #2254f4;
  --abc2-color: pink;
}
</style>

创建模板文件

如需要<Icon name=""/>这种集成所有图标组件的使用方式，可创建相应模板，进行自定义； 工具内同时提供了图标预览页模板。

根据模板，创建文件。执行后可选： icon 集成所有图标的 Icon 组件模板 preview 图标预览页模板 both 同时创建两种模板文件

# outputDir: 输出文件目录，不传则默认取当前根目录
xicon template [outputDir]

配置参数说明

| 参数名 | 描述 | 是否必填 | 类型 | 默认值 | | ------ | -------- | -------- | ------------------------------------------------------- | ------ | | input | 输入配置 | 是 | InputOption | InputOption[] | 无 | | output | 输出配置 | 是 | OutputOption |OutputOption[] | 无 |

输入配置 InputOption

支持 figma 与 iconfont 输入，同时支持本地 svg 目录或者 json 文件输入。 类型：FigmaInputOption | IconfontInputOption| SvgInputOption | JsonInputOption

通用参数

| 参数名 | 描述 | 是否必填 | 类型 | | -------------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------- | | type | 源数据类型 | 是 | 'figma' | 'iconfont' | 'svg' | 'json' | | prefix | 图标名前缀，用来避免不同数据源有同名的图标 | 否 | string | | filter | 过滤函数 | 否 | (icon: Icon, index: number, array: Array<Icon>) => boolean; | | formatIconName | 自定义修改图标名称 | 否 | (name: string) => string; | | formatIconType | 自定义图标类型，static 固定色、configurable 可变色、multiple 多色 | 否 | (name: string) => 'configurable' | 'static' | 'multiple'; |

FigmaInputOption

| 参数名 | 描述 | 是否必填 | 类型 | | ------- | ------------------------------------- | -------- | -------- | | url | figma 文档链接 | 是 | string | | token | figma api 需要的 token | 是 | string | | modules | 自定义选择 figma 模块内的图标进行输出 | 否 | string[] |

IconfontInputOption

| 参数名 | 描述 | 是否必填 | 类型 | | ------ | ---------------- | -------- | ------ | | url | iconfont js 链接 | 是 | string |

SvgInputOption

| 参数名 | 描述 | 是否必填 | 类型 | | ------ | ------------------- | -------- | ------ | | dir | 输入的 svg 文件目录 | 是 | string |

JsonInputOption

| 参数名 | 描述 | 是否必填 | 类型 | | ------ | ------------------------------------------------------ | -------- | ------ | | file | 输入的 json 文件的路径，内容格式同 json 输出的内容格式 | 是 | string |

输出配置 OutputOption

支持多种输出类型： CommonOutputOption | JsonOutputOption | SymbolOutputOption | ComponentOutputOption

| type 值 | 描述 | 类型 | | ----------- | --------------------------------------------------------------------- | --------------------- | | diff | 输出前后图标数据差异对比 | CommonOutputOption | | svg | 输出所有图标 svg 文件 | CommonOutputOption | | json | 集合所有图标数据的 json 文件，如需输出 diff 文件，json 文件也必须输出 | JsonOutputOption | | component | 输出图标组件 | ComponentOutputOption | | symbol | 输出类似 iconfont symbol 方式的文件 | SymbolOutputOption |

通用参数 CommonOutputOption

| 参数名 | 描述 | 是否必填 | 类型 | 默认值 | | ------ | -------- | -------- | ---------------------------------------------------- | ------ | | type | 输出类型 | 是 | 'diff' | 'svg' | 'json' | 'component' | 'symbol' | '' | | dir | 输出目录 | 否 | string | 'src' |

JsonOutputOption

| 参数名 | 描述 | 是否必填 | 类型 | 默认值 | | -------- | ---------------------- | -------- | ------ | ------------ | | filename | 输出 json 文件的文件名 | 否 | string | 'icons.json' |

SymbolOutputOption

| 参数名 | 描述 | 是否必填 | 类型 | 默认值 | | ------------- | -------------------------------------------------------- | -------- | ------------------------ | -------- | | className | 图标组件上的 class 名，如 arrow -> 'xicon xicon-arrow' | 否 | string | 'xicon' | | style | 自定义组件的 style | 否 | string | '' | | cssVars | css 变量配置 | 否 | Record<string, string> | | | hideCustomVar | 隐藏自定义 css 变量 | 否 | boolean | false |

ComponentOutputOption

| 参数名 | 描述 | 是否必填 | 类型 | 默认值 | | ------------------ | -------------------------------------------------------- | -------- | -------------------------------------------------------------------------- | ------------ | | format | 选择预置的格式化方式, 可传入值或者对应的配置 | 否 | string | FormatOption | 'vue' | | dirname | 输出图标组件存放目录名 | 否 | string | 'components' | | filename | 输出图标组件的入口文件名 | 否 | string | 'index.js' | | prefix | 生成图标组件的前缀，如 arrow -> IconArrow | 否 | string | 'icon' | | className | 图标组件上的 class 名，如 arrow -> 'xicon xicon-arrow' | 否 | string | 'xicon' | | style | 自定义组件的 style | 否 | string | '' | | cssVars | css 变量配置 | 否 | Record<string, string> | | | hideCustomVar | 隐藏自定义 css 变量 | 否 | boolean | false | | formatSvg | 自定义格式化 svg 的函数 | 否 | (options: SvgFormatOption) => string | 无 | | formatStyle | 自定义格式化组件样式的函数 | 否 | (options: StyleFormatOption) => string | 无 | | formatComponent | 自定义格式化组件的函数 | 否 | (options: ComponentFormatOption) => string | 无 | | formatExportString | 自定义格式化导出组件的字符串 | 否 | (options: ExportStringFormatOption) => string | 无 |

format 参数说明

| 值 | 框架 | 标签 | 描述 | 常用场景 | | ----- | ---- | ------------------ | ----------------------------------------------------------- | --------------------------------------------------------- | | vue | vue | svg | 正常的 svg 标签组件 | | | min | vue | svg | 正常的 svg 标签组件, css 改为 js 动态插入、保证只有一份 | | | img | vue | img | 图标转化为 base64 输出到 img 标签的 src 参数中 | | | bg | vue | 自定义，默认'span' | 图标转化为 base64 输出到标签 style 中的 background-image 中 | 微信小程序下不支持 svg 标签，可使用 text 标签输出图标组件 |

注：微信小程序使用bg的方式，因转化 base64 时使用到了 btoa 函数，但小程序环境下并没有该函数，故此需在全局提前注入 btoa 函数，此处提供一个 btoa 函数供参考：btoa

• 通用参数 BaseFormatOption

| 参数名 | 描述 | 是否必填 | 类型 | 默认值 | | ------ | -------------------- | -------- | ---------- | ------ | | type | 选择预置的格式化方式 | 是 | FormatType | 'vue' |

• VueFormatOption type=vue | min

| 参数名 | 描述 | 是否必填 | 类型 | 默认值 | | ------- | -------------- | -------- | ------ | -------------------------------------- | | svgAttr | svg 标签的额外属性 | 否 | string | 'v-on="$listeners"' | | tag | 外层标签 | 否 | string | '' |

• BgFormatOption type=bg

| 参数名 | 描述 | 是否必填 | 类型 | 默认值 | | ------------ | ------------------ | -------- | ---------------- | ------ | | defaultColor | 图标组件默认颜色值 | 否 | string | '' | | defaultSize | 图标组件默认大小 | 否 | string | number | 20 | | tag | 外层标签 | 否 | string | 'span' |

自定义函数的参数

通用参数 FormatFnOption

| 参数名 | 描述 | 类型 | | ------ | -------------------------------- | ------ | | name | 图标的名称 | string | | origin | 默认输出值，可基于此微调输出内容 | string |

SvgFormatOption

| 参数名 | 描述 | 类型 | | ------------- | ------------------- | ---------------------------------- | | content | 图标 svg 的字符串 | string | | className | 输出图标组件的类名 | string | | type | 图标的类型 | string<"configurable" | "static" | "multiple"> | | tag | 外层标签 | string | | cssVars | css 变量配置 | string | | hideCustomVar | 隐藏自定义 css 变量 | boolean |

StyleFormatOption

| 参数名 | 描述 | 类型 | | --------- | ------------------ | ------ | | className | 输出图标组件的类名 | string | | style | 自定义图标组件样式 | string |

ComponentFormatOption

| 参数名 | 描述 | 类型 | | ------------- | ---------------------------------- | ---------------- | | svgContent | formatSvg 返回的 svg 字符串 | string | | componentName | 输出成图标组件的组件名 | string | | className | 输出图标组件的类名 | string | | tag | format=bg 时生效，自定义组件的标签 | string | | defaultColor | 图标组件默认颜色值 | string | | defaultSize | 图标组件默认大小 | string | number | | style | 自定义图标组件样式 | string |

ExportStringFormatOption

| 参数名 | 描述 | 类型 | | ------------- | -------------------- | ------ | | componentName | 图标组件的组件名 | string | | iconDirName | 图标组件输出的目录名 | string |