# @iconify/vue 中文文档

规范地址：https://npmcn.com/package/%40iconify/vue/

版本：5\.0\.5
npm 元数据更新时间：2026-11-01T07:10:46.507Z
中文译文更新时间：2026-11-01T10:40:06.496Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40iconify/vue
原文对照：https://npmcn.com/package/%40iconify/vue/?lang=original
项目主页：https://iconify.design/
源码仓库：https://github.com/iconify/iconify

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：182 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：vue \>=3\.0\.0
- 首次发布：2020-04-20T17:02:40.257Z
- 最新版本发布：2026-11-01T07:10:46.318Z
- 已发布版本数：52（近 12 个月 5 个）

## 中文简介

将Vue 3的图标组件图标化。

## 安装

```sh
npm install @iconify/vue
```

也可以使用：`pnpm add @iconify/vue`、`yarn add @iconify/vue`、`bun add @iconify/vue`

## README

# 图标为Vue

用于Vue的Iconify还不是另一个图标组件！已经有很多了。

使用其他组件可以得到什么：

-   有限的图标集。
-   大的包大小，因为所有图标都是捆绑的。

Iconify图标组件不是这样的。组件不包含任何图标数据，它不绑定到任何特定的图标集。相反，所有数据都是按需从公共API中检索的。

这意味着:

-   一种语法，从150+图标集超过200000图标。
-   SVG呈现。许多组件只是简单地呈现图标字体，看起来很难看。Iconify呈现像素完美的SVG。
-   按需加载图标。不需要绑定图标，组件会自动从Iconify API加载图标数据。

