qxs-bns

Appearance

CSS 类图标 ​

使用自定义 CSS 类作为图标，兼容现有的图标字体和 CSS 图标系统。QxsIcon 组件智能识别 CSS 类图标，支持多种格式和多类名组合。

🚀 基本使用 ​

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

<template>
  <!-- Font Awesome 图标（多类名） -->
  <QxsIcon icon="fas fa-home" :size="24" />
  <QxsIcon icon="far fa-user" color="#409eff" />
  <QxsIcon icon="fab fa-github" :size="32" />

  <!-- Iconfont 图标（多类名） -->
  <QxsIcon icon="iconfont icon-home" :size="24" />
  <QxsIcon icon="iconfont icon-user" :size="32" />

  <!-- 自定义 CSS 类（i- 前缀） -->
  <QxsIcon icon="i-custom-home" :size="24" />
  <QxsIcon icon="i-custom-user" color="#67c23a" />

  <!-- 其他自定义 CSS 类 -->
  <QxsIcon icon="my-custom-icon" color="#409eff" />
  <QxsIcon icon="demo-icon icon-square" :size="20" />
</template>

🔍 图标类型识别 ​

QxsIcon 组件会自动识别以下 CSS 类图标格式：

1. 以 i- 开头的自定义类（不含冒号） ​

vue
<QxsIcon icon="i-custom-home" />
<QxsIcon icon="i-brand-logo" />
<QxsIcon icon="i-my-icon" />

2. 多类名组合（包含空格） ​

vue
<QxsIcon icon="fas fa-home" />
<QxsIcon icon="iconfont icon-user" />
<QxsIcon icon="material-icons md-home" />

3. 单个自定义类名 ​

vue
<QxsIcon icon="my-custom-icon" />
<QxsIcon icon="company-logo" />

注意：i-provider:name 格式（包含冒号）会被识别为 UnoCSS 图标，而不是 CSS 类图标。

🎨 常见图标字体集成 ​

Font Awesome ​

vue
<!-- 1. 引入 Font Awesome CSS -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">

<!-- 2. 使用图标 -->
<template>
  <QxsIcon icon="fas fa-home" :size="24" />
  <QxsIcon icon="far fa-user" color="#409eff" />
  <QxsIcon icon="fab fa-github" :size="32" />
</template>

Iconfont (阿里巴巴矢量图标库) ​

vue
<!-- 1. 引入 Iconfont CSS -->
<link rel="stylesheet" href="//at.alicdn.com/t/font_xxx.css">

<!-- 2. 使用图标 -->
<template>
  <QxsIcon icon="iconfont icon-home" :size="24" />
  <QxsIcon icon="iconfont icon-user" color="#67c23a" />
</template>

🔧 自定义 CSS 图标 ​

创建自定义图标类 ​

方式一：使用 i- 前缀（推荐） ​

css
/* 自定义图标样式 - 使用 i- 前缀 */
.i-custom-home::before {
  content: "🏠";
  font-style: normal;
}

.i-custom-user::before {
  content: "👤";
  font-style: normal;
}

.i-custom-setting::before {
  content: "⚙️";
  font-style: normal;
}

方式二：使用 SVG 背景 ​

css
.i-custom-logo {
  background-image: url('data:image/svg+xml;utf8,<svg viewBox="0 0 24 24"><path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/></svg>');
  background-size: contain;
  background-repeat: no-repeat;
  background-position: center;
  display: inline-block;
  width: 1em;
  height: 1em;
}

方式三：多类名组合 ​

css
/* 基础类 */
.demo-icon {
  display: inline-block;
  width: 1em;
  height: 1em;
  text-align: center;
  line-height: 1;
}

/* 具体图标 */
.icon-square::before {
  content: "■";
  color: currentColor;
}

.icon-circle::before {
  content: "●";
  color: currentColor;
}

.icon-triangle::before {
  content: "▲";
  color: currentColor;
}

在组件中使用 ​

vue
<template>
  <!-- 使用 i- 前缀的自定义图标 -->
  <QxsIcon icon="i-custom-home" :size="24" />
  <QxsIcon icon="i-custom-user" color="#e6a23c" />
  <QxsIcon icon="i-custom-setting" :size="32" />

  <!-- 使用多类名组合 -->
  <QxsIcon icon="demo-icon icon-square" :size="20" />
  <QxsIcon icon="demo-icon icon-circle" color="#67c23a" />
  <QxsIcon icon="demo-icon icon-triangle" color="#f56c6c" />
</template>

🎯 使用场景 ​

1. 兼容旧项目 ​

vue
<template>
  <!-- 保持与现有图标系统的兼容 -->
  <QxsIcon icon="legacy-icon-class" :size="24" />
