uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
uni-app x
uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
简体中文
API
uni.loadFontFace(options)
loadFontFace 兼容性
参数
LoadFontFaceSuccess 的属性值
LoadFontFaceFail 的属性值
LoadFontFaceComplete 的属性值
返回值
注意事项
示例
参见
展示全部

# uni.loadFontFace(options) GitCodeGitHub

动态加载网络字体

# loadFontFace 兼容性

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

# 参数

名称 类型 必填 默认值 兼容性 描述
options LoadFontFaceOptions 是 -
-
名称 类型 必备 默认值 兼容性 描述
global boolean 否 -
是否全局生效微信小程序 '2.10.0'起支持全局生效。需在 app.uvue 中调用。
family string 是 -
定义的字体名称
source string.FontURIString 是 -
字体资源的地址, App-Android 平台不支持 woff、woff2 格式字体文件
desc LoadFontFaceOptionDesc 否 -
可选的字体描述符
名称 类型 必备 默认值 兼容性 描述
style string 否 -
-
weight string 否 -
-
variant string 否 -
-
success (result: LoadFontFaceSuccess) => void 否 -
接口调用成功的回调函数
fail (error: LoadFontFaceFail) => void 否 -
接口调用失败的回调函数
complete (res: LoadFontFaceComplete) => void 否 -
接口调用结束的回调函数（调用成功、失败都会执行）
scopes Array<any> 否 -
字体作用范围，可选值为 webview / native / skyline，默认全选，设置 native 可在 Canvas 2D 下使用

# LoadFontFaceSuccess 的属性值

名称 类型 必备 默认值 兼容性 描述
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 是 -
-

# LoadFontFaceComplete 的属性值

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

# 返回值

类型 必备
Promise<LoadFontFaceSuccess> 否
名称 类型 必备 默认值 兼容性 描述
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 alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

示例

<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>
<script>
  export default {
    data() {
      return {
        uniIcon1: '\ue100',
        uniIcon2: '\ue101',
        uniIcon3: '\ue102',
        successTriggeredNum: 0,
      }
    },
  onLoad() {
      const self = this
      uni.loadFontFace({
        global: true,
        family: 'UniFontFamily',
        source: "url('/static/font/uni.ttf')",
        success() {
          self.successTriggeredNum++;
          console.log('global loadFontFace uni.ttf success')
        },
        fail(error) {
          console.warn('global loadFontFace uni.ttf fail', error.errMsg)
        },
      })
      uni.loadFontFace({
        family: 'UniFontFamily2',
        source: "url(data:font/ttf;charset=utf-8;base64,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)",
        success() {
          self.successTriggeredNum++;
          console.log('loadFontFace uni.ttf(base64 format) success')
        },
        fail(error) {
          console.warn('loadFontFace uni.ttf(base64 format) fail', error.errMsg)
        },
      })
      uni.loadFontFace({
        family: 'AlimamaDaoLiTiTTF',
        source:
          "url('https://qiniu-web-assets.dcloud.net.cn/uni-app-x/static/font/AlimamaDaoLiTi.ttf')",
        success() {
          self.successTriggeredNum++;
          console.log('loadFontFace Remote AlimamaDaoLiTi.ttf success')
        },
        fail(error) {
          console.warn('loadFontFace Remote AlimamaDaoLiTi.ttf fail', error.errMsg)
        },
      })
      uni.loadFontFace({
        family: 'AlimamaDaoLiTiOTF',
        source: "url('/static/font/AlimamaDaoLiTi.otf')",
        success() {
          self.successTriggeredNum++;
          console.log('loadFontFace AlimamaDaoLiTi.otf success')
        },
        fail(error) {
          console.warn('loadFontFace AlimamaDaoLiTi.otf fail', error.errMsg)
        },
      })
      uni.loadFontFace({
        family: 'AlimamaDaoLiTiWOFF',
        source: "url('/static/font/AlimamaDaoLiTi.woff')",
        success() {
          self.successTriggeredNum++;
          console.log('loadFontFace AlimamaDaoLiTi.woff success')
        },
        fail(error) {
          console.warn('loadFontFace AlimamaDaoLiTi.woff fail', error.errMsg)
        },
      })
      uni.loadFontFace({
        family: 'AlimamaDaoLiTiWOFF2',
        source: "url('/static/font/AlimamaDaoLiTi.woff2')",
        success() {
          self.successTriggeredNum++;
          console.log('loadFontFace AlimamaDaoLiTi.woff2 success')
        },
        fail(error) {
          console.warn('loadFontFace AlimamaDaoLiTi.woff2 fail', error.errMsg)
        },
      })
    },
    methods: {
      navigateToChild() {
        uni.navigateTo({
          url: '/pages/API/load-font-face/load-font-face-child',
        })
      },
    },
  }
</script>

<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>

# 参见

# 通用类型

# GeneralCallbackResult

名称 类型 必备 默认值 兼容性 描述
errMsg string 是 -
错误信息
本页导读
uni.loadFontFace(options)
loadFontFace 兼容性
参数
LoadFontFaceSuccess 的属性值
LoadFontFaceFail 的属性值
LoadFontFaceComplete 的属性值
返回值
注意事项
示例
参见
通用类型
GeneralCallbackResult