Appearance
QxsIcon
qxs-icon 是 @qxs-bns/components 里的统一图标入口，面向跨框架宿主直接接字符串型图标来源，支持 Iconify、UnoCSS、CSS 类、图片 URL 和 SVG Sprite。
qxs-icon 接入
图标能力现在已经统一收口到这一个组件，不再单独维护 @qxs-bns/icons 包和 Icons 分组。
这页先解决“组件库里的图标能力怎么接起来”，再区分不同图标来源。
如果你的宿主不是纯 Vue 组件树，而是原生 HTML、React、Vue 混合接入，或者你就是希望统一走 Custom Element，那么直接使用 qxs-icon。
图标接入口径已更新
如果你的页面原来直接导入 Home、Delete 这类 Vue 图标组件，现在需要改成统一使用 qxs-icon。
- 在线图标：优先用 Iconify 名称，如
ep:home-filled - 原子类图标：用 UnoCSS / iconfont / 自定义 CSS 类
- 本地图标资产：用图片 URL 或 SVG Sprite
基础用法
loading
ts
import '@qxs-bns/components/icon'如果你已经全量引入：
ts
import '@qxs-bns/components'使用说明
loading
推荐输入形式
WC 版优先推荐传字符串型图标值。
这样原生 HTML、Vue、React 或任意宿主都能直接复用同一套 icon 字段。
CSS 类 / UnoCSS 图标依赖宿主全局样式
qxs-icon 为了兼容 iconfont、UnoCSS 和自定义类图标，使用的是 light DOM 渲染。
如果你传的是 CSS 类图标，宿主需要确保对应样式已经加载到当前文档。
Iconify 在 WC 版里走远程 SVG
WC 版没有依赖 @iconify/vue，而是把 ep:home-filled 这类图标名转换成远程 SVG 地址来渲染。
如果你的场景不能接受在线请求，优先使用 UnoCSS、本地 CSS 类或 SVG Sprite。
常见场景
loading
本地 SVG Sprite 接入
如果你希望继续使用本地 SVG 资源，推荐在宿主里维护自己的 Sprite，再由 qxs-icon 统一消费。
bash
pnpm add -D vite-plugin-svg-iconsts
// vite.config.ts
import path from 'node:path'
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
export default {
plugins: [
createSvgIconsPlugin({
iconDirs: [path.resolve(process.cwd(), 'src/assets/icons')],
symbolId: 'icon-[name]',
}),
],
}ts
// main.ts
import 'virtual:svg-icons-register'html
<qxs-icon icon="home" local-icon-prefix="icon-"></qxs-icon>宿主接入示例
loading
API
属性
| Name | Description | Type | Default |
|---|---|---|---|
icon | 图标值。支持 Iconify 名称、UnoCSS 类名、CSS 类名、图片地址和 SVG Sprite 名称 | string | '' |
size | 图标尺寸。纯数字会自动补成 px | string | number | - |
color | 图标颜色 | string | '' |
flip | 翻转方向 | 'horizontal' | 'vertical' | 'both' | '' | '' |
rotate | 旋转角度，单位为度 | number | 0 |
local-icon-prefix | 本地 SVG Sprite 的前缀 | string | 'icon-' |
fallback | 图片加载失败时显示的后备 CSS 类名 | string | '' |
loading | 图片加载中显示的占位 CSS 类名 | string | '' |
事件
| Name | Description |
|---|---|
| - | qxs-icon 不额外抛出业务事件 |
方法
| Name | Description |
|---|---|
| - | qxs-icon 不提供公开实例方法 |
插槽
| Name | Description |
|---|---|
| - | qxs-icon 不提供具名插槽 |
图标来源类型
| 来源类型 | 示例 | 说明 |
|---|---|---|
| Iconify | icon="ep:home-filled" | 适合快速接第三方图标库 |
| UnoCSS 图标 | icon="i-ep:home-filled" | 依赖宿主全局 UnoCSS 图标规则 |
| CSS 类图标 | icon="fas fa-home" | 兼容 iconfont 或自定义类名 |
| 图片地址 | icon="/assets/logo.png" | 会走图片加载逻辑，可配 fallback / loading |
| SVG Sprite | icon="home" | 最终会拼成 #icon-home 形式的引用 |
常见问题
为什么 CSS 类图标在页面里不显示？
因为 qxs-icon 不会替宿主注入 iconfont 或 UnoCSS 规则。
如果你传的是类名形式的图标，宿主需要自己先把对应样式加载进页面。
为什么这里没有把 Vue 图标组件作为主输入形式？
因为当前 @qxs-bns/components 已经统一到跨框架宿主接入方向。
如果把 Vue 组件引用当成主要输入形式，调用方又会重新依赖 Vue 运行时，这和 qxs-icon 的定位不一致。
是否支持把 Vue 组件或 DOM 节点直接传给 icon？
不支持。qxs-icon 现在只接受字符串型图标来源；如果你传入组件对象或 DOM 节点，组件会按空值处理，不再尝试渲染。
为什么不再单独提供 @qxs-bns/icons？
因为图标接入已经统一到 qxs-icon，再保留一个只面向 Vue 组件树的图标包会让使用方式分叉。
现在统一只保留字符串型图标入口，文档、接入方式和跨框架宿主语义都更一致。