在这里插入图片描述

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀

前言

写界面文案时,经常会遇到这种需求:欢迎语里要嵌入用户名,通知里要显示消息条数,提示里要带上具体数值。很多开发者的第一反应是在 JS/ArkTS 层把字符串拼起来——把翻译好的前缀取出来,然后用 + 或模板字符串把动态值接上去。

这种做法本身能跑,但有一个隐患:一旦不同语言的语序不同(比如中文"你有 5 条消息"和某些语言的语序是"5 messages you have"),硬拼接就会出问题。ResourceManager 的格式化字符串能力正是为了解决这件事。

一、这个能力解决什么问题

HarmonyOS 的多语言资源文件(resources/base/element/string.json 以及各 locale 目录下的同名文件)支持在字符串值中嵌入格式占位符,由 ResourceManager 在运行时负责将动态参数填入。

这样一来,翻译文案和代码逻辑是完全解耦的:翻译人员只需要在自己的语言里调整占位符的位置,代码层不需要知道最终字符串长什么样子。

ResourceManager 当前在 getStringSync 接口上明确支持以下占位符格式:

占位符对应类型说明
%sstring字符串参数
%dnumber(整数)十进制整数
%inumber(整数)十进制整数(同 %d)
%fnumber(浮点数)浮点数
%onumber八进制整数
%xnumber十六进制整数(小写)
%bboolean布尔值
%%—输出字面量 %

本文聚焦最常用的两个:%s(动态字符串,如用户名)和 %d(动态整数,如消息条数)。

二、接口定义和版本情况

根据官方 API Reference,ResourceManager 提供同步和异步两种字符串获取方式。带格式化参数的同步接口签名如下:

getStringSync(resId: number, ...args: Array<string | number | boolean>): string;

以及资源名称版本(使用 Resource 对象):

getStringSync(resource: Resource, ...args: Array<string | number | boolean>): string;
  • Kit:Localization Kit(也属于 Resource Management 能力)
  • 模块:@ohos.app.ability.common / 通过 UIAbility 或 ExtensionAbility 上下文的 resourceManager 属性访问
  • API Level:getStringSync 带参数版本从 API 9 开始支持
  • 运行模型:Stage 模型
  • 设备:Phone、Tablet、2in1、Foldable(通用能力,无设备限制)
  • 权限:不需要额外声明权限

带 ...args 可变参数的 getStringSync 重载是在 API 9(对应 HarmonyOS 3.1 及以后版本)引入的,HarmonyOS 7 完全支持。

如果你还在用 FA 模型,访问 ResourceManager 的方式不同;Stage 模型通过 this.context.resourceManager 获取,是目前的主流路径。

三、资源文件怎么写

在 resources/base/element/string.json 里,直接把占位符嵌入字符串值:

{
  "string": [
    {
      "name": "welcome_user",
      "value": "欢迎你,%s"
    },
    {
      "name": "message_count",
      "value": "你有 %d 条消息"
    },
    {
      "name": "level_info",
      "value": "%s,当前等级 %d"
    }
  ]
}

如果有英文 locale,对应在 resources/en_US/element/string.json 里:

{
  "string": [
    {
      "name": "welcome_user",
      "value": "Welcome, %s"
    },
    {
      "name": "message_count",
      "value": "You have %d messages"
    },
    {
      "name": "level_info",
      "value": "%s, current level %d"
    }
  ]
}

这里体现的正是格式化字符串的核心价值:中英文字符串的结构各自独立,占位符位置可以不同,但调用代码只写一次。

四、核心代码实现

4.1 在 UIAbility 的 Page 里获取 ResourceManager

Stage 模型下,Page 组件可以通过 this.context 访问 resourceManager,但 @Component 装饰的自定义组件无法直接使用 this.context。标准做法是在 UIAbility 或 Page 的入口组件里取到 context,然后通过参数或 AppStorage 传递下去,或者直接在入口 @Entry 组件里调用。

下面是一个最小示例,直接在 @Entry 组件的构建阶段从 context 取资源:

// Index.ets
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  @State welcomeText: string = '';
  @State messageText: string = '';
  @State levelText: string = '';

  aboutToAppear(): void {
    // 获取当前 UIAbility 的 context
    const context = getContext(this) as common.UIAbilityContext;
    const rm = context.resourceManager;

    // 使用资源名称 + 格式化参数
    // $r('app.string.welcome_user') 只能在模板里使用,这里改用资源名称字符串方式
    this.welcomeText = rm.getStringSync($r('app.string.welcome_user'), '张三');
    this.messageText = rm.getStringSync($r('app.string.message_count'), 5);
    this.levelText   = rm.getStringSync($r('app.string.level_info'), '李四', 12);
  }

  build() {
    Column({ space: 12 }) {
      Text(this.welcomeText)
      Text(this.messageText)
      Text(this.levelText)
    }
    .padding(24)
    .width('100%')
  }
}

代码的核心就三行调用,其余是标准的组件结构,没有多余内容。

4.2 传参方式拆解

// %s 传字符串
rm.getStringSync($r('app.string.welcome_user'), '张三');
// 结果:"欢迎你,张三"

