1# @ohos.font (Custom Font Registration) 2 3The **font** module provides APIs for registering custom fonts. 4 5> **NOTE** 6> 7> 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. 8> 9> 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](./js-apis-arkui-UIContext.md#uicontext). 10> 11> Since API version 10, you can use the [getFont](./js-apis-arkui-UIContext.md#getfont) API in [UIContext](./js-apis-arkui-UIContext.md#uicontext) to obtain the [Font](./js-apis-arkui-UIContext.md#font) object associated with the current UI context. 12 13## Modules to Import 14 15```ts 16import { font } from '@kit.ArkUI' 17``` 18 19## font.registerFont 20 21registerFont(options: FontOptions): void 22 23Registers a custom font with the font manager. 24 25**Atomic service API**: This API can be used in atomic services since API version 11. 26 27**System capability**: SystemCapability.ArkUI.ArkUI.Full 28 29**Parameters** 30 31| Name | Type | Mandatory | Description | 32| ------- | --------------------------- | ---- | ----------- | 33| options | [FontOptions](#fontoptions) | Yes | Information about the custom font to register.| 34 35## FontOptions 36 37**Atomic service API**: This API can be used in atomic services since API version 11. 38 39**System capability**: SystemCapability.ArkUI.ArkUI.Full 40 41| Name | Type | Mandatory | Description | 42| ---------- | ------ | ---- | ------------ | 43| familyName | string \| [Resource](arkui-ts/ts-types.md#resource)<sup>10+</sup> | Yes | Name of the custom font to register. | 44| familySrc | string \| [Resource](arkui-ts/ts-types.md#resource)<sup>10+</sup> | Yes | Path of the custom font to register.| 45 46**Example** 47 48> **NOTE** 49> 50> You are advised to use the [getFont](./js-apis-arkui-UIContext.md#getfont) API in [UIContext](./js-apis-arkui-UIContext.md#uicontext) to obtain the [Font](./js-apis-arkui-UIContext.md#font) object associated with the current UI context. 51 52```ts 53// xxx.ets 54import { font } from '@kit.ArkUI'; 55 56@Entry 57@Component 58struct FontExample { 59 @State message: string = 'Hello World'; 60 // 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. 61 @State unicode: string = '\u0000'; 62 @State codePoint: string = String.fromCharCode(0x0000); 63 64 aboutToAppear() { 65 // Both familyName and familySrc support the Resource type. 66 font.registerFont({ 67 // You are advised to use this.getUIContext().getFont().registerFont(). 68 familyName: $r('app.string.font_name'), 69 familySrc: $r('app.string.font_src') 70 }) 71 72 // familySrc supports the $rawfile type. 73 font.registerFont({ 74 familyName: 'mediumRawFile', 75 familySrc: $rawfile('font/medium.ttf') 76 }) 77 78 // Register iconFont. 79 font.registerFont({ 80 familyName: 'iconFont', 81 familySrc: '/font/iconFont.ttf' 82 }) 83 84 // Both familyName and familySrc support the string type. 85 font.registerFont({ 86 familyName: 'medium', 87 familySrc: '/font/medium.ttf' // The font folder is at the same level as the pages folder. 88 }) 89 } 90 91 build() { 92 Column() { 93 Text(this.message) 94 .align(Alignment.Center) 95 .fontSize(20) 96 .fontFamily('medium') // medium: name of the custom font to register. (Registered fonts such as $r('app.string.mediumFamilyName') and 'mediumRawFile' can also be used.) 97 98 // Two methods of using iconFont 99 Text(this.unicode) 100 .align(Alignment.Center) 101 .fontSize(20) 102 .fontFamily('iconFont') 103 Text(this.codePoint) 104 .align(Alignment.Center) 105 .fontSize(20) 106 .fontFamily('iconFont') 107 }.width('100%') 108 } 109} 110``` 111> **NOTE** 112> 113> To use custom fonts globally in an application, register the fonts through the [windowStage.loadContent](js-apis-window.md#loadcontent9) API in the [onWindowStageCreate](../apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate) lifecycle callback in the **EntryAbility.ets** file. 114> 115> In HSP projects, avoid using relative paths to register custom fonts. For details, see [Accessing Resources in an HSP Through $r](../../quick-start/in-app-hsp.md). 116 117## font.getSystemFontList<sup>10+</sup> 118 119getSystemFontList(): Array\<string> 120 121Obtains the system font list. 122 123**Atomic service API**: This API can be used in atomic services since API version 11. 124 125**System capability**: SystemCapability.ArkUI.ArkUI.Full 126 127**Return value** 128 129| Type | Description | 130| -------------------- | ----------------- | 131| Array\<string> | List of supported fonts. | 132 133> **NOTE** 134> 135> This API takes effect only on 2-in-1 devices. 136 137**Example** 138 139> **NOTE** 140> 141> You are advised to use the [getFont](./js-apis-arkui-UIContext.md#getfont) API in [UIContext](./js-apis-arkui-UIContext.md#uicontext) to obtain the [Font](./js-apis-arkui-UIContext.md#font) object associated with the current UI context. 142 143```ts 144// xxx.ets 145import { font } from '@kit.ArkUI'; 146 147@Entry 148@Component 149struct FontExample { 150 fontList: Array<string> = new Array<string>(); 151 152 build() { 153 Column() { 154 Button("getSystemFontList") 155 .width('60%') 156 .height('6%') 157 .onClick(() => { 158 this.fontList = font.getSystemFontList() // You are advised to use the this.getUIContext().getFont().getSystemFontList() API. 159 }) 160 }.width('100%') 161 } 162} 163``` 164 165## font.getFontByName<sup>10+</sup> 166 167getFontByName(fontName: string): FontInfo 168 169Obtains information about a system font based on the font name. 170 171**Atomic service API**: This API can be used in atomic services since API version 11. 172 173**System capability**: SystemCapability.ArkUI.ArkUI.Full 174 175**Parameters** 176 177| Name | Type | Mandatory | Description | 178| ---------- | --------- | ------- | ------------ | 179| fontName | string | Yes | System font name.| 180 181**Return value** 182 183| Type | Description | 184| ---------------- | ---------------------------- | 185| FontInfo | Information about the system font. | 186 187## FontInfo<sup>10+</sup> 188 189**Atomic service API**: This API can be used in atomic services since API version 11. 190 191**System capability**: SystemCapability.ArkUI.ArkUI.Full 192 193| Name | Type | Mandatory | Description | 194| -------------- | ------- | ------------------------- | ------------------------- | 195| path | string | Yes| File path of the system font. | 196| postScriptName | string | Yes| PostScript name of the system font.| 197| fullName | string | Yes| Name of the system font. | 198| family | string | Yes| Family of the system font. | 199| subfamily | string | Yes| Subfamily of the system font. | 200| weight | number | Yes| Weight of the system font.<br>Value range: [0, 8], with intervals of 1, corresponding to the values in the [FontWeight](../apis-arkgraphics2d/js-apis-graphics-text.md#fontweight) enum<br>Default value: **0** | 201| width | number | Yes| Width of the system font.<br>Value range: [1, 9], with intervals of 1, corresponding to the values in the [FontWidth](../apis-arkgraphics2d/js-apis-graphics-text.md#fontwidth) enum | 202| italic | boolean | Yes| Whether the system font is italic.<br>Default value: **false**<br>**true**: The system font is italic.<br>**false**: The system font is not italic. | 203| monoSpace | boolean | Yes| Whether the system font is monospaced.<br>Default value: **false**<br>**true**: The system font is monospaced.<br>**false**: The system font is not monospaced. | 204| symbolic | boolean | Yes| Whether the system font supports symbols.<br>Default value: **false**<br>**true**: The system font supports symbols.<br>**false**: The system font does not support symbols. | 205 206**Example** 207 208> **NOTE** 209> 210> You are advised to use the [getFont](./js-apis-arkui-UIContext.md#getfont) API in [UIContext](./js-apis-arkui-UIContext.md#uicontext) to obtain the [Font](./js-apis-arkui-UIContext.md#font) object associated with the current UI context. 211 212```ts 213// xxx.ets 214import { font } from '@kit.ArkUI'; 215 216@Entry 217@Component 218struct FontExample { 219 fontList: Array<string> = new Array<string>(); 220 fontInfo: font.FontInfo = font.getFontByName(''); 221 222 build() { 223 Column() { 224 Button("getFontByName") 225 .onClick(() => { 226 this.fontInfo = 227 font.getFontByName('HarmonyOS Sans Italic') // You are advised to use this.getUIContext().getFont().getFontByName(). 228 console.log("getFontByName(): path = " + this.fontInfo.path) 229 console.log("getFontByName(): postScriptName = " + this.fontInfo.postScriptName) 230 console.log("getFontByName(): fullName = " + this.fontInfo.fullName) 231 console.log("getFontByName(): Family = " + this.fontInfo.family) 232 console.log("getFontByName(): Subfamily = " + this.fontInfo.subfamily) 233 console.log("getFontByName(): weight = " + this.fontInfo.weight) 234 console.log("getFontByName(): width = " + this.fontInfo.width) 235 console.log("getFontByName(): italic = " + this.fontInfo.italic) 236 console.log("getFontByName(): monoSpace = " + this.fontInfo.monoSpace) 237 console.log("getFontByName(): symbolic = " + this.fontInfo.symbolic) 238 }) 239 }.width('100%') 240 } 241} 242``` 243 244## font.getUIFontConfig<sup>11+</sup> 245getUIFontConfig() : UIFontConfig 246 247Obtains the UI font configuration of the system. 248 249**Atomic service API**: This API can be used in atomic services since API version 12. 250 251**System capability**: SystemCapability.ArkUI.ArkUI.Full 252 253**Return value** 254| Type | Description | 255| ---------------- | ---------------------------- | 256| [UIFontConfig](#uifontconfig11) | UI font configuration of the system. | 257 258## UIFontConfig<sup>11+</sup> 259 260**Atomic service API**: This API can be used in atomic services since API version 12. 261 262**System capability**: SystemCapability.ArkUI.ArkUI.Full 263| Name | Type | Mandatory | Description | 264| -------------- | ------- | ------------------------- | ------------------------- | 265| fontDir | Array\<string> | Yes| Path to the system font file. | 266| generic | Array\<[UIFontGenericInfo](#uifontgenericinfo11)> | Yes| List of supported generic font families.| 267| fallbackGroups | Array\<[UIFontFallbackGroupInfo](#uifontfallbackgroupinfo11)> | Yes| List of alternate generic font families. | 268 269## UIFontGenericInfo<sup>11+</sup> 270 271**Atomic service API**: This API can be used in atomic services since API version 12. 272 273**System capability**: SystemCapability.ArkUI.ArkUI.Full 274| Name | Type | Mandatory | Description | 275| -------------- | ------- | ------------------------- | ------------------------- | 276| family | string | Yes| Font family name, which is the value of **family** specified in the font file. | 277| alias | Array\<[UIFontAliasInfo](#uifontaliasinfo11)> | Yes| Alias list.| 278| adjust | Array\<[UIFontAdjustInfo](#uifontadjustinfo11)> | Yes| Weight of the font when displayed, which corresponds to the original weight.| 279 280## UIFontFallbackGroupInfo<sup>11+</sup> 281 282**Atomic service API**: This API can be used in atomic services since API version 12. 283 284**System capability**: SystemCapability.ArkUI.ArkUI.Full 285| Name | Type | Mandatory | Description | 286| -------------- | ------- | ------------------------- | ------------------------- | 287| fontSetName | string | Yes| Name of the font family corresponding to the alternate fonts. | 288| fallback | Array\<[UIFontFallbackInfo](#uifontfallbackinfo11)> | 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.| 289 290## UIFontAliasInfo<sup>11+</sup> 291 292**Atomic service API**: This API can be used in atomic services since API version 12. 293 294**System capability**: SystemCapability.ArkUI.ArkUI.Full 295| Name | Type | Mandatory | Description | 296| -------------- | ------- | ------------------------- | ------------------------- | 297| name | string | Yes| Alias name. | 298| 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.<br>Valid values are **0**, **100**, **400**, **700**, and **900**.| 299 300## UIFontAdjustInfo<sup>11+</sup> 301 302**Atomic service API**: This API can be used in atomic services since API version 12. 303 304**System capability**: SystemCapability.ArkUI.ArkUI.Full 305| Name | Type | Mandatory | Description | 306| -------------- | ------- | ------------------------- | ------------------------- | 307| weight | number | Yes| Original weight of the font.<br>Valid values are **50**, **80**, **100**, and **200**. | 308| to | number | Yes| Weight of the font displayed in the application.<br>Valid values are **100**, **400**, **700**, and **900**.| 309 310## UIFontFallbackInfo<sup>11+</sup> 311 312**Atomic service API**: This API can be used in atomic services since API version 12. 313 314**System capability**: SystemCapability.ArkUI.ArkUI.Full 315| Name | Type | Mandatory | Description | 316| -------------- | ------- | ------------------------- | ------------------------- | 317| language | string | Yes| Language supported by the font family. The language format is BCP 47. | 318| family | string | Yes| Font family name, which is the value of **family** specified in the font file.| 319 320**Example** 321 322```ts 323// xxx.ets 324import { font } from '@kit.ArkUI'; 325 326@Entry 327@Component 328struct FontExample { 329 build() { 330 Column() { 331 Button("getUIFontConfig") 332 .width('60%') 333 .height('6%') 334 .margin(50) 335 .onClick(() => { 336 let fontConfig = font.getUIFontConfig(); 337 console.log("font-dir -----------" + String(fontConfig.fontDir.length)); 338 for (let i = 0; i < fontConfig.fontDir.length; i++) { 339 console.log(fontConfig.fontDir[i]); 340 } 341 console.log("generic-------------" + String(fontConfig.generic.length)); 342 for (let i = 0; i < fontConfig.generic.length; i++) { 343 console.log("family:" + fontConfig.generic[i].family); 344 for (let j = 0; j < fontConfig.generic[i].alias.length; j++) { 345 console.log(fontConfig.generic[i].alias[j].name + " " + fontConfig.generic[i].alias[j].weight); 346 } 347 for (let j = 0; j < fontConfig.generic[i].adjust.length; j++) { 348 console.log(fontConfig.generic[i].adjust[j].weight + " " + fontConfig.generic[i].adjust[j].to); 349 } 350 } 351 console.log("fallback------------" + String(fontConfig.fallbackGroups.length)); 352 for (let i = 0; i < fontConfig.fallbackGroups.length; i++) { 353 console.log("fontSetName:" + fontConfig.fallbackGroups[i].fontSetName); 354 for (let j = 0; j < fontConfig.fallbackGroups[i].fallback.length; j++) { 355 console.log("language:" + fontConfig.fallbackGroups[i].fallback[j].language + " family:" + 356 fontConfig.fallbackGroups[i].fallback[j].family); 357 } 358 } 359 }) 360 }.width('100%') 361 } 362} 363``` 364