使用方法 - Iconify官网中文站

什么是 Iconify

Iconify 是一个通用的图标管理框架，它允许开发者从超过 100 个图标集中使用超过 200,000 个图标，而无需为每个图标集单独安装库。其核心思想是“按需加载”——只加载你实际使用的图标，而不是整个图标字体文件。Iconify 支持 SVG 格式，兼容所有现代前端框架和原生 HTML 页面，并且完全开源。

安装与基础配置

使用 Iconify 的第一步是安装核心库。在项目中通过 npm 或 yarn 安装 @iconify/iconify 包：

npm install @iconify/iconify

安装完成后，在入口文件中导入框架：

import 'iconify-icon';

对于无构建工具的传统 HTML 页面，可以直接通过 CDN 引入：

<script src="https://code.iconify.design/iconify-icon/1.0.7/iconify-icon.min.js"></script>

引入后，页面中即可使用自定义元素 <iconify-icon> 来渲染图标。

在网页中使用图标

Iconify 最直接的用法是通过 HTML 标签引用图标。使用 <iconify-icon> 元素，并设置 icon 属性为图标名称。图标名称由“图标集前缀:图标名称”组成，例如 Material Design Icons 中的“home”图标，应写为：

<iconify-icon icon="mdi:home"></iconify-icon>

其中“mdi”是 Material Design Icons 的前缀。你可以从官方图标浏览器中查找任何图标的正确名称。该元素还支持常用属性：width、height、color、flip、rotate 等，可以直接修改图标样式：

<iconify-icon icon="mdi:home" width="48" height="48" color="#ff6600"></iconify-icon>

不需要额外加载任何 CSS，图标会以内联 SVG 形式渲染，保持清晰且可缩放。

在 React 项目中使用

React 项目推荐安装 @iconify/react 包，它提供了 React 组件：

npm install @iconify/react

然后在组件中导入 Icon 组件并使用：

import { Icon } from '@iconify/react';

function HomePage() {
  return <Icon icon="mdi:home" width="32" height="32" />;
}

Icon 组件接受所有标准属性，包括 style、className，并且支持动态改变图标名称。在 SSR 或静态生成场景下，Icon 组件默认输出内联 SVG，不会破坏服务端渲染。

在 Vue 3 项目中使用

Vue 3 用户应安装 @iconify/vue：

npm install @iconify/vue

在 main.js 中全局注册组件：

import { createApp } from 'vue';
import App from './App.vue';
import { Icon } from '@iconify/vue';

const app = createApp(App);
app.component('Icon', Icon);
app.mount('#app');

之后在模板中直接使用：

<Icon icon="mdi:home" width="32" height="32" color="blue" />

Vue 2 版本也有对应包 @iconify/vue2，用法与 Vue 3 相似，只是在组件注册方式上略有差异。

使用在线 API 实现按需加载

如果不希望安装任何 npm 包，Iconify 提供在线 API 服务。通过一个简单的 URL 即可加载特定图标：

https://api.iconify.design/mdi/home.svg

将上述 URL 直接用于 <img> 标签或 CSS background-image，即可获取对应图标的 SVG 文件。更灵活的做法是使用 JavaScript 动态加载：

fetch('https://api.iconify.design/mdi/home.svg')
  .then(response => response.text())
  .then(svg => {
    document.getElementById('icon-container').innerHTML = svg;
  });

在线 API 支持所有图标集，并且会自动返回压缩后的 SVG，减少网络传输。你还可以通过查询参数定制颜色、尺寸，例如：

https://api.iconify.design/mdi/home.svg?color=%23ff0000&width=64

这种方法适合无构建工具的静态页面或后端模板渲染场景。

自定义图标与本地图标集

Iconify 允许你将自定义 SVG 图标注册到系统中。使用 Iconify 的 addIcon 函数可以添加单个图标：

import { addIcon } from 'iconify-icon';

addIcon('custom:my-logo', {
  body: '<path d="..."/>',
  width: 24,
  height: 24
});

之后就能以 custom:my-logo 的名称在项目中引用。如果你有一整套本地图标，可以直接使用 @iconify/utils 中的 addCollection 批量注册。这种方式适合设计系统或需要维护私有图标库的项目。

图标集管理工具 CLI

对于大型项目，官方提供了命令行工具 @iconify/tools，可以帮助你从远程图标集下载、过滤并生成本地 JSON 数据文件。这样在离线环境或内网部署时，可以完全脱离在线 API 运行。基本用法：

npx @iconify/tools import --prefix mdi --output ./icons.json

生成 JSON 文件后，通过 import 方式加载到项目中：

import { addCollection } from 'iconify-icon';
import iconsData from './icons.json';
addCollection(iconsData);

这种方式将图标集完全本地化，减少对外部服务的依赖，同时获得最佳加载性能。

性能优化建议

Iconify 默认使用 Intersection Observer 实现懒加载——只有进入视口的图标才会被渲染，这大幅减少了初始 DOM 节点数。如果你需要手动控制，可以通过 loading 属性设置：

<iconify-icon icon="mdi:home" loading="eager"></iconify-icon>

将 loading 设为 eager 会立即加载图标。此外，在框架组件中尽量使用静态图标名称（而非动态字符串），可以帮助构建工具进行更好的 tree-shaking。Iconify 的图标数据本身也经过了压缩处理，每个图标仅占用几百字节，远小于字体图标文件。