有关Iconify项目的更多信息，请访问 [https://iconify.design/](https://iconify.design/).

有关详细文件，请访问 [图标化为Vue文档](https://iconify.design/docs/icon-components/vue/).

## 安装

如果你正在使用NPM：

```bash
npm install --save-dev @iconify/vue
```

如果你正在使用Yarn：

```bash
yarn add --dev @iconify/vue
```

### Vue 2兼容性

该组件与Vue 2不向后兼容。

如果您使用的是Vue 2，则需要安装 `@iconify/vue2` 组件。它几乎与这个组件相同，但对于Vue 2。

看到 [为Vue 2文档添加图标](https://iconify.design/docs/icon-components/vue2/).

## API用法

安装 `@iconify/vue` 和导入 `Icon` 来自:

```js
import { Icon } from '@iconify/vue';
```

然后使用 `Icon` 模板中图标名称或数据为“icon”参数的组件：

```jsx
<Icon icon="mdi-light:home" />
```

组件将自动从Iconify API中检索“midi -light:home”的数据并渲染它。Iconify API上有超过20万个图标，来自各种免费和开源的图标集，包括所有最流行的图标集。

## 离线使用

这个图标组件被设计为与Iconify API一起使用，按需加载图标数据，而不是捆绑它。

如果你想使用没有Iconify API的图标， [还有很多其他的选择](https://iconify.design/docs/usage/).

## Web组件

如果你遇到SSR水合作用的问题，有一个可供选择的解决方案： [Iconify图标web组件](https://iconify.design/docs/iconify-icon/).

Web组件优先于此组件，如果：

-   您的页面运行缓慢。Web组件在影子DOM中分离图标渲染，提高性能。
-   您正在经历CSS冲突。
-   它在next和Vitepress上运行得更好。

## 图标名称

图标名称是一个字符串。一些例子:

-   `@api-provider:icon-set-prefix:icon-name`
-   `mdi-light:home` （在本例中，API provider为空，因此跳过它）

它有3个部分，用“：”隔开：

-   提供者指向API源。以“@”开头，可以为空（空值用于公共Iconify API）。
-   前缀是图标集的名称。
-   Name是图标的名称。

看到 [Iconify为Vue图标名称文档](https://iconify.design/docs/icon-components/vue/icon-name.html) 有关更详细的解释。

## 使用图标数据

你可以将图标数据传递给组件，而不是图标名称：

```vue
<template>
    <Icon :icon="icons.chart" height="24" />
</template>

<script lang="ts">
import { Icon } from '@iconify/vue';
import areaChartOutlined from '@iconify-icons/ant-design/area-chart-outlined';

export default {
    components: {
        Icon,
    },
    data() {
        return {
            // Assign icon data to icons.chart
            icons: {
                chart: areaChartOutlined,
            },
        };
    },
};
</script>
```

看到 [图标包文档](https://iconify.design/docs/icons/) 了解更多详情。

### ES / CommonJS包

上面的例子在某些用例中可能会失败。包 `@iconify-icons/mdi-light` 使用某些软件可能还不支持的ES模块。但是不要担心，有一个简单的解决方案：切换到CommonJS图标包。

要切换到CommonJS包，替换上面例子中的这一行：

```js
import home from '@iconify-icons/mdi-light/home';
```

与

```js
import home from '@iconify/icons-mdi-light/home';
```

所有图标都可以作为ES模块用于现代的捆绑器，作为CommonJS模块用于过时的捆绑器。ES模块使用格式 `@iconify-icons/{prefix}`， CommonJS模块使用 `@iconify/icons-{prefix}`.

有关详细信息，请参见 [图标包文档](https://iconify.design/docs/icons/).

### 垂直对齐

图标有两种模式：内联模式和块模式。模式之间的差异是 `vertical-align` 它被添加到内联图标中。

内联图标的对齐略低于基线，因此与文本相比，它们看起来像字形字体一样居中。

块图标没有对齐，像图像一样，默认情况下会对齐到基线。

添加了对齐选项，使图标看起来像文本的延续，表现得像字形字体。这将使从字形字体的迁移更容易。

要在块模式和内联模式之间切换，可以使用布尔值 `inline` 属性:

```vue
<template>
    <div>
        <p>
            Block:
            <Icon icon="line-md:image-twotone" />
            <Icon icon="mdi:account-box-outline" />
        </p>
        <p>
            Inline:
            <Icon icon="line-md:image-twotone" :inline="true" />
            <Icon icon="mdi:account-box-outline" :inline="true" />
        </p>
    </div>
</template>

<script>
import { Icon } from '@iconify/vue';

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

显示内联模式和块模式之间区别的可视化示例：

![Inline icon](https://iconify.design/assets/images/inline.png)

## 图标组件属性

`icon` 财产是必须的。它告诉组件渲染哪个图标。如果属性值无效，组件将呈现一个空图标。该值可以是包含图标名称的字符串(图标必须在使用前通过调用 `addIcon` 或者 `addCollection`（参见上面的说明）或包含图标数据的对象。

icon组件有以下可选属性：

-   `inline`。更改图标行为以匹配图标字体。请参阅下面的“内联图标”部分。
-   `width` 和 `height`。图标尺寸。两者的默认值都是“1em”。参见下面的“尺寸”部分。
-   `color`。图标的颜色。这和设定风格的颜色是一样的。请参阅下面的“图标颜色”部分。
-   `flip`， `horizontalFlip`， `verticalFlip`。水平和/或垂直翻转图标。请参阅下面的“转换”部分。
-   `rotate`。旋转图标90、180或270度。请参阅下面的“转换”部分。
-   `align`， `verticalAlign`， `horizontalAlign`， `slice`。图标对齐。请参阅下面的“对齐”部分。
-   `onLoad`。当图标数据被加载时调用的回调函数。请参阅下面的“onLoad”部分。

注意：在模板中，你可以使用“camelCase”属性作为“kebab-case”。例如, `horizontalFlip` 可以用作 `horizontal-flip`.

### 其他属性和事件

除了上面提到的属性之外，图标组件还接受任何其他属性和事件。所有其他属性和事件都将传递给generate `SVG` 元素，你可以分配click事件，设置内联样式，添加标题等等。

### 维

默认情况下，图标高度为“1em”。With是动态的，使用图标的宽高比计算。

有几种方法可以改变图标的尺寸：

-   设置 `font-size` 在风格。
-   设置 `width` 和/或 `height` 财产。

值 `width` 和 `height` 可以是数字或字符串。

如果你只设置一个维度，另一个维度将使用图标的宽高比计算。例如，如果图标大小为16 × 24，则将高度设置为48，则宽度将设置为32。计算不仅适用于数字，也适用于字符串值。

#### 以数字表示维度

你可以用数字来表示 `width` 和 `height`.

```html
<Icon icon="mdi-light:home" :height="24" />
```

```html
<Icon icon="mdi-light:home" :width="16" :height="16" />
```

注意属性之前的“:“ -在Vue中，它将值更改为表达式，因此”20”是一个数字，而不是字符串。

数值被视为像素。这意味着在上面的例子中，值与“24px”和“16px”相同。

#### 维度是没有单位的字符串

如果您使用没有单位的字符串，它们将被视为与上面示例中的数字相同。

```html
<Icon icon="mdi-light:home" height="24" />
```

```html
<Icon icon="mdi-light:home" width="16" height="16" />
```

#### 维度作为带单位的字符串

你可以在宽度和高度值中使用单位：

```html
<Icon icon="mdi-light:home" height="2em" />
```

使用时要小心 `calc`，基于单位或百分比的查看端口。在SVG元素中，它们的行为可能不像您期望的那样，当使用这些单元时，您应该同时考虑宽度和高度的设置。

#### 尺寸为“auto”

关键字“auto”设置图标的尺寸 `viewBox` 维度。例如，对于24 × 24的图标使用 `height="auto"` 设置高度为24像素。

```html
<Icon icon="mdi-light:home" height="auto" />
```

### 图标颜色

有两种类型的图标：没有调色板的图标和有调色板的图标。

有调色板的图标，比如表情符号，是不能自定义的。为这些图标设置颜色不会改变任何东西。

没有调色板的图标可以自定义。默认情况下，颜色设置为“currentColor”，这意味着图标的颜色与文本颜色匹配。要改变颜色，你可以：

-   集 `color` 样式或使用样式表来定位图标。如果您正在使用样式表，则目标 `svg` 元素。
-   添加 `color` 财产。

示例：

使用 `color` 属性:

```html
<Icon icon="eva:alert-triangle-fill" color="red" />
<Icon icon="eva:alert-triangle-fill" color="#f00" />
```

使用行内样式：

```html
<Icon icon="eva:alert-triangle-fill" style="color: red;" />
<Icon icon="eva:alert-triangle-fill" :style="{color: 'red'}" />
<Icon icon="eva:alert-triangle-fill" :style="{color: '#f00'}" />
```

使用样式表:

```vue
<template>
    <Icon icon="eva:alert-triangle-fill" class="red-icon" />
</template>

<style>
.red-icon {
    color: red;
}
</style>
```

### 转换

你可以旋转和翻转图标。

这似乎是多余的，因为图标也可以使用CSS转换来旋转和翻转。那么为什么存在转换属性呢？因为这是一种不同类型的变换。

-   CSS变换变换整个图标。
-   图标转换转换图标的内容。

如果你有一个方形图标，这没有什么区别。然而，如果你有一个图标有不同的宽度和高度值，它会产生巨大的差异。

将16 × 24的图标旋转90度会得到：

-   CSS转换保持16x24的边界框，这可能会导致图标重叠周围的文本。
-   图标转换将边界框更改为24x16，旋转图标内的内容。

看到 [图标转换文档](https://iconify.design/docs/icon-components/vue/transform.html) 了解更多详情。

#### 翻转图标

有几个属性可以用来翻转图标：

-   `horizontal-flip` 或者 `h-flip`：布尔属性，水平翻转图标。
-   `vertical-flip` 或者 `v-flip`：布尔属性，垂直翻转图标。
-   `flip`：速记字符串属性，可以水平和/或垂直翻转图标。

示例：

水平翻转图标：

```html
<Icon icon="eva:alert-triangle-fill" :h-flip="true" />
<Icon icon="eva:alert-triangle-fill" :horizontal-flip="true" />
<Icon icon="eva:alert-triangle-fill" flip="horizontal" />
```

垂直翻转图标：

```html
<Icon icon="eva:alert-triangle-fill" :v-flip="true" />
<Icon icon="eva:alert-triangle-fill" :vertical-flip="true" />
<Icon icon="eva:alert-triangle-fill" flip="vertical" />
```

水平和垂直翻转图标（与180度旋转相同）：

```html
<Icon icon="eva:alert-triangle-fill" :h-flip="true" :v-flip="true" />
<Icon icon="eva:alert-triangle-fill" :horizontal-flip="true" :vertical-flip="true" />
<Icon icon="eva:alert-triangle-fill" flip="horizontal,vertical" />
```

为什么有多个布尔属性翻转图标？

在其他框架的组件中，用于翻转图标的属性是 `hFlip` 和 `vFlip`。Vue对以v-开头的属性有特殊处理 `vFlip` (同样适用于 `vAlign` Attribute)属性不使用复杂的语法是不可用的。

正因为如此，Vue组件使用更长的属性名： `verticalFlip` 而不是 `vFlip` 和 `horizontalFlip` 而不是 `hFlip` 的一致性。

#### 旋转图标

一个图标可以旋转90度、180度和270度。只有图标的内容被旋转。

要旋转图标，请使用 `rotate` 财产。Value可以是字符串（度或百分比）或数字。

数值是1代表90度，2代表180度，3代表270度。

90度旋转的例子：

```html
<Icon icon="eva:alert-triangle-fill" :rotate="1" />
<Icon icon="eva:alert-triangle-fill" rotate="90deg" />
<Icon icon="eva:alert-triangle-fill" rotate="25%" />
```

### onLoad

`onLoad` 属性是可选的回调函数。它在加载图标数据时被调用。

它不是一个事件，比如 `onClick` 事件的链接，它是一个简单的回调函数。

当 `onLoad` 被称为:

-   如果icon属性的值是一个对象， `onLoad` 未被调用。
-   如果icon属性的值是一个字符串并且图标数据可用， `onLoad` 在第一次渲染时调用。
-   如果图标属性的值是字符串且图标数据不可用， `onLoad` 在从API检索图标数据后第一次重新渲染时调用。

目的是什么 `onLoad`？ 让您知道图标组件何时呈现图标，何时不呈现任何内容。这允许你做一些事情，比如为父元素添加类名，比如“container——with-icon”，在显示图标时修改布局。

## 完整的文档

有关详细文件，请访问 [图标化为Vue文档](https://iconify.design/docs/icon-components/vue/).

## 许可证

Vue组件使用MIT许可发布。

©2020-至今Vjacheslav Trushkin

看到 [图标化图标集页面](https://icon-sets.iconify.design/) 查看集合列表及其许可证。

## 常见问题

### @iconify/vue 是什么？

将Vue 3的图标组件图标化。

### 如何安装 @iconify/vue？

在项目目录运行 npm install @iconify/vue，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（\>=3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @iconify/vue 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @iconify/vue 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @iconify/vue 可以商用吗？

@iconify/vue 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @iconify/vue 还在维护吗？

最新版本 5\.0\.5 发布于 2026/11/01（2 天前）；至今共发布 52 个版本，其中过去 12 个月发布了 5 个；首次发布于 2020/04/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。