适用范围本文适用于使用 ArkTS 和 ArkUI 开发的 HarmonyOS 应用说明如何将.ttf或.otf字体文件放入工程、完成字体注册并在Text等组件中使用较早的项目可能使用ohos.font中的静态registerFont()方法该方法在较新的 API 中已经废弃新代码应优先使用UIContext提供的字体管理接口准备字体文件第三方字体通常以.ttf或.otf文件提供HarmonyOS 工程可以同时存放多个字体文件使用字体前需要确认以下事项字体授权允许嵌入应用并随安装包分发中文字体文件通常较大需要关注 HAP 安装包体积文件名建议只使用英文字母、数字、连字符和下划线放置字体文件在模块的resources/rawfile目录下创建fonts目录并将字体文件放入其中entry/src/main/resources/rawfile/fonts/SourceHanSerifSC-Regular.otf字体授权文件 ( license / OFL ) 建议与字体一起保留但授权文件不参与字体注册定义字体名称常量建议将应用使用的字体名称集中定义避免在多个页面中重复填写字符串在以下位置创建字体配置文件entry/src/main/ets/common/AppFonts.ets写入exportconstAPP_SERIF_FONT_FAMILY:stringxxSourceHanSerif;这里的xxSourceHanSerif是应用内部使用的字体别名可以自行命名该名称不必与字体文件名完全一致但注册字体和使用字体时必须保持一致注册字体字体文件放入工程后不能直接通过.fontFamily()使用必须先在 UI 上下文中完成注册可以在应用入口页面的aboutToAppear()生命周期中注册例如import{hilog}fromkit.PerformanceAnalysisKit;import{APP_SERIF_FONT_FAMILY}from../common/AppFonts;EntryComponentstruct Index{aboutToAppear():void{try{this.getUIContext().getFont().registerFont({familyName:APP_SERIF_FONT_FAMILY,familySrc:$rawfile(fonts/SourceHanSerifSC-Regular.otf)});}catch(error){hilog.error(0x0000,HomePage,Register app font failed: %{public}s,JSON.stringify(error));}}build(){Column(){Text(应用首页)}}}familyName字体在应用中的注册名称后续.fontFamily()必须使用同一个名称familySrc字体文件资源使用$rawfile()进行链接$rawfile(fonts/SourceHanSerifSC-Regular.otf)注册时机应在首次渲染使用该字体的组件之前完成注册单 UIAbility、单主窗口应用通常可以在入口页面注册一次不应在每个普通组件中重复注册如果应用包含多个 UIAbility、多个窗口或彼此独立的 UIContext需要在相应 UIContext 中分别确认字体已经注册在组件中使用字体先导入字体名称常量import{APP_SERIF_FONT_FAMILY}from../common/AppFonts;然后通过.fontFamily()应用字体Text(瓷序).fontSize(30).fontFamily(APP_SERIF_FONT_FAMILY).fontColor(#D8A756)只需要对部分文字使用第三方字体时给对应的Text组件设置.fontFamily()即可Column({space:12}){Text(使用第三方字体的标题).fontFamily(APP_SERIF_FONT_FAMILY).fontSize(28)Text(继续使用系统默认字体的正文).fontSize(16)}注册多个字体文件fonts目录中可以放置多个.otf或.ttf文件每个需要使用的字体文件都应单独注册例如entry/src/main/resources/rawfile/fonts/ ├─ SourceHanSerifSC-Regular.otf ├─ SourceHanSerifSC-Medium.otf └─ SourceHanSansSC-Regular.otf可以先定义多个字体名称exportconstAPP_SERIF_REGULAR:stringxxSerifRegular;exportconstAPP_SERIF_MEDIUM:stringxxSerifMedium;exportconstAPP_SANS_REGULAR:stringxxSansRegular;再分别注册constfontManagerthis.getUIContext().getFont();fontManager.registerFont({familyName:APP_SERIF_REGULAR,familySrc:$rawfile(fonts/SourceHanSerifSC-Regular.otf)});fontManager.registerFont({familyName:APP_SERIF_MEDIUM,familySrc:$rawfile(fonts/SourceHanSerifSC-Medium.otf)});fontManager.registerFont({familyName:APP_SANS_REGULAR,familySrc:$rawfile(fonts/SourceHanSansSC-Regular.otf)});使用时选择对应的字体名称Text(中等字重标题).fontFamily(APP_SERIF_MEDIUM).fontSize(24)Text(无衬线正文).fontFamily(APP_SANS_REGULAR).fontSize(16)推荐的工程组织方式字体文件、字体名称和字体使用代码建议分别承担不同职责entry/src/main/resources/rawfile/fonts/存放字体文件和授权文件entry/src/main/ets/common/AppFonts.ets定义字体名称常量entry/src/main/ets/pages/Index.ets在入口页面注册字体entry/src/main/ets/components/ entry/src/main/ets/pages/在具体组件和页面中通过.fontFamily()使用字体完整链接关系字体从文件到界面生效的关系如下字体文件 entry/src/main/resources/rawfile/fonts/SourceHanSerifSC-Regular.otf │ │ $rawfile(fonts/SourceHanSerifSC-Regular.otf) ▼ registerFont({ familyName, familySrc }) │ │ familyName: xxSourceHanSerif ▼ APP_SERIF_FONT_FAMILY │ │ .fontFamily(APP_SERIF_FONT_FAMILY) ▼ Text 等 ArkUI 组件常见问题粗体效果不符合预期不要只依赖系统模拟粗体将对应的 Medium、Semibold 或 Bold 字体文件单独注册并使用应用安装包明显变大中文字体可能包含大量字符应只保留项目确实需要的字体和字重并在字体授权允许的前提下考虑使用官方子集版本字体文件可以放多个吗可以同一个fonts目录能够存放多个.otf和.ttf文件但每个实际使用的文件都需要注册
