ArkUI Cangjie UIContext Font API:仓颉语言下自定义字体注册、系统字体枚举与字体信息查询实战指南
ArkUI Cangjie UIContext Font API:仓颉语言下自定义字体注册、系统字体枚举与字体信息查询实战指南
本文基于 CangjieCorpus 语料库中的 ArkUI Cangjie 字体 API 参考文档(cj-apis-uicontext-font.md),系统讲解仓颉(Cangjie)语言在 HarmonyOS ArkUI 框架中通过 UIContext.getFont() 获取 Font 实例的完整链路,覆盖 registerFont 注册自定义字体、getSystemFontList 枚举系统字体、getFontByName 查询字体详细信息三大接口,以及 FontInfo 数据类的全部十个属性。读完本文,你能够掌握:在仓颉声明式 UI 中加载 rawfile 目录下的 TTF 字体并让 Text 组件生效、按设备形态安全地读取系统字体列表、以及使用 Option 模式匹配处理字体查不到的场景。
一、Font API 的使用前提与获取方式
Font 类并非直接暴露的全局对象。按照参考文档的说明,所有字体相关 API 必须先使用 UIContext 中的 getFont() 方法获取 Font 实例,再通过该实例调用对应方法:
public func getFont(): Font
getFont() 的返回类型即为本文的主角 Font(文档中标注其引用为 Font 公共类型)。其系统能力为 SystemCapability.ArkUI.ArkUI.Full,起始版本为 22。
整个 Font 模块的导入方式为:
import kit.ArkUI.*
模块整体定义如下:
public class Font {}
功能定位:字体类,提供字体注册、获取系统字体列表和根据字体名称获取字体信息等功能。所有方法共享同样的系统能力(SystemCapability.ArkUI.ArkUI.Full)与起始版本(22)。这意味着使用该能力需要在设备能力声明中确认设备支持完整 ArkUI 能力,且应用编译目标需为 API 22 及以上。
二、Font 类方法详解
2.1 registerFont(ResourceStr, ResourceStr):注册自定义字体
这是 Font 类中最核心的接口,用于将应用携带的字体文件纳入 ArkUI 字体管理体系,注册后即可在组件属性中通过字体族名称引用。
public func registerFont(familyName!: ResourceStr, familySrc!: ResourceStr): Unit
参数说明(两个参数均为命名参数且必填,无默认值):
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| familyName | ResourceStr | 是 | - | 命名参数。 字体名称(字体族名),注册后供 fontFamily 等属性引用。 |
| familySrc | ResourceStr | 是 | - | 命名参数。 字体资源路径。 |
关于参数类型 ResourceStr,从 ArkUI 公共类型定义看,它是一个字符串类型接口,用于描述字符串入参可以使用的类型,其中 String 被扩展为其子类型(extend String <: ResourceStr),因此可以直接传普通字符串字面量(如 "/resources/rawfile/xxx.ttf"),也可以传入资源引用形式。
返回值:Unit(仓颉中表示无返回值)。
异常:BusinessException,对应错误码如下(详见通用错误码):
| 错误码 | 说明 |
|---|---|
| 401 | Invalid input parameter(必填参数为空、参数类型不正确或参数校验失败) |
| 100001 | Internal error. |
从 通用错误码文档中可以看到,401 的典型成因是:必选参数没有传入、参数类型错误(Type Error)、参数数量错误(Argument Count Error)。对 registerFont 而言,实际开发中最常见的是字体资源路径不存在导致资源解析失败,触发 401。
字体资源的放置约定:结合 资源分类与访问说明,TTF 字体文件通常放在工程 resources 下的 rawfile 目录。rawfile 目录中的文件会被直接打包进应用,不经过编译、不赋予资源 ID,通过指定文件路径和文件名引用;应用资源一般以 @rawfile("filename") 形式引用(文件名需含后缀,路径开头不能以 / 开头)。官方示例代码中 familySrc 传值 /resources/rawfile/SmileySans-Oblique.ttf,即指向 rawfile 目录下的字体文件。
2.2 getSystemFontList():获取系统字体列表
public func getSystemFontList(): Array<String>
功能:获取系统支持的字体列表。
返回值:
| 类型 | 说明 |
|---|---|
| Array<String> | 系统字体名称列表。 |
重要限制:该接口仅在 PC/2in1 设备上生效,在其他设备上返回空数组。这是一个必须牢记的平台相关行为——在平板、手机上调用该接口不会报错,但会得到长度为 0 的数组,因此在做字体选择器、字体预览等 UI 功能前,应先判断返回数组是否为空,避免在非 PC 形态设备上出现空列表界面。
2.3 getFontByName(String):根据名称查询字体详细信息
public func getFontByName(fontName: String): ?FontInfo
功能:根据字体名称获取字体详细信息。
参数:
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| fontName | String | 是 | - | 字体名称。 |
返回值:
| 类型 | 说明 |
|---|---|
| ?FontInfo | 返回字体信息,如果找不到对应字体则返回 None。 |
注意返回值使用了仓颉的可空类型 ?FontInfo,即"要么有一个 FontInfo 值、要么为 None"。这与仓颉语言中 Option/可空类型的模式匹配惯用法直接对应:调用方应通过 match 对 Some(v) / None 两种分支分别处理,而不是直接解引用,这也是官方示例 3 的写法(见第五节)。
三、FontInfo 类详解:字体详细信息数据类
FontInfo 用于承载 getFontByName 返回的字体元数据:
public class FontInfo {
public var family: String
public var fullName: String
public var italic: Bool
public var monoSpace: Bool
public var path: String
public var postScriptName: String
public var subfamily: String
public var symbolic: Bool
public var weight: UInt32
public var width: UInt32
}
功能:字体的详细信息。系统能力:SystemCapability.ArkUI.ArkUI.Full;起始版本:22。
十个字段均为可读写公开属性,语义如下:
| 属性 | 类型 | 功能 | 典型用途 |
|---|---|---|---|
family |
String | 字体家族 | 与 fontFamily 属性、registerFont 的 familyName 对应,用于按族归类字体 |
fullName |
String | 字体完整名称 | 展示层完整字体名,如 "HarmonyOS Sans Italic" 这类带样式的名称 |
italic |
Bool | 是否为斜体 | 字体样式筛选、斜体变体识别 |
monoSpace |
Bool | 是否为等宽字体 | 代码编辑器、日志面板等对等宽字体的偏好判断 |
path |
String | 字体文件路径 | 定位字体文件本体(示例 3 中直接打印该字段) |
postScriptName |
String | PostScript 名称 | 与底层字体引擎/排版系统交互时的规范名称 |
subfamily |
String | 字体子族名称 | 区分同族内的 Regular/Bold 等变体 |
symbolic |
Bool | 是否支持符号字体 | 判断字体是否覆盖特殊符号字形 |
weight |
UInt32 | 字体粗细 | 数值化字重(对应 OpenType 中 100~900 的字重刻度语义),可用于与 fontWeight 属性联动 |
width |
UInt32 | 字体宽度 | 数值化宽度比例(常规宽度通常为 100),可用于等宽/压缩/扩展字体判断 |
weight 与 width 采用 UInt32 而非浮点,从数值语义看与 OpenType 规范中的 usWeightClass / usWidthClass 保持一致,即"字重 400=Regular、700=Bold;宽度 100=常规"这类整数量表。这一推断基于字体技术通用惯例,仓颉文档本身未展开数值刻度表,具体渲染以系统行为为准。
从 FontInfo 字段与 ArkUI 组件体系的对应关系看("从源码结构看"指文档间的交叉引用):family/postScriptName 对应 Text 组件 fontFamily 属性 的取值;weight/width/italic 对应 fontWeight、fontStyle 等排版属性的维度;monoSpace 则可用于识别等宽字体。这也解释了为什么 getFontByName 返回 FontInfo 而非简单布尔值——它提供的是"可驱动排版属性设置"的完整元数据。
四、字体名称的约定与 fontFamily 的联动
registerFont 注册时使用 familyName 命名字体族,随后组件通过 fontFamily 属性按名引用。结合 Text 组件文档,fontFamily 的定义为:
public func fontFamily(value: ?ResourceStr): This
参数 value 类型为 ?ResourceStr(可空),用于设置文本的字体族,初始值为 "HarmonyOS Sans"(系统默认字体)。传 None 即恢复默认字体。
因此完整的自定义字体工作流为:
- 将 TTF 文件放入工程
rawfile目录(见资源访问说明); - 在合适时机(示例中选择组件
onAppear()生命周期回调)调用registerFont(familyName: ..., familySrc: ...)完成注册; - 在任意
Text组件上通过.fontFamily("注册的字体族名")引用; - 若需验证字体已生效,可调用
getFontByName查询其FontInfo(如path、postScriptName)确认。
五、完整示例代码
以下三个示例完整继承自参考文档(均标注 <!-- run -->,即仓库中可直接运行的示例),展示三大接口的实际调用方式。
示例 1:注册自定义字体
package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*
import ohos.i18n.*
import ohos.resource_manager.*
@Entry
@Component
class EntryView {
protected func onAppear() {
getUIContext().getFont().registerFont(
familyName: "Deyihei",
familySrc: "/resources/rawfile/SmileySans-Oblique.ttf"
)
}
func build() {
Row {
Column {
Text("HelloWorld").fontFamily("Deyihei")
Text("HelloWorld")
}.width(100.percent)
}.height(100.percent)
}
}
示例要点:
- 注册动作放在
onAppear()生命周期回调中,保证组件构建完成、字体可用后再参与排版; familyName使用自定义名称"Deyihei",familySrc指向 rawfile 下的SmileySans-Oblique.ttf;- 第一个
Text通过.fontFamily("Deyihei")使用刚注册的字体,第二个Text使用默认字体"HarmonyOS Sans"作对照,两者并排即可直观看到字形差异; - 命名参数(
familyName:/familySrc:)是仓颉调用该 API 的强制语法,参数名不可省略。
示例 2:获取系统字体列表
package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*
import ohos.hilog.*
@Entry
@Component
class EntryView {
func build() {
Row {
Column {
Button("HelloWorld")
.onClick({evt =>
let list = getUIContext().getFont().getSystemFontList()
Hilog.info(0, "AppLogCj", "${list.size}")
})
}.width(100.percent)
}.height(100.percent)
}
}
示例要点:
- 点击按钮时调用
getSystemFontList(),将字体数量通过Hilog.info打印到日志(domain 为 0,tag 为"AppLogCj"); - 再次提醒:仅 PC/2in1 设备返回非空列表,其他设备
list.size为 0; - 字符串模板插值
${list.size}是仓颉语言的特性,日志输出为格式化后的字符串。
示例 3:获取字体详细信息
package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*
import ohos.hilog.*
@Entry
@Component
class EntryView {
func build() {
Row {
Column {
Button("HelloWorld")
.onClick({evt =>
let info = getUIContext().getFont().getFontByName("HarmonyOS Sans Italic")
match (info) {
case Some(v) =>
Hilog.info(0, "AppLogCj", "${v.path}")
Hilog.info(0, "AppLogCj", "${v.postScriptName}")
Hilog.info(0, "AppLogCj", "${v.fullName}")
Hilog.info(0, "AppLogCj", "${v.family}")
Hilog.info(0, "AppLogCj", "${v.subfamily}")
Hilog.info(0, "AppLogCj", "${v.weight}")
Hilog.info(0, "AppLogCj", "${v.width}")
Hilog.info(0, "AppLogCj", "${v.italic}")
Hilog.info(0, "AppLogCj", "${v.monoSpace}")
Hilog.info(0, "AppLogCj", "${v.symbolic}")
case None => Hilog.error(0, "AppLogCj", "None")
}
})
}.width(100.percent)
}.height(100.percent)
}
}
示例要点:
- 以系统自带字体
"HarmonyOS Sans Italic"为例,演示了FontInfo全部 10 个字段(path、postScriptName、fullName、family、subfamily、weight、width、italic、monoSpace、symbolic)的逐项读取; - 返回值
?FontInfo通过仓颉的match模式匹配解构:Some(v)分支持有字体信息对象并逐字段打日志,None分支说明按名未找到字体,输出错误日志——这是处理可空返回值的标准姿势; - 该示例与 仓颉枚举与模式匹配章节 的语法体系一致:
match表达式对可空/Option 类型做穷尽分支。
六、常见问题与注意事项汇总
- 必须先获取 Font 实例:Font 的所有方法都挂在
UIContext.getFont()返回的实例上,不能直接以Font.registerFont(...)的方式静态调用。 - 平台差异:
getSystemFontList()仅 PC/2in1 生效,其他设备静默返回空数组,不会抛异常,做 UI 时要有空列表兜底。 - 命名参数不可省略:
registerFont的两个参数均为命名参数(familyName!、familySrc!),调用时必须带参数名,否则触发 401 参数检查失败。 - 资源路径:字体文件建议置于
rawfile目录,路径以/resources/rawfile/xxx.ttf形式传入;rawfile 资源不经编译、按路径直接引用(参见资源分类与访问)。 - 能力与版本约束:
SystemCapability.ArkUI.ArkUI.Full、起始版本 22,使用前需确认设备能力声明与 API 版本满足要求。 - 异常处理:
registerFont可能抛出BusinessException(401 / 100001),生产代码中应结合仓颉的异常处理机制(try/catch)捕获并按 通用错误码 排查参数问题。
七、相关文档索引
| 主题 | 文档路径 |
|---|---|
| 本文主体:Font / FontInfo API 参考 | cj-apis-uicontext-font.md |
| UIContext 及 getFont() 入口 | cj-apis-uicontext-uicontext.md |
| ResourceStr 等公共类型定义 | cj-common-types.md |
| Text 组件 fontFamily 属性 | cj-text-input-text.md |
| MeasureUtils(字体/文本测量) | cj-apis-uicontext-measureutils.md |
| 通用错误码(401 / 201 等) | cj-errorcode-universal.md |
| 资源目录与 rawfile 访问方式 | ide-resource-categories-and-access.md |
| 仓颉 match 模式匹配语法 | match.md |
掌握 UIContext.getFont() 入口、三大接口的参数与平台限制、FontInfo 十个字段的语义,以及 fontFamily 的联动方式后,即可在仓颉 ArkUI 应用中完整实现"携带自定义字体 → 注册 → 按名引用 → 查询校验"的字体能力闭环。