UnoCSS 通过 preset-icons 预设实现 CSS 类名形式的图标使用，无需注册组件即可在模板中通过 class="i-mdi-home" 引用任意图标。本文讲解 preset-icons 的配置、图标样式定制及与 unplugin-icons 的协作策略。
pnpm add -D @iconify/json// uno.config.ts
import { defineConfig, presetIcons, presetWind } from 'unocss'
export default defineConfig({
presets: [
presetWind(),
presetIcons({
prefix: 'i-',
extraProperties: {
'display': 'inline-block',
'vertical-align': 'middle',
},
}),
],
})<template>
<!-- 格式：i-{集合}-{图标名} -->
<span class="i-mdi-home text-xl text-blue-500" />
<span class="i-carbon-settings text-2xl" />
<button class="btn">
<span class="i-mdi-plus mr-1" />
新增
</button>
</template>| 模式 | CSS 实现 | 颜色控制 | 适用场景 |
|---|---|---|---|
| mask（默认） | mask-image + background-color | color / background-color | 单色图标 |
| background | background-image: url(svg) | 不可通过 CSS 修改 | 多色图标 |
配置渲染模式：
presetIcons({
mode: 'mask', // 或 'background-img'
})<!-- 通过 font-size 或 width/height -->
<span class="i-mdi-home text-3xl" />
<span class="i-mdi-home w-8 h-8" />// uno.config.ts
import fs from 'node:fs'
export default defineConfig({
presets: [
presetIcons({
customCollections: {
// 从本地 SVG 文件加载
'my-icons': {
logo: fs.readFileSync('./assets/logo.svg', 'utf-8'),
banner: fs.readFileSync('./assets/banner.svg', 'utf-8'),
},
},
}),
],
})使用：<span class="i-my-icons-logo" />
| 场景 | 推荐方案 |
|---|---|
| 纯装饰性图标（箭头、关闭） | UnoCSS preset-icons |
| 需要交互/动画的图标 | unplugin-icons（组件形式） |
| 图标按钮 | 两者均可 |
| 多色图标 | UnoCSS（background 模式） |
两者可共存于同一项目，按具体需求选择。
Q: 图标显示为方块或不显示？
确认 @iconify/json 已安装，且类名前缀与配置的 prefix 一致。默认前缀为 i-，类名格式为 i-{collection}-{icon}。
Q: 如何改变图标颜色？
mask 模式下直接设置 color 或 background-color：class="i-mdi-heart text-red-500"。background 模式无法通过 CSS 修改颜色。