• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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示例，假设****为指定icon的Unicode
54  @State unicode: string = '\u****'
55  @State codePoint: string = String.fromCharCode(0x****)
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## font.getSystemFontList<sup>10+</sup>
104
105getSystemFontList(): Array\<string>
106
107获取系统支持的字体名称列表。
108
109**系统能力：** SystemCapability.ArkUI.ArkUI.Full
110
111**返回值：**
112
113| 类型                 | 说明               |
114| -------------------- | ----------------- |
115| Array\<string>       | 系统的字体名列表。  |
116
117**示例：**
118
119```ts
120// xxx.ets
121import font from '@ohos.font';
122
123@Entry
124@Component
125struct FontExample {
126  fontList: Array<string> = new Array<string>();
127  build() {
128    Column() {
129      Button("getSystemFontList")
130        .width('60%')
131        .height('6%')
132        .onClick(()=>{
133          this.fontList = font.getSystemFontList()
134        })
135    }.width('100%')
136  }
137}
138```
139
140## font.getFontByName<sup>10+</sup>
141
142getFontByName(fontName: string): FontInfo;
143
144根据传入的系统字体名称获取系统字体的相关信息。
145
146**系统能力：** SystemCapability.ArkUI.ArkUI.Full
147
148**参数：**
149
150| 参数名      | 类型      | 必填    | 说明          |
151| ---------- | --------- | ------- | ------------ |
152| fontName   | string    | 是      | 系统的字体名。 |
153
154**返回值：**
155
156| 类型             | 说明                          |
157| ---------------- | ---------------------------- |
158| FontInfo         | 字体的详细信息                 |
159
160## FontInfo<sup>10+</sup>
161
162**系统能力：** SystemCapability.ArkUI.ArkUI.Full
163
164| 名称            | 类型    | 必填  | 说明                       |
165| -------------- | ------- | ------------------------- | ------------------------- |
166| path           | string  | 是 | 系统字体的文件路径。        |
167| postScriptName | string  | 是 | 系统字体的postScript名称。 |
168| fullName       | string  | 是 | 系统字体的名称。           |
169| family         | string  | 是 | 系统字体的字体家族。       |
170| subfamily      | string  | 是 | 系统字体的子字体家族。      |
171| weight         | number  | 是 | 系统字体的粗细程度，单位px。        |
172| width          | number  | 是 | 系统字体的宽窄风格属性，单位px。    |
173| italic         | boolean | 是 | 系统字体是否倾斜。          |
174| monoSpace      | boolean | 是 | 系统字体是否紧凑。         |
175| symbolic       | boolean | 是 | 系统字体是否支持符号字体。  |
176
177**示例：**
178
179```ts
180// xxx.ets
181import font from '@ohos.font';
182
183@Entry
184@Component
185struct FontExample {
186  fontList: Array<string> = new Array<string>();
187  fontInfo: font.FontInfo = font.getFontByName('');
188  build() {
189    Column() {
190      Button("getFontByName")
191        .onClick(() => {
192          this.fontInfo = font.getFontByName('Sans Italic')
193          console.log("getFontByName(): path = " + this.fontInfo.path)
194          console.log("getFontByName(): postScriptName = " + this.fontInfo.postScriptName)
195          console.log("getFontByName(): fullName = " + this.fontInfo.fullName)
196          console.log("getFontByName(): Family = " + this.fontInfo.family)
197          console.log("getFontByName(): Subfamily = " + this.fontInfo.subfamily)
198          console.log("getFontByName(): weight = " + this.fontInfo.weight)
199          console.log("getFontByName(): width = " + this.fontInfo.width)
200          console.log("getFontByName(): italic = " + this.fontInfo.italic)
201          console.log("getFontByName(): monoSpace = " + this.fontInfo.monoSpace)
202          console.log("getFontByName(): symbolic = " + this.fontInfo.symbolic)
203        })
204    }.width('100%')
205  }
206}
207```