本模块提供注册自定义字体、获取系统字体列表、获取字体详细信息以及获取系统字体配置等能力,适用于应用需要使用自定义字体样式(如品牌字体、图标字体)或获取系统字体信息的场景。通过使用本模块,开发者可以实现品牌字体统一、提升用户界面美观度和一致性,满足多样化的设计需求。
registerFont(options: FontOptions): void
在字体管理中注册自定义字体。
该接口为异步接口,不支持并发调用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| options | FontOptions | 是 | 注册的自定义字体信息。 |
注册的自定义字体信息。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| familyName | string | Resource10+ | 否 | 否 | 设置注册的字体名称。建议使用字母、数字和下划线组成。 |
| familySrc | string | Resource10+ | 否 | 否 | 设置注册字体文件的路径。支持Resource资源引用、$rawfile路径、相对路径和绝对路径。 说明: 读取系统沙箱路径内的资源时,建议使用file://路径前缀的字符串,需要确保沙箱目录路径下的文件存在并且有可读权限。 |
示例:
// xxx.ets
@Entry
@Component
struct FontExample {
@State message: string = 'Hello World';
// iconFont示例,假设0000为指定icon的Unicode,实际需要开发者从注册的iconFont的ttf文件里面获取Unicode
@State unicode: string = '\u0000';
@State codePoint: string = String.fromCharCode(0x0000);
private uiContext: UIContext = this.getUIContext();
aboutToAppear() {
// familyName和familySrc都支持系统Resource
this.uiContext.getFont().registerFont({
// 建议使用 this.getUIContext().getFont().registerFont()接口
// 'app.string.font_name'和'app.string.font_src'仅作示例,请替换为实际使用资源字符串
familyName: $r('app.string.font_name'),
familySrc: $r('app.string.font_src')
});
// familySrc支持RawFile
this.uiContext.getFont().registerFont({
familyName: 'mediumRawFile',
familySrc: $rawfile('font/medium.ttf') // 'font/medium.ttf'仅作示例,请替换为实际使用资源字体文件
});
// 注册iconFont
this.uiContext.getFont().registerFont({
familyName: 'iconFont',
familySrc: '/font/iconFont.ttf'
});
// familyName和familySrc都支持string
this.uiContext.getFont().registerFont({
familyName: 'medium',
familySrc: '/font/medium.ttf' // font文件夹与pages目录同级
});
}
build() {
Column() {
Text(this.message)
.align(Alignment.Center)
.fontSize(20)
.fontFamily('medium') // medium:注册自定义字体的名字($r('app.string.font_name')、'mediumRawFile'等已注册字体也能正常使用)
// 使用iconFont的两种方式
Text(this.unicode)
.align(Alignment.Center)
.fontSize(20)
.fontFamily('iconFont')
Text(this.codePoint)
.align(Alignment.Center)
.fontSize(20)
.fontFamily('iconFont')
}.width('100%')
}
}
应用若需全局使用自定义字体,请在EntryAbility.ets文件的onWindowStageCreate生命周期中,通过windowStage.loadContent回调注册。
在HSP工程中,不推荐采用相对路径的方式注册自定义字体,详见通过$r访问HSP中的资源。
getSystemFontList(): Array<string>
获取系统字体列表。
该接口仅在PC/2in1设备上生效,在其他设备上返回空数组。
推荐使用getSystemFontFullNamesByType接口获取系统最新支持的字体列表数据。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| Array<string> | 系统的字体名列表。 |
示例:
// 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(); // 建议使用 this.getUIContext().getFont().getSystemFontList()接口
})
}.width('100%')
}
} getFontByName(fontName: string): FontInfo
根据传入的系统字体名称获取系统字体的相关信息。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fontName | string | 是 | 系统的字体名。 |
返回值:
| 类型 | 说明 |
|---|---|
| FontInfo | 字体的详细信息,包含路径、名称、字重、宽度、是否倾斜等属性。 |
字体的详细信息。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| path | string | 否 | 否 | 系统字体的文件路径。 |
| postScriptName | string | 否 | 否 | 系统字体的postScript名称。 |
| fullName | string | 否 | 否 | 系统字体的名称。 |
| family | string | 否 | 否 | 系统字体的字体家族。 |
| subfamily | string | 否 | 否 | 系统字体的子字体家族。 |
| weight | number | 否 | 否 | 系统字体的字重。 取值范围:[100,900],取值间隔为100,分别对应FontWeight枚举中的值。 |
| width | number | 否 | 否 | 系统字体的宽度。 取值范围:[1,9],取值间隔为1,分别对应FontWidth枚举中的值。 |
| italic | boolean | 否 | 否 | 系统字体是否倾斜。 默认值:false 值为true,表示斜体字体,值为false,表示非斜体字体。 |
| monoSpace | boolean | 否 | 否 | 系统字体是否等宽。 默认值:false 值为true,表示等宽字体,值为false,表示非等宽字体。 |
| symbolic | boolean | 否 | 否 | 系统字体是否支持符号字体。 默认值:false 值为true,表示支持符号字体,值为false,表示不支持符号字体。 |
示例:
// xxx.ets
@Entry
@Component
struct FontExample {
private fontInfo = this.getUIContext().getFont().getFontByName('');
build() {
Column() {
Button('getFontByName')
.onClick(() => {
this.fontInfo =
this.getUIContext().getFont().getFontByName('HarmonyOS Sans Italic');
console.info('getFontByName(): path = ' + this.fontInfo.path);
console.info('getFontByName(): postScriptName = ' + this.fontInfo.postScriptName);
console.info('getFontByName(): fullName = ' + this.fontInfo.fullName);
console.info('getFontByName(): family = ' + this.fontInfo.family);
console.info('getFontByName(): subfamily = ' + this.fontInfo.subfamily);
console.info('getFontByName(): weight = ' + this.fontInfo.weight);
console.info('getFontByName(): width = ' + this.fontInfo.width);
console.info('getFontByName(): italic = ' + this.fontInfo.italic);
console.info('getFontByName(): monoSpace = ' + this.fontInfo.monoSpace);
console.info('getFontByName(): symbolic = ' + this.fontInfo.symbolic);
})
}.width('100%')
}
} getUIFontConfig() : UIFontConfig
获取系统字体配置文件的UI字体配置信息。常用于需要分析或查看系统字体配置的场景,例如:字体管理工具、字体调试与诊断、字体配置信息展示等。
该接口仅支持获取配置文件内的信息以及当UI上下文不明确时可能返回undefined,如需获取全量的字体配置信息,推荐使用字体引擎的getSystemFontFullNamesByType接口获取系统最新支持的字体列表数据。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| UIFontConfig | 系统的UI字体配置信息,包含字体目录、通用字体集、备用字体集等。 |
系统的UI字体配置信息。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| fontDir | Array<string> | 否 | 否 | 系统字体文件所在的路径列表,数组元素为系统绝对路径。 |
| generic | Array<UIFontGenericInfo> | 否 | 否 | 系统所支持的通用字体集列表。 |
| fallbackGroups | Array<UIFontFallbackGroupInfo> | 否 | 否 | 系统备用字体集列表,用于指定当主字体不支持某些字符时使用的备用字体。 |
系统所支持的通用字体集列表。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| family | string | 否 | 否 | 字体集名,字体文件中指定的"family"值。 |
| alias | Array<UIFontAliasInfo> | 否 | 否 | 字体集的别名列表,用于提供字体的替代名称。 |
| adjust | Array<UIFontAdjustInfo> | 否 | 否 | 字体weight值映射列表,将字体原本的weight值映射为实际显示的weight值。 |
备用字体集。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| fontSetName | string | 否 | 否 | 备用字体集所对应的字体集名称。如果fontSetName为"",表示备用字体集可用于所有字体集。 |
| fallback | Array<UIFontFallbackInfo> | 否 | 否 | 表示以下列表为该字体集的备用字体,如果fontSetName为"",表示可以作为所有字体集的备用字体。 |
别名列表。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| name | string | 否 | 否 | 别名名称。 |
| weight | number | 否 | 否 | 当weight>0时表示此字体集只包含所指定weight的字体,当weight=0时,表示此字体集包含所有字体。 可返回的值有0、100、400、700、900。 |
字体原本的weight值和显示实际值的映射列表。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| weight | number | 否 | 否 | 字体原本的weight值。 可返回的值有50、80、100、200。 |
| to | number | 否 | 否 | 字体在应用中显示的weight值。 可返回的值有100、400、700、900。 |
该字体集的备用字体。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| language | string | 否 | 否 | 字体集所支持的语言类型,语言格式为BCP47标签(如"zh-Hans"表示简体中文,"en"表示英语)。 |
| family | string | 否 | 否 | 字体集名,字体文件中指定的"family"值。 |
示例:
// 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.info('font-dir -----------' + String(fontConfig.fontDir.length));
for (let i = 0; i < fontConfig.fontDir.length; i++) {
console.info(fontConfig.fontDir[i]);
}
console.info('generic-------------' + String(fontConfig.generic.length));
for (let i = 0; i < fontConfig.generic.length; i++) {
console.info('family:' + fontConfig.generic[i].family);
for (let j = 0; j < fontConfig.generic[i].alias.length; j++) {
console.info(fontConfig.generic[i].alias[j].name + ' ' + fontConfig.generic[i].alias[j].weight);
}
for (let j = 0; j < fontConfig.generic[i].adjust.length; j++) {
console.info(fontConfig.generic[i].adjust[j].weight + ' ' + fontConfig.generic[i].adjust[j].to);
}
}
console.info('fallbackGroups------------' + String(fontConfig.fallbackGroups.length));
for (let i = 0; i < fontConfig.fallbackGroups.length; i++) {
console.info('fontSetName:' + fontConfig.fallbackGroups[i].fontSetName);
for (let j = 0; j < fontConfig.fallbackGroups[i].fallback.length; j++) {
console.info('language:' + fontConfig.fallbackGroups[i].fallback[j].language + ' family:' +
fontConfig.fallbackGroups[i].fallback[j].family);
}
}
})
}.width('100%')
}
}