harmony 鸿蒙@ohos.font (Custom Font Registration)

2025-06-12
浏览 (4)

@ohos.font (Custom Font Registration)

The font module provides APIs for registering custom fonts.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where the UI context is unclear. For details, see UIContext.

Modules to Import

import { font } from '@kit.ArkUI'

font.registerFont^(deprecated)

registerFont(options: FontOptions): void

Registers a custom font with the font manager.

NOTE

This API is deprecated since API version 18. You are advised to use registerFont instead on the obtained Font object.

Since API version 10, you can use the getFont API in UIContext to obtain the Font object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
options	FontOptions	Yes	Information about the custom font to register.

FontOptions

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
familyName	string \|Resource¹⁰⁺	Yes	Name of the custom font to register.
familySrc	string \|Resource¹⁰⁺	Yes	Path of the custom font to register.

Example

NOTE

You are advised to use the getFont API in UIContext to obtain the Font object associated with the current UI context.

// xxx.ets
@Entry
@Component
struct FontExample {
  @State message: string = 'Hello World';
  // iconFont example, where 0000 is the Unicode character of the specified icon. You need to obtain the Unicode character from the TTF file of the registered iconFont.
  @State unicode: string = '\u0000';
  @State codePoint: string = String.fromCharCode(0x0000);
  private uiContext: UIContext = this.getUIContext();

  aboutToAppear() {
    // Both familyName and familySrc support the Resource type.
    this.uiContext.getFont().registerFont({
      // You are advised to use this.getUIContext().getFont().registerFont().
      familyName: $r('app.string.font_name'),
      familySrc: $r('app.string.font_src')
    })

    // familySrc supports the $rawfile type.
    this.uiContext.getFont().registerFont({
      familyName: 'mediumRawFile',
      familySrc: $rawfile('font/medium.ttf')
    })

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

    // Both familyName and familySrc support the string type.
    this.uiContext.getFont().registerFont({
      familyName: 'medium',
      familySrc: '/font/medium.ttf' // The font folder is at the same level as the pages folder.
    })
  }

  build() {
    Column() {
      Text(this.message)
        .align(Alignment.Center)
        .fontSize(20)
        .fontFamily('medium') // medium: name of the custom font to register. (Registered fonts such as $r('app.string.mediumFamilyName') and 'mediumRawFile' can also be used.)

      // Two methods of using iconFont
      Text(this.unicode)
        .align(Alignment.Center)
        .fontSize(20)
        .fontFamily('iconFont')
      Text(this.codePoint)
        .align(Alignment.Center)
        .fontSize(20)
        .fontFamily('iconFont')
    }.width('100%')
  }
}

NOTE

To use custom fonts globally in an application, register the fonts through the windowStage.loadContent API in the onWindowStageCreate lifecycle callback in the EntryAbility.ets file.

In HSP projects, avoid using relative paths to register custom fonts. For details, see Accessing Resources in an HSP Through $r.

font.getSystemFontList^(deprecated)

getSystemFontList(): Array<string>

Obtains the system font list.

NOTE

This API is supported since API version 10 and deprecated since API version 18. You are advised to use getSystemFontList instead on the obtained Font object.

Since API version 10, you can use the getFont API in UIContext to obtain the Font object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Array<string>	List of supported fonts.

NOTE

This API takes effect only on 2-in-1 devices.
To obtain the latest list of fonts supported by the system, use the getSystemFontFullNamesByType API.

Example

NOTE

You are advised to use the getFont API in UIContext to obtain the Font object associated with the current UI context.

// 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() // You are advised to use the this.getUIContext().getFont().getSystemFontList() API.
        })
    }.width('100%')
  }
}

font.getFontByName^(deprecated)

getFontByName(fontName: string): FontInfo

Obtains information about a system font based on the font name.

NOTE

This API is supported since API version 10 and deprecated since API version 18. You are advised to use getFontByName instead on the obtained Font object.

Since API version 10, you can use the getFont API in UIContext to obtain the Font object associated with the current UI context.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
fontName	string	Yes	System font name.

Return value

Type	Description
FontInfo	Information about the system font.

FontInfo¹⁰⁺

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
path	string	Yes	File path of the system font.
postScriptName	string	Yes	PostScript name of the system font.
fullName	string	Yes	Name of the system font.
family	string	Yes	Family of the system font.
subfamily	string	Yes	Subfamily of the system font.
weight	number	Yes	Weight of the system font. Value range: [0, 8], with intervals of 1, corresponding to the values in the FontWeight enum Default value: 0
width	number	Yes	Width of the system font. Value range: [1, 9], with intervals of 1, corresponding to the values in the FontWidth enum
italic	boolean	Yes	Whether the system font is italic. Default value: false true: The system font is italic. false: The system font is not italic.
monoSpace	boolean	Yes	Whether the system font is monospaced. Default value: false true: The system font is monospaced. false: The system font is not monospaced.
symbolic	boolean	Yes	Whether the system font supports symbols. Default value: false true: The system font supports symbols. false: The system font does not support symbols.

Example

NOTE

You are advised to use the getFont API in UIContext to obtain the Font object associated with the current UI context.

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

@Entry
@Component
struct FontExample {
  fontList: Array<string> = new Array<string>();
  fontInfo: font.FontInfo = font.getFontByName('');

  build() {
    Column() {
      Button("getFontByName")
        .onClick(() => {
          this.fontInfo =
            font.getFontByName('HarmonyOS Sans Italic') // You are advised to use this.getUIContext().getFont().getFontByName().
          console.log("getFontByName(): path = " + this.fontInfo.path)
          console.log("getFontByName(): postScriptName = " + this.fontInfo.postScriptName)
          console.log("getFontByName(): fullName = " + this.fontInfo.fullName)
          console.log("getFontByName(): Family = " + this.fontInfo.family)
          console.log("getFontByName(): Subfamily = " + this.fontInfo.subfamily)
          console.log("getFontByName(): weight = " + this.fontInfo.weight)
          console.log("getFontByName(): width = " + this.fontInfo.width)
          console.log("getFontByName(): italic = " + this.fontInfo.italic)
          console.log("getFontByName(): monoSpace = " + this.fontInfo.monoSpace)
          console.log("getFontByName(): symbolic = " + this.fontInfo.symbolic)
        })
    }.width('100%')
  }
}