页面里的文字为什么不建议直接写死?从 $r(‘app.string.xxx‘) 开始【鸿蒙心迹】

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的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/ 子目录中。
三、搭一个最小实践场景
目标很简单:做一个登录页面,页面上有标题、输入框提示、按钮文字,全部通过字符串资源引用,不硬编码任何中文文字。
同时,给这个场景加上英文版本,观察切换语言后的行为。
需要处理的文件:
resources/base/element/string.json— 默认字符串(中文)resources/en_US/element/string.json— 英文字符串- 页面组件文件
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 类型直接做字符串操作。 这一条已经在上面说过,但这是最高频的使用错误,单独再强调一次。
七、排查字符串资源不生效时的顺序
遇到资源引用的文字没有正确显示,可以按以下顺序排查:
- 确认文件路径:
string.json是否在resources/base/element/或对应限定目录的element/下。 - 确认
name拼写:$r()内的名字和string.json中的name字段是否完全一致。 - 确认 JSON 格式:
string.json是否符合格式要求,有没有多余的逗号、缺少引号等 JSON 语法错误。编译时一般有提示。 - 确认限定目录命名:多语言目录名格式是否正确,比如
zh_CN(注意是下划线,不是连字符zh-CN)。 - 确认资源类型前缀:
$r()里的第一段是app还是sys,引用自己应用资源时必须是app。 - 确认组件是否支持
Resource类型:绝大多数显示文字的属性都支持,但如果你在非组件属性的逻辑中使用,需要先转成字符串。
八、最后整理一下
几个实际有用的结论:
resources/base/element/string.json是字符串资源的默认定义位置,多语言版本放在对应语言目录下,目录命名格式为语言_地区(如zh_CN、en_US)。$r('app.string.xxx')返回Resource类型,ArkUI 组件属性可以直接接受,但逻辑代码里拼接字符串需要通过resourceManager.getStringSync()先取值。- 命名规范是维护资源文件的基础,建议从项目初期就按模块前缀统一命名。
base/目录作为兜底,实际匹配时限定目录优先级高于base/。
把字符串从页面里抽出来,本质上是把"数据"和"结构"分离,这个习惯在项目早期几乎没有额外成本,但在后续维护、国际化或者多人协作时会带来明显的便利。
如果你现在的工程里已经有大量硬编码字符串,可以考虑先从高频复用的文案(比如通用按钮文字、错误提示、导航标题)开始迁移,不必一次性全部改完。
如果你正在做多语言支持,可以关注一个容易忽略的问题:当界面文字长度在不同语言间差异较大时(比如英文比中文长很多),固定宽度的布局可能会导致文字截断。这个问题和字符串资源本身无关,但往往要等到真正加载多语言资源之后才会暴露出来,值得在适配阶段一并检查。
❤️ 如果本文帮到了你…
- 请点个赞,让我知道你还在坚持阅读技术长文!
- 请收藏本文,因为你以后一定还会用上!
- 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
更多推荐


所有评论(0)