图标变更

约 1872 字大约 6 分钟

2024-09-30

图标语法糖在 1.0.0-rc.144 版本中进行了破坏性变更。

:[collect:name size/color]: 语法糖已弃用，请使用 ::collect:name =size /color:: 代替。

主题计划在未来的版本中，支持如 iconfont / fontawesome / lucide 等图标库的图标，原有语法糖不足以支持新的扩展，因此此破坏性变更是必要的。

旧的语法在近期的版本中依然支持，但不再推荐使用，且在未来会删除。

主题会检测是否使用旧的语法，如果使用，会在控制台输出警告信息和修改建议，请根据修改建议进行调整。

概述

主题支持在 Markdown 文件中以下来源的图标：

iconify - 默认支持
iconfont - 可选
fontawesome - 可选

主题提供图标 markdown 语法支持，使用简单灵活的方式在 Markdown 中插入图标。

主题还提供了 <Icon /> 组件支持，点击了解更多

语法

图标语法为行内语法，可以在段落中与其他 markdown 语法混合使用。

基础语法，使用 :: 包裹图标名称：

::name::

设置图标大小和颜色：(注意空格不可缺少)

::name =size::
::name /color::
::name =size /color::

=size：设置图标大小
- =16：图标的宽高为 16px
- =24x16：图标的宽为 24px，高为 16px
- =x16：图标的高为 16px，宽为自适应
- =1.2em：图标的宽高为 1.2em
- =1.2emx1.5em：图标的宽为 1.2em，高为 1.5em
/color：设置图标颜色，支持 hex/ rgb / rgba / hsl / hsla 等合法颜色色值
- /#fff ：图标的颜色为 #fff
- /rgb(255,0,0)：图标的颜色为 rgb(255,0,0)

Iconify

iconify 提供了 200K + 的开源图标支持，足以满足大多数项目的需求。主题将 iconify 作为默认的图标来源支持。

在 Markdown 中使用 ::collect:name 语法来插入图标。

配置

.vuepress/config.ts
import { defineUserConfig
 } from 'vuepress'
import { plumeTheme
 } from 'vuepress-theme-plume'

export default defineUserConfig
({
  theme
: plumeTheme
({
    markdown
: { 
      icon
: { provider
: 'iconify' } // 默认支持
    }
  })
})

interface IconOptions {
  provider: 'iconify'
  prefix?: string
}

使用

从 iconify search 搜索想要使用的图标，复制图标名称：
在 Markdown 中使用 ::collect:name 语法来插入图标
```
::carbon:home::
```
输出：

在 Iconify 中，图标被分为不同的 collect，每个 collect 下有若干个图标。在 ::collect:name 语法中，使用 : 来分隔 collect 和 name。

如果你主要使用某个 collect 下的图标，可以在配置中指定 prefix, 以便在 ::collect:name 语法中省略 collect 前缀：

.vuepress/config.ts
import { defineUserConfig
 } from 'vuepress'
import { plumeTheme
 } from 'vuepress-theme-plume'

export default defineUserConfig
({
  theme
: plumeTheme
({
    markdown
: {
      icon
: {
        provider
: 'iconify',
        prefix
: 'carbon', // 默认使用 `collect` 图标集合
      }
    }
  })
})

::home::    <!-- 默认使用 `carbon` 图标集，自动补全为 `carbon:home` -->
::solar:user-bold::  <!-- 显式的使用其他图标集 -->

输出：

安装

对于企业内部项目，或无法访问外部网络资源的情况下，主题推荐安装 @iconify/json 依赖。

主题自动解析 @iconify/json 中的图标数据，将已使用的图标打包为本地资源。

pnpm

pnpm add @iconify/json

yarn

yarn add @iconify/json

npm

npm install @iconify/json

示例

输入：

github: ::tdesign:logo-github-filled::
修改颜色：::tdesign:logo-github-filled /#f00::
修改大小：::tdesign:logo-github-filled =36px::
修改大小颜色：::tdesign:logo-github-filled =36px /#f00::

彩色图标 ::skill-icons:vscode-dark =36px::

输出：

github: 修改颜色：修改大小：修改大小颜色：

彩色图标

Iconfont

iconfont 是提供了海量的图标支持。

配置

.vuepress/config.ts
import { defineUserConfig
 } from 'vuepress'
import { plumeTheme
 } from 'vuepress-theme-plume'

export default defineUserConfig
({
  theme
: plumeTheme
({
    markdown
: { 
      icon
: {
        provider
: 'iconfont',
        assets
: 'https://at.alicdn.com/t/c/xxxx.css' // 示例地址
      }
    }
  })
})

interface IconOptions {
  provider: 'iconfont'
  /**
   * 图标前缀
   * @default 'iconfont icon-'
   */
  prefix?: string

  /**
   * iconfont 资源地址
   */
  assets: string | string[]
}

使用

前往 iconfont 帮助中心 了解 创建项目和 添加图标

从 iconfont 获取项目的资源地址，复制并粘贴到 assets 配置中：

.vuepress/config.ts
export default defineUserConfig({
  theme: plumeTheme({
    markdown: {
      icon: {
        provider: 'iconfont',
        assets: 'https://at.alicdn.com/t/c/xxxx.css' // 示例地址
      }
    }
  })
})

