一、业务需求（为什么这么设计）

前 11 个应用的多语言方案都是运行时文案表：STRINGS: Map<locale, Map<key, text>> 由代码维护，应用内切换即时生效。本应用展示 HarmonyOS 的官方资源方案——它的定位完全不同：

• 资源随语言自动匹配：$r('app.string.app_name') 在布局里一写，系统按当前语言自动解析，零代码；
• 多类型资源统一管理：字符串、颜色、图片、布局、媒体都可以放进限定符目录，不只是文案；
• 覆盖绝大多数静态 UI：按钮、标题、提示这类"随版本发布、不随内容变"的文案，官方方案是正解。

本页用"资源演示 App"把这条路线讲透：展示目录结构、$r() 静态引用、resourceManager 动态读取、语言匹配模拟。由于页面运行在固定设备上无法真正改系统语言，本页用内存模拟表复现资源匹配算法——这是教学 App 的常见做法。本文记录完整技术方案。

二、总体架构

┌─ 资源数据层：RES_TABLE 模拟表（base + zh/en/ja/ko 五列，对应五个限定符目录）
├─ 目录展示层：DIR_TREE 树形文本（对应 resources/ 真实目录）
├─ 匹配算法层：resFor(lang, key) 模拟资源限定符匹配（语言 → base 兜底）
├─ 静态引用层：resFor(currentLocale, key) 模拟 $r() 自动跟随
└─ 模拟器层：simLang 独立状态，模拟任意"系统语言"

技术核心是 resFor()——它把"资源限定符匹配"压缩成一个纯函数，UI 层两个区块（静态卡 + 模拟器）都复用它，只是传入的语言来源不同。

三、资源数据模型：一张表模拟五个目录

interface ResEntry {
  key: string;
  base: string;     // base 目录（默认）
  zh: string;       // zh_CN
  en: string;       // en_US
  ja: string;       // ja_JP
  ko: string;       // ko_KR
}

const RES_TABLE: ResEntry[] = [
  {
    key: 'app_name',
    base: 'ResourceDemo',
    zh: '资源演示', en: 'Resource Demo', ja: 'リソースデモ', ko: '리소스 데모'
  },
  { key: 'greeting', base: 'Hello',
    zh: '你好，欢迎回来', en: 'Hello, welcome back', ja: 'こんにちは、おかえりなさい', ko: '안녕하세요, 돌아오신 것을 환영합니다' },
  // btn_ok / btn_cancel / status_loading ...
];

为什么用"一表五列"：真实工程里是五个目录（base/zh_CN/en_US/ja_JP/ko_KR）各放一个 string.json。内存表把五个目录压成一行五列，行 = 资源 key、列 = 语言目录——表结构与目录结构一一对应，语义无损且便于演示。真实读取时每列对应一次 resourceManager.getStringSync('app.string.' + key) 调用。

四、匹配算法：语言限定符 → base 兜底

/** 动态读取：模拟 resourceManager.getStringSync 按语言取资源 */
private resFor(lang: string, key: string): string {
  const e = RES_TABLE.find((r: ResEntry) => r.key === key);
  if (e === undefined) {
    return key;                    // 资源不存在 → 返回 key 本身
  }
  if (lang === 'zh_CN') return e.zh;
  if (lang === 'en_US') return e.en;
  if (lang === 'ja_JP') return e.ja;
  if (lang === 'ko_KR') return e.ko;
  return e.base;                   // 未匹配 → base 兜底
}

这对应真实资源匹配的优先级规则（从高到低）：

1. 精确语言匹配：zh_CN → resources/zh_CN/ 目录；
2. 语言族匹配（真实系统有）：zh 可匹配 zh_CN/zh_HK 等（本演示未展开）；
3. base 兜底：任何未覆盖语言 → resources/base/；
4. 连 base 都没有：返回 key 本身（开发期可见的"资源缺失"信号）。

演示中的降级路径：

simLang	app_name 的值	说明
zh_CN	资源演示	精确匹配
en_US	Resource Demo	精确匹配
fr_FR（未列出）	ResourceDemo	未覆盖 → base
base	ResourceDemo	显式选 base

刻意设计：resFor 没有为 zh_TW 设列——界面语言包含 zh_TW 但资源表没有，选中繁中徽章时界面文案走 STRINGS 表（应用内文案），资源演示值走 base 兜底——两个系统并存、各走各的降级，这正是真实工程的常态（资源未翻全 ≠ 界面不工作）。

五、$r() 静态引用：官方链路

真实工程中静态引用是编译期解析 + 运行时匹配：

// 布局中（真实写法）
Text($r('app.string.app_name'))          // 编译期校验 key 存在
  .fontColor($r('app.color.primary'))    // 颜色也能进资源

// resources/base/element/string.json
{ "string": [ { "name": "app_name", "value": "ResourceDemo" } ] }
// resources/zh_CN/element/string.json
{ "string": [ { "name": "app_name", "value": "资源演示" } ] }

工作链路：

编译期：$r('app.string.app_name') 的 key 被校验（不存在直接编译失败）
  → 生成资源索引
运行期：系统语言 = zh_CN
  → 资源管理器查找 resources/zh_CN/element/string.json
  → 找到 app_name → 返回 "资源演示"
  → 若 zh_CN 目录缺此 key → 回溯 base 目录 → 返回 "ResourceDemo"

