1# @ohos.font (注册自定义字体) 2 3本模块提供注册自定义字体。 4 5> **说明** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用，参见[UIContext](./js-apis-arkui-UIContext.md#uicontext)说明。 10> 11> 从API version 10开始，可以通过使用[UIContext](./js-apis-arkui-UIContext.md#uicontext)中的[getFont](./js-apis-arkui-UIContext.md#getfont)方法获取当前UI上下文关联的[Font](./js-apis-arkui-UIContext.md#font)对象。 12 13## 导入模块 14 15```ts 16import font from '@ohos.font' 17``` 18 19## font.registerFont 20 21registerFont(options: FontOptions): void 22 23在字体管理中注册自定义字体。 24 25**系统能力：** SystemCapability.ArkUI.ArkUI.Full 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------- | --------------------------- | ---- | ----------- | 31| options | [FontOptions](#fontoptions) | 是 | 注册的自定义字体信息。 | 32 33## FontOptions 34 35**系统能力：** SystemCapability.ArkUI.ArkUI.Full 36 37| 名称 | 类型 | 必填 | 说明 | 38| ---------- | ------ | ---- | ------------ | 39| familyName | string\| [Resource](arkui-ts/ts-types.md#resource)<sup>10+</sup> | 是 | 设置注册的字体名称。 | 40| familySrc | string\| [Resource](arkui-ts/ts-types.md#resource)<sup>10+</sup> | 是 | 设置注册字体文件的路径。 | 41 42**示例：** 43 44```ts 45// xxx.ets 46import font from '@ohos.font'; 47 48@Entry 49@Component 50struct FontExample { 51 @State message: string = 'Hello World' 52 53 // iconFont示例，假设0000为指定icon的Unicode，实际需要开发者从注册的iconFont的ttf文件里面获取Unicode 54 @State unicode: string = '\u0000' 55 @State codePoint: string = String.fromCharCode(0x0000) 56 57 aboutToAppear() { 58 // familyName和familySrc都支持string 59 font.registerFont({ 60 familyName: 'medium', 61 familySrc: '/font/medium.ttf' // font文件夹与pages目录同级 62 }) 63 64 // familyName和familySrc都支持系统Resource 65 font.registerFont({ 66 familyName: $r('app.string.font_name'), 67 familySrc: $r('app.string.font_src') 68 }) 69 70 // familySrc支持RawFile 71 font.registerFont({ 72 familyName: 'mediumRawFile', 73 familySrc: $rawfile('font/medium.ttf') 74 }) 75 76 // 注册iconFont 77 font.registerFont({ 78 familyName: 'iconFont', 79 familySrc: '/font/iconFont.ttf' 80 }) 81 } 82 83 build() { 84 Column() { 85 Text(this.message) 86 .align(Alignment.Center) 87 .fontSize(20) 88 .fontFamily('medium') // medium：注册自定义字体的名字（$r('app.string.mediumFamilyName')、'mediumRawFile'等已注册字体也能正常使用） 89 90 // 使用iconFont的两种方式 91 Text(this.unicode) 92 .align(Alignment.Center) 93 .fontSize(20) 94 .fontFamily('iconFont') 95 Text(this.codePoint) 96 .align(Alignment.Center) 97 .fontSize(20) 98 .fontFamily('iconFont') 99 }.width('100%') 100 } 101} 102``` 103> **说明：** 104> 105> 若需全局使用自定义字体，请在EntryAbility.ets文件的[onWindowStageCreate](../apis-ability-kit/js-apis-app-ability-uiAbility.md#uiabilityonwindowstagecreate)生命周期中，通过[windowStage.loadContent](js-apis-window.md#loadcontent9)回调注册。 106 107## font.getSystemFontList<sup>10+</sup> 108 109getSystemFontList(): Array\<string> 110 111获取系统支持的字体名称列表。 112 113**系统能力：** SystemCapability.ArkUI.ArkUI.Full 114 115**返回值：** 116 117| 类型 | 说明 | 118| -------------------- | ----------------- | 119| Array\<string> | 系统的字体名列表。 | 120 121**示例：** 122 123```ts 124// xxx.ets 125import font from '@ohos.font'; 126 127@Entry 128@Component 129struct FontExample { 130 fontList: Array<string> = new Array<string>(); 131 build() { 132 Column() { 133 Button("getSystemFontList") 134 .width('60%') 135 .height('6%') 136 .onClick(()=>{ 137 this.fontList = font.getSystemFontList() 138 }) 139 }.width('100%') 140 } 141} 142``` 143 144## font.getFontByName<sup>10+</sup> 145 146getFontByName(fontName: string): FontInfo 147 148根据传入的系统字体名称获取系统字体的相关信息。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| ---------- | --------- | ------- | ------------ | 156| fontName | string | 是 | 系统的字体名。 | 157 158**返回值：** 159 160| 类型 | 说明 | 161| ---------------- | ---------------------------- | 162| FontInfo | 字体的详细信息 | 163 164## FontInfo<sup>10+</sup> 165 166**系统能力：** SystemCapability.ArkUI.ArkUI.Full 167 168| 名称 | 类型 | 必填 | 说明 | 169| -------------- | ------- | ------------------------- | ------------------------- | 170| path | string | 是 | 系统字体的文件路径。 | 171| postScriptName | string | 是 | 系统字体的postScript名称。 | 172| fullName | string | 是 | 系统字体的名称。 | 173| family | string | 是 | 系统字体的字体家族。 | 174| subfamily | string | 是 | 系统字体的子字体家族。 | 175| weight | number | 是 | 系统字体的粗细程度，单位px。 | 176| width | number | 是 | 系统字体的宽窄风格属性，单位px。 | 177| italic | boolean | 是 | 系统字体是否倾斜。 | 178| monoSpace | boolean | 是 | 系统字体是否紧凑。 | 179| symbolic | boolean | 是 | 系统字体是否支持符号字体。 | 180 181**示例：** 182 183```ts 184// xxx.ets 185import font from '@ohos.font'; 186 187@Entry 188@Component 189struct FontExample { 190 fontList: Array<string> = new Array<string>(); 191 fontInfo: font.FontInfo = font.getFontByName(''); 192 build() { 193 Column() { 194 Button("getFontByName") 195 .onClick(() => { 196 this.fontInfo = font.getFontByName('Sans Italic') 197 console.log("getFontByName(): path = " + this.fontInfo.path) 198 console.log("getFontByName(): postScriptName = " + this.fontInfo.postScriptName) 199 console.log("getFontByName(): fullName = " + this.fontInfo.fullName) 200 console.log("getFontByName(): Family = " + this.fontInfo.family) 201 console.log("getFontByName(): Subfamily = " + this.fontInfo.subfamily) 202 console.log("getFontByName(): weight = " + this.fontInfo.weight) 203 console.log("getFontByName(): width = " + this.fontInfo.width) 204 console.log("getFontByName(): italic = " + this.fontInfo.italic) 205 console.log("getFontByName(): monoSpace = " + this.fontInfo.monoSpace) 206 console.log("getFontByName(): symbolic = " + this.fontInfo.symbolic) 207 }) 208 }.width('100%') 209 } 210} 211``` 212 213## font.getUIFontConfig<sup>11+</sup> 214getUIFontConfig() : UIFontConfig 215 216获取系统的UI字体配置。 217 218**系统能力：** SystemCapability.ArkUI.ArkUI.Full 219 220**返回值：** 221| 类型 | 说明 | 222| ---------------- | ---------------------------- | 223| [UIFontConfig](#uifontconfig11) | 系统的UI字体配置信息。 | 224 225## UIFontConfig<sup>11+</sup> 226**系统能力：** SystemCapability.ArkUI.ArkUI.Full 227| 名称 | 类型 | 必填 | 说明 | 228| -------------- | ------- | ------------------------- | ------------------------- | 229| fontDir | Array\<string> | 是 | 系统字体文件所在的路径。 | 230| generic | Array\<[UIFontGenericInfo](#uifontgenericinfo11)> | 是 | 系统所支持的通用字体集列表。 | 231| fallbackGroups | Array\<[UIFontFallbackGroupInfo](#uifontfallbackgroupinfo11)> | 是 | 备用字体集。 | 232 233## UIFontGenericInfo<sup>11+</sup> 234**系统能力：** SystemCapability.ArkUI.ArkUI.Full 235| 名称 | 类型 | 必填 | 说明 | 236| -------------- | ------- | ------------------------- | ------------------------- | 237| family | string | 是 | 字体集名，字体文件中指定的"family"值。 | 238| alias | Array\<[UIFontAliasInfo](#uifontaliasinfo11)> | 是 | 别名列表。 | 239| adjust | Array\<[UIFontAdjustInfo](#uifontadjustinfo11)> | 否 | 字体原本的weight值对应需显示的值。 | 240 241## UIFontFallbackGroupInfo<sup>11+</sup> 242**系统能力：** SystemCapability.ArkUI.ArkUI.Full 243| 名称 | 类型 | 必填 | 说明 | 244| -------------- | ------- | ------------------------- | ------------------------- | 245| fontSetName | string | 是 | 备用字体集所对应的字体集名称。 | 246| fallback | Array\<[UIFontFallbackInfo](#uifontfallbackinfo11)> | 是 | 表示以下列表为该字体集的备用字体，如果fontSetName为""，表示可以作为所有字体集的备用字体。 | 247 248## UIFontAliasInfo<sup>11+</sup> 249**系统能力：** SystemCapability.ArkUI.ArkUI.Full 250| 名称 | 类型 | 必填 | 说明 | 251| -------------- | ------- | ------------------------- | ------------------------- | 252| name | string | 是 | 别名名称。 | 253| weight | number | 是 | 当weight>0时表示此字体集只包含所指定weight的字体，当weight=0时，表示此字体集包含所有字体。 | 254 255## UIFontAdjustInfo<sup>11+</sup> 256**系统能力：** SystemCapability.ArkUI.ArkUI.Full 257| 名称 | 类型 | 必填 | 说明 | 258| -------------- | ------- | ------------------------- | ------------------------- | 259| weight | number | 是 | 字体原本的weight值。 | 260| to | number | 是 | 字体在应用中显示的weight值。 | 261 262## UIFontFallbackInfo<sup>11+</sup> 263**系统能力：** SystemCapability.ArkUI.ArkUI.Full 264| 名称 | 类型 | 必填 | 说明 | 265| -------------- | ------- | ------------------------- | ------------------------- | 266| language | string | 是 | 字体集所支持的语言类型，语言格式为bcp47。 | 267| family | string | 是 | 字体集名，字体文件中指定的"family"值。 | 268 269**示例：** 270 271```ts 272// xxx.ets 273import font from '@ohos.font'; 274@Entry 275@Component 276struct FontExample { 277 build() { 278 Column() { 279 Button("getUIFontConfig") 280 .width('60%') 281 .height('6%') 282 .margin(50) 283 .onClick(()=>{ 284 let fontConfig = font.getUIFontConfig(); 285 console.log("font-dir -----------" + String(fontConfig.fontDir.length)); 286 for (let i = 0; i < fontConfig.fontDir.length; i ++) { 287 console.log(fontConfig.fontDir[i]); 288 } 289 console.log("generic-------------" + String(fontConfig.generic.length)); 290 for (let i = 0; i < fontConfig.generic.length; i ++){ 291 console.log("family:" + fontConfig.generic[i].family); 292 for (let j = 0; j < fontConfig.generic[i].alias.length; j ++){ 293 console.log(fontConfig.generic[i].alias[j].name + " " + fontConfig.generic[i].alias[j].weight); 294 } 295 for (let j = 0; j < fontConfig.generic[i].adjust.length; j ++){ 296 console.log(fontConfig.generic[i].adjust[j].weight + " " + fontConfig.generic[i].adjust[j].to); 297 } 298 } 299 console.log("fallback------------" + String(fontConfig.fallbackGroups.length)); 300 for (let i = 0; i < fontConfig.fallbackGroups.length; i ++){ 301 console.log("fontSetName:" + fontConfig.fallbackGroups[i].fontSetName); 302 for (let j = 0; j < fontConfig.fallbackGroups[i].fallback.length; j ++){ 303 console.log("language:" + fontConfig.fallbackGroups[i].fallback[j].language + " family:" + fontConfig.fallbackGroups[i].fallback[j].family); 304 } 305 } 306 }) 307 }.width('100%') 308 } 309} 310``` 311