Nuxt 图标

基于 Iconify，将 200,000+ 可直接使用的图标添加到您的 Nuxt 应用程序中。

功能 ✨

支持 Nuxt 3
支持服务器端渲染
通过 Iconify 支持 200,000 个开源矢量图标
支持 CSS 模式和 SVG 模式
自定义 SVG 支持（通过 Vue 组件或本地 SVG 文件）

！注意您正在查看此模块的 v1.0 版本，该版本进行了完全重写，以提供更好的开发体验和性能。如果您要从 v0.6 迁移，请查看此 PR 以获取完整的更改列表。

设置 ⛓️

运行以下命令将模块添加到您的项目中

npx nuxi module add icon

就是这样，您现在可以在组件中使用 <Icon /> 了！

✨ 如果您使用的是 VS Code，您可以使用 Iconify IntelliSense 扩展程序（由 @antfu 开发）。

手动设置

您可以使用以下命令手动安装模块

npm i -D @nuxt/icon

更新您的 nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ]
})

如果您安装了旧版模块 nuxt-icon，您可能需要将其从 modules 列表中删除。

用法 👌

属性

name（必需）：图标名称或全局组件名称
size：图标大小（默认：1em）
mode：图标渲染模式（svg 或 css，默认：css）

属性:

当使用来自 Iconify 的图标时，将根据渲染模式创建 <span> 或 <svg>，您可以为原生元素提供所有属性。

<Icon name="uil:github" style="color: black" />

Iconify 数据集

您可以使用 https://icones.js.org 集合中的任何名称

<Icon name="uil:github" />

它支持 i- 前缀（例如，i-uil-github）。

强烈建议使用以下命令在本地安装图标数据：

npm i -D @iconify-json/collection-name

例如，要使用 uil:github 图标，请使用 @iconify-json/uil 安装其集合。这样，图标可以从本地或您的无服务器函数中提供服务，这在 SSR 和客户端上都更快且更可靠。

！注意您可能还知道您可以安装 @iconify/json 包以包含所有 iconify 图标。不建议这样做，因为它会增加服务器包大小并降低构建性能。如果您选择这样做，建议您明确指定所需的集合名称。
export default defineNuxtConfig({
  modules: ['@nuxt/icon'],
  icon: {
    serverBundle: {
      collections: ['uil', 'mdi'] // <!--- this
    }
  }
})

Vue 组件

当 name 与全局注册的组件匹配时，它将被渲染为该组件（在这种情况下，将忽略 mode）。

<Icon name="MyComponent" />

请注意，MyComponent 必须位于 components/global/ 文件夹中（请参阅示例）。

！提示您还可以使用以下命令更改组件名称：
export default defineNuxtConfig({
  icon: {
    componentName: 'NuxtIcon'
  }
})

自定义本地集合

您可以使用本地 SVG 文件创建自定义 Iconify 集合。

例如，将图标的 SVG 文件放在您选择的文件夹下，例如 ./assets/my-icons

assets/my-icons
├── foo.svg
├── bar-outline.svg

在您的 nuxt.config.ts 中，在 icon.customCollections 中添加一个项目

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    customCollections: [
      {
        prefix: 'my-icon',
        dir: './assets/my-icons'
      },
    ],
  },
})

然后您可以像这样使用图标

<template>
  <Icon name="my-icon:foo" />
  <Icon name="my-icon:bar-outline" />
</template>

请注意，自定义本地集合需要您拥有一个服务器来提供 API。当设置 ssr: false 时，提供程序将默认为 Iconify API（其中不包含您的自定义图标）。如果您想使用服务器端点构建 SPA，您可以明确设置 provider: 'server'

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  ssr: false,
  icon: {
    provider: 'server', // <-- this
    customCollections: [
      {
        prefix: 'my-icon',
        dir: './assets/my-icons'
      },
    ],
  },
})

图标自定义

要更新 <Icon /> 的默认大小（1em），请创建一个带有 icon.size 属性的 app.config.ts。

