• 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 = '你好，世界'
52
53  aboutToAppear() {
54    // familyName和familySrc都支持string
55    font.registerFont({
56      familyName: 'medium',
57      familySrc: '/font/medium.ttf' // font文件与pages目录同级
58    })
59
60    // familyName和familySrc都支持系统Resource
61    font.registerFont({
62      familyName: $r('app.string.mediumFamilyName'),
63      familySrc: $r('app.string.mediumFamilySrc')
64    })
65
66    // familySrc支持RawFile
67    font.registerFont({
68      familyName: 'mediumRawFile',
69      familySrc: $rawfile('font/medium.ttf')
70    })
71  }
72
73  build() {
74    Column() {
75      Text(this.message)
76        .align(Alignment.Center)
77        .fontSize(20)
78        .fontFamily('medium') // medium：注册自定义字体的名字（$r('app.string.mediumFamilyName')、'mediumRawFile'等已注册字体也能正常使用）
79        .height('100%')
80    }.width('100%')
81  }
82}
83```
84## font.getSystemFontList<sup>10+</sup>
85
86getSystemFontList(): Array\<string>
87
88获取系统支持的字体名称列表。
89
90**系统能力：** SystemCapability.ArkUI.ArkUI.Full
91
92**返回值：**
93
94| 类型                 | 说明               |
95| -------------------- | ----------------- |
96| Array\<string>       | 系统的字体名列表。  |
97
98**示例：**
99
100```ts
101// xxx.ets
102import font from '@ohos.font';
103
104@Entry
105@Component
106struct FontExample {
107  fontList: Array<string> = new Array<string>();
108  build() {
109    Column() {
110      Button("getSystemFontList")
111        .width('60%')
112        .height('6%')
113        .onClick(()=>{
114          this.fontList = font.getSystemFontList()
115        })
116    }.width('100%')
117  }
118}
119```
120
121## font.getFontByName<sup>10+</sup>
122
123getFontByName(fontName: string): FontInfo;
124
125根据传入的系统字体名称获取系统字体的相关信息。
126
127**系统能力：** SystemCapability.ArkUI.ArkUI.Full
128
129**参数：**
130
131| 参数名      | 类型      | 必填    | 说明          |
132| ---------- | --------- | ------- | ------------ |
133| fontName   | string    | 是      | 系统的字体名。 |
134
135**返回值：**
136
137| 类型             | 说明                          |
138| ---------------- | ---------------------------- |
139| FontInfo         | 字体的详细信息                 |
140
141## FontInfo<sup>10+</sup>
142
143**系统能力：** SystemCapability.ArkUI.ArkUI.Full
144
145| 名称            | 类型    | 必填  | 说明                       |
146| -------------- | ------- | ------------------------- | ------------------------- |
147| path           | string  | 是 | 系统字体的文件路径。        |
148| postScriptName | string  | 是 | 系统字体的postScript名称。 |
149| fullName       | string  | 是 | 系统字体的名称。           |
150| family         | string  | 是 | 系统字体的字体家族。       |
151| subfamily      | string  | 是 | 系统字体的子字体家族。      |
152| weight         | number  | 是 | 系统字体的粗细程度。        |
153| width          | number  | 是 | 系统字体的宽窄风格属性。    |
154| italic         | boolean | 是 | 系统字体是否倾斜。          |
155| monoSpace      | boolean | 是 | 系统字体是否紧凑。         |
156| symbolic       | boolean | 是 | 系统字体是否支持符号字体。  |
157
158**示例：**
159
160```ts
161// xxx.ets
162import font from '@ohos.font';
163
164@Entry
165@Component
166struct FontExample {
167  fontList: Array<string> = new Array<string>();
168  fontInfo: font.FontInfo = font.getFontByName('');
169  build() {
170    Column() {
171      Button("getFontByName")
172        .onClick(() => {
173          this.fontInfo = font.getFontByName('Sans Italic')
174          console.log("getFontByName(): path = " + this.fontInfo.path)
175          console.log("getFontByName(): postScriptName = " + this.fontInfo.postScriptName)
176          console.log("getFontByName(): fullName = " + this.fontInfo.fullName)
177          console.log("getFontByName(): Family = " + this.fontInfo.family)
178          console.log("getFontByName(): Subfamily = " + this.fontInfo.subfamily)
179          console.log("getFontByName(): weight = " + this.fontInfo.weight)
180          console.log("getFontByName(): width = " + this.fontInfo.width)
181          console.log("getFontByName(): italic = " + this.fontInfo.italic)
182          console.log("getFontByName(): monoSpace = " + this.fontInfo.monoSpace)
183          console.log("getFontByName(): symbolic = " + this.fontInfo.symbolic)
184        })
185    }.width('100%')
186  }
187}
188```