Skip to content

自定义图标 ​

17:43

ux-icon 默认渲染组件库内置的图标集。项目已有自己的图标字体(例如从 iconfont 平台导出的 ttf)时,可以把它接到 ux-icon 上,组件源码不用改。接入分三步,全部在应用侧完成。

TIP

组件库不内置任何自定义字体文件,字体资源和码点表由业务项目自己维护。

接入步骤 ​

步骤位置做什么
1项目 static/ 目录放入字体文件,保证打包时被带上
2App.uvue 全局样式声明 @font-face,font-family 即后续使用的前缀
3App.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 端不支持伪元素。前缀登记过后,组件会:

  1. 从登记表取该图标的码点;
  2. 把前缀内联为节点的 font-family,覆盖内置字体类样式(App 端类样式优先级不可靠,内联保证生效)。

业务侧不需要再写 .custom-icon-sun 这类图标类,也无需为自定义字体维护字体类样式。

兼容性 ​

平台支持说明
App✅ 支持字体文件放 static/ 随应用打包,由全局 @font-face 加载
H5✅ 支持url('/static/...') 可直接访问;部署在子路径时改为对应路径
微信小程序✅ 支持本地字体文件放 static/ 可正常显示(已实测);如遇不显示,检查字体路径与全局样式声明

注意事项 ​

  1. 字体文件必须放在 static/ 目录,其他目录的文件不会被打包带上。
  2. @font-face 的 font-family、registerIconFont 的前缀、custom-prefix 三处必须同名,任意一处不一致都会显示空白或回退内置图标。
  3. uicon 是内置图标的保留前缀,用它登记会被忽略并输出告警,请换一个前缀名。
  4. 同一前缀重复登记按最后一次整体替换,不做合并;增删图标后要重新登记完整码点表。
  5. 前缀未登记时不会报错:组件回退内置码点表与内置字体,自定义图标名通常显示为空白。
  6. 码点写成十六进制字符串(如 e712),不带 \u、0x 或 &#x; 包裹;格式写错显示空白。
  7. 图标名不要包含 /,也不要使用 data: 开头的 base64 形式,这两种会被当作图片图标处理。
  8. 自定义图标与内置图标可以在同一页面混用;内置图标不传 custom-prefix(默认 uicon)。
  9. App 端不要给图标写 ::before 类样式,组件已用 unicode 直显。

常见问题 ​

现象排查方向
图标空白三处前缀是否同名;name 是否在码点表里;字体文件是否在 static/;码点格式是否正确
显示成内置图标onLaunch 是否执行、前缀是否登记成功、是否误用了 uicon
打包后图标消失字体文件是否在 static/;构建产物是否清理了该文件
微信小程序不显示检查 src 是否为 /static/... 正确路径、@font-face 是否写在 App.uvue 全局样式里

下一步 ​