目录

@ohos.font (注册自定义字体)

本模块提供注册自定义字体、获取系统字体列表、获取字体详细信息以及获取系统字体配置等能力,适用于应用需要使用自定义字体样式(如品牌字体、图标字体)或获取系统字体信息的场景。通过使用本模块,开发者可以实现品牌字体统一、提升用户界面美观度和一致性,满足多样化的设计需求。

  • 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

  • 本模块功能依赖UI的执行上下文,不可在UI上下文不明确的地方使用,参见UIContext说明。

  • 推荐使用字体引擎的loadFontSync接口注册自定义字体。

导入模块

import { font } from '@kit.ArkUI';

font.registerFont(deprecated)

registerFont(options: FontOptions): void

在字体管理中注册自定义字体。

该接口为异步接口,不支持并发调用。

  • 从API version 9开始支持,从API version 18开始废弃,建议使用registerFont替代。registerFont需要先通过UIContext中的getFont方法获取Font对象,然后通过该对象进行调用。且直接使用registerFont可能导致UI上下文不明确的问题。

  • 从API version 10开始,可以通过使用UIContext中的getFont方法获取当前UI上下文关联的Font对象。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
options FontOptions 是 注册的自定义字体信息。

FontOptions

注册的自定义字体信息。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
familyName string | Resource10+ 否 否 设置注册的字体名称。建议使用字母、数字和下划线组成。
familySrc string | Resource10+ 否 否

设置注册字体文件的路径。支持Resource资源引用、$rawfile路径、相对路径和绝对路径。

说明:

读取系统沙箱路径内的资源时,建议使用file://路径前缀的字符串,需要确保沙箱目录路径下的文件存在并且有可读权限。

直接使用font可能导致UI上下文不明确的问题,推荐通过使用UIContext中的getFont方法获取当前UI上下文关联的Font对象。

示例:

// xxx.ets
@Entry
@Component
struct FontExample {
  @State message: string = 'Hello World';
  // iconFont示例,假设0000为指定icon的Unicode,实际需要开发者从注册的iconFont的ttf文件里面获取Unicode
  @State unicode: string = '\u0000';
  @State codePoint: string = String.fromCharCode(0x0000);
  private uiContext: UIContext = this.getUIContext();

  aboutToAppear() {
    // familyName和familySrc都支持系统Resource
    this.uiContext.getFont().registerFont({
      // 建议使用 this.getUIContext().getFont().registerFont()接口
      // 'app.string.font_name'和'app.string.font_src'仅作示例,请替换为实际使用资源字符串
      familyName: $r('app.string.font_name'),
      familySrc: $r('app.string.font_src')
    });

    // familySrc支持RawFile
    this.uiContext.getFont().registerFont({
      familyName: 'mediumRawFile',
      familySrc: $rawfile('font/medium.ttf') // 'font/medium.ttf'仅作示例,请替换为实际使用资源字体文件
    });

    // 注册iconFont
    this.uiContext.getFont().registerFont({
      familyName: 'iconFont',
      familySrc: '/font/iconFont.ttf'
    });

    // familyName和familySrc都支持string
    this.uiContext.getFont().registerFont({
      familyName: 'medium',
      familySrc: '/font/medium.ttf' // font文件夹与pages目录同级
    });
  }

  build() {
    Column() {
      Text(this.message)
        .align(Alignment.Center)
        .fontSize(20)
        .fontFamily('medium') // medium:注册自定义字体的名字($r('app.string.font_name')、'mediumRawFile'等已注册字体也能正常使用)

      // 使用iconFont的两种方式
      Text(this.unicode)
        .align(Alignment.Center)
        .fontSize(20)
        .fontFamily('iconFont')
      Text(this.codePoint)
        .align(Alignment.Center)
        .fontSize(20)
        .fontFamily('iconFont')
    }.width('100%')
  }
}

应用若需全局使用自定义字体,请在EntryAbility.ets文件的onWindowStageCreate生命周期中,通过windowStage.loadContent回调注册。

在HSP工程中,不推荐采用相对路径的方式注册自定义字体,详见通过$r访问HSP中的资源。

font.getSystemFontList(deprecated)

getSystemFontList(): Array<string>

获取系统字体列表。

该接口仅在PC/2in1设备上生效,在其他设备上返回空数组。