使用 icon.class 属性更新 <Icon /> 的默认类（.icon），对于无头图标，请设置 icon.class: ''`。

您还可以定义别名，以便通过利用 icon.aliases 属性更轻松地交换图标。

！注意请注意，它是 app.config.ts 而不是 nuxt.config.ts 用于运行时配置。

// app.config.ts
export default defineAppConfig({
  icon: {
    size: '24px', // default <Icon> size applied
    class: 'icon', // default <Icon> class applied
    mode: 'css', // default <Icon> mode applied
    aliases: {
      'nuxt': 'logos:nuxt-icon',
    }
  }
})

图标将具有 24px 的默认大小，并且 nuxt 图标将可用

<Icon name="nuxt" />

默认情况下，此模块将创建一个服务器端点 /api/_nuxt_icon/:collection 以从您的本地服务器包中提供图标（您可以通过将 icon.localApiEndpoint 设置为您所需的路径来覆盖默认路径）。当请求本地包中不存在的图标时，它将回退到请求官方 Iconify API。您可以通过将 icon.fallbackToApi 设置为 false 来禁用回退，或设置您自己的 Iconify API 并将 icon.iconifyApiEndpoint 更新为您自己的 API 端点。

使用 customize 选项自定义图标

customize 选项允许您修改项目中使用的 SVG 图标的各个方面。使用此选项，您可以

更改笔划宽度
更改颜色
更改动画持续时间
更改不透明度
添加额外的形状

使用这些自定义选项，您可以完全控制 SVG 内容。

在组件中，您可以在组件中定义一个 customize 函数，以对图标应用各种修改。

<script setup lang="ts">
// Define the customize function to modify SVG content
const customize = (content: string, name: string, prefix: string, provider: string) => {
  if (prefix !== 'tabler') return content // Ignore Prefix

  return content
    .replace(/stroke-width="[^"]*"/g, `stroke-width="2"`) // Change stroke width to 2
    .replace(/stroke="[^"]*"/g, `stroke="#FF5733"`) // Change stroke color to red
    .replace(/fill="[^"]*"/g, `fill="#FF5733"`) // Change fill color to red
    .replace(/animation-duration="[^"]*"/g, `animation-duration="1s"`) // Change animation duration to 1s (for animated icons)
    .replace(/opacity="[^"]*"/g, `opacity="0.8"`);// Change opacity to 0.8
}
</script>

<template>
  <Icon name="tabler:star" :customize="customize" />
</template>

在应用程序配置文件中

或者，您可以在 app.config.ts 文件中全局应用这些自定义项。

// app.config.ts
export default defineAppConfig({
  icon: {
    customize: (content: string, name: string, prefix: string, provider: string) => {
      // ...
    },
  }
})

通过此配置，整个应用程序中的所有图标都将始终应用这些自定义项。

服务器包

自从 @nuxt/icon v1.0 以来，我们引入了服务器包的概念，以从 Nuxt 服务器端点提供图标。这使客户端包保持精简并能够按需加载图标，同时具有使用可能在构建时未知的图标的所有动态功能。

服务器包模式：`local`

此模式会将您在本地安装的图标集合（如 @iconify-json/*）捆绑到您的服务器包中作为动态块。只有当您的客户端请求来自该集合的图标时，才会按需加载集合数据。

服务器包模式：`remote`

在 @nuxt/icon v1.2 中引入，您现在可以使用 remote 服务器包从远程 CDN 提供图标。

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    serverBundle: 'remote',
  },
})

或者您可以指定远程提供程序

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    serverBundle: {
      remote: 'jsdelivr', // 'unpkg' or 'github-raw', or a custom function
    }
  },
})

这将使服务器请求 https://cdn.jsdelivr.net.cn/npm/@iconify-json/ph/icons.json 以在运行时获取图标，而不是将它们与您的服务器捆绑在一起。

在幕后，它不再将 () => import('@iconify-json/ph/icons.json') 捆绑到您的服务器包中，而是使用类似 () => fetch('https://cdn.jsdelivr.net.cn/npm/@iconify-json/ph/icons.json').then(res => res.json()) 的内容，其中集合不会内联。

这在服务器包大小成为问题时非常有用，例如在无服务器或工作程序环境中。

服务器包模式：`auto`

这是默认选项，其中模块将根据您的部署环境在 local 和 remote 之间进行选择。除非您部署到无服务器或工作程序环境（如 Vercel Edge 或 Cloudflare Workers），否则将优先使用 local。

外部化图标 JSON

默认情况下，Nitro 会将您在本地安装的图标集合（如 @iconify-json/*）捆绑到您的服务器包中作为动态块。当您有大量图标时，这可能会使您的捆绑过程变慢并占用大量内存。您可以更改为通过将 icon.serverBundle.externalizeIconsJson 设置为 true 来外部化图标 JSON 文件。

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    serverBundle: {
      externalizeIconsJson: true,
    }
  },
})

请注意，这需要您的生产 Node.js 服务器能够导入 JSON 文件（请注意，在 Node.js v22 中，JSON 模块仍然是实验性功能）。在最终构建中，它将包含类似 () => import('@iconify-json/ph/icons.json', { with: { type: 'json' } }) 的语句。

另请注意，在某些无服务器环境（如 Cloudflare Workers）中，由于它们没有动态导入，因此无论此选项如何，它们始终会被内联。

启用 icon.serverBundle.remote 时，将忽略此选项。

完全禁用服务器包

如果您想完全禁用服务器包，可以将 icon.serverBundle 设置为 false 并将 provider 设置为 iconify

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    provider: 'iconify',
    serverBundle: false,
  },
})

这将每次客户端请求图标时都向 Iconify API 发出请求。除非其他选项不可行，否则我们不建议这样做。

客户端包

对于您知道将经常使用的图标，您可以将它们与客户端包捆绑在一起以避免网络请求。

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    clientBundle: {
      // list of icons to include in the client bundle
      icons: [
        'uil:github',
        'logos:vitejs'
      ],

      // scan all components in the project and include icons 
      scan: true,

      // include all custom collections in the client bundle
      includeCustomCollections: true, 

      // guard for uncompressed bundle size, will fail the build if exceeds
      sizeLimitKb: 256,
    },
  },
})

includeCustomCollections 将包含您在 icon.customCollections 中定义的所有自定义集合到客户端包中。它默认情况下是禁用的，但在设置 ssr: false 时会自动启用。

扫描组件

启用 scan 时，模块将扫描项目中的所有组件并将客户端包中使用的图标包含在内。这将大大减少静态已知图标所需的网络请求次数，但根据项目中使用的图标数量，也可能会增加客户端包大小。

您还可以微调扫描目标，例如

export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    clientBundle: {
      scan: {
        // note that when you specify those values, the default behavior will be overridden
        globInclude: ['components/**/*.vue', /* ... */],
        globExclude: ['node_modules', 'dist', /* ... */],
      },
    },
  },
})

!提示扫描依赖于静态分析，这意味着只会检测字面上的用法。尽可能避免动态构建图标名称。
<template>
  
  <Icon :name="`carbon:${dark ? 'moon' : 'sun'}`" />

  
  <Icon :name="dark ? 'carbon:moon' : 'carbon:sun'" />
</template>

渲染函数

您可以在渲染函数中使用 Icon 组件（如果您创建了一个函数式组件，这将很有用），为此，您可以从 #components 导入它。

import { Icon } from '#components'

查看 <MyIcon> 组件的示例

<script setup>
import { Icon } from '#components'

const MyIcon = h(Icon, { name: 'uil:twitter' })
</script>

<template>
  <p><MyIcon /></p>
</template>

贡献 🙏

克隆此仓库
使用 pnpm install 安装依赖项（使用 corepack enable 安装 pnpm，了解更多）
运行 npm run dev:prepare 生成类型声明文件。
使用 npm run dev 在开发模式下启动 playground。

鸣谢 💌

@benjamincanac 初始版本
@cyberalien 创建了 Iconify

许可证 📎

MIT 许可证