自定义图标
17:43ux-icon 默认渲染组件库内置的图标集。项目已有自己的图标字体(例如从 iconfont 平台导出的 ttf)时,可以把它接到 ux-icon 上,组件源码不用改。接入分三步,全部在应用侧完成。
TIP
组件库不内置任何自定义字体文件,字体资源和码点表由业务项目自己维护。
接入步骤
| 步骤 | 位置 | 做什么 |
|---|---|---|
| 1 | 项目 static/ 目录 | 放入字体文件,保证打包时被带上 |
| 2 | App.uvue 全局样式 | 声明 @font-face,font-family 即后续使用的前缀 |
| 3 | App.uvue 的 onLaunch | 用 $u.registerIconFont(prefix, icons) 登记码点表 |
三步里的前缀(@font-face 的 font-family、registerIconFont 的第一个参数、custom-prefix 的取值)必须是同一个字符串。
准备字体与码点表
字体文件放在 static/ 目录,例如 static/iconfont.ttf。从图标库导出的 CSS 里能读到每个图标的码点:
css
.custom-icon-sun:before { content: "\e712"; }取 content 中的十六进制值、去掉反斜杠,整理成码点表(键为图标名,值为十六进制字符串):
ts
// iconfont.ts
export const customIconFont: JsonObject = {
'sun': 'e712',
'moon': 'e609',
'eye': 'e68e'
}声明字体并登记
在 App.uvue 的全局样式里声明字体,并在 onLaunch 中登记码点表:
vue
<!-- App.uvue -->
<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x'
import { customIconFont } from './iconfont.ts'
onLaunch(() => {
$u.registerIconFont('custom-icon', customIconFont)
})
</script>
<style>
@font-face {
font-family: 'custom-icon';
src: url('/static/iconfont.ttf') format('truetype');
font-weight: normal;
font-style: normal;
}
</style>登记要在图标渲染之前完成,放在 onLaunch 里最稳妥。
在页面中使用
vue
<template>
<view class="icon-row">
<ux-icon name="sun" size="20" custom-prefix="custom-icon"></ux-icon>
<ux-icon name="eye" size="20" color="#2979ff" custom-prefix="custom-icon"></ux-icon>
</view>
</template>
<style scoped>
.icon-row {
display: flex;
flex-direction: row;
align-items: center;
}
</style>name 取码点表的键;size、color、type、bold、top 等属性的行为与内置图标一致。
列举全部图标
码点表的键就是图标清单,可以直接遍历渲染:
ts
import { customIconFont } from '@/iconfont.ts'
const customIconList: string[] = JsonObject.keys(customIconFont)vue
<view class="icon-grid">
<view class="icon-item" v-for="(item, index) in customIconList" :key="index">
<ux-icon :name="item" size="20" color="#2979ff" custom-prefix="custom-icon"></ux-icon>
<text class="icon-name">{{ item }}</text>
</view>
</view>实现说明
字体图标用 unicode 直显,不依赖 ::before 伪元素——App 端不支持伪元素。前缀登记过后,组件会:
- 从登记表取该图标的码点;
- 把前缀内联为节点的
font-family,覆盖内置字体类样式(App 端类样式优先级不可靠,内联保证生效)。
业务侧不需要再写 .custom-icon-sun 这类图标类,也无需为自定义字体维护字体类样式。
兼容性
| 平台 | 支持 | 说明 |
|---|---|---|
| App | ✅ 支持 | 字体文件放 static/ 随应用打包,由全局 @font-face 加载 |
| H5 | ✅ 支持 | url('/static/...') 可直接访问;部署在子路径时改为对应路径 |
| 微信小程序 | ✅ 支持 | 本地字体文件放 static/ 可正常显示(已实测);如遇不显示,检查字体路径与全局样式声明 |
注意事项
- 字体文件必须放在
static/目录,其他目录的文件不会被打包带上。 @font-face的font-family、registerIconFont的前缀、custom-prefix三处必须同名,任意一处不一致都会显示空白或回退内置图标。uicon是内置图标的保留前缀,用它登记会被忽略并输出告警,请换一个前缀名。- 同一前缀重复登记按最后一次整体替换,不做合并;增删图标后要重新登记完整码点表。
- 前缀未登记时不会报错:组件回退内置码点表与内置字体,自定义图标名通常显示为空白。
- 码点写成十六进制字符串(如
e712),不带\u、0x或&#x;包裹;格式写错显示空白。 - 图标名不要包含
/,也不要使用data:开头的 base64 形式,这两种会被当作图片图标处理。 - 自定义图标与内置图标可以在同一页面混用;内置图标不传
custom-prefix(默认uicon)。 - App 端不要给图标写
::before类样式,组件已用 unicode 直显。
常见问题
| 现象 | 排查方向 |
|---|---|
| 图标空白 | 三处前缀是否同名;name 是否在码点表里;字体文件是否在 static/;码点格式是否正确 |
| 显示成内置图标 | onLaunch 是否执行、前缀是否登记成功、是否误用了 uicon |
| 打包后图标消失 | 字体文件是否在 static/;构建产物是否清理了该文件 |
| 微信小程序不显示 | 检查 src 是否为 /static/... 正确路径、@font-face 是否写在 App.uvue 全局样式里 |