图标预设

在 UnoCSS 中使用任何纯 CSS 图标。

源代码

提示

推荐阅读：纯 CSS 中的图标

遵循以下约定来使用图标

• <prefix><collection>-<icon>
• <prefix><collection>:<icon>

例如

<!-- A basic anchor icon from Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- An orange alarm from Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- A large Vue logo -->
<div class="i-logos-vue text-3xl" />
<!-- Sun in light mode, Moon in dark mode, from Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji of laugh, turns to tear on hovering -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

悬停它

查看所有可用图标。

安装

pnpm

pnpm add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

yarn

yarn add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

npm

npm install -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

我们使用 Iconify 作为我们的图标数据源。您需要按照 @iconify-json/* 模式在 devDependencies 中安装相应的图标集。例如，@iconify-json/mdi 用于 Material Design Icons，@iconify-json/tabler 用于 Tabler。您可以参考 Icônes 或 Iconify 获取所有可用集合。

uno.config.ts

import presetIcons from '@unocss/preset-icons'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({ /* options */ }),
    // ...other presets
  ],
})

提示

此预设包含在 unocss 包中，您也可以从那里导入它

import { presetIcons } from 'unocss'

信息

您也可以单独使用此预设作为现有 UI 框架的补充，以拥有纯 CSS 图标！

如果您希望一次安装 Iconify 上所有可用的图标集（约 130MB）

pnpm

pnpm add -D @iconify/json

yarn

yarn add -D @iconify/json

npm

npm install -D @iconify/json

额外属性

您可以提供额外的 CSS 属性来控制图标的默认行为。以下是如何将图标默认设置为内联的示例

presetIcons({
  extraProperties: {
    'display': 'inline-block',
    'vertical-align': 'middle',
    // ...
  },
})

模式覆盖

默认情况下，此预设将根据图标的特征自动为每个图标选择渲染模式。您可以在此 博客文章 中了解更多信息。在某些情况下，您可能希望为每个图标显式设置渲染模式。

• ?bg 用于 background-img - 将图标渲染为背景图像
• ?mask 用于 mask - 将图标渲染为蒙版图像

例如，vscode-icons:file-type-light-pnpm，一个带有颜色的图标（svg 不包含 currentColor），它将被渲染为背景图像。使用 vscode-icons:file-type-light-pnpm?mask 将其渲染为蒙版图像并绕过其颜色。

<div class="w-full flex items-center justify-center gap-x-4 text-4xl p-2 mt-4">
  <div class="i-vscode-icons:file-type-light-pnpm" />
  <div class="i-vscode-icons:file-type-light-pnpm?mask text-red-300" />
</div>

配置集合和图标解析器

您可以通过 @iconify-json/[the-collection-you-want]、@iconify/json 或使用您在 UnoCSS 配置中的 collections 选项提供的自定义集合来提供集合。

浏览器

要加载 iconify 集合，您应该使用 @iconify-json/[the-collection-you-want] 而不是 @iconify/json，因为 json 文件很大。

捆绑器

使用捆绑器时，您可以使用 dynamic imports 提供集合，以便它们被捆绑为异步块并按需加载。

import presetIcons from '@unocss/preset-icons/browser'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default),
        mdi: () => import('@iconify-json/mdi/icons.json').then(i => i.default),
        logos: () => import('@iconify-json/logos/icons.json').then(i => i.default),
      }
    })
  ]
})

CDN

或者，如果您希望从 CDN 获取它们，您可以从 v0.32.10 开始指定 cdn 选项。我们推荐 esm.sh 作为 CDN 提供商。

presetIcons({
  cdn: 'https://esm.sh/'
})

自定义

您还可以使用 CustomIconLoader 或 InlineCollection 提供您自己的自定义集合，例如使用 InlineCollection

presetIcons({
  collections: {
    custom: {
      circle: '<svg viewBox="0 0 120 120"><circle cx="60" cy="60" r="50"></circle></svg>',
      /* ... */
    },
    carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default as any),
    /* ... */
  }
})

然后，您可以在您的 html 上使用它：<span class="i-custom:circle"></span>

Node.js

在 Node.js 中，预设会自动搜索已安装的 iconify 数据集，因此您无需注册 iconify 集合。

您还可以使用 CustomIconLoader 或 InlineCollection 提供您自己的自定义集合。

FileSystemIconLoader

此外，您还可以使用 FileSystemIconLoader 从您的文件系统加载自定义图标。您需要安装 @iconify/utils 包作为 dev dependency。

unocss.config.ts

import fs from 'node:fs/promises'
import { defineConfig, presetIcons } from 'unocss'

// loader helpers
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // key as the collection name
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // load your custom icon lazily
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // your custom loader here. Do whatever you want.
          // for example, fetch from a remote server:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // a helper to load icons from the file system
        // files under `./assets/icons` with `.svg` extension will be loaded as it's file name
        // you can also provide a transform callback to change each icon (optional)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

从 @iconify/utils v2.1.20 开始，您可以使用其他包从其他作者那里加载图标，使用新的 createExternalPackageIconLoader 助手。

警告

外部包必须包含 icons.json 文件，其中包含 IconifyJSON 格式的 icons 数据，可以使用 Iconify Tools 导出。查看 将图标集导出为 JSON 包 获取更多详细信息。