$r() 的优点与边界：

维度	$r() 静态	resourceManager 动态
写法	声明式，一行	命令式，方法调用
语言来源	系统语言，自动	调用方指定（或系统）
编译期校验	✅ key 拼错即失败	❌ 运行时才知道
适用场景	静态 UI 文案	运行时拼装、动态内容
即时切换	需重启/重进生效	可编程控制

六、页面演示层：静态卡 + 模拟器

两个区块复用 resFor()，语言来源不同：

// 静态引用卡：跟随界面语言（模拟系统语言）
Text(this.resFor(this.currentLocale, e.key))

// 模拟器：跟随用户拨动的 simLang（模拟任意系统语言）
Text(this.resFor(this.simLang, e.key))

@StorageLink(STORAGE_LOCALE) currentLocale: string = DEFAULT_LOCALE;
@State simLang: string = 'zh_CN';

为什么用两个独立状态：教学场景需要演示"界面语言 ≠ 系统语言"的组合。真实设备上 $r() 永远跟随系统语言，与 App 内部语言无关——两个状态分离正好还原了这个事实：currentLocale 管 App 界面，simLang 管"假设的系统语言"。真实产品中切换系统语言需要用户在设置里改，本页用模拟器免去这步。

七、数据流复盘（一次完整交互）

启动 → aboutToAppear 初始化 + persistProp
  → build：中文界面、静态卡显示 5 条中文资源、模拟器默认 zh_CN

用户点击模拟器 🇯🇵 ja_JP
  → simLang = 'ja_JP'
  → 匹配结果 5 行：app_name = リソースデモ、greeting = こんにちは…
  → 界面语言仍是中文（静态卡不变）——两个系统互不干扰

用户把界面语言切到 🇺🇸 EN
  → currentLocale = 'en_US'
  → 静态卡 5 行变英文（界面文案 + 资源演示值）
  → 模拟器仍是 ja_JP 结果（独立状态）

八、ArkTS 兼容要点

1. ForEach(['zh_CN', ...] as string[], ...) 数组字面量断言；
2. catch (err) 不带类型注解（本页主要是数据查找无异常，但真实 resourceManager 调用需 try/catch）；
3. ResEntry 显式接口，禁止隐式 Object；
4. 两个 ForEach 渲染同一 RES_TABLE：key 生成器区分（e.key vs `sim-${e.key}`）避免复用错乱；
5. DIR_TREE 的 ForEach key 用 `${idx}-${line}`：树形文本行可能重复，必须 idx 参与；
6. langLabel() 用 if 链而非 Map——5 个分支可读性更好，且免去 Map 初始化。

与真实工程的差异对照

维度	本页演示	真实工程
数据来源	RES_TABLE 内存表	resources/ 目录 + resourceManager
语言来源	手动选择的模拟器	系统语言自动匹配
匹配时机	每次 build 现算	编译期索引 + 运行时查找
覆盖类型	仅 string	string/color/media/layout 全类型
编译期校验	无（key 缺失返回 key）	$r() 拼错 key 编译失败
即时性	秒级切换	需重启/重进生效

这张对照表是读者把演示代码迁移到生产的关键桥梁——本页的 resFor() 逻辑与真实匹配优先级完全一致，只是数据源从目录换成了内存表。

九、性能与内存

• resFor() 是线性查找（5 条数据），O(n) 可忽略；资源量大时应建 Map<key, ResEntry> 索引；
• 每次 build 最多 10 次 resFor（静态 5 + 模拟器 5），无格式化器创建、无 IO；
• 页面无定时器，无内存泄漏风险；
• 真实工程中 resourceManager.getStringSync 是同步 IO（读内存缓存），高频调用建议改用异步 getString + 结果缓存；
• 真实工程建议用 getString 异步 API：同步版本在极端情况下可能阻塞 UI 线程，列表滚动加载大量资源时用异步 + 缓存更稳妥。

十、小结

本应用补全了系列的"多语言拼图"：运行时文案表（01）适合动态切换，资源限定符（12）适合静态 UI。技术核心是 resFor() 这个匹配函数——精确语言 → base 兜底 → key 兜底的三级降级，与官方资源方案的匹配优先级一致；currentLocale 与 simLang 双状态分离，还原了"系统语言与界面语言独立"的真实模型。

应用	深化维度
01	运行时文案表 + 应用内切换（动态方案）
10	资源中的历法/时间文化数据
12	资源限定符 + $r()/resourceManager（静态方案）← 本文
14	跟随系统语言（系统维度，与 12 互补）

给生产环境的三条铁律：① 静态 UI 文案走资源限定符（编译期校验、官方标准），动态内容走运行时文案表；② base 目录必须完整覆盖所有 key——它是所有语言的最终兜底；③ 新增语言 = 新建限定符目录，不要只加运行时表——图片、颜色、布局等资源只有限定符方案能承载。三条铁律之外再加一条工程纪律：把 resFor() 的降级优先级（精确语言 → base → key）写进团队文档——它是整个资源方案的"宪法"，任何新增语言、新资源类型都要先对照这条优先级确认预期行为。