</template>

2. 第三方图标库 ​

vue
<template>
  <!-- 使用第三方图标库 -->
  <QxsIcon icon="material-icons">home</QxsIcon>
  <QxsIcon icon="bootstrap-icons bi-house" :size="24" />
</template>

3. 自定义图标系统 ​

vue
<template>
  <!-- 企业内部图标系统 -->
  <QxsIcon icon="company-icon-dashboard" :size="24" />
  <QxsIcon icon="company-icon-analytics" color="#409eff" />
</template>

📚 热门图标字体库 ​

图标库CSS 类格式官方链接
Font Awesomefas fa-homefontawesome.com
Material Iconsmaterial-iconsfonts.google.com/icons
Bootstrap Iconsbi bi-houseicons.getbootstrap.com
Iconfonticonfont icon-xxxiconfont.cn

🔄 类型识别优先级 ​

QxsIcon 组件按以下优先级识别图标类型：

  1. UnoCSS 图标：i-provider:name 格式（包含冒号）
  2. 自定义 CSS 类：i- 开头且不包含冒号
  3. Iconify 图标：provider:name 格式（不以 i- 开头）
  4. SVG Sprite：单个单词，只包含字母、数字、下划线、连字符
  5. CSS 类图标：其他所有格式（包括多类名）

示例对比 ​

vue
<template>
  <!-- UnoCSS 图标 -->
  <QxsIcon icon="i-ep:home-filled" />

  <!-- 自定义 CSS 类 -->
  <QxsIcon icon="i-custom-home" />

  <!-- Iconify 图标 -->
  <QxsIcon icon="ep:home" />

  <!-- SVG Sprite -->
  <QxsIcon icon="home" />

  <!-- CSS 类图标（多类名） -->
  <QxsIcon icon="fas fa-home" />
</template>

⚠️ 注意事项 ​

类型识别 ​

  • 冒号区分：i-custom:icon 会被识别为 UnoCSS 图标，而 i-custom-icon 是 CSS 类图标
  • 空格处理：包含空格的字符串会被自动拆分为多个类名
  • 命名规范：建议使用 i- 前缀来明确标识自定义 CSS 类图标

样式冲突 ​

  • 命名空间：使用明确的类名前缀避免冲突
  • CSS 优先级：注意 CSS 选择器的优先级
  • 样式隔离：在组件中使用 scoped 样式

性能考虑 ​

  • 字体加载：图标字体可能影响首屏加载时间
  • 缓存策略：确保图标字体文件被正确缓存
  • 回退方案：提供字体加载失败时的回退方案

兼容性 ​

  • 浏览器支持：确保目标浏览器支持使用的 CSS 特性
  • 字体格式：提供多种字体格式以支持不同浏览器

🔧 高级配置 ​

关于 QxsIcon 组件的高级功能（旋转、翻转、颜色等），请参考：

👉 QxsIcon 组件文档

💡 最佳实践 ​

命名规范 ​

  1. 使用 i- 前缀：自定义 CSS 类图标建议使用 i- 前缀
  2. 避免冒号：自定义类名中不要使用冒号，以免与 UnoCSS 图标冲突
  3. 语义化命名：使用有意义的类名，如 i-custom-home 而不是 i-icon1

代码组织 ​

vue
<template>
  <!-- ✅ 推荐：明确的前缀和语义化命名 -->
  <QxsIcon icon="i-custom-home" />
  <QxsIcon icon="i-brand-logo" />

  <!-- ✅ 推荐：标准的多类名格式 -->
  <QxsIcon icon="fas fa-home" />
  <QxsIcon icon="iconfont icon-user" />

  <!-- ❌ 不推荐：容易与其他类型混淆 -->
  <QxsIcon icon="i-ep:home" />  <!-- 这是 UnoCSS 图标 -->
  <QxsIcon icon="home" />       <!-- 这是 SVG Sprite -->
</template>

样式管理 ​

  1. 统一管理：建立统一的图标类命名规范
  2. 文档维护：维护图标类的使用文档和示例
  3. 版本控制：对图标字体文件进行版本控制
  4. 性能优化：只加载需要的图标字体，避免加载整个图标库

错误处理 ​

vue
<template>
  <!-- 为图标提供回退方案 -->
  <QxsIcon
    icon="i-custom-icon"
    :fallback="'i-ep:picture'"
    @error="handleIconError"
  />
</template>

<script setup>
function handleIconError() {
  console.warn('图标加载失败，请检查 CSS 样式是否正确引入')
}
</script>

Released under the MIT License.

Copyright © 2024-present The Muse Catcher