圖示預設集

在 UnoCSS 中使用任何純 CSS 圖示。

提示

請遵循以下慣例使用圖示

<前綴><集合>-<圖示>
<前綴><集合>:<圖示>

例如

html

<!-- 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" />

滑鼠懸停

查看所有可用圖示。

安裝

pnpmyarnnpm

bash

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

bash

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

bash

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）

pnpmyarnnpm

bash

pnpm add -D @iconify/json

bash

yarn add -D @iconify/json

bash

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` 將其渲染為遮罩圖片並繞過其顏色。

html

<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/[您想要的集合]`、`@iconify/json` 或使用您在 `UnoCSS` 設定中 `collections` 選項自定義的集合來提供集合。

瀏覽器

要載入 `iconify` 集合，您應該使用 `@iconify-json/[您想要的集合]` 而不是 `@iconify/json`，因為 `json` 檔案很大。

打包器

使用打包器時，您可以使用 `動態導入` 提供集合，這樣它們將被打包為非同步區塊並按需載入。

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` 套件安裝為 `開發依賴項`。

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 輔助函數從其他作者那裡載入圖示。

警告

外部套件必須包含具有 `IconifyJSON` 格式 `圖示` 資料的 `icons.json` 檔案，可以使用 Iconify 工具匯出。查看將圖示集匯出為 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`：更改預設圖示自定義值。

對於每個載入的圖示，將按以下順序套用自定義

如果提供並使用自定義圖示集合，則將 `transform` 套用於原始 `svg`
如果提供，則將 `customize` 與預設自定義套用
如果提供，則將 `iconCustomizer` 與 `customize` 自定義套用

全域自定義圖示轉換

載入自定義圖示時，您可以轉換它們，例如使用 `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` 載入器、`自定義集合` 中的 `內嵌` 或來自 `@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()` 指令來獲取圖示的後設資料。

css

.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-'

匹配圖示規則的 Class 前綴。

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 工具中找到。

您可以查看此 repo，在 Vue 3 專案中使用此預設值：@iconify/tools/@iconify-demo/unocss。

閱讀清理圖示文章，了解更多 Iconify 的詳細資訊。

致謝

此預設值的靈感來自此議題，由 @husayt 建立。
基於此 PR 的成果，由 @userquin 貢獻。

圖示預設集 ​

安裝 ​

額外屬性 ​

模式覆蓋 ​

設定集合和圖示解析器 ​

瀏覽器 ​

打包器 ​

CDN ​

自定義 ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

圖示自定義 ​

全域自定義圖示轉換 ​

全域圖示自定義 ​

圖示/集合自定義 ​

指令 ​

選項 ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

進階自定義圖示集清理 ​

致謝 ​

圖示預設集

安裝

額外屬性

模式覆蓋

設定集合和圖示解析器

瀏覽器

打包器

CDN

自定義

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

圖示自定義

全域自定義圖示轉換

全域圖示自定義

圖示/集合自定義

指令

選項

scale

mode

prefix

extraProperties

warn

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

進階自定義圖示集清理

致謝