在这里插入图片描述

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

前言

写 ArkUI 页面的时候,最容易犯的一个习惯是把文字直接写在组件属性里:

Text('登录')
Text('请输入手机号')
Text('提交')

这样写,页面短期内没有任何问题。但一旦项目需要国际化、换肤、统一改文案,或者工程要被其他模块复用,这些硬编码的字符串就会变成改不完的散点。

HarmonyOS 官方推荐的做法是把字符串统一放进资源文件,通过 $r() 函数引用。这篇文章用一个最小示例把这套流程完整走一遍。

一、硬编码字符串会带来哪些实际麻烦

先说清楚问题的根源,再讲怎么解决。

多语言支持做不了。 HarmonyOS 的国际化机制是基于资源文件的。系统根据当前语言环境自动加载对应的字符串资源。如果你的文字写死在代码里,这套机制就对你没有任何作用,国际化改造需要从头找代码。

维护成本高。 一个"提交"按钮如果在五个页面出现,写死之后要改成"确认",就得改五处。如果放在资源文件里,只改一行就够了。

协作困难。 产品经理或翻译人员想要核查或修改文案,字符串资源文件比翻遍几十个 .ets 文件要直观得多。

主题和品牌统一性差。 即使只针对中文,正式上线的应用通常有统一的文案规范。硬编码越多,越难保证一致性。

二、官方资源目录结构先弄清楚

在 HarmonyOS Stage 模型中,应用的资源文件统一放在模块的 resources 目录下。按照华为官方开发指南,resources 目录的典型结构如下:

entry/src/main/resources/
├── base/
│   ├── element/
│   │   └── string.json      ← 默认字符串资源
│   ├── media/
│   └── profile/
├── zh_CN/
│   └── element/
│       └── string.json      ← 简体中文
├── en_US/
│   └── element/
│       └── string.json      ← 英文
└── rawfile/

这里需要理解一个核心逻辑:

  • base/ 是兜底资源,当系统当前语言没有匹配的限定目录时,就加载 base/ 里的内容。
  • zh_CN/、en_US/ 这类目录是限定资源,目录名按照语言-地区格式命名,系统在匹配到对应语言时优先加载。

字符串资源文件必须命名为 string.json,放在对应目录下的 element/ 子目录中。

三、搭一个最小实践场景

目标很简单:做一个登录页面,页面上有标题、输入框提示、按钮文字,全部通过字符串资源引用,不硬编码任何中文文字。

同时,给这个场景加上英文版本,观察切换语言后的行为。

需要处理的文件:

  1. resources/base/element/string.json — 默认字符串(中文)
  2. resources/en_US/element/string.json — 英文字符串
  3. 页面组件文件 LoginPage.ets

四、核心代码实现

第一步:定义 string.json

resources/base/element/string.json

这里定义的是默认字符串,也就是中文内容。每个条目是一个对象,包含 name 和 value 两个字段。

{
  "string": [
    {
      "name": "login_title",
      "value": "欢迎登录"
    },
    {
      "name": "login_phone_hint",
      "value": "请输入手机号"
    },
    {
      "name": "login_password_hint",
      "value": "请输入密码"
    },
    {
      "name": "login_submit_button",
      "value": "登录"
    },
    {
      "name": "login_agreement_prefix",
      "value": "登录即表示同意"
    },
    {
      "name": "login_agreement_link",
      "value": "《用户协议》"
    }
  ]
}

name 字段是这个字符串的唯一标识符,在 $r() 中会用到它。value 是实际显示的文字。

resources/en_US/element/string.json

英文版本只需要列出 name 和对应的英文 value,name 必须和 base 里保持一致。

{
  "string": [
    {
      "name": "login_title",
      "value": "Welcome"
    },
    {
      "name": "login_phone_hint",
      "value": "Enter phone number"
    },
    {
      "name": "login_password_hint",
      "value": "Enter password"
    },
    {
      "name": "login_submit_button",
      "value": "Log In"
    },
    {
      "name": "login_agreement_prefix",
      "value": "By logging in, you agree to the"
    },
    {
      "name": "login_agreement_link",
      "value": "Terms of Service"
    }
  ]
}

第二步:页面中用 $r() 引用字符串

这段代码用最小的结构展示了如何在 ArkUI 组件中引用字符串资源。

LoginPage.ets

@Entry
@Component
struct LoginPage {
  build() {
    Column({ space: 24 }) {

      // 页面标题
      Text($r('app.string.login_title'))
        .fontSize(28)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 60 })

      // 手机号输入框
      TextInput({ placeholder: $r('app.string.login_phone_hint') })
        .type(InputType.PhoneNumber)
        .width('90%')

      // 密码输入框
      TextInput({ placeholder: $r('app.string.login_password_hint') })
        .type(InputType.Password)
        .width('90%')

      // 登录按钮
      Button($r('app.string.login_submit_button'))
        .width('90%')
        .type(ButtonType.Capsule)

      // 协议提示
      Row() {
        Text($r('app.string.login_agreement_prefix'))
          .fontSize(12)
        Text($r('app.string.login_agreement_link'))
          .fontSize(12)
          .fontColor(Color.Blue)
      }

    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
  }
}

五、几个关键点拆开看

$r() 的参数格式

