HarmonyOS 应用国际化和主题适配：ResUtil 综合运用实战指南

背景

近期发现一款很有意思的HarmonyOS 三方库, 地址 @pura/harmony-utils(V1.4.0) , 作者是"桃花镇童长老", 我这里也是直接通过该作者公布的源码进行案例编写进行,写了到目前写了一部分demo ,感觉确实很有帮助,这里呢也是开始写一个系列的演示demo 供大家参考。如有帮助可以在OpenHarmony中进行下载安装进行使用哦

案例demo导航展示

↓↓↓↓↓↓接下来言归正传 ↓↓↓↓
前面讲了ResUtil各个方法的用法，这篇来讲几个完整的业务场景，把资源读取的知识串起来。

方法总览

场景一：多语言文本显示

应用多语言支持的核心是把文本放到资源文件里，代码里通过ResUtil读取：

资源文件结构：

resources/ ├── base/ │ └── element/ │ └── string.json # 默认语言（通常是中文） ├── zh_CN/ │ └── element/ │ └── string.json # 简体中文（可覆盖 base） └── en_US/ └── element/ └── string.json # 英文

string.json示例：

{"string":[{"name":"app_name","value":"HoUtils"},{"name":"welcome","value":"欢迎使用"}]}

读取方式：

// Demo 中展示的资源读取方式this.Btn('getStringSync($r("app.string.app_name"))','#27AE60',()=>{this.tryLog('getStringSync($r("app.string.app_name"))',()=>ResUtil.getStringSync($r('app.string.app_name')));})this.Btn('getStringByNameSync(resName)','#1E8449',()=>{this.tryLog(`getStringByNameSync("${this.resName}")`,()=>ResUtil.getStringByNameSync(this.resName));})

在组件里使用：

import{ResUtil}from'../Utils/ResUtil';@Entry@Componentstruct WelcomePage{build(){Column(){// 方式1：用 $r，编译期检查Text($r('app.string.welcome')).fontSize(18)// 方式2：用 ResUtil 运行时读取（适合需要逻辑处理的场景）Text(ResUtil.getStringSync($r('app.string.app_name'))).fontSize(14).fontColor('#666')}}}

检测当前语言：

this.Btn('getConfigurationSync() 获取设备配置','#16A085',()=>{this.tryLog('getConfigurationSync()',()=>{constcfg=ResUtil.getConfigurationSync();return`locale=${cfg.locale}direction=${cfg.direction}colorMode=${cfg.colorMode}`;});})

constcfg=ResUtil.getConfigurationSync();constisChineseLocale=cfg.locale.startsWith('zh');constisRTL=cfg.direction===1;// 从右到左（阿拉伯语等）

场景二：暗色模式检测与适配

this.Btn('getConfigurationSync() 获取设备配置','#16A085',()=>{this.tryLog('getConfigurationSync()',()=>{constcfg=ResUtil.getConfigurationSync();return`locale=${cfg.locale}direction=${cfg.direction}colorMode=${cfg.colorMode}`;});})

colorMode字段：0= 浅色，1= 深色。

实现动态主题：

import{ResUtil}from'../Utils/ResUtil';// 主题颜色工具functiongetThemeColors(){constisDark=ResUtil.getConfigurationSync().colorMode===1;return{background:isDark?'#1A1A2E':'#FFFFFF',text:isDark?'#E0E0E0':'#333333',card:isDark?'#16213E':'#F8F9FA',border:isDark?'#2A2A4A':'#E0E0E0'};}@Entry@Componentstruct MainPage{@StateisDark:boolean=ResUtil.getConfigurationSync().colorMode===1;build(){Column(){Text('主页内容').fontColor(this.isDark?'#E0E0E0':'#333333')}.backgroundColor(this.isDark?'#1A1A2E':'#FFFFFF')}}

场景三：根据屏幕密度选择图片质量

不同屏幕密度的设备，显示不同质量的图片可以平衡清晰度和性能：

this.Btn('getDeviceCapabilitySync() 获取设备能力','#1ABC9C',()=>{this.tryLog('getDeviceCapabilitySync()',()=>{constcap=ResUtil.getDeviceCapabilitySync();return`screenDensity=${cap.screenDensity}deviceType=${cap.deviceType}`;});})

import{ResUtil}from'../Utils/ResUtil';functiongetImageQuality():string{constcap=ResUtil.getDeviceCapabilitySync();if(cap.screenDensity>=4){// 高密度屏幕（XLDPI 320dpi+）加载高清图return'high';}elseif(cap.screenDensity>=2){// 中等密度屏幕return'medium';}else{// 低密度屏幕，加载低清图节省流量return'low';}}

场景四：动态读取图片资源用于分享

把应用的图标/图片转成 Base64 用于分享或上传：

this.Btn('getMediaContentBase64Sync($r("app.media.startIcon"))','#9B59B6',()=>{this.tryLog('getMediaContentBase64Sync($r("app.media.startIcon"))',()=>{constb64=ResUtil.getMediaContentBase64Sync($r('app.media.startIcon'));return`${b64.substring(0,40)}... (length=${b64.length})`;});})

// 获取应用图标的 Base64，嵌入分享内容consticonBase64=ResUtil.getMediaContentBase64Sync($r('app.media.startIcon'));// iconBase64 格式：'data:image/png;base64,xxxxx'// 可以直接放 Image 组件的 src，或传给需要 Base64 图片的接口

场景五：获取原始资源文件

rawfile目录适合存放 JSON 配置、音频等原始文件：

// 检查路径是否为目录this.Btn('isRawDir("") 根路径','#E67E22',()=>{this.tryLog('isRawDir("")',()=>ResUtil.isRawDir('').toString());})

// 在代码里判断 rawfile 路径constisDir=ResUtil.isRawDir('config');// 检查 rawfile/config 是否为目录if(isDir){// 读取目录下的文件列表}

ResUtil 使用小结

从 Demo 里可以看出，资源读取有几个规律：

1. 有$r引用和资源名两种方式：$r在编译期检查（类型安全），资源名是字符串（动态灵活）
2. 有同步和异步两种：同步简单直接，适合初始化；异步不阻塞 UI，适合运行时按需加载
3. 颜色返回数字：需要用.toString(16)转十六进制才好看
4. 媒体有 Base64 和字节两种格式：根据后续用途选择

写在最后

ResUtil是 HarmonyOS 应用资源规范化管理的核心工具。把颜色、文字、图片都放资源文件里，然后通过ResUtil读取，这是做好多语言、暗色模式适配的必要前提。