
阅读时长:约 19 分钟 | 难度:★★★☆☆ | 篇章:第 1 篇 · 项目架构与设计哲学
对应源码:xuanxiang_ohos_app/AppScope/、entry/src/main/resources/

前言
在 HarmonyOS 应用开发中,全局资源体系是工程化协作的基础。玄象项目通过 AppScope/ 目录统一管理应用名、图标、主题色等全局资源,确保 30+ 个页面在视觉语言上保持高度一致。本篇将深入剖析玄象项目的 AppScope 资源体系,包括 app.json5 全局配置、string.json 字符串资源、layered_image 分层图标、element/color.json 主题色策略等核心知识点。
提示:AppScope 资源是应用级全局资源,与
entry/src/main/resources/模块级资源互补。掌握两者的边界与协作方式,是规模化 HarmonyOS 应用开发的关键。
一、AppScope 目录结构
1.1 完整目录树
AppScope/
├── app.json5 # 应用全局配置(应用名、版本、图标)
└── resources/
└── base/
├── element/
│ └── string.json # 全局字符串资源
└── media/
├── background.png # 分层图标背景层
├── foreground.png # 分层图标前景层
└── layered_image.json # 分层图标配置
1.2 AppScope 与模块级 resources 的区别
| 维度 | AppScope/resources | entry/src/main/resources |
|---|---|---|
| 作用域 | 应用全局,所有模块共享 | 仅 entry 模块可用 |
| 用途 | 应用名、全局图标、品牌色 | 页面级字符串、图标、配置 |
| 访问方式 | $string:xxx / $media:xxx | $string:xxx / $r('app.string.xxx') |
| 优先级 | 模块级资源覆盖 AppScope | 模块级优先 |
提示:玄象项目将应用名
玄象放在 AppScope 的string.json,确保应用在桌面、设置、通知栏都显示统一名称。
二、app.json5 全局配置
2.1 配置全貌
{
"app": {
"bundleName": "com.xuanxiang.app",
"vendor": "xuanxiang",
"versionCode": 1000000,
"versionName": "1.0.0",
"icon": "$media:layered_image",
"label": "$string:app_name"
}
}
2.2 关键字段解析
玄象项目的 app.json5 配置体现了 HarmonyOS 应用的标准身份:
- bundleName:
com.xuanxiang.app,反向域名格式,全局唯一。 - vendor:
xuanxiang,应用开发商标识。 - versionCode:
1000000,整数版本号,用于升级判断。 - versionName:
1.0.0,用户可见的版本名。 - icon:
$media:layered_image,引用分层图标资源。 - label:
$string:app_name,引用字符串资源。
2.3 versionCode 编码规范
玄象项目采用 十进制分段编码 规范:
versionCode = 主版本 × 1000000 + 次版本 × 1000 + 修订版本
1000000 = 1.0.0
1010000 = 1.1.0
1000001 = 1.0.1
提示:
versionCode必须为正整数,且每次上架版本号必须递增。玄象项目预留了 6 位空间,可支撑 100 个主版本演进。
三、string.json 字符串资源管理
3.1 全局字符串清单
玄象项目 AppScope/resources/base/element/string.json 定义了应用全局字符串:
{
"string": [
{ "name": "app_name", "value": "MyApplication" }
]
}
提示:玄象项目此处仍保留 DevEco 默认的
MyApplication,实际生产中应改为玄象。本系列后续篇章会展示批量替换字符串的最佳实践。
3.2 模块级字符串资源
除了 AppScope 全局字符串,玄象项目在 entry/src/main/resources/base/element/string.json 定义了模块级字符串:
{
"string": [
{ "name": "module_desc", "value": "玄象主模块" },
{ "name": "EntryAbility_desc", "value": "玄象应用入口" },
{ "name": "EntryAbility_label", "value": "玄象" },
{ "name": "location_reason", "value": "用于风水方位测算" },
{ "name": "camera_reason", "value": "用于 AI 拍照风水分析" },
{ "name": "media_reason", "value": "用于保存风水报告截图" }
]
}
3.3 字符串资源分层策略
玄象项目采用 全局字符串 + 模块字符串 分层策略:
- 全局字符串(AppScope):应用名、品牌词、全局提示。
- 模块字符串(entry):模块描述、Ability 标签、权限理由。
| 字符串类型 | 资源位置 | 使用场景 |
|---|---|---|
| 应用名 | AppScope/string.json | 桌面图标、设置列表 |
| Ability 描述 | entry/string.json | 权限申请弹窗 |
| 权限申请理由 | entry/string.json | module.json5 的 reason 字段 |
| UI 文案 | 页面内联或模块字符串 | Text('玄象') |
3.4 字符串资源引用方式
在 ArkTS 代码中引用字符串资源有两种方式:
// 方式一:$string 简写(推荐)
Text($string:app_name)
// 方式二:$r 完整路径
Text($r('app.string.app_name'))
提示:玄象项目主要在
.json5配置文件中使用$string:xxx,而在 ArkTS 代码中直接使用内联字符串(如Text('玄象'))。这种方式在 UI 文案相对固定的中文应用中是可接受的折中。
四、layered_image 分层图标
4.1 分层图标的概念
HarmonyOS 引入 分层图标(layered image) 机制,将应用图标拆分为前景层与背景层,便于系统在不同场景下动态调整:
- 前景层(foreground):图标主体内容。
- 背景层(background):图标底色或纹理。
4.2 玄象项目分层图标配置
// layered_image.json
{
"layered-image": {
"background": "$media:background",
"foreground": "$media:foreground"
}
}
4.3 分层图标在 module.json5 的引用
玄象项目在多个位置引用分层图标:
{
"app": {
"icon": "$media:layered_image" // 应用图标
},
"module": {
"abilities": [{
"icon": "$media:layered_image", // Ability 图标
"startWindowIcon": "$media:startIcon"
}]
}
}
提示:
startIcon与layered_image是两套图标资源。startIcon用于应用启动瞬间的窗口图标(小尺寸),layered_image用于桌面图标(大尺寸,支持分层)。
4.4 分层图标尺寸规范
HarmonyOS 对应用图标尺寸有严格规范:
| 资源 | 尺寸(px) | 用途 |
|---|---|---|
foreground.png | 216 × 216 | 前景层 |
background.png | 216 × 216 | 背景层 |
startIcon.png | 96 × 96 | 启动窗口图标 |
layered_image.json | — | 分层配置 |
玄象项目的分层图标设计为:金色太极图(前景) + 深色背景,呼应启动页的视觉语言。
五、主题色策略
5.1 主题色三层架构
玄象项目构建了 三层主题色架构,确保颜色管理一致性:
- 资源层(
element/color.json):颜色资源定义。 - 常量层(
Colors.ets):ArkTS 代码可引用的颜色常量。 - 样式层(
Styles.ets):基于颜色的复合样式封装。
5.2 资源层:element/color.json
玄象项目在 entry/src/main/resources/base/element/color.json 定义颜色资源:
{
"color": [
{ "name": "start_window_background", "value": "#0A0E17" },
{ "name": "primary_gold", "value": "#D4A843" },
{ "name": "bg_dark", "value": "#0A0E17" },
{ "name": "bg_card", "value": "#1A1F2E" }
]
}
5.3 常量层:Colors.ets
export class Colors {
// 主色
static readonly PRIMARY_GOLD: string = '#D4A843';
static readonly LIGHT_GOLD: string = '#F0D078';
static readonly DARK_GOLD: string = '#A07830';
// 背景色
static readonly BG_DARK: string = '#0A0E17';
static readonly BG_CARD: string = '#1A1F2E';
static readonly BG_CARD_BORDER: string = '#2A3040';
static readonly BG_CARD_HIGHLIGHT: string = '#252B3D';
// 文字色
static readonly TEXT_PRIMARY: string = '#FFFFFF';
static readonly TEXT_SECONDARY: string = '#B0B0B0';
static readonly TEXT_GOLD: string = '#D4A843';
static readonly TEXT_DIM: string = '#808080';
// 五行色
static readonly WOOD_GREEN: string = '#4CAF50';
static readonly FIRE_RED: string = '#F44336';
static readonly EARTH_YELLOW: string = '#FFC107';
static readonly METAL_WHITE: string = '#E0E0E0';
static readonly WATER_BLUE: string = '#2196F3';
// 宜忌色
static readonly YI_GREEN: string = '#4CAF50';
static readonly JI_RED: string = '#F44336';
// 四象色
static readonly DRAGON_CYAN: string = '#00BCD4';
static readonly BIRD_RED: string = '#E91E63';
static readonly TIGER_WHITE: string = '#ECEFF1';
static readonly TURTLE_PURPLE: string = '#9C27B0';
// 四季色
static readonly SEASON_SPRING: string = '#4CAF50';
static readonly SEASON_SUMMER: string = '#F44336';
static readonly SEASON_AUTUMN: string = '#FF9800';
static readonly SEASON_WINTER: string = '#2196F3';
// 透明度
static readonly TRANSPARENT: string = '#00000000';
static readonly GOLD_TRANSPARENT: string = '#33D4A843';
static readonly CARD_OVERLAY: string = '#CC1A1F2E';
}
5.4 颜色分组与命名规范
玄象项目 Colors.ets 采用 语义化分组 + 大写常量 的命名规范:
| 颜色组 | 命名前缀 | 用途 |
|---|---|---|
| 主色 | PRIMARY_GOLD / LIGHT_GOLD | 标题、强调元素 |
| 背景 | BG_DARK / BG_CARD | 页面背景、卡片背景 |
| 文字 | TEXT_PRIMARY / TEXT_DIM | 文字颜色分级 |
| 五行 | WOOD_GREEN / FIRE_RED | 五行属性配色 |
| 宜忌 | YI_GREEN / JI_RED | 宜忌标签配色 |
| 四象 | DRAGON_CYAN / TIGER_WHITE | 四象配色 |
| 四季 | SEASON_SPRING / SEASON_WINTER | 四季配色 |
| 透明度 | GOLD_TRANSPARENT | 半透明叠加 |
提示:玄象项目颜色命名遵循
组别_语义模式,例如BG_CARD_HIGHLIGHT表示"卡片高亮背景色"。这种命名方式让颜色用途一目了然。
5.5 透明度色值的 16 进制规则
玄象项目使用 8 位 16 进制色值(#AARRGGBB 格式)表示带透明度的颜色:
static readonly GOLD_TRANSPARENT: string = '#33D4A843'; // 20% 透明度金色
static readonly CARD_OVERLAY: string = '#CC1A1F2E'; // 80% 透明度卡片色
透明度前缀对照表:
| 16 进制前缀 | 透明度百分比 | 玄象用途 |
|---|---|---|
00 | 0% | 完全透明 |
33 | 20% | 半透明叠加 |
80 | 50% | 中等透明 |
CC | 80% | 卡片蒙层 |
FF | 100% | 完全不透明 |
六、element 资源类型详解
6.1 element 目录可定义的资源类型
玄象项目 element/ 目录下使用了以下资源类型:
| 资源类型 | 文件 | 用途 |
|---|---|---|
| 字符串 | string.json | UI 文案、Ability 描述 |
| 颜色 | color.json | 主题色、背景色 |
| 整数 | integer.json | 数值常量(如超时时间) |
| 布尔 | boolean.json | 布尔配置 |
| 整数数组 | intarray.json | 数值数组配置 |
| 字符串数组 | strarray.json | 字符串数组配置 |
| 主题样式 | theme.json | 主题样式配置 |
| 资源数组 | plural.json | 复数化资源 |
6.2 string.json 详细结构
{
"string": [
{
"name": "app_name",
"value": "玄象"
}
]
}
每个字符串条目包含两个字段:
- name:资源标识符,必须全局唯一。
- value:字符串内容,支持转义字符。
6.3 color.json 详细结构
{
"color": [
{
"name": "primary_gold",
"value": "#D4A843"
}
]
}
颜色值支持以下格式:
#RGB:3 位 16 进制。#RRGGBB:6 位 16 进制(玄象项目主要使用)。#AARRGGBB:8 位 16 进制(带透明度)。#AA:仅透明度,与 RGB 组合使用。
七、多语言与多设备资源适配
7.1 多语言资源目录
HarmonyOS 通过 限定词目录 支持多语言适配:
resources/
├── base/ # 默认资源
├── en_US/ # 英文资源
├── zh_CN/ # 简体中文资源
├── zh_TW/ # 繁体中文资源
└── ...
玄象项目作为传统文化应用,目前仅提供简体中文版本,未来若国际化,只需新建 en_US/element/string.json 并翻译即可。
7.2 多设备资源适配
通过限定词目录适配不同设备:
resources/
├── base/ # 默认资源
├── phone/ # 手机专用
├── tablet/ # 平板专用
└── ...
玄象项目当前仅支持 phone,未来若推出平板版本,可在 tablet/ 目录下提供更高分辨率的图标资源。
7.3 暗色模式资源适配
resources/
├── base/ # 浅色模式默认
└── dark/ # 暗色模式
提示:玄象项目默认采用深色主题,因此
dark/目录下放置的是对应的暗色模式资源。系统切换暗色模式时,会自动加载dark/目录的资源。
八、资源访问的最佳实践
8.1 在 ArkTS 代码中访问资源
// 字符串资源
Text($r('app.string.app_name'))
// 颜色资源
.backgroundColor($r('app.color.primary_gold'))
// 媒体资源
Image($r('app.media.background'))
// 简写方式(推荐)
Text($string:app_name)
Image($media:layered_image)
8.2 在 JSON 配置文件中访问资源
{
"label": "$string:EntryAbility_label",
"icon": "$media:layered_image",
"startWindowBackground": "$color:start_window_background"
}
8.3 在 rawfile 中访问原始资源
// 加载 rawfile 资源
const context = getContext(this);
const rawData = await context.resourceManager.getRawFileContent('hexagrams.json');
提示:玄象项目的
HexagramData.ets、MansionData.ets等数据文件可以转为 JSON 放入rawfile/,通过resourceManager加载,实现数据与代码解耦。本系列后续篇章会详细演示这种模式。
总结
本篇以玄象项目为蓝本,系统讲解了 HarmonyOS 应用的全局资源体系:从 app.json5 全局配置、string.json 字符串资源、layered_image 分层图标,到 color.json 主题色策略,再到多语言、多设备、暗色模式的资源适配。掌握这套资源管理体系,是构建可维护、可国际化、可主题化 HarmonyOS 应用的基础。
下一篇:《04 · 颜色与样式常量化:Colors.ets 与 Styles.ets 的统一设计令牌》,将带您深入玄象项目的"设计令牌"体系。
如果这篇文章对你有帮助,欢迎点赞👍、收藏⭐、关注🔔,你的支持是我持续创作的动力!
相关资源:
- HarmonyOS 官方文档:资源文件分类与访问
- HarmonyOS 官方文档:应用配置文件概述
- HarmonyOS 官方文档:限定词目录
- 开源鸿蒙跨平台社区:https://openharmonycrossplatform.youkuaiyun.com
815



被折叠的 条评论
为什么被折叠?



