【HarmonyOS实战】 资源文件那些事：颜色、字符串、图片怎么管理？

前言

写过 Android 的同学肯定知道res/values/colors.xml、res/values/strings.xml，HarmonyOS 有类似的机制，但格式是 JSON，路径规则也略有不同。

这篇文章把项目里的resources/目录扒开来看，搞清楚颜色、字符串、图片资源是怎么定义和使用的，还有多语言和暗色模式资源是怎么工作的。

项目预览

一、resources 目录结构

entry/src/main/resources/ ├── base/ # 默认资源（兜底） │ ├── element/ │ │ ├── color.json # 颜色资源（亮色模式默认值） │ │ ├── float.json # 浮点数资源（尺寸值） │ │ └── string.json # 字符串资源（英文默认） │ ├── media/ │ │ ├── layered_image.json # 分层图标配置 │ │ ├── image1.png # 加油站图片1 │ │ ├── image2.png # 加油站图片2 │ │ └── ... # 其他图片 │ └── profile/ │ ├── main_pages.json # 页面路由配置 │ └── route_map.json # Navigation路由表 │ ├── dark/ # 深色模式资源（覆盖base） │ └── element/ │ └── color.json # 暗色模式颜色 │ └── zh_CN/ # 中文资源（覆盖base/element） └── element/ └── string.json # 中文字符串

资源加载优先级：

设备语言为zh_CN + 暗色模式： zh_CN/element/string.json → base/element/string.json（字符串） dark/element/color.json → base/element/color.json（颜色） base/media/ （图片，无覆盖）

系统会根据设备语言和主题自动选择合适的资源文件，代码里不需要做任何判断。

二、颜色资源

2.1 定义颜色

// resources/base/element/color.json{"color":[{"name":"start_window_background","value":"#FFFFFF"},{"name":"page_background","value":"#F1F3F5"},{"name":"gas_station_name_color","value":"#182431"},{"name":"gas_station_addr_color","value":"#99182431"},{"name":"bind_sheet_background","value":"#FFFFFF"}]}

颜色值格式：

• #RRGGBB：不透明颜色（如#FFFFFF白色）
• #AARRGGBB：带透明度（如#99182431，99是透明度十六进制，约 60% 不透明度）

2.2 暗色模式颜色

// resources/dark/element/color.json{"color":[{"name":"start_window_background","value":"#000000"}]}

暗色模式文件只需要定义需要覆盖的颜色，没定义的自动使用base/里的值。

2.3 代码中使用颜色

// 使用 $r() 函数引用资源Text('加油站名称').fontColor($r('app.color.gas_station_name_color'))Column().backgroundColor($r('app.color.page_background'))

$r('app.color.XXX')的格式是固定的：

• app：当前应用的资源
• color：资源类型
• XXX：资源名称（对应 JSON 里的name字段）

三、字符串资源

3.1 英文默认字符串

// resources/base/element/string.json{"string":[{"name":"EntryAbility_label","value":"nearby gas station"},{"name":"gas_station","value":"gas station"},{"name":"car_life","value":"car life"},{"name":"nearby","value":"vicinity"},{"name":"navigation_text","value":"Navigation"},{"name":"calculate_text2","value":"Km"},{"name":"Stay_tuned","value":"Stay tuned"}]}

3.2 中文字符串（覆盖）

// resources/zh_CN/element/string.json{"string":[{"name":"EntryAbility_label","value":"附近加油站"},{"name":"gas_station","value":"加油站"},{"name":"car_life","value":"汽车生活"},{"name":"nearby","value":"附近"},{"name":"navigation_text","value":"导航"},{"name":"calculate_text2","value":"公里"},{"name":"Stay_tuned","value":"敬请期待"}]}

当设备语言是中文时，自动使用zh_CN/里的字符串；其他语言使用base/里的英文默认值。

3.3 代码中使用字符串

// 方式一：直接在组件里用Text($r('app.string.car_life'))// 自动显示"汽车生活"或"car life"// 方式二：在逻辑代码里获取字符串值letdistanceText=this.getUIContext().getHostContext()?.resourceManager.getStringSync($r('app.string.calculate_text2').id);// distanceText = "公里" 或 "Km"

项目中距离显示就用到了方式二：

// GasStationPage.etsText(`${CalculateUtil.getDistance(this.currentLatitude,this.currentLongitude,gasStation.latitude,gasStation.longitude)}${this.getUIContext().getHostContext()?.resourceManager.getStringSync($r('app.string.calculate_text2').id)}`)

这段代码把计算出的距离数字和"公里"单位拼在一起，单位文字通过资源管理器获取，支持多语言。

四、图片资源

4.1 图片放置位置

resources/base/media/ ├── image1.png # 加油站图片（石化品牌） ├── image2.png # 加油站图片 ├── image3.png # 加油站图片 ├── back.png # 返回按钮图标 ├── chevron_right.png # 右箭头图标 └── station.svg # 地图标记（加油站图标，SVG格式）

图片支持多种格式：PNG、JPG、SVG、WebP 等。

4.2 代码中使用图片

// 引用 media 目录下的图片Image($r('app.media.image1')).width(48).height(48)// 引用 SVG 图标Image($r('app.media.back')).width(40).height(40)

格式：$r('app.media.文件名')（不需要写扩展名）

五、profile 配置文件

5.1 main_pages.json（页面路由入口）

// resources/base/profile/main_pages.json{"src":["pages/MainPage"]}

这里定义了应用有哪些入口页面（@Entry修饰的页面）。MainPage是主页面，GasStationPage是通过 Navigation 路由管理的，不需要在这里注册。

5.2 route_map.json（Navigation路由表）

// resources/base/profile/route_map.json{"routerMap":[{"name":"GasStationPage","pageSourceFile":"src/main/ets/pages/GasStationPage.ets","buildFunction":"GasStationPageBuilder","data":{"description":"this is gas station page"}}]}

这是 Navigation 路由系统的配置表，定义了路由名称（GasStationPage）对应的页面文件和构建函数。后续第 09 篇会详细讲 Navigation 路由系统。

六、float.json：尺寸资源

// resources/base/element/float.json{"float":[{"name":"page_padding","value":"16vp"}]}

float.json可以定义浮点数尺寸，使用vp（虚拟像素）作为单位。不过项目中这类值大多放在Constants.ets里管理，float.json用得比较少。

提示：HarmonyOS 中px是物理像素，vp（viewport pixel）是虚拟像素，会根据屏幕密度自动换算，更推荐使用vp来做响应式布局。

七、layered_image.json：分层图标

// resources/base/media/layered_image.json{"layered-image":{"foreground":"app.media.foreground","background":"app.media.background"}}

这是应用图标的分层图标配置（HarmonyOS 的自适应图标），前景层和背景层分开设计，系统可以根据桌面主题做不同的圆角处理。

八、资源引用总结表

总结

HarmonyOS 的资源系统有几个核心优势：

1. 自动语言切换：zh_CN/目录里的资源自动覆盖base/，代码无感知
2. 自动主题切换：dark/目录里的颜色在深色模式下自动生效
3. 统一引用格式：$r('app.类型.名称')格式固定，好记
4. 编译时检查：引用了不存在的资源，编译会报错，不会到运行时才发现

下一篇开始进入 Ability 部分，讲UIAbility 的生命周期——应用是怎么启动、进入前台、切换后台的。