通过 100+ 技巧学习 Nuxt！
56.4K

icon
@nuxt/icon

用于 Nuxt 的 Icon 模块，包含来自 Iconify 的 200,000+ 个即用图标。
390.6K 下载
1.1K 收藏
v1.10.3
AtinuxAtinux
antfuantfu

nuxt-icon

Nuxt Icon

npm versionnpm downloadsLicenseNuxtVolta board

为你的 Nuxt 应用程序添加 200,000+ 个即用图标，基于 Iconify。

特性 ✨

  • Nuxt 3 就绪
  • SSR 友好
  • 通过 Iconify 支持 200,000 个开源矢量图标
  • 同时支持 CSS 模式 / SVG 模式
  • 自定义 SVG 支持 (通过 Vue 组件，或通过本地 SVG 文件)

!NOTE 注意：您正在查看此模块的 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 列表中移除。

用法 👌

Props

  • name (必填): 图标名称或全局组件名称
  • size: 图标大小 (默认: 1em)
  • mode: 图标渲染模式 (svg 或 css, 默认: css)

Attributes:

当使用来自 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 安装其集合。这样，图标可以从本地或你的 Serverless Functions 提供，这在 SSR 和客户端都更快更可靠。

!NOTE 你可能也知道你可以安装 @iconify/json 包来包含所有 Iconify 图标。但不建议这样做，因为它会增加你的服务器 bundle 大小和构建性能。如果你选择这样做，我们建议明确指定你需要的集合名称

export default defineNuxtConfig({
  modules: ['@nuxt/icon'],
  icon: {
    serverBundle: {
      collections: ['uil', 'mdi'] // <!--- this
    }
  }
})

Vue 组件

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

<Icon name="MyComponent" />

请注意，MyComponent 需要位于 components/global/ 文件夹内 (参见 示例)。

!TIP 你也可以使用以下方式更改组件名称

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 时，provider 将默认使用 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'
      },
    ],
  },
})

区分大小写的自定义集合

在 v1.10 之前，由于 Iconify 之前约定的限制，所有自定义图标都被标准化为 kebab-case 并带有警告。感谢 Iconify 方面的更新，从 v1.10 开始，你可以选择使用区分大小写的自定义集合，并绕过标准化。

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

这使得可以使用 assets/my-icons/FooBar.svg 作为 my-icon:FooBar，例如。

normalizeIconName 默认设置为 true 以实现向后兼容性，并且将在未来的主要版本中翻转。有关更多上下文，请参见 #265。

图标自定义

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

使用 icon.class 属性更新 <Icon /> 的默认 class (.icon)，对于无头 Icon，设置 icon.class: ''`。

你还可以通过利用 icon.aliases 属性来定义别名，从而更轻松地替换图标。

!NOTE 注意：运行时配置使用的是 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，以从你的本地服务器 bundle 提供图标 (你可以通过将 icon.localApiEndpoint 设置为你想要的路径来覆盖默认路径)。当请求的图标在本地 bundle 中不存在时，它将回退到请求 官方 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) => {
      // ...
    },
  }
})

通过此配置，整个应用程序中的所有图标都将一致地应用这些自定义设置。

服务器 Bundle

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

服务器 Bundle 模式: local

此模式会将你本地安装的图标集合 (例如 @iconify-json/*) 打包到你的服务器 bundle 中作为动态 chunk。集合数据将按需加载，仅当你的客户端请求该集合中的图标时才加载。

服务器 Bundle 模式: remote

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

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

或者你可以指定远程 provider

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 以在运行时获取图标，而不是将它们与你的服务器捆绑在一起。

在底层，它现在使用类似 () => fetch('https://cdn.jsdelivr.net.cn/npm/@iconify-json/ph/icons.json').then(res => res.json()) 的代码，而不是将 () => import('@iconify-json/ph/icons.json') 捆绑到你的服务器 bundle 中，其中集合未内联。

当服务器 bundle 大小是一个问题时，例如在 Serverless 或 Worker 环境中，这将非常有用。

服务器 Bundle 模式: auto

这是默认选项，模块将根据你的部署环境在 local 和 remote 之间选择。除非你部署到 Serverless 或 Worker 环境 (例如 Vercel Edge 或 Cloudflare Workers)，否则将首选 local。

外部化 Icons JSON

默认情况下，Nitro 会将你本地安装的图标集合 (例如 @iconify-json/*) 打包到你的服务器 bundle 中作为动态 chunk。当你有大量图标时，这可能会使你的打包过程变慢且占用大量内存。你可以通过将 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' } }) 的语句。

另请注意，在某些 Serverless 环境 (例如 Cloudflare Workers) 中，由于它们没有动态导入，因此无论此选项如何，它们都将始终内联。

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

完全禁用服务器 Bundle

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

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

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

客户端 Bundle

对于你知道你将频繁使用的图标，你可以将它们与你的客户端 bundle 捆绑在一起，以避免网络请求。

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 中定义的所有自定义集合到客户端 bundle 中。默认情况下禁用，但在设置 ssr: false 时会自动启用。

扫描组件

当启用 scan 时，模块将扫描你项目中的所有组件，并将使用的图标包含在客户端 bundle 中。这将显著减少静态已知图标所需的网络请求数量，但也可能会增加客户端 bundle 大小，具体取决于项目中使用的图标数量。

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

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', /* ... */],
      },
    },
  },
})

!TIP 提示：扫描依赖于静态分析，这意味着只有字面用法才会被检测到。尽可能避免动态构造图标名称。

<template>
  <!-- Avoid this -->
  <Icon :name="`carbon:${dark ? 'moon' : 'sun'}`" />

  <!-- Prefer this -->
  <Icon :name="dark ? 'carbon:moon' : 'carbon:sun'" />
</template>

Render 函数

你可以在 render 函数中使用 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>

贡献 🙏

  1. 克隆此仓库
  2. 使用 pnpm install 安装依赖 (使用 corepack enable 安装 pnpm, 了解更多)
  3. 运行 npm run dev:prepare 以生成类型定义文件。
  4. 使用 npm run dev 在开发模式下启动 playground。

致谢 💌

许可证 📎

MIT 许可证