引言在移动应用界面设计中字体是用户体验的第一触点。不同于 Web 前端的 CSSfont-face即可加载网络字体也不同于 iOS 的有限系统字体集HarmonyOS NEXT 的ohos.font模块提供了一套完整的字体管理 API——开发者可以枚举系统中安装的所有字体、查询任意字体的详细元数据包括 weight、italic、monoSpace 等、注册自定义 .ttf/.otf 文件供全局使用甚至窥探系统 UI 字体配置的内部结构。本文构建一个字体实验室Demo浏览系统字体列表并让每种字体以自身字形展示其名称点击即可查看该字体的完整元数据family/subfamily/postScriptName/weight/width/italic/monoSpace/symbolic在实时预览区输入任意文字以选中的字体渲染并演示通过registerFont()动态加载自定义 .ttf 文件。读完本文你将掌握字体枚举getSystemFontList()返回系统安装的所有字体名数组字体详情查询getFontByName()返回FontInfo— 9 个字段的完整字体档案字形预览通过fontFamily()属性将字体名作用于 Text 组件自定义字体注册registerFont({ familyName, familySrc })动态加载外部字体文件UI 字体配置getUIFontConfig()暴露系统的 generic/alias/adjust/fallback 字体策略API 演进部分 API 在 API 18 标记 deprecated迁移到 UIContext.Font 的趋势环境与权限ohos.font属于ArkUI工具包自 API 9 开始提供。导入方式importfontfromohos.font;零权限需求字体查询和注册操作完全是客户端的行为不涉及系统服务调用或用户数据访问因此不需要任何权限声明。一、核心数据类型1.1 FontInfo — 字体元数据档案interfaceFontInfo{path:string;// 字体文件路径postScriptName:string;// PostScript 名称字体唯一标识fullName:string;// 完整字体名family:string;// 字体系列名subfamily:string;// 子系列名如 Bold/Italic/Regularweight:number;// 字重100Thin ~ 900Blackwidth:number;// 字体宽度italic:boolean;// 是否斜体monoSpace:boolean;// 是否等宽字体symbolic:boolean;// 是否支持符号字体}FontInfo是最核心的数据结构——它完整描述了一个字体的身份档案。postScriptName是字体的身份证号每个字体文件有且只有一个familysubfamily共同定位字体在族系中的位置weight遵循 CSS 字重规范100Thin到 900Blackitalic标识是否斜体变体monoSpace标识是否等宽symbolic标识是否包含符号字形1.2 FontOptions — 注册配置interfaceFontOptions{familyName:string|Resource;// 注册后的字体名familySrc:string|Resource;// 字体文件路径}familyName是注册后用于Text().fontFamily()的名称familySrc指向 .ttf 或 .otf 文件的沙箱路径。1.3 UIFontConfig — 系统字体策略interfaceUIFontConfig{fontDir:Arraystring;// 系统字体文件目录generic:ArrayUIFontGenericInfo;// 通用字体组配置fallbackGroups:ArrayUIFontFallbackGroupInfo;// 回退字体策略}UIFontConfig是 HarmonyOS 字体系统的配置档案暴露了系统如何组织通用字体generic和回退字体fallback的策略。这是理解 HarmonyOS 多语言排版能力的关键入口。二、枚举系统字体列表2.1 getSystemFontList()letfontNames:string[]font.getSystemFontList();同步返回所有系统安装字体的名称数组。典型系统包含 50-100 款字体涵盖中英文、日文、韩文等多个语言族系。2.2 以字体本身展示字体名最基本的字体预览就是把字体作用在自身名称上ForEach(fontNames,(name:string){Text(name).fontFamily(name)// 精确匹配——该字体渲染自己的名字.fontSize(16)})这个简单的技巧让用户能在列表中直观感受到每个字体的笔画风格。HarmonyOS Sans 系列字体会展示为现代无衬线风格而宋体/楷体等中文字体会呈现出各自的经典造型。三、查询字体详情3.1 getFontByName()letinfo:font.FontInfofont.getFontByName(HarmonyOS Sans SC);同步返回指定字体名的完整FontInfo对象。如果字体名不存在该方法会抛出异常需要try/catch包裹。3.2 字重解码weight字段的值与字重名称的对应关系Weight 值名称CSS 等价100Thinfont-weight: 100200ExtraLightfont-weight: 200300Lightfont-weight: 300400Regular / Normalfont-weight: 400500Mediumfont-weight: 500600SemiBoldfont-weight: 600700Boldfont-weight: 700800ExtraBoldfont-weight: 800900Blackfont-weight: 900在 Demo 中我们通过weightLabel()辅助函数将数值映射为人类可读的字重名称。3.3 实战代码获取并展示字体详情letnameHarmonyOS Sans SC;letinfofont.getFontByName(name);console.log(字体全名: info.fullName);console.log(PostScript 标识: info.postScriptName);console.log(字重: info.weight (Regular));console.log(是否等宽: (info.monoSpace?是:否));console.log(是否斜体: (info.italic?是:否));console.log(是否支持符号: (info.symbolic?是:否));console.log(文件路径: info.path);四、自定义字体注册4.1 registerFont()try{font.registerFont({familyName:MyBrandFont,familySrc:/data/storage/el2/base/files/fonts/brand.ttf});console.log(自定义字体注册成功);}catch(e){console.error(注册失败: JSON.stringify(e));}registerFont()将外部 .ttf/.otf 字体文件加载到系统 FontManager 中。注册成功后该字体可以通过fontFamily(MyBrandFont)在任何 Text 组件中使用效果等同于系统自带字体。注意事项familySrc路径必须是应用沙箱内的绝对路径如/data/storage/el2/base/...字体文件需要提前放入应用的沙箱存储中通常通过file.fs写入注册是进程级的——应用退出后需要重新注册该方法在 API 18 标记为deprecated推荐迁移到UIContext.Font#registerFont4.2 注册后验证// 注册后立即验证letnamesfont.getSystemFontList();if(names.indexOf(MyBrandFont)0){console.log(字体已在系统列表中);}注册成功后getSystemFontList()的返回数组中会包含新注册的字体名。五、系统 UI 字体配置5.1 getUIFontConfig()letconfigfont.getUIFontConfig();console.log(字体目录: config.fontDir.length 个);config.fontDir.forEach((dir,idx){console.log( [idx] dir);});console.log(通用字体组: config.generic.length 组);config.generic.forEach((gen){console.log( gen.family (别名: gen.alias.length));});console.log(回退字体组: config.fallbackGroups.length 组);getUIFontConfig()返回的是 HarmonyOS 字体系统的完整内部策略配置包含三个核心维度fontDir系统从哪些目录加载字体文件通常是/system/fonts等系统路径generic通用字体组——每组的family定义了一个抽象字体系列如 “sans-serif”alias定义了不同字重的实际映射字体adjust定义了字重映射规则fallbackGroups回退策略——当渲染指定字体缺失的字形时按languagefamily匹配回退字体这个 API 对于想深入理解 HarmonyOS 文本渲染管线的开发者来说是无价的。六、Text.fontFamily() — 在 UI 中使用字体获取字体名和详情的最终目的是在 UI 渲染中使用它们// 使用系统字体Text(HarmonyOS 鸿蒙操作系统).fontFamily(HarmonyOS Sans SC).fontSize(28)// 使用自定义注册字体Text(Welcome to HarmonyOS).fontFamily(MyBrandFont).fontSize(24).fontWeight(FontWeight.Bold)fontFamily()属性接受字体名family name字符串。系统会优先使用指定字体渲染文本如果该字体缺少某个字符的字形会自动触发回退机制根据UIFontConfig.fallbackGroups查找替代字体。七、API 演进趋势从 API 版本注解中可以看出字体 API 的演进方向API状态新方向font.registerFont()API 18 deprecatedUIContext.Font#registerFontfont.getSystemFontList()API 18 deprecatedUIContext.Font#getSystemFontListfont.getFontByName()API 18 deprecatedUIContext.Font#getFontByNameHarmonyOS 正在将字体管理从全局单例模型迁移到UIContext上下文模型。这意味着未来的字体操作将按 UIWindow/UIAbility 上下文隔离——不同的 Ability 实例可以有不同的字体配置而不共享全局状态。这对于多窗口应用、跨设备分布式场景来说是一个重要的架构升级。八、实战 Demo字体实验室页面结构字体实验室 ├── 状态栏 — 已加载字体数量 UIFontConfig 摘要 ├── 字体预览区 │ ├── 可编辑样本文字输入框 │ ├── 字号调节± 按钮12-72px │ └── 大尺寸预览卡片以选中字体渲染样本文字 ├── 字体详情面板选中字体后显示 │ ├── fullName postScriptName │ ├── family / subfamily / weight │ ├── italic / monoSpace / symbolic 标签 │ └── 字体文件路径 ├── 系统字体列表50 款 │ ├── 每种字体以自身字形展示其名称 │ ├── 字重标签Thin/Regular/Bold 等 │ └── 高亮选中项 ├── 自定义字体注册 │ ├── 字体名 文件路径输入 │ └── 注册按钮 状态反馈 └── 核心 API 参考 — 10 个关键 API4 个交互点浏览系统字体列表— 每种字体以自身字形展示其名称右侧显示字重标签点击选中高亮实时字形预览— 在顶部输入框编辑任意文字选择字号12-72选中字体实时渲染用户输入的样本文字字体详情查看— 选中字体后展示完整的 FontInfo9 个字段含 family/subfamily/weight/italic/monoSpace/symbolic 标签自定义字体注册— 输入字体名和沙箱路径点击注册字体将外部 .ttf 文件注册到系统成功后刷新字体列表核心代码位置完整代码在dev/entry/src/main/ets/pages/TypographyLabPage.ets约 330 行路由已注册为pages/TypographyLabPage。九、与 CSS font-face 的对比对于有 Web 开发经验的开发者维度CSS font-faceHarmonyOS ohos.font字体注册font-face { font-family; src; }font.registerFont()字体枚举无标准 APIfont.getSystemFontList()字体元数据无标准 APIfont.getFontByName()— FontInfo字体策略查询无font.getUIFontConfig()字形变体font-weight/font-styleFontInfo.weight / .italic回退机制font-family: A, B, CUIFontConfig.fallbackGroups运行时动态加载Web Font Loader 库font.registerFont()原生支持HarmonyOS 的字体 API 远超 CSS 标准的能力范围——不仅提供了运行时注册还提供了完整的字体元数据查询和系统策略检查。十、总结ohos.font是 HarmonyOS NEXT 字体系统的程序化入口核心能力字体枚举getSystemFontList()返回系统全部字体名通过fontFamily()即时预览元数据查询getFontByName()提供 9 字段 FontInfo覆盖字重/宽度/斜体/等宽/符号等所有维度自定义字体registerFont()支持运行时加载外部字体文件品牌定制化不再受限策略洞察getUIFontConfig()暴露系统通用字体和回退策略的内部配置演进趋势API 18 起迁移到 UIContext 上下文模型为多窗口场景铺路结合 SymbolGlyph系统图标、RichEditor富文本编辑器和 Span富文本排版HarmonyOS 开发者已经掌握了从字体管理到排版渲染的完整工具链。