UnoCSS 图标

通过 UnoCSS 的图标预设使用编译时优化的图标，实现零运行时开销。

🌐 关于 UnoCSS

UnoCSS 是一个即时原子化 CSS 引擎，其图标预设提供了编译时的图标解决方案。

📖 官方文档：https://unocss.dev/presets/icons

📦 安装配置

1. 安装依赖

# 安装 UnoCSS
npm install -D unocss

# 安装图标集合（按需选择）
npm install -D @iconify-json/ep @iconify-json/mdi @iconify-json/lucide

2. 配置 UnoCSS

创建 uno.config.ts：

import { defineConfig, presetIcons, presetUno } from 'unocss'

export default defineConfig({
  presets: [
    presetUno(),
    presetIcons({
      collections: {
        ep: () => import('@iconify-json/ep/icons.json').then(i => i.default),
        mdi: () => import('@iconify-json/mdi/icons.json').then(i => i.default),
        lucide: () => import('@iconify-json/lucide/icons.json').then(i => i.default),
      },
      extraProperties: {
        'display': 'inline-block',
        'vertical-align': 'middle',
      },
    }),
  ],
})

3. 配置构建工具

Vite 配置：

// vite.config.ts
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
  ],
}

引入样式：

// main.ts
import 'uno.css'

🚀 基本使用

<script setup>
import { QxsIcon } from '@qxs-bns/components'
</script>

<template>
  <!-- Element Plus 图标 -->
  <QxsIcon icon="i-ep:home" :size="24" />
  <QxsIcon icon="i-ep:user" color="#409eff" />
  
  <!-- Material Design Icons -->
  <QxsIcon icon="i-mdi:home" :size="32" />
  <QxsIcon icon="i-mdi:account" color="#67c23a" />
  
  <!-- Lucide 图标 -->
  <QxsIcon icon="i-lucide:home" :rotate="45" />
  <QxsIcon icon="i-lucide:user" flip="horizontal" />
</template>

🔍 图标命名规则

UnoCSS 图标使用 i-集合名:图标名 的格式（注意包含冒号）：

• i-ep:home - Element Plus 的 home 图标
• i-mdi:account - Material Design Icons 的 account 图标
• i-lucide:user - Lucide 的 user 图标

与 CSS 类图标的区别

类型	格式	示例	说明
UnoCSS 图标	i-集合名:图标名	i-ep:home-filled	包含冒号，编译时生成
CSS 类图标	i-自定义名称	i-custom-home	不包含冒号，需要自定义 CSS

<template>
  <!-- UnoCSS 图标 - 自动生成样式 -->
  <QxsIcon icon="i-ep:home-filled" />

  <!-- CSS 类图标 - 需要自定义样式 -->
  <QxsIcon icon="i-custom-home" />
</template>

🎯 优势

• 零运行时：编译时生成 CSS，无 JavaScript 开销
• 按需生成：只生成使用的图标样式
• 原子化：与 UnoCSS 原子化 CSS 完美集成
• 类型安全：可配置 TypeScript 类型提示

⚠️ 注意事项

• 构建配置：需要正确配置 UnoCSS 和图标预设
• 图标集合：需要安装对应的 @iconify-json/* 包
• 字符串类型：图标名为字符串，需要手动管理
• 命名格式：必须使用 i-集合名:图标名 格式，包含冒号
• 类型区分：不要与自定义 CSS 类图标（i-custom-name）混淆

📚 更多配置

详细的 UnoCSS 图标配置选项：

👉 UnoCSS Icons Preset 文档

🔧 高级功能

关于 QxsIcon 组件的高级功能，请参考：

👉 QxsIcon 组件文档