# uni.loadFontFace(options)

动态加载网络字体

# 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>
  <page-intro content="本页演示 uni.loadFontFace:全局与非全局加载字体(本地、base64、网络),展示各字体效果;可跳转子页测试字体生效范围。"></page-intro>
  <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;">{{data.uniIcon3}}</text>
      <text class="icon-text">\ue102</text>
      <!-- #endif -->
      <!-- #ifndef MP-WEIXIN -->
      <text class="font-size-20" style="font-family: UniFontFamily;">{{data.uniIcon1}}</text>
      <text class="icon-text">\ue100</text>
      <text class="font-size-20" style="font-family: UniFontFamily;">{{data.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;">{{data.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>

    <!-- #ifdef APP-IOS -->
    <text class="item" style="font-family: AlimamaDaoLiTiWOFF">font-family: 阿里妈妈刀隶体-woff</text>
    <text class="item" style="font-family: AlimamaDaoLiTiWOFF2">font-family: 阿里妈妈刀隶体-woff2</text>
    <!-- #endif -->
    <button class="uni-btn" @click="navigateToChild">跳转子页面测试字体生效范围</button>
  </view>
</template>
<script setup lang="uts">
  type DataType = {
    uniIcon1: string;
    uniIcon2: string;
    uniIcon3: string;
    successTriggeredNum: number;
    loadFontStatus: Array<boolean>;
  }

  const data = reactive({
    uniIcon1: '\ue100',
    uniIcon2: '\ue101',
    uniIcon3: '\ue102',
    successTriggeredNum: 0,
    // 字体加载状态数组
    loadFontStatus: [false, false, false, false],
  } as DataType)

  const navigateToChild = () => {
    uni.navigateTo({
      url: '/pages/API/load-font-face/load-font-face-child',
    })
  }

  onLoad(() => {
    let status1 = false
    uni.loadFontFace({
      global: true,
      family: 'UniFontFamily',
      source: "url('/static/font/uni.ttf')",
      success() {
        data.successTriggeredNum++;
        status1 = true;
      },
      fail(error) {
        console.warn('global loadFontFace uni.ttf fail', error.errMsg)
        status1 = false;
      },
      complete: () => {
        console.log('uni-font-family complete')
        // 在complete中检查状态,如果都为true则认为测试通过
        if (status1 == true) {
          data.loadFontStatus[0] = true;
        }
      }
    })
    let status2 = false
    uni.loadFontFace({
      family: 'UniFontFamily2',
      source: "url(data:font/ttf;charset=utf-8;base64,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)",
      success() {
        data.successTriggeredNum++;
        status2 = true;
        console.log('loadFontFace uni.ttf(base64 format) success')
      },
      fail(error) {
        status2 = false;
        console.warn('loadFontFace uni.ttf(base64 format) fail', error.errMsg)
      },
      complete:()=> {
        // 在complete中检查状态,如果都为true则认为测试通过
        if (status2 == true) {
          data.loadFontStatus[1] = true;
        }
      }
    })
    // 重置回调状态
    let status3 = false
    uni.loadFontFace({
      family: 'AlimamaDaoLiTiTTF',
      source:
        "url('https://qiniu-web-assets.dcloud.net.cn/uni-app-x/static/font/AlimamaDaoLiTi.ttf')",
      success() {
        data.successTriggeredNum++;
        status3 = true;
        console.log('loadFontFace Remote AlimamaDaoLiTi.ttf success')
      },
      fail(error) {
        status3 = false;
        console.warn('loadFontFace Remote AlimamaDaoLiTi.ttf fail', error.errMsg)
      },
      complete:()=> {
        if (status3 == true) {
          data.loadFontStatus[2] = true;
        }
      }
    })
    // 重置回调状态
    let status4 = false
    uni.loadFontFace({
      family: 'AlimamaDaoLiTiOTF',
      source: "url('/static/font/AlimamaDaoLiTi.otf')",
      success() {
        data.successTriggeredNum++;
        status4 = true;
        console.log('loadFontFace AlimamaDaoLiTi.otf success')
      },
      fail(error) {
        status4 = false;
        console.warn('loadFontFace AlimamaDaoLiTi.otf fail', error.errMsg)
      },
      complete:()=> {
        if (status4 == true) {
          data.loadFontStatus[3] = true;
        }
      }
    })
    // #ifdef APP-IOS
    data.loadFontStatus.push(false, false);

    // 重置回调状态
    let status5 = false
    uni.loadFontFace({
      family: 'AlimamaDaoLiTiWOFF',
      source: "url('/static/app-ios/AlimamaDaoLiTi.woff')",
      success() {
        data.successTriggeredNum++;
        status5 = true;
        console.log('loadFontFace AlimamaDaoLiTi.woff success')
      },
      fail(error) {
        status5 = false;
        console.warn('loadFontFace AlimamaDaoLiTi.woff fail', error.errMsg)
      },
      complete:()=> {
        if (status5 == true) {
          data.loadFontStatus[4] = true;
        }
      }
    })
    // 重置回调状态
    let status6 = false
    uni.loadFontFace({
      family: 'AlimamaDaoLiTiWOFF2',
      source: "url('/static/app-ios/AlimamaDaoLiTi.woff2')",
      success() {
        data.successTriggeredNum++;
        status6 = true;
        console.log('loadFontFace AlimamaDaoLiTi.woff2 success')
      },
      fail(error) {
        status6 = false;
        console.warn('loadFontFace AlimamaDaoLiTi.woff2 fail', error.errMsg)
      },
      complete:()=> {
        if (status6 == true) {
          data.loadFontStatus[5] = true;
        }
      }
    })
    // #endif

  })

  defineExpose({
    data
  })
</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
错误信息