uni.loadFontFace(options) @loadfontface

展示全部

# uni.loadFontFace(options)

动态加载网络字体

# loadFontFace 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.0	4.41	√	4.10	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

options

LoadFontFaceOptions

是

名称

类型

必备

默认值

兼容性

描述

global

boolean

否

是否全局生效。微信小程序 '2.10.0'起支持全局生效，需在 app.vue 中调用。

family

string

是

定义的字体名称

source

string.FontURIString

是

字体资源的地址, App-Android 平台不支持 woff、woff2 格式字体文件

desc

LoadFontFaceOptionDesc

否

可选的字体描述符

名称	类型	必备	默认值	兼容性
style	string	否	-	-
weight	string	否	-	-
variant	string	否	-	-

success

(result: AsyncApiSuccessResult) => void

否

接口调用成功的回调函数

fail

(error: LoadFontFaceFail) => void

否

接口调用失败的回调函数

complete

(res: AsyncApiResult) => void

否

接口调用结束的回调函数（调用成功、失败都会执行）

scopes

Array<any>

否

字体作用范围，可选值为 webview / native，默认 webview，设置 native 可在 Canvas 2D 下使用

# AsyncApiSuccessResult 的属性值

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	-	-

# LoadFontFaceFail 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

number

是

错误码

合法值	兼容性	描述
4	-	框架内部异常
99	-	page is not ready
101	-	参数错误
100001	-	family is null
100002	-	source is null
200001	-	local font not found
300001	-	same source task is loading
300002	-	download fail

status

string

否

加载字体结果

errSubject

string

是

统一错误主题（模块）名称

data

any

否

错误信息中包含的数据

cause

Error

否

源错误信息，可以包含多个错误，详见SourceError

errMsg

string

是

# AsyncApiResult 的属性值

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	-	-

# 返回值

类型

必备

Promise<AsyncApiSuccessResult>

否

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	-	-

# 注意事项

app-ios 平台 加载字体一定是全局生效，不支持通过global属性设置为非全局生效

source 属性指定自定义字体路径，支持本地文件路径、远程地址，app 平台 4.33 版本开始支持 base64 格式数据；必须使用url()包裹。可能某些平台不包裹也可以生效，但标准规范是包裹，按标准写法才能全端生效。如下：

uni.loadFontFace({
  global: true,
  family: 'UniFontFamily',
  source: "url('/static/font/uni.ttf')", //需使用url方法包裹。本地字体请放在/static目录下，否则打包时不会把字体文件打进去。也支持网络字体
  success() {
    console.log('global loadFontFace uni.ttf success')
  },
  fail(error) {
    console.warn('global loadFontFace uni.ttf fail', error.errMsg)
  },
})

HarmonyOS 注意事项
1. 使用 @ohos.font 实现
- ttf
- otf
1. base64 格式字体是通过转换成 buffer 保存在磁盘上并引入实现的，因此页面上过多的使用 base64 可能会有性能问题
2. HarmonyOS 字体都是全局生效的

不同平台支持的字体格式不同，另见css字体

# 示例

hello uni-app x

Template

Script

<template>
  <page-head title="loadFontFace"></page-head>
  <view class="uni-padding-wrap">
    <text class="font-size-20">全局加载字体：</text>
    <text class="font-size-20 line-height-40" style="font-family: UniFontFamily">font-family: uni.ttf</text>
    <view style="flex-direction: row;">
      <!-- 微信小程序只支持加载网络字体 -->
      <!-- #ifdef MP-WEIXIN -->
      <text class="font-size-20" style="font-family: UniFontFamily2;">{{uniIcon3}}</text>
      <text class="icon-text">\ue102</text>
      <!-- #endif -->
      <!-- #ifndef MP-WEIXIN -->
      <text class="font-size-20" style="font-family: UniFontFamily;">{{uniIcon1}}</text>
      <text class="icon-text">\ue100</text>
      <text class="font-size-20" style="font-family: UniFontFamily;">{{uniIcon2}}</text>
      <text style="margin-left:5px;line-height:22px;">\ue101</text>
      <!-- #endif -->
    </view>
    <!-- #ifndef APP-HARMONY -->
    <text class="uni-common-mt font-size-20">非全局加载字体：</text>
    <!-- #endif -->
    <text class="font-size-20 line-height-40">font-family: uni.ttf(base64格式)</text>
    <view style="flex-direction: row;">
      <text class="font-size-20" style="font-family: UniFontFamily2;">{{uniIcon3}}</text>
      <text class="icon-text">\ue102</text>
    </view>
    <text class="font-size-20 line-height-40" style="font-family: AlimamaDaoLiTiTTF">font-family: 阿里妈妈刀隶体-ttf
      (网络字体下载后生效)</text>
    <text class="font-size-20 line-height-40" style="font-family: AlimamaDaoLiTiOTF">font-family:
      阿里妈妈刀隶体-otf</text>
    <text class="item" style="font-family: AlimamaDaoLiTiWOFF">font-family: 阿里妈妈刀隶体-woff</text>
    <text class="item" style="font-family: AlimamaDaoLiTiWOFF2">font-family: 阿里妈妈刀隶体-woff2</text>
    <button class="uni-btn" @click="navigateToChild">跳转子页面测试字体生效范围</button>
  </view>
</template>


<style>
  .font-size-20 {
    font-size: 20px;
  }

  .line-height-40 {
    line-height: 40px;
  }

  .icon-text{
    margin-left:5px;
    margin-right: 20px;
    line-height:22px;
  }
</style>