ArkUI Cangjie UIContext Font API:仓颉语言下自定义字体注册、系统字体枚举与字体信息查询实战指南

原创2026-10-15 16:05:551,877 阅读
文章标签:文档知识库

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 即恢复默认字体。

因此完整的自定义字体工作流为:

  1. 将 TTF 文件放入工程 rawfile 目录(见资源访问说明);
  2. 在合适时机(示例中选择组件 onAppear() 生命周期回调)调用 registerFont(familyName: ..., familySrc: ...) 完成注册;
  3. 在任意 Text 组件上通过 .fontFamily("注册的字体族名") 引用;
  4. 若需验证字体已生效,可调用 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 类型做穷尽分支。

六、常见问题与注意事项汇总

  1. 必须先获取 Font 实例:Font 的所有方法都挂在 UIContext.getFont() 返回的实例上,不能直接以 Font.registerFont(...) 的方式静态调用。
  2. 平台差异:getSystemFontList() 仅 PC/2in1 生效,其他设备静默返回空数组,不会抛异常,做 UI 时要有空列表兜底。
  3. 命名参数不可省略:registerFont 的两个参数均为命名参数(familyName!、familySrc!),调用时必须带参数名,否则触发 401 参数检查失败。
  4. 资源路径:字体文件建议置于 rawfile 目录,路径以 /resources/rawfile/xxx.ttf 形式传入;rawfile 资源不经编译、按路径直接引用(参见资源分类与访问)。
  5. 能力与版本约束:SystemCapability.ArkUI.ArkUI.Full、起始版本 22,使用前需确认设备能力声明与 API 版本满足要求。
  6. 异常处理: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 应用中完整实现"携带自定义字体 → 注册 → 按名引用 → 查询校验"的字体能力闭环。

登录后查看全文
CangjieCorpus