@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 |Resource10+	Yes	Name of the custom font to register.
familySrc	string |Resource10+	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%')
  }
}

font.getUIFontConfig¹¹⁺

getUIFontConfig() : UIFontConfig

Obtains the UI font configuration of the system.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
UIFontConfig	UI font configuration of the system.

UIFontConfig¹¹⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
fontDir	Array<string>	Yes	Path to the system font file.
generic	Array<UIFontGenericInfo>	Yes	List of supported generic font families.
fallbackGroups	Array<UIFontFallbackGroupInfo>	Yes	List of alternate generic font families.

UIFontGenericInfo¹¹⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
family	string	Yes	Font family name, which is the value of family specified in the font file.
alias	Array<UIFontAliasInfo>	Yes	Alias list.
adjust	Array<UIFontAdjustInfo>	Yes	Weight of the font when displayed, which corresponds to the original weight.

UIFontFallbackGroupInfo¹¹⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
fontSetName	string	Yes	Name of the font family corresponding to the alternate fonts.
fallback	Array<UIFontFallbackInfo>	Yes	Alternate fonts for the font family. If fontSetName is "", it indicates that the fonts can be used as alternate fonts for all font families.

UIFontAliasInfo¹¹⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
name	string	Yes	Alias name.
weight	number	Yes	Weight of the fonts included in the font family. If the value is greater than 0, the font family contains only the fonts with the specified weight. If the value is 0, the font family contains all fonts. Valid values are 0, 100, 400, 700, and 900.

UIFontAdjustInfo¹¹⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
weight	number	Yes	Original weight of the font. Valid values are 50, 80, 100, and 200.
to	number	Yes	Weight of the font displayed in the application. Valid values are 100, 400, 700, and 900.

UIFontFallbackInfo¹¹⁺

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Type	Mandatory	Description
language	string	Yes	Language supported by the font family. The language format is BCP 47.
family	string	Yes	Font family name, which is the value of family specified in the font file.

Example

// 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.log("font-dir -----------" + String(fontConfig.fontDir.length));
          for (let i = 0; i < fontConfig.fontDir.length; i++) {
            console.log(fontConfig.fontDir[i]);
          }
          console.log("generic-------------" + String(fontConfig.generic.length));
          for (let i = 0; i < fontConfig.generic.length; i++) {
            console.log("family:" + fontConfig.generic[i].family);
            for (let j = 0; j < fontConfig.generic[i].alias.length; j++) {
              console.log(fontConfig.generic[i].alias[j].name + " " + fontConfig.generic[i].alias[j].weight);
            }
            for (let j = 0; j < fontConfig.generic[i].adjust.length; j++) {
              console.log(fontConfig.generic[i].adjust[j].weight + " " + fontConfig.generic[i].adjust[j].to);
            }
          }
          console.log("fallback------------" + String(fontConfig.fallbackGroups.length));
          for (let i = 0; i < fontConfig.fallbackGroups.length; i++) {
            console.log("fontSetName:" + fontConfig.fallbackGroups[i].fontSetName);
            for (let j = 0; j < fontConfig.fallbackGroups[i].fallback.length; j++) {
              console.log("language:" + fontConfig.fallbackGroups[i].fallback[j].language + " family:" +
              fontConfig.fallbackGroups[i].fallback[j].family);
            }
          }
        })
    }.width('100%')
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkUI

harmony 鸿蒙ARKUI_TextPickerCascadeRangeContent

harmony 鸿蒙ARKUI_TextPickerRangeContent

harmony 鸿蒙ArkUI_AnimateCompleteCallback

harmony 鸿蒙ArkUI_AttributeItem

harmony 鸿蒙ArkUI_ColorStop

harmony 鸿蒙ArkUI_ContextCallback

harmony 鸿蒙ArkUI_EventModule

harmony 鸿蒙ArkUI_ExpectedFrameRateRange

harmony 鸿蒙ArkUI_IntOffset