阅读时长约 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/resourcesentry/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 应用的标准身份bundleNamecom.xuanxiang.app反向域名格式全局唯一。vendorxuanxiang应用开发商标识。versionCode1000000整数版本号用于升级判断。versionName1.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.jsonmodule.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.png216 × 216前景层background.png216 × 216背景层startIcon.png96 × 96启动窗口图标layered_image.json—分层配置玄象项目的分层图标设计为金色太极图前景 深色背景呼应启动页的视觉语言。五、主题色策略5.1 主题色三层架构玄象项目构建了三层主题色架构确保颜色管理一致性资源层element/color.json颜色资源定义。常量层Colors.etsArkTS 代码可引用的颜色常量。样式层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.etsexportclassColors{// 主色staticreadonlyPRIMARY_GOLD:string#D4A843;staticreadonlyLIGHT_GOLD:string#F0D078;staticreadonlyDARK_GOLD:string#A07830;// 背景色staticreadonlyBG_DARK:string#0A0E17;staticreadonlyBG_CARD:string#1A1F2E;staticreadonlyBG_CARD_BORDER:string#2A3040;staticreadonlyBG_CARD_HIGHLIGHT:string#252B3D;// 文字色staticreadonlyTEXT_PRIMARY:string#FFFFFF;staticreadonlyTEXT_SECONDARY:string#B0B0B0;staticreadonlyTEXT_GOLD:string#D4A843;staticreadonlyTEXT_DIM:string#808080;// 五行色staticreadonlyWOOD_GREEN:string#4CAF50;staticreadonlyFIRE_RED:string#F44336;staticreadonlyEARTH_YELLOW:string#FFC107;staticreadonlyMETAL_WHITE:string#E0E0E0;staticreadonlyWATER_BLUE:string#2196F3;// 宜忌色staticreadonlyYI_GREEN:string#4CAF50;staticreadonlyJI_RED:string#F44336;// 四象色staticreadonlyDRAGON_CYAN:string#00BCD4;staticreadonlyBIRD_RED:string#E91E63;staticreadonlyTIGER_WHITE:string#ECEFF1;staticreadonlyTURTLE_PURPLE:string#9C27B0;// 四季色staticreadonlySEASON_SPRING:string#4CAF50;staticreadonlySEASON_SUMMER:string#F44336;staticreadonlySEASON_AUTUMN:string#FF9800;staticreadonlySEASON_WINTER:string#2196F3;// 透明度staticreadonlyTRANSPARENT:string#00000000;staticreadonlyGOLD_TRANSPARENT:string#33D4A843;staticreadonlyCARD_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格式表示带透明度的颜色staticreadonlyGOLD_TRANSPARENT:string#33D4A843;// 20% 透明度金色staticreadonlyCARD_OVERLAY:string#CC1A1F2E;// 80% 透明度卡片色透明度前缀对照表16 进制前缀透明度百分比玄象用途000%完全透明3320%半透明叠加8050%中等透明CC80%卡片蒙层FF100%完全不透明六、element 资源类型详解6.1 element 目录可定义的资源类型玄象项目element/目录下使用了以下资源类型资源类型文件用途字符串string.jsonUI 文案、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 } ] }颜色值支持以下格式#RGB3 位 16 进制。#RRGGBB6 位 16 进制玄象项目主要使用。#AARRGGBB8 位 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 资源constcontextgetContext(this);constrawDataawaitcontext.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.csdn.net