Icons 插件

@pikacss/plugin-icons 讓你可以使用 Iconify 上的任何圖示作為原子化 CSS class——由 @iconify/utils 和 @unocss/preset-icons 提供支援。圖示在建置時期解析並以優化的 CSS data URI 嵌入，零執行期開銷。

安裝

此插件需要 @iconify/utils 作為 peer dependency：

pnpm add @pikacss/plugin-icons @iconify/utils

基本設定

// pika.config.ts
import { icons } from '@pikacss/plugin-icons'
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	plugins: [icons()],
	icons: {
		autoInstall: true,
	},
})

圖示命名慣例

圖示遵循以下模式：prefix + collection:name

預設前綴為 i-。使用 Iconify collection 和圖示名稱以冒號分隔來參照圖示：

簡寫	Collection	圖示
i-mdi:home	Material Design Icons	home
i-lucide:settings	Lucide	settings
i-carbon:warning	Carbon	warning
i-tabler:brand-github	Tabler Icons	brand-github

瀏覽可用圖示：Iconify。

使用方式

// pika() is available as a global function — no import needed

// Basic icon usage: prefix + collection:name
pika('i-mdi:home')
pika('i-mdi:account')
pika('i-lucide:settings')

// Force mask mode (icon inherits text color via currentColor)
pika('i-mdi:home?mask')

// Force background mode (icon keeps original colors)
pika('i-mdi:home?bg')

// Auto mode (default): uses mask if SVG contains currentColor, otherwise bg
pika('i-mdi:home?auto')

在 Vue 元件中：

<template>
	<div>
		<!-- Basic icon -->
		<span :class="pika('i-mdi:home')" />

		<!-- Force mask mode: icon color follows text color -->
		<span
			:class="pika('i-mdi:account?mask')"
			style="color: red;"
		/>

		<!-- Force bg mode: icon keeps its original SVG colors -->
		<span :class="pika('i-mdi:palette?bg')" />
	</div>
</template>

渲染模式

插件支援兩種渲染模式，決定如何將圖示 SVG 作為 CSS 套用：

Mask 模式

在 mask 模式中，SVG 作為 CSS mask 使用。圖示繼承元素的文字 color，便於主題化：

/* Mask mode: icon inherits text color via currentColor */
.pika-xxxx {
  --svg-icon: var(--pika-svg-icon-mdi-home);
  -webkit-mask: var(--svg-icon) no-repeat;
  mask: var(--svg-icon) no-repeat;
  -webkit-mask-size: 100% 100%;
  mask-size: 100% 100%;
  background-color: currentColor;
  color: inherit;
}

Background 模式

在 background 模式中，SVG 作為 CSS 背景圖片使用。圖示保留其原始 SVG 顏色：

/* Background mode: icon retains its original SVG colors */
.pika-xxxx {
  --svg-icon: var(--pika-svg-icon-mdi-home);
  background: var(--svg-icon) no-repeat;
  background-size: 100% 100%;
  background-color: transparent;
}

Auto 模式（預設）

當 mode 為 'auto'（預設值）時，插件自動選擇適合的模式：

• mask — 若 SVG 包含 currentColor
• bg — 否則

你可以在 shortcut 名稱後加上 ?mask、?bg 或 ?auto 來覆蓋每個圖示的模式。

自訂 Collection

你可以在設定中定義內嵌 SVG collection：

// pika.config.ts
import { icons } from '@pikacss/plugin-icons'
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	plugins: [icons()],
	icons: {
		collections: {
			// Inline SVG collection
			custom: {
				logo: '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="currentColor"/></svg>',
			},
		},
	},
})
// Usage: pika('i-custom:logo')

自訂處理器

使用 processor 選項在 CSS 屬性發出前修改它們：

// pika.config.ts
import { icons } from '@pikacss/plugin-icons'
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	plugins: [icons()],
	icons: {
		// Custom processor to modify icon CSS before output
		processor: (styleItem, meta) => {
			// Add display: inline-block to all icons
			styleItem.display = 'inline-block'
			styleItem['vertical-align'] = 'middle'

			// Access icon metadata
			console.log(`Processing icon: ${meta.collection}:${meta.name}, mode: ${meta.mode}`)
		},
	},
})

自動完成

提供圖示名稱清單以增強 IDE 自動完成建議：

// pika.config.ts
import { icons } from '@pikacss/plugin-icons'
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	plugins: [icons()],
	icons: {
		// Add custom entries to IDE autocomplete suggestions
		autocomplete: [
			'mdi:home',
			'mdi:account',
			'mdi:settings',
			'lucide:check',
			'lucide:x',
		],
	},
})

進階設定

// pika.config.ts
import { icons } from '@pikacss/plugin-icons'
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	plugins: [icons()],
	icons: {
		// Icon scale factor (default: 1)
		scale: 1.2,
		// Rendering mode: 'auto' | 'mask' | 'bg' (default: 'auto')
		mode: 'mask',
		// Shortcut prefix (default: 'i-')
		prefix: 'i-',
		// Auto-install icon packages on demand
		autoInstall: true,
		// Extra CSS properties applied to every icon
		extraProperties: {
			'display': 'inline-block',
			'vertical-align': 'middle',
		},
		// CSS unit for width/height (e.g., 'em', 'rem')
		unit: 'em',
		// CDN URL for loading icons (optional)
		// cdn: 'https://esm.sh/',
	},
})

設定參考

此插件以 icons 欄位擴充 EngineConfig：

interface EngineConfig {
  icons?: IconsConfig
}

IconsConfig 繼承 @unocss/preset-icons 的選項（排除 warn、layer 和 customFetcher），並加入 PikaCSS 特定的項目：

選項	型別	預設值	說明
scale	number	1	圖示縮放係數
mode	'auto' | 'mask' | 'bg'	'auto'	預設渲染模式
prefix	string | string[]	'i-'	圖示 shortcut 的 class 名稱前綴
collections	Record<string, IconifyJSON | (() => Awaitable<IconifyJSON>)>	—	自訂圖示 collection
customizations	IconCustomizations	—	轉換圖示（旋轉、調整大小等）
autoInstall	boolean	false	依需求自動安裝圖示套件
cdn	string	—	載入圖示的 CDN 基底 URL
unit	string	—	圖示尺寸的 CSS 單位（例如 'em'）
extraProperties	Record<string, string>	—	每個圖示的額外 CSS 屬性
processor	(styleItem: StyleItem, meta: Required<IconMeta>) => void	—	修改每個圖示的 CSS 輸出
autocomplete	string[]	—	額外的自動完成項目

運作原理

1. 插件註冊一個符合 regex 模式 /^(?:i-)([\w:-]+)(?:\?(mask|bg|auto))?$/ 的動態 shortcut
2. 當符合的 shortcut 被解析時，它會解析圖示名稱（collection:name 格式）
3. SVG 透過 @iconify/utils 和 @unocss/preset-icons 載入器載入
4. SVG 被編碼為 CSS data URI 並儲存為 CSS 變數（--<prefix>svg-icon-...），標記為 pruneUnused: true
5. 根據解析的模式，產生以 mask 為基礎或以背景為基礎的 CSS 屬性

下一步

• 繼續至 Reset 插件