例如，您可以使用 an-awesome-collection 或 @my-awesome-collections/some-collection 来加载您的自定义或第三方图标

unocss.config.ts

import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: createExternalPackageIconLoader('an-awesome-collection')
    })
  ]
})

您也可以将其与其他自定义图标加载器组合使用，例如

unocss.config.ts

import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'
import { FileSystemIconLoader } from 'unplugin-icons/loaders'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        ...createExternalPackageIconLoader('other-awesome-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-other-collection'),
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/^<svg /, '<svg fill="currentColor" ')
        )
      }
    })
  ]
})

图标自定义

您可以使用 customizations 配置选项自定义所有图标。

可用的自定义函数

• transform：转换原始 svg，仅在使用 custom 图标集合（iconify 集合除外）时应用。
• customize：更改默认图标自定义值。
• iconCustomizer：更改默认图标自定义值。

对于每个加载的图标，自定义将按以下顺序应用

• 如果提供，则对原始 svg 应用 transform，并使用自定义图标集合
• 如果提供，则使用默认自定义项应用 customize
• 如果提供，则使用 customize 自定义项应用 iconCustomizer

全局自定义图标转换

加载自定义图标时，您可以转换它们，例如添加带有 currentColor 的 fill 属性

presetIcons({
  customizations: {
    transform(svg) {
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

从版本 0.30.8 开始，transform 提供 collection 和 icon 名称

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // do not apply fill to this icons on this collection
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

全局图标自定义

加载任何图标时，您可以自定义所有图标的通用属性，例如配置相同的大小

presetIcons({
  customizations: {
    customize(props) {
      props.width = '2em'
      props.height = '2em'
      return props
    }
  }
})

图标/集合自定义

您可以使用 iconCustomizer 配置选项自定义每个图标。

iconCustomizer 将优先于配置。

iconCustomizer 将应用于任何集合，也就是说，对于来自 custom 加载器、在 custom collections 上内联或来自 @iconify 的每个图标。

例如，您可以配置 iconCustomizer 来更改集合的所有图标或集合中的单个图标

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // customize all icons in this collection
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // customize this icon in this collection
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // customize this @iconify icon in this collection
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

指令

您可以在 CSS 中使用 icon() 指令来获取图标的元数据。

.icon {
  background-image: icon('i-carbon-sun');
}

警告

icon() 依赖于 @unocss/preset-icons 并将使用配置，确保您已添加此预设。

有关 icon() 指令的更多信息，请查看 指令。

选项

scale

• 类型：number
• 默认值：1

相对于当前字体大小（1em）的比例。

mode

• 类型：'mask' | 'bg' | 'auto'
• 默认值：'auto'
• 查看：https://antfu.me/posts/icons-in-pure-css

生成的 CSS 图标的模式。

提示

• mask - 使用背景颜色和 mask 属性用于单色图标
• bg - 使用背景图像作为图标，颜色是静态的
• auto - 智能地根据图标的样式在 mask 和 bg 之间决定模式

prefix

• 类型：string | string[]
• 默认值：'i-'

用于匹配图标规则的类前缀。

extraProperties

• 类型: Record<string, string>
• 默认: {}

应用于生成的 CSS 的额外 CSS 属性。

warn

• 类型: boolean
• 默认: false

在匹配到缺失的图标时发出警告。

collections

• 类型: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
• 默认: undefined

在 Node.js 环境中，预设将自动搜索已安装的 iconify 数据集。在浏览器中使用时，此选项用于提供具有自定义加载机制的数据集。

layer

• 类型: string
• 默认: 'icons'

规则层。

customizations

• 类型: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
• 默认: undefined

自定义图标定制。

autoInstall

• 类型: boolean
• 默认: false

在检测到使用情况时自动安装图标源包。

警告

仅在 node 环境下，在 browser 环境下此选项将被忽略。

unit

• 类型: string
• 默认: 'em'

自定义图标单位。

cdn

• 类型: string
• 默认: undefined

从 CDN 加载图标。应以 https:// 开头，以 / 结尾。

推荐

• https://esm.sh/
• https://cdn.skypack.dev/

customFetch

• 类型: (url: string) => Promise<any>
• 默认: undefined

预设使用 ofetch 作为默认的获取器，你也可以自定义获取函数来提供图标数据。

processor

• 类型: (cssObject: CSSObject, meta: Required<IconMeta>) => void
• 默认: undefined

interface IconMeta {
  collection: string
  icon: string
  svg: string
  mode?: IconsOptions['mode']
}

字符串化之前的 CSS 对象的处理器。查看 示例.

高级自定义图标集清理

在将此预设与自定义图标一起使用时，请考虑使用类似于 Iconify 对任何图标集进行的清理过程。所有需要的工具都在 Iconify Tools 中。

你可以查看这个仓库，它在一个 Vue 3 项目中使用此预设：@iconify/tools/@iconify-demo/unocss.

阅读 清理图标 来自 Iconify 的文章，了解更多详细信息。

致谢

• 此预设的灵感来自 此问题，由 @husayt 创建。
• 基于 此 PR 的工作，由 @userquin 完成。