整理一篇学习笔记，把看到的一些要点和自己的理解都记下来。
阅读时长：约 18 分钟 | 难度：★★★☆☆ | 篇章：第 1 篇 · 项目架构与设计哲学 对应源码：xuanxiang_ohos_app/entry/src/main/module.json5、AppScope/app.json5
前言
玄象是一款以中华传统文化为核心主题的 HarmonyOS 原生应用，涵盖二十八星宿、周易卦象、八字命理、风水罗盘、农历节气、月相乐律、AI 取名与助手等十余个功能模块。本系列将以玄象项目真实源码为蓝本，分 100 篇技术博文逐步拆解一款商用 HarmonyOS 应用从架构搭建到功能落地的全过程。
本篇作为系列开篇，将带您俯瞰整个 ArkTS 工程结构，并深入剖析 module.json5 中权限声明与 Ability 注册的实战写法。掌握这些底层配置，是后续每一篇 ArkUI 组件实战的地基。
提示：本系列不涉及环境搭建与 ArkTS 基础语法，默认您已具备 DevEco Studio 工程创建与 ArkTS 语法基础。
一、工程总览：从目录树看 ArkTS 项目骨架
1.1 顶层目录结构
玄象工程采用标准的 HarmonyOS 应用工程模型，顶层目录如下：
xuanxiang_ohos_app/
├── AppScope/ # 应用全局配置与资源
│ ├── app.json5 # 应用全局配置
│ └── resources/base/ # 全局资源（字符串、图片、媒体）
├── entry/ # 主 HAP 模块
│ └── src/main/ets/ # ArkTS 源码主目录
├── build-profile.json5 # 应用级构建配置
├── code-linter.json5 # 代码静态检查规则
├── hvigorfile.ts # Hvigor 构建脚本
├── oh-package.json5 # 工程级依赖配置
└── oh-package-lock.json5 # 依赖锁定文件
1.2 entry 模块 ets 源码分层
玄象主模块 entry/src/main/ets/ 采用 六层架构，职责清晰、便于维护：
ets/
├── entryability/ # UIAbility 入口
├── entrybackupability/ # 备份扩展能力
├── pages/ # 页面级组件
│ ├── Index.ets # 路由根
│ ├── SplashPage.ets # 启动页
│ ├── HomePage.ets # 首页
│ ├── mansion/ # 二十八星宿
│ ├── yijing/ # 周易易学
│ ├── mingli/ # 八字命理
│ ├── fengshui/ # 风水罗盘
│ ├── astronomy/ # 天文历法
│ ├── music/ # 乐律
│ ├── geography/ # 地理九州
│ ├── naming/ # AI 取名
│ ├── assistant/ # AI 助手
│ ├── stems/ # 天干地支
│ └── profile/ # 用户中心
├── common/
│ ├── components/ # 复用组件（GoldBorderCard 等）
│ ├── constants/ # 常量（Colors、Styles）
│ └── utils/ # 工具类（LunarCalendar、MansionData 等）
└── ...
提示：pages/ 下的子目录划分严格对应应用功能模块，每个功能模块独立成包，便于后续按需拆分为 HSP 动态共享包或 HAR 静态共享包。
1.3 关键文件清单
文件作用篇章覆盖AppScope/app.json5应用全局配置本篇 + 第 03 篇entry/src/main/module.json5模块配置（权限/Ability）本篇entry/src/main/ets/pages/Index.ets路由根第 05 篇entry/src/main/ets/pages/SplashPage.ets启动页第 11-20 篇entry/src/main/ets/pages/HomePage.ets首页第 21-30 篇entry/src/main/ets/common/constants/Colors.ets颜色常量第 04 篇entry/src/main/ets/common/constants/Styles.ets样式常量第 04 篇
二、app.json5：应用全局身份
2.1 配置内容
AppScope/app.json5 是应用的全局身份标识，玄象项目配置如下：
{
"app": {
"bundleName": "com.xuanxiang.app",
"vendor": "xuanxiang",
"versionCode": 1000000,
"versionName": "1.0.0",
"icon": "$media:layered_image",
"label": "$string:app_name"
}
}
2.2 字段含义详解
1. bundleName：应用唯一标识符，采用反向域名格式，全局唯一。
2. vendor：应用开发商名称，用于 AppGallery 商店展示。
3. versionCode：版本号（整数），用于版本升级判断。
4. versionName：版本名（字符串），向用户展示。
5. icon：应用图标，引用 resources 下的媒体资源。
6. label：应用名称，引用 resources 下的字符串资源。
提示：$media:layered_image 是 ArkTS 资源引用语法，$ 前缀表示引用 resources/base/element 或 media 目录下的资源。
三、module.json5：模块级核心配置
3.1 配置全貌
entry/src/main/module.json5 是 entry 模块的核心配置文件，玄象项目完整配置如下：
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"mainElement": "EntryAbility",
"deviceTypes": ["phone"],
"deliveryWithInstall": true,
"installationFree": false,
"pages": "$profile:main_pages",
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:layered_image",
"label": "$string:EntryAbility_label",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"entities": ["entity.system.home"],
"actions": ["ohos.want.action.home"]
}
]
}
],
"extensionAbilities": [
{
"name": "EntryBackupAbility",
"srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
"type": "backup",
"exported": false,
"metadata": [
{
"name": "ohos.extension.backup",
"resource": "$profile:backup_config"
}
]
}
],
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" },
{
"name": "ohos.permission.LOCATION",
"reason": "$string:location_reason",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
},
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"reason": "$string:location_reason",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
},
{
"name": "ohos.permission.CAMERA",
"reason": "$string:camera_reason",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
},
{
"name": "ohos.permission.READ_MEDIA",
"reason": "$string:media_reason",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
},
{
"name": "ohos.permission.WRITE_MEDIA",
"reason": "$string:media_reason",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
}
]
}
}
3.2 模块基础字段
字段值说明nameentry模块名称，与目录名一致typeentry模块类型，entry 表示主入口模块mainElementEntryAbility模块入口 Ability 名称deviceTypes["phone"]支持的设备类型deliveryWithInstalltrue是否在应用安装时下载该模块installationFreefalse是否支持免安装pages$profile:main_pages路由表资源引用
3.3 Ability 配置详解
abilities 数组注册 UIAbility，玄象项目仅有一个 EntryAbility：
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:layered_image",
"label": "$string:EntryAbility_label",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"entities": ["entity.system.home"],
"actions": ["ohos.want.action.home"]
}
]
}
关键字段说明：
- startWindowIcon：启动窗口图标，应用冷启动时展示。
- startWindowBackground：启动窗口背景色，决定冷启动瞬间的视觉感受。
- skills：声明 Ability 可接收的隐式 Want，
entity.system.home+ohos.want.action.home表示该 Ability 作为应用桌面入口。
提示：exported: true 表示该 Ability 可被其他应用调用，对于仅作为桌面入口的 EntryAbility，务必设置为 true。
3.4 extensionAbilities 备份扩展
玄象项目通过 extensionAbilities 注册了备份扩展能力：
{
"name": "EntryBackupAbility",
"srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
"type": "backup",
"exported": false,
"metadata": [
{
"name": "ohos.extension.backup",
"resource": "$profile:backup_config"
}
]
}
EntryBackupAbility 继承自 BackupExtensionAbility，在应用云端备份/恢复时被回调：
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
export default class EntryBackupAbility extends BackupExtensionAbility {
async onBackup() {
hilog.info(0x0000, 'testTag', 'onBackup ok');
await Promise.resolve();
}
async onRestore(bundleVersion: BundleVersion) {
hilog.info(0x0000, 'testTag', 'onRestore ok %{public}s', JSON.stringify(bundleVersion));
await Promise.resolve();
}
}
四、requestPermissions：六大权限实战声明
4.1 权限清单总览
玄象项目声明了 6 个权限，分别对应不同功能模块：
权限名用途对应模块ohos.permission.INTERNET网络访问AI 取名、AI 助手ohos.permission.LOCATION精确位置GPS 风水ohos.permission.APPROXIMATELY_LOCATION大致位置GPS 风水降级方案ohos.permission.CAMERA相机访问AI 拍照风水ohos.permission.READ_MEDIA读取媒体风水报告配图ohos.permission.WRITE_MEDIA写入媒体风水报告保存
4.2 权限声明三要素
每个权限声明包含三个核心要素：
1. name：权限名，务必是系统预定义的 ohos.permission.*。
2. reason：权限申请理由，务必引用字符串资源（如 $string:location_reason）。
3. usedScene：权限使用场景，包括 abilities（使用该权限的 Ability 列表）与 when（使用时机）。
4.3 权限等级分类
normal（普通权限）：
- INTERNET
- READ_MEDIA / WRITE_MEDIA
→ 安装时自动授予
user_grant（用户授权权限）：
- LOCATION / APPROXIMATELY_LOCATION
- CAMERA
→ 必须运行时动态申请，用户授权后才生效
提示：对于 user_grant 类权限，必须在代码中调用 @ohos.abilityAccessCtrl 的 requestPermissionsFromUser 接口动态申请，仅在 module.json5 声明是不够的。本系列第 64、65 篇会详细演示 GPS 与相机的动态授权流程。
4.4 权限申请最佳实践
玄象项目遵循以下权限申请原则：
1. 最小权限原则：仅申请功能必需的权限，避免过度索权。
2. 场景化授权：用户进入对应功能页时才申请权限，而非一启动就申请。
3. 降级方案：如 LOCATION 申请失败时降级到 APPROXIMATELY_LOCATION。
4. 理由透明：每个 user_grant 权限都通过 reason 字段说明用途。
五、main_pages.json：路由表注册
5.1 路由表与 pages 字段
module.json5 中 pages: "$profile:main_pages" 引用了 resources/base/profile/main_pages.json 路由表文件。该文件列出应用所有可跳转的页面路径。
5.2 路由注册规范
玄象项目的页面注册严格遵循以下规则：
1. 所有需要通过 router.pushUrl 跳转的页面，必须在路由表中注册。
2. 页面路径以 pages/ 开头，与 ets/pages/ 目录结构对应。
3. 启动页 SplashPage 作为 Index 的初始内容，不单独注册。
六、设计稿与源码对应关系
6.1 30 张设计稿概览
玄象项目在 designs/ 目录下提供了 30 张 UI 设计稿，覆盖应用所有核心界面：
序号设计稿对应源码01启动页SplashPage.ets02首页-今日天地HomePage.ets03二十八星宿MansionListPage.ets04星宿详情MansionDetailPage.ets05星野分野StarTerritoryPage.ets06十二次TwelveCiPage.ets07农历LunarCalendarPage.ets08二十四节气SolarTermsPage.ets09月相MoonPhasesPage.ets10天干地支HeavenlyStemsPage.ets
完整 30 张设计稿与源码对应关系详见 articles/00_index.md。
6.2 设计稿驱动开发流程
玄象项目采用"设计稿 → 组件树 → ArkTS 达成"的标准化开发流程：
1. 设计稿拆解：将设计稿分解为可复用的 ArkUI 组件。
2. 组件树构建：使用 Column / Row / Stack 等容器组件构建页面骨架。
3. 样式达成：通过 border / shadow / borderRadius 等属性还原设计稿视觉。
4. 交互接入：绑定 onClick / onChange 等事件处理。
七、HarmonyOS 应用工程模型演进
7.1 工程模型分类
HarmonyOS 提供两种工程模型：
- Stage 模型（建议用）：API 9 起引入，配置简洁，支持复杂应用架构。
- FA 模型（已废弃）：早期模型，配置繁琐，新项目不应使用。
module.json5 配置均遵循 Stage 模型规范。
7.2 Stage 模型核心组件
UIAbility → 界面载体，承载页面生命周期
WindowStage → 窗口舞台，管理窗口与内容加载
ExtensionAbility → 扩展能力，无界面后台服务
AbilityStage → 模块入口，HAP 加载时回调
Context → 上下文，提供资源、权限、能力访问
八、项目构建与运行链路
8.1 构建工具链
玄象项目使用 HarmonyOS 官方构建工具 Hvigor，构建脚本位于 hvigorfile.ts：
// hvigorfile.ts
import { appTasks } from '@ohos/hvigor-ohos-plugin';
export default {
system: appTasks,
};
8.2 构建产物
Hvigor 构建链路产出的核心文件包括：
1. HAP 包：HarmonyOS Ability Package，应用安装包。
2. HSP 包：HarmonyOS Shared Package，动态共享包。
3. APP 包：应用上架 AppGallery 的最终包格式。
8.3 构建模式
玄象项目 build-profile.json5 中声明了两种构建模式：
"buildModeSet": [
{ "name": "debug" },
{ "name": "release" }
]
- debug：开发调试模式，包含完整日志与符号表。
- release：发布模式，开启代码混淆与性能优化。
九、入口 Ability：EntryAbility 实战
9.1 EntryAbility 全貌
EntryAbility 是玄象应用的唯一 UIAbility 入口，继承自 UIAbility：
import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
const DOMAIN = 0x0000;
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
try {
this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
} catch (err) {
hilog.error(DOMAIN, 'testTag', 'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
}
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
}
onWindowStageCreate(windowStage: window.WindowStage): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
return;
}
hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
});
}
}
9.2 生命周期回调
UIAbility 提供以下生命周期回调，玄象项目按需达成：
回调触发时机玄象用途onCreateAbility 创建设置颜色模式、初始化日志onDestroyAbility 销毁资源释放onWindowStageCreate窗口创建加载首页 pages/IndexonWindowStageDestroy窗口销毁UI 资源释放onForeground切到前台恢复计时器、刷新数据onBackground切到后台暂停计时器、保存状态
9.3 setColorMode 颜色模式设置
玄象项目在 onCreate 中调用 setColorMode(COLOR_MODE_NOT_SET)，表示跟随系统颜色模式。该接口需要 try-catch 包裹，避免在低版本系统上抛出异常。
提示：HarmonyOS 提供 COLOR_MODE_NOT_SET（跟随系统）、COLOR_MODE_LIGHT（浅色）、COLOR_MODE_DARK（深色）三种模式。玄象采用深色主题为主，故选择跟随系统。
十、玄象项目架构图
10.1 整体架构
下图展示了玄象项目的整体架构分层：
图 10-1：玄象项目架构分层图（共分为应用层、模块层、组件层、工具层、资源层五层）
10.2 模块依赖关系
玄象项目的模块依赖关系遵循"上层依赖下层，同层不互相依赖"的原则：
1. 应用层（EntryAbility）依赖 模块层（pages）。
2. 模块层 依赖 组件层（common/components）与 工具层（common/utils）。
3. 组件层 与 工具层 依赖 资源层（Colors、Styles）。
总结
本篇作为玄象百篇技术博文的开篇，系统梳理了 HarmonyOS 应用的工程结构、app.json5 与 module.json5 配置实战，并深入剖析了六大权限声明规范与 EntryAbility 生命周期回调。掌握这些底层配置，是后续每一篇 ArkUI 组件实战的地基。
下一篇：《02 · 从 30 张设计稿到 ArkUI 组件树：UI 拆解方法论》，将带您看玄象项目如何将 30 张视觉设计稿系统性地拆解为可复用的 ArkUI 组件树。
---
相关资源：
- HarmonyOS 官方文档：应用包结构说明
- HarmonyOS 官方文档：module.json5 配置文件
- HarmonyOS 官方文档：UIAbility 组件
- HarmonyOS 官方文档：权限管理
- 开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
- ArkTS 资源引用语法：资源引用
就写这么多吧，内容比较基础，适合入门回顾。有补充的地方欢迎留言一起完善。
评论 (0)
暂无评论