阅读时长约 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 字段含义详解bundleName应用唯一标识符采用反向域名格式全局唯一。vendor应用开发商名称用于 AppGallery 商店展示。versionCode版本号整数用于版本升级判断。versionName版本名字符串向用户展示。icon应用图标引用resources下的媒体资源。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 可接收的隐式 Wantentity.system.homeohos.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}fromkit.PerformanceAnalysisKit;import{BackupExtensionAbility,BundleVersion}fromkit.CoreFileKit;exportdefaultclassEntryBackupAbilityextendsBackupExtensionAbility{asynconBackup(){hilog.info(0x0000,testTag,onBackup ok);awaitPromise.resolve();}asynconRestore(bundleVersion:BundleVersion){hilog.info(0x0000,testTag,onRestore ok %{public}s,JSON.stringify(bundleVersion));awaitPromise.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 权限声明三要素每个权限声明包含三个核心要素name权限名必须是系统预定义的ohos.permission.*。reason权限申请理由必须引用字符串资源如$string:location_reason。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 权限申请最佳实践玄象项目遵循以下权限申请原则最小权限原则仅申请功能必需的权限避免过度索权。场景化授权用户进入对应功能页时才申请权限而非一启动就申请。降级方案如 LOCATION 申请失败时降级到 APPROXIMATELY_LOCATION。理由透明每个user_grant权限都通过reason字段说明用途。五、main_pages.json路由表注册5.1 路由表与 pages 字段module.json5中pages: $profile:main_pages引用了resources/base/profile/main_pages.json路由表文件。该文件列出应用所有可跳转的页面路径。5.2 路由注册规范玄象项目的页面注册严格遵循以下规则所有需要通过router.pushUrl跳转的页面必须在路由表中注册。页面路径以pages/开头与ets/pages/目录结构对应。启动页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 实现的标准化开发流程设计稿拆解将设计稿分解为可复用的 ArkUI 组件。组件树构建使用Column/Row/Stack等容器组件构建页面骨架。样式实现通过border/shadow/borderRadius等属性还原设计稿视觉。交互接入绑定onClick/onChange等事件处理。七、HarmonyOS 应用工程模型演进7.1 工程模型分类HarmonyOS 提供两种工程模型Stage 模型推荐API 9 起引入配置简洁支持复杂应用架构。FA 模型已废弃早期模型配置繁琐新项目不应使用。玄象项目采用Stage 模型所有module.json5配置均遵循 Stage 模型规范。7.2 Stage 模型核心组件UIAbility → 界面载体承载页面生命周期 WindowStage → 窗口舞台管理窗口与内容加载 ExtensionAbility → 扩展能力无界面后台服务 AbilityStage → 模块入口HAP 加载时回调 Context → 上下文提供资源、权限、能力访问八、项目构建与运行链路8.1 构建工具链玄象项目使用 HarmonyOS 官方构建工具Hvigor构建脚本位于hvigorfile.ts// hvigorfile.tsimport{appTasks}fromohos/hvigor-ohos-plugin;exportdefault{system:appTasks,};8.2 构建产物Hvigor 构建链路产出的核心文件包括HAP 包HarmonyOS Ability Package应用安装包。HSP 包HarmonyOS Shared Package动态共享包。APP 包应用上架 AppGallery 的最终包格式。8.3 构建模式玄象项目build-profile.json5中声明了两种构建模式buildModeSet: [ { name: debug }, { name: release } ]debug开发调试模式包含完整日志与符号表。release发布模式开启代码混淆与性能优化。九、入口 AbilityEntryAbility 实战9.1 EntryAbility 全貌EntryAbility是玄象应用的唯一 UIAbility 入口继承自UIAbilityimport{AbilityConstant,ConfigurationConstant,UIAbility,Want}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{window}fromkit.ArkUI;constDOMAIN0x0000;exportdefaultclassEntryAbilityextendsUIAbility{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 模块依赖关系玄象项目的模块依赖关系遵循上层依赖下层同层不互相依赖的原则应用层EntryAbility依赖模块层pages。模块层依赖组件层common/components与工具层common/utils。组件层与工具层依赖资源层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.netArkTS 资源引用语法资源引用