鸿蒙三方库 | harmony-utils之AppUtil字体与语言设置详解

前言

国际化（i18n）是应用走向全球的基础能力。HarmonyOS提供了丰富的语言和字体设置接口，@pura/harmony-utils的AppUtil将这些接口封装为简洁易用的方法，开发者可以轻松获取系统语言、字体大小等信息，实现应用的国际化适配。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、字体与语言核心API

AppUtil提供了以下字体与语言相关方法，开发者可以根据实际需求选择调用：

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 统一风格：与harmony-utils其他工具类保持一致的调用风格

1.2 字体缩放影响对比

二、完整使用步骤

2.1 安装依赖

在项目根目录执行以下命令安装harmony-utils：

ohpminstall@pura/harmony-utils

安装完成后，在oh-package.json5中确认依赖已添加：

{"dependencies":{"@pura/harmony-utils":"^1.0.0"}}

2.2 获取系统语言

import{AppUtil}from'@pura/harmony-utils';Button('获取系统语言').width('100%').onClick(()=>{try{letlang=AppUtil.getLanguage();this.result=`系统语言:${lang}`;}catch(e){this.result='异常: '+e;}})

2.3 获取字体缩放比例

Button('获取字体缩放').width('100%').onClick(()=>{try{letscale=AppUtil.getFontScale();this.result=`字体缩放:${scale}\n提示: 大于1.0表示放大字体`;}catch(e){this.result='异常: '+e;}})

2.4 判断时间格式

Button('判断时间格式').width('100%').onClick(()=>{try{letis24=AppUtil.is24HourClock();this.result=`时间格式:${is24?'24小时制':'12小时制'}`;}catch(e){this.result='异常: '+e;}})

三、完整页面示例

以下是一个完整的页面组件，展示了字体与语言设置在实际项目中的集成方式：

import{AppUtil}from'@pura/harmony-utils';@Entry@Componentstruct FontLangDemo{@Stateresult:string='';@Statelanguage:string='';@StatefontScale:number=1.0;aboutToAppear(){this.language=AppUtil.getLanguage();this.fontScale=AppUtil.getFontScale();}build(){Column({space:12}){Button('获取全部信息').width('100%').onClick(()=>{try{letlang=AppUtil.getLanguage();letscale=AppUtil.getFontScale();letis24=AppUtil.is24HourClock();this.result=`系统语言:${lang}\n字体缩放:${scale}\n时间格式:${is24?'24小时制':'12小时制'}`;}catch(e){this.result='异常: '+e;}});Text(this.result).fontSize(14).fontColor('#333333').width('100%').padding(12).backgroundColor('#F5F5F5').borderRadius(8)}.padding(16)}}

四、进阶用法

4.1 结合其他工具类使用

AppUtil的字体与语言设置可以与ToastUtil配合，在语言变化时提醒用户：

import{AppUtil,ToastUtil}from'@pura/harmony-utils';functioncheckLanguageAndNotify(){try{letlang=AppUtil.getLanguage();if(lang.startsWith('zh')){ToastUtil.showToast('当前语言：中文');}else{ToastUtil.showToast('当前语言：'+lang);}}catch(e){console.error('语言检测失败: '+e);}}

4.2 字体缩放自适应布局

根据字体缩放比例动态调整UI布局：

import{AppUtil}from'@pura/harmony-utils';@Entry@Componentstruct AdaptiveLayout{@StatelineHeight:number=20;@Statepadding:number=16;aboutToAppear(){letscale=AppUtil.getFontScale();this.lineHeight=Math.ceil(20*scale);this.padding=Math.ceil(16*scale);}build(){Scroll(){Text('自适应字体缩放的文本内容').fontSize(14).lineHeight(this.lineHeight).padding(this.padding)}}}

五、注意事项

1. 国际化适配：根据getLanguage()返回值加载对应语言资源
2. 字体适配：根据getFontScale()调整UI布局，避免文字溢出
3. 时间格式：根据is24HourClock()选择时间显示格式
4. 初始化依赖：使用前需确保AppUtil.init()已调用
5. 动态变化：语言和字体设置可能随系统设置变化，建议在onPageShow中重新获取

六、常见问题

Q1: 调用AppUtil方法时抛出异常怎么办？

首先检查AppUtil.init()是否已正确调用，其次确认是否配置了所需权限。如果问题仍然存在，请检查方法参数是否正确。

Q2: AppUtil支持在多线程环境中使用吗？

harmony-utils的工具类主要设计用于主线程，如果需要在Worker线程中使用，建议通过消息机制将结果传递回主线程处理。

Q3: 如何在HSP模块中使用AppUtil？

在HSP（Harmony Shared Package）中使用时，需要依赖主应用的AppUtil.init()初始化。确保主应用启动时已完成初始化，HSP模块即可正常调用。

Q4: getFontScale()返回值大于1.0时如何适配？

建议使用缩放值动态调整行高、间距、padding等布局参数，避免文字溢出容器。对于固定高度的容器，可以考虑使用minHeight代替height。

总结

AppUtil的字体与语言设置方法为应用的国际化适配提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据这些信息动态调整UI显示，确保应用在不同语言和字体设置下都能提供良好的用户体验。

本文基于@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。