$r('app.string.login_title') 这个字符串由三段组成:

  • app — 表示引用的是应用自身的资源。如果引用的是系统资源,前缀是 sys。
  • string — 表示资源类型,对应 element/ 目录下的文件名(去掉 .json)。其他类型还有 color、float、media 等。
  • login_title — 对应 string.json 中的 name 字段值。

三段之间用英文句点分隔,整体包在单引号内传给 $r()。

$r() 的返回类型是 Resource,不是 string

这是一个容易误解的地方。$r() 返回的是 Resource 类型对象,不是普通字符串。

ArkUI 组件中接受文字内容的属性(比如 Text 的内容、TextInput 的 placeholder、Button 的 label)都支持 Resource 类型,可以直接传入。

但如果你需要在 TypeScript 逻辑中拼接或处理字符串,不能直接用 + 操作符。这种情况下,需要通过 getContext(this).resourceManager.getStringSync() 来获取真实的字符串值。

// ❌ 这样不能用于字符串拼接
let title = $r('app.string.login_title') + '!'

// ✅ 需要获取实际字符串时,通过 resourceManager
import { common } from '@kit.AbilityKit';

// 在 Component 中
let context = getContext(this) as common.UIAbilityContext;
let titleStr = context.resourceManager.getStringSync($r('app.string.login_title'));
let titleWithMark = titleStr + '!';

getStringSync 是同步方法,API 9 及以上版本可用。

name 的命名规范

官方文档里对资源名有约束:只能包含字母、数字和下划线,且不能以数字开头。建议按照功能模块 + 语义的方式命名,比如 login_submit_button,而不是 btn1 或 text_3,否则项目规模大了之后资源文件会完全失去可读性。

base/ 和限定目录的关系

如果只有 base/string.json,没有 zh_CN/ 目录,在中文环境下系统仍然会加载 base/ 里的内容,效果是一样的。但如果同时存在 zh_CN/string.json,系统在简体中文语言下会优先加载 zh_CN/ 的内容,base/ 只作为兜底。

所以在工程里,base/ 建议放主要语言(通常是中文),其他语言各自维护限定目录。

六、容易踩坑的地方

资源文件路径写错。 string.json 必须在 element/ 目录下,不能直接放在 base/ 或语言目录的根目录。路径写错了编译时一般不会报错,但运行时资源取不到。

name 拼写不一致。 $r() 里的资源名和 string.json 里 name 字段的值必须完全一致,包括大小写。IDE 会提供资源名的补全提示,但如果直接手打很容易出错,这类问题运行时表现为文字不显示或显示为资源引用路径字符串。

多语言目录里漏写条目。 如果 en_US/string.json 里缺少某个条目,而 base/ 里有,切换英文后那个条目会回退到 base/ 里的中文值。这本身是系统设计的兜底行为,但如果你希望英文版完整显示,需要保持各语言目录中的条目数量和 name 一致。

在逻辑代码里对 Resource 类型直接做字符串操作。 这一条已经在上面说过,但这是最高频的使用错误,单独再强调一次。

七、排查字符串资源不生效时的顺序

遇到资源引用的文字没有正确显示,可以按以下顺序排查:

  1. 确认文件路径:string.json 是否在 resources/base/element/ 或对应限定目录的 element/ 下。
  2. 确认 name 拼写:$r() 内的名字和 string.json 中的 name 字段是否完全一致。
  3. 确认 JSON 格式:string.json 是否符合格式要求,有没有多余的逗号、缺少引号等 JSON 语法错误。编译时一般有提示。
  4. 确认限定目录命名:多语言目录名格式是否正确,比如 zh_CN(注意是下划线,不是连字符 zh-CN)。
  5. 确认资源类型前缀:$r() 里的第一段是 app 还是 sys,引用自己应用资源时必须是 app。
  6. 确认组件是否支持 Resource 类型:绝大多数显示文字的属性都支持,但如果你在非组件属性的逻辑中使用,需要先转成字符串。

八、最后整理一下

几个实际有用的结论:

  • resources/base/element/string.json 是字符串资源的默认定义位置,多语言版本放在对应语言目录下,目录命名格式为 语言_地区(如 zh_CN、en_US)。
  • $r('app.string.xxx') 返回 Resource 类型,ArkUI 组件属性可以直接接受,但逻辑代码里拼接字符串需要通过 resourceManager.getStringSync() 先取值。
  • 命名规范是维护资源文件的基础,建议从项目初期就按模块前缀统一命名。
  • base/ 目录作为兜底,实际匹配时限定目录优先级高于 base/。

把字符串从页面里抽出来,本质上是把"数据"和"结构"分离,这个习惯在项目早期几乎没有额外成本,但在后续维护、国际化或者多人协作时会带来明显的便利。

如果你现在的工程里已经有大量硬编码字符串,可以考虑先从高频复用的文案(比如通用按钮文字、错误提示、导航标题)开始迁移,不必一次性全部改完。


如果你正在做多语言支持,可以关注一个容易忽略的问题:当界面文字长度在不同语言间差异较大时(比如英文比中文长很多),固定宽度的布局可能会导致文字截断。这个问题和字符串资源本身无关,但往往要等到真正加载多语言资源之后才会暴露出来,值得在适配阶段一并检查。

❤️ 如果本文帮到了你…

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

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

更多推荐