也可以选择下载至本地，将资源存放到 .vuepress/public 目录中，然后在 assets 配置中填写本地文件路径。

检查 iconfont 的项目配置，获取 prefix 配置：
其中 prefix 配置由 font family 和 font class 前缀组成，如果 iconfont 的项目配置为默认配置，则 prefix 为 iconfont icon-，此时你可以忽略此步骤。
.vuepress/config.ts
```
export default defineUserConfig({
  theme: plumeTheme({
    markdown: {
      icon: {
        provider: 'iconfont',
        prefix: 'iconfont icon-', // 默认值
      }
    }
  })
})
```
在 Markdown 中使用 ::name:: 语法来插入图标：
将图片中的 font class 填入 ::name:: 语法中：
```
::hot::
::hot =24px::
::hot =24px /#f00::
```
输出:

Fontawesome

Fontawesome 提供了免费和付费的图标支持，付费图标需要进行订阅。

查看 Fontawesome 官方文档

配置

.vuepress/config.ts
import { defineUserConfig
 } from 'vuepress'
import { plumeTheme
 } from 'vuepress-theme-plume'

export default defineUserConfig
({
  theme
: plumeTheme
({
    markdown
: { 
      icon
: {
        provider
: 'fontawesome',
        assets
: 'fontawesome' // 预设资源地址，从 CDN 加载
      }
    }
  })
})

interface IconOptions {
  provider: 'fontawesome'
  /**
   * 图标前缀
   * @default 'fas'
   */
  prefix?: FontAwesomePrefix
  /**
   * iconfont 资源地址
   */
  assets: (FontAwesomeAssetBuiltin | string)[]
}

type FontAwesomeAssetBuiltin = 'fontawesome' | 'fontawesome-with-brands'

type FontAwesomePrefix =
  | 'fas' | 's' // fa-solid fa-name
  | 'far' | 'r' // fa-regular fa-name
  | 'fal' | 'l' // fa-light fa-name
  | 'fat' | 't' // fa-thin fa-name
  | 'fads' | 'ds' // fa-duotone fa-solid fa-name
  | 'fass' | 'ss' // fa-sharp fa-solid fa-name
  | 'fasr' | 'sr' // fa-sharp fa-regular fa-name
  | 'fasl' | 'sl' // fa-sharp fa-light fa-name
  | 'fast' | 'st' // fa-sharp fa-thin fa-name
  | 'fasds' | 'sds' // fa-sharp-duotone fa-solid fa-name
  | 'fab' | 'b' // fa-brands fa-name

在 Fontawesome 中，图标通过 families + styles 控制样式，查看详情

为便于管理，可以通过 ::prefix:name:: 语法，通过前缀设置 families + styles，默认前缀为 fas，可以省略它：

::name:: <!-- prefix = fas -->
::fas:name:: <!-- prefix = fas -->
::s:name:: <!-- prefix = fas ， s 为 fas 的缩写 -->

可以通过配置 markdown.icon.prefix 修改默认前缀。

提示

Fontawesome 的免费图标仅支持 solid 、部分 regular 以及 brands，对于免费版本，前缀仅支持 fas / far / fab 和它们的缩写前缀。

使用

前往 https://fontawesome.com/search?ic=free 搜索免费图标

复制图标名称：

在 Markdown 中使用 ::prefix:name:: 语法插入图标:

::circle-user:: <!-- prefix = fas -->
::fas:circle-user:: <!-- prefix = fas -->
::s:circle-user:: <!-- prefix = fas， s 为 fas 的缩写 -->

示例

::circle-user::
::circle-user =24px::
::circle-user =24px /#f00::

输出:

为 Fontawesome 添加更多样式支持

::circle-user 2xl::  <!-- 2xl 为 fa-2xl 的缩写, 图标大小为 2em -->
::circle-user rotate-90:: <!-- 图标旋转 90 度 -->
::circle-user beat:: <!-- 图标动画 -->
::circle-user border:: <!-- 图标边框 -->
::circle-user 2xl beat:: <!-- 混合多种样式 -->

输出:

其它说明

当 markdown.icon.provider 设置为非 iconify 时，iconify 作为默认支持，依然可以在 markdown 中插入 iconify 图标：

在 ::collect:name:: 语法中，在开始位置添加 iconify：

::iconify carbon:home::

输出:

贡献者

pengzhanbo

更新日志

2025/5/16 13:37

查看所有更新日志

dcecb-docs: update docs于 2025/5/16
14973-feat: add multiple provider support for icon, close #568 (#596)于 2025/5/16
a023c-feat(theme)!: deprecate old icon syntax and use ::icon:: syntax instead (#563)于 2025/4/25
0fd6c-refactor(theme): improve types and flat config (#524)于 2025/3/15
b721b-feat(plugin-md-power): add support npm-to container (#256)于 2024/10/8
c177f-docs: improve docs (#240)于 2024/9/30

markdown

代码块

代码演示

图表

资源嵌入

图标变更

概述

语法

Iconify

配置

使用

安装

示例

Iconfont

配置

使用

Fontawesome

配置

使用

示例

其它说明

贡献者

更新日志

图标 变更

图标变更