// %d 传整数
rm.getStringSync($r('app.string.message_count'), 5);
// 结果:"你有 5 条消息"

// 多个占位符按顺序传入多个参数
rm.getStringSync($r('app.string.level_info'), '李四', 12);
// 结果:"李四,当前等级 12"

参数按照占位符在字符串中出现的从左到右顺序依次对应。第一个 args 对应第一个占位符,第二个对应第二个,以此类推。

五、几个关键点拆开看

5.1 $r() 是编译期资源引用,不是运行时字符串

$r('app.string.welcome_user') 返回的是 Resource 类型对象,不是字符串本身。把它直接传给 getStringSync 的第一个参数是正确用法。不要试图用字符串拼接的方式动态构造资源名,比如 $r('app.string.' + key)——这在编译时就会报错,因为 $r() 要求参数是字面量字符串。

如果需要动态决定资源名,应该改用 rm.getStringByNameSync(name: string, ...args) 这个接口,第一个参数直接传资源名称字符串,不需要 $r()。

5.2 参数顺序和类型必须与占位符对应

%d 占位符对应的参数需要传 number 类型。如果传入了字符串 '5',理论上类型声明是 string | number | boolean,但运行时格式化结果是否符合预期取决于底层实现——建议严格按占位符类型传参,不要依赖隐式转换。

5.3 getStringSync 和 getString 的选择

两者功能相同,区别是 getString 是异步接口,返回 Promise<string>。在组件 aboutToAppear 里,同步接口更直观;但如果是在 Promise 链或 async 函数里,用 getString 更自然。没有性能上的特别差异,根据调用上下文选择即可。

5.4 多语言文件里占位符数量必须一致

如果 base 里的 welcome_user 有一个 %s,但 en_US 里忘记写了直接变成 "Welcome"——运行时多传了一个参数也不会崩溃,但格式化没有意义。反过来,如果某语言文件里的占位符数量多于传入参数数量,多余的占位符会原样保留在输出字符串里,比如直接显示 %s,这个问题不会有编译期提示。

5.5 在非 UIAbility 上下文中获取 ResourceManager

如果是在没有 UI context 的场景(比如后台 Service ExtensionAbility),可以用 getContext() 获取 AbilityContext,同样有 resourceManager 属性,使用方式一致。

六、容易踩坑的地方

占位符大小写:%S、%D 等大写形式不是合法占位符,资源文件里只能用小写,写错之后字符串会原样输出,且没有运行时报错。

不要在 build() 方法里直接调用 getStringSync:build() 是声明式 UI 的描述函数,会被频繁调用。把字符串获取逻辑放在 aboutToAppear() 或响应状态变化的函数里更合适。

资源文件 JSON 格式错误会导致整个 string.json 加载失败:添加新条目时注意检查逗号、引号是否完整,这类问题会让同文件内的其他资源也一起失效,排查起来比较绕。

$r() 只能在 ArkTS UI 文件里用:如果把资源获取逻辑抽取到独立的工具类或 Service 层,$r() 不可用,要用 getStringByNameSync 替代。

七、排查思路

如果格式化字符串没有按预期输出,建议按以下顺序排查:

  1. 确认 API Level:检查 build-profile.json5 里的 compileSdkVersion 是否在 API 9 及以上;
  2. 确认资源文件存在且加载正常:在 DevEco Studio 里通过 Preview 或 Run 时观察是否有资源相关 Error 日志;
  3. 确认占位符格式正确:检查 string.json 里是否用了小写 %s/%d,不是大写,不是 {0} 或 %@ 之类其他格式;
  4. 确认传参顺序和类型:%s 对应 string,%d 对应 number,按从左到右顺序传入;
  5. 确认当前 locale 对应的资源文件存在:如果用户系统语言是英文,但工程里没有 en_US/element/string.json,会回落到 base,这本身是预期行为,但如果 base 里没有目标 key 就会抛错;
  6. 确认调用时机:aboutToAppear 里 context 已经就绪,这是最安全的调用时机;在 build() 里或组件初始化参数里调用有时会拿到 undefined context。

开发经验总结

  • ResourceManager 的 getStringSync 从 API 9 起支持可变参数,通过 %s、%d 等占位符实现格式化,不需要在代码层做字符串拼接;
  • 资源文件里的占位符数量和类型必须与调用时传入的参数一致,多余占位符不会报错但会直接显示原始格式符;
  • $r() 只能作为字面量使用,动态资源名场景改用 getStringByNameSync;
  • 格式化逻辑留在资源文件里,对多语言场景下语序差异的处理是最干净的;
  • build() 方法不是调用 getStringSync 的合适位置,优先在 aboutToAppear 或业务状态更新函数里完成。

如果你的项目里已经有一批用拼接方式处理的动态文案,可以重点看一下有没有语序依赖的语言需求——如果有,这类文案是最值得优先迁移到格式化字符串方式的。

❤️ 如果本文帮到了你…

  • 请点个赞,让我知道你还在坚持阅读技术长文!
  • 请收藏本文,因为你以后一定还会用上!
  • 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