鸿蒙应用的两级结构
HarmonyOS应用采用应用级 + 模块级的两层结构：
应用 (App) ├── AppScope/ ← 应用级配置（全局唯一） │ ├── app.json5 ← 应用清单 │ └── resources/ ← 应用级资源 └── entry/ ← 模块（可以有多个） ├── build-profile.json5 ├── oh-package.json5 └── src/main/ ├── module.json5 ← 模块清单 └── ets/ ← 源代码AppScope：应用级配置
app.json5 — 应用身份证
{ "app": { "bundleName": "com.example.gomoku", // 应用唯一标识 "vendor": "example", // 开发者名称 "versionCode": 1000000, // 版本号（整数） "versionName": "1.0.0", // 版本名（展示用） "icon": "$media:app_icon", // 应用图标 "label": "$string:app_name" // 应用名称 } }关键字段解读：
| 字段 | 说明 | 注意事项 |
|---|---|---|
bundleName | 应用包名 | 全局唯一，上架后不可更改 |
versionCode | 版本号 | 必须为正整数，每次更新必须递增 |
versionName | 版本名 | 用户可见的版本字符串 |
icon/label | 图标和名称 | 使用$资源类型:资源名引用资源 |
应用级资源
AppScope/resources/ ├── base/element/string.json # 默认字符串 └── dark/element/color.json # 深色模式颜色base目录存放默认资源，dark目录存放深色模式下的覆盖资源。这种资源限定机制让应用能自动适配不同模式。
entry模块：主功能模块
module.json5 — 模块配置核心
{ "module": { "name": "entry", // 模块名称 "type": "entry", // 模块类型：entry(主模块)/feature(特性模块) "mainElement": "EntryAbility", // 入口Ability "deviceTypes": ["phone", "tablet", "2in1"], // 支持的设备类型 "deliveryWithInstall": true, // 是否随应用安装 "installationFree": false, // 是否支持免安装 "pages": "$profile:main_pages", // 页面路由配置 "abilities": [...] // Ability列表 } }Ability配置
"abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "description": "$string:EntryAbility_desc", "icon": "$media:app_icon", "label": "$string:EntryAbility_label", "startWindowIcon": "$media:app_icon", "startWindowBackground": "$color:start_window_background", "exported": true, "skills": [ { "entities": ["entity.system.home"], "actions": ["action.system.home"] } ] } ]skills配置是应用被系统识别的关键——entity.system.home+action.system.home表示这是一个可以通过桌面图标启动的入口Ability。
页面路由配置
// resources/base/profile/main_pages.json { "src": [ "pages/Index", "pages/TwoPlayerPage", "pages/AIBattlePage" ] }所有页面必须在main_pages.json中注册，否则router.pushUrl()会找不到目标页面。
资源引用机制
鸿蒙使用$资源类型:资源名的语法引用资源：
| 语法 | 示例 | 说明 |
|---|---|---|
$string:xxx | $string:app_name | 引用字符串 |
$color:xxx | $color:start_window_background | 引用颜色 |
$media:xxx | $media:app_icon | 引用媒体资源 |
$profile:xxx | $profile:main_pages | 引用profile配置 |
字符串资源示例
// AppScope/resources/base/element/string.json{"string":[{"name":"app_name","value":"五子棋"}]}// entry/src/main/resources/base/element/string.json{"string":[{"name":"module_desc","value":"Gomoku module"},{"name":"EntryAbility_desc","value":"Gomoku entry ability"},{"name":"EntryAbility_label","value":"五子棋"}]}颜色资源与深色模式
// entry/src/main/resources/base/element/color.json{"color":[{"name":"start_window_background","value":"#F5F5DC"},{"name":"board_color","value":"#D4A868"},{"name":"line_color","value":"#3B2F2F"}]}// entry/src/main/resources/dark/element/color.json{"color":[{"name":"start_window_background","value":"#333333"}]}深色模式下，start_window_background自动从#F5F5DC（米色）变为#333333（深灰），系统会自动选择对应目录的资源。
模块类型：entry vs feature
| 特性 | entry模块 | feature模块 |
|---|---|---|
| 数量 | 仅1个 | 可多个 |
| 作用 | 应用入口 | 动态特性（按需下载） |
| deliveryWithInstall | 必须为true | 可为false |
| mainElement | 必须配置 | 不需要 |
本项目只使用了单个entry模块，对于小型应用这已经足够。大型应用可以拆分feature模块实现按需加载。
总结
理解鸿蒙应用的两级结构是开发的基础：
- AppScope管应用级别的配置和资源
- entry模块管具体功能和页面
- 资源限定机制让应用自动适配不同设备/模式
- module.json5是模块的核心配置文件