推荐使用getSystemFontFullNamesByType接口获取系统最新支持的字体列表数据。

  • 从API version 10开始支持,从API version 18开始废弃,建议使用getSystemFontList替代。getSystemFontList需要先通过UIContext中的getFont方法获取Font对象,然后通过该对象进行调用。且直接使用getSystemFontList可能导致UI上下文不明确的问题。

  • 从API version 10开始,可以通过使用UIContext中的getFont方法获取当前UI上下文关联的Font对象。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

类型 说明
Array<string> 系统的字体名列表。

直接使用font可能导致UI上下文不明确的问题,推荐通过使用UIContext中的getFont方法获取当前UI上下文关联的Font对象。

示例:

// xxx.ets
import { font } from '@kit.ArkUI';

@Entry
@Component
struct FontExample {
  fontList: Array<string> = new Array<string>();

  build() {
    Column() {
      Button("getSystemFontList")
        .width('60%')
        .height('6%')
        .onClick(() => {
          this.fontList = font.getSystemFontList(); // 建议使用 this.getUIContext().getFont().getSystemFontList()接口
        })
    }.width('100%')
  }
}

font.getFontByName(deprecated)

getFontByName(fontName: string): FontInfo

根据传入的系统字体名称获取系统字体的相关信息。

  • 从API version 10开始支持,从API version 18开始废弃,建议使用getFontByName替代。getFontByName需要先通过UIContext中的getFont方法获取Font对象,然后通过该对象进行调用。且直接使用getFontByName可能导致UI上下文不明确的问题。

  • 从API version 10开始,可以通过使用UIContext中的getFont方法获取当前UI上下文关联的Font对象。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
fontName string 是 系统的字体名。

返回值:

类型 说明
FontInfo 字体的详细信息,包含路径、名称、字重、宽度、是否倾斜等属性。

FontInfo10+

字体的详细信息。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
path string 否 否 系统字体的文件路径。
postScriptName string 否 否 系统字体的postScript名称。
fullName string 否 否 系统字体的名称。
family string 否 否 系统字体的字体家族。
subfamily string 否 否 系统字体的子字体家族。
weight number 否 否

系统字体的字重。

取值范围:[100,900],取值间隔为100,分别对应FontWeight枚举中的值。

width number 否 否

系统字体的宽度。

取值范围:[1,9],取值间隔为1,分别对应FontWidth枚举中的值。

italic boolean 否 否

系统字体是否倾斜。

默认值:false

值为true,表示斜体字体,值为false,表示非斜体字体。

monoSpace boolean 否 否

系统字体是否等宽。

默认值:false

值为true,表示等宽字体,值为false,表示非等宽字体。

symbolic boolean 否 否

系统字体是否支持符号字体。

默认值:false

值为true,表示支持符号字体,值为false,表示不支持符号字体。

示例:

直接使用font可能导致UI上下文不明确的问题,推荐通过使用UIContext中的getFont方法获取当前UI上下文关联的Font对象。

// xxx.ets
@Entry
@Component
struct FontExample {
  private fontInfo = this.getUIContext().getFont().getFontByName('');

  build() {
    Column() {
      Button('getFontByName')
        .onClick(() => {
          this.fontInfo =
            this.getUIContext().getFont().getFontByName('HarmonyOS Sans Italic');
          console.info('getFontByName(): path = ' + this.fontInfo.path);
          console.info('getFontByName(): postScriptName = ' + this.fontInfo.postScriptName);
          console.info('getFontByName(): fullName = ' + this.fontInfo.fullName);
          console.info('getFontByName(): family = ' + this.fontInfo.family);
          console.info('getFontByName(): subfamily = ' + this.fontInfo.subfamily);
          console.info('getFontByName(): weight = ' + this.fontInfo.weight);
          console.info('getFontByName(): width = ' + this.fontInfo.width);
          console.info('getFontByName(): italic = ' + this.fontInfo.italic);
          console.info('getFontByName(): monoSpace = ' + this.fontInfo.monoSpace);
          console.info('getFontByName(): symbolic = ' + this.fontInfo.symbolic);
        })
    }.width('100%')
  }
}

font.getUIFontConfig11+

getUIFontConfig() : UIFontConfig

获取系统字体配置文件的UI字体配置信息。常用于需要分析或查看系统字体配置的场景,例如:字体管理工具、字体调试与诊断、字体配置信息展示等。

