前言

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

一、字体与语言核心API

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

方法	说明	返回类型	使用场景
getLanguage()	获取系统语言	string	国际化资源加载
getFontScale()	获取字体缩放比例	number	UI布局适配
is24HourClock()	判断是否24小时制	boolean	时间格式显示

1.1 核心特性

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

1.2 字体缩放影响对比

缩放值	含义	UI适配建议
1.0	默认大小	标准布局
1.15	中等放大	增加行高和间距
1.3	较大放大	减少每行字数，增加滚动区域
1.5+	最大放大	考虑简化UI，减少文字密度

二、完整使用步骤

2.1 安装依赖

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

ohpm install @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 {
      let lang = AppUtil.getLanguage();
      this.result = `系统语言: ${lang}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 获取字体缩放比例

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

2.4 判断时间格式

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

三、完整页面示例

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

import { AppUtil } from '@pura/harmony-utils';

@Entry
@Component
struct FontLangDemo {
  @State result: string = '';
  @State language: string = '';
  @State fontScale: number = 1.0;

  aboutToAppear() {
    this.language = AppUtil.getLanguage();
    this.fontScale = AppUtil.getFontScale();
  }

  build() {
    Column({ space: 12 }) {
      Button('获取全部信息').width('100%').onClick(() => {
        try {
          let lang = AppUtil.getLanguage();
          let scale = AppUtil.getFontScale();
          let is24 = 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';

function checkLanguageAndNotify() {
  try {
    let lang = 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
@Component
struct AdaptiveLayout {
  @State lineHeight: number = 20;
  @State padding: number = 16;

  aboutToAppear() {
    let scale = 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 工具库，更多功能请参考官方文档与后续系列文章。