该接口仅支持获取配置文件内的信息以及当UI上下文不明确时可能返回undefined,如需获取全量的字体配置信息,推荐使用字体引擎的getSystemFontFullNamesByType接口获取系统最新支持的字体列表数据。

需要先通过UIContext中的getFont方法获取Font对象,然后通过该对象进行调用。且直接使用getUIFontConfig可能导致UI上下文不明确的问题。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

类型 说明
UIFontConfig 系统的UI字体配置信息,包含字体目录、通用字体集、备用字体集等。

UIFontConfig11+

系统的UI字体配置信息。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
fontDir Array<string> 否 否 系统字体文件所在的路径列表,数组元素为系统绝对路径。
generic Array<UIFontGenericInfo> 否 否 系统所支持的通用字体集列表。
fallbackGroups Array<UIFontFallbackGroupInfo> 否 否 系统备用字体集列表,用于指定当主字体不支持某些字符时使用的备用字体。

UIFontGenericInfo11+

系统所支持的通用字体集列表。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
family string 否 否 字体集名,字体文件中指定的"family"值。
alias Array<UIFontAliasInfo> 否 否 字体集的别名列表,用于提供字体的替代名称。
adjust Array<UIFontAdjustInfo> 否 否 字体weight值映射列表,将字体原本的weight值映射为实际显示的weight值。

UIFontFallbackGroupInfo11+

备用字体集。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
fontSetName string 否 否 备用字体集所对应的字体集名称。如果fontSetName为"",表示备用字体集可用于所有字体集。
fallback Array<UIFontFallbackInfo> 否 否 表示以下列表为该字体集的备用字体,如果fontSetName为"",表示可以作为所有字体集的备用字体。

UIFontAliasInfo11+

别名列表。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
name string 否 否 别名名称。
weight number 否 否

当weight>0时表示此字体集只包含所指定weight的字体,当weight=0时,表示此字体集包含所有字体。

可返回的值有0、100、400、700、900。

UIFontAdjustInfo11+

字体原本的weight值和显示实际值的映射列表。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
weight number 否 否

字体原本的weight值。

可返回的值有50、80、100、200。

to number 否 否

字体在应用中显示的weight值。

可返回的值有100、400、700、900。

UIFontFallbackInfo11+

该字体集的备用字体。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
language string 否 否 字体集所支持的语言类型,语言格式为BCP47标签(如"zh-Hans"表示简体中文,"en"表示英语)。
family string 否 否 字体集名,字体文件中指定的"family"值。

示例:

// xxx.ets
import { font } from '@kit.ArkUI';

@Entry
@Component
struct FontExample {
  build() {
    Column() {
      Button('getUIFontConfig')
        .width('60%')
        .height('6%')
        .margin(50)
        .onClick(() => {
          let fontConfig = font.getUIFontConfig();
          console.info('font-dir -----------' + String(fontConfig.fontDir.length));
          for (let i = 0; i < fontConfig.fontDir.length; i++) {
            console.info(fontConfig.fontDir[i]);
          }
          console.info('generic-------------' + String(fontConfig.generic.length));
          for (let i = 0; i < fontConfig.generic.length; i++) {
            console.info('family:' + fontConfig.generic[i].family);
            for (let j = 0; j < fontConfig.generic[i].alias.length; j++) {
              console.info(fontConfig.generic[i].alias[j].name + ' ' + fontConfig.generic[i].alias[j].weight);
            }
            for (let j = 0; j < fontConfig.generic[i].adjust.length; j++) {
              console.info(fontConfig.generic[i].adjust[j].weight + ' ' + fontConfig.generic[i].adjust[j].to);
            }
          }
          console.info('fallbackGroups------------' + String(fontConfig.fallbackGroups.length));
          for (let i = 0; i < fontConfig.fallbackGroups.length; i++) {
            console.info('fontSetName:' + fontConfig.fallbackGroups[i].fontSetName);
            for (let j = 0; j < fontConfig.fallbackGroups[i].fallback.length; j++) {
              console.info('language:' + fontConfig.fallbackGroups[i].fallback[j].language + ' family:' +
              fontConfig.fallbackGroups[i].fallback[j].family);
            }
          }
        })
    }.width('100%')
  }
}