本文解析 ImportantDays 项目中的两个核心配置文件
app.json5和module.json5，包括应用级配置（包名、版本、图标）、模块级配置（Ability 声明、设备类型、权限申请）、以及这些配置与代码运行时的关联关系。
一、配置文件体系
HarmonyOS 应用的配置文件采用 JSON5 格式（支持注释和尾逗号），分为两个层级：
AppScope/ └── app.json5 ← 应用级配置（全局） entry/ └── src/main/ └── module.json5 ← 模块级配置（entry 模块）配置层级
app.json5 (应用级) ├── bundleName ← 应用唯一标识 ├── versionCode/Name ← 版本信息 ├── icon/label ← 应用图标和名称 └── modules ← 包含的模块 module.json5 (模块级) ├── name/type ← 模块名称和类型 ├── mainElement ← 入口 Ability ├── deviceTypes ← 支持设备 ├── abilities ← Ability 列表 └── requestPermissions ← 权限申请二、app.json5 详解
完整内容
{"app":{"bundleName":"com.importantdays.app","vendor":"importantdays","versionCode":1000000,"versionName":"1.0.0","icon":"$media:app_icon","label":"$string:app_name"}}字段解析
bundleName
"bundleName":"com.importantdays.app"应用的唯一包名，全局唯一。
用途：
- 应用在系统中的唯一标识
- WantAgent 中使用：
bundleName: 'com.importantdays.app' - 安装和卸载的标识
命名规范：反向域名格式（com.公司名.应用名）
vendor
"vendor":"importantdays"应用供应商名称。
versionCode
"versionCode":1000000版本号（数字），用于版本比较。
规则：
- 必须是整数
- 新版本必须大于旧版本
1000000= 1.0.0 的编码（1 × 1000000）
versionName
"versionName":"1.0.0"版本名称（字符串），显示给用户。
格式：主版本.次版本.修订号
icon
"icon":"$media:app_icon"应用图标资源引用。
语法：$media:资源名→ 引用resources/base/media/目录下的资源。
label
"label":"$string:app_name"应用名称资源引用。
语法：$string:资源名→ 引用resources/base/element/string.json中的字符串。
string.json 内容
{"string":[{"name":"app_name","value":"重要日"}]}应用名称为"重要日"，显示在桌面图标下方和设置中。
三、module.json5 详解
完整内容
{"module":{"name":"entry","type":"entry","description":"$string:module_desc","mainElement":"EntryAbility","deviceTypes":["phone","tablet"],"deliveryWithInstall":true,"installationFree":false,"pages":"$profile:main_pages","abilities":[{"name":"EntryAbility","srcEntry":"./ets/entryability/EntryAbility.ets","description":"$string:entry_ability_desc","icon":"$media:app_icon","label":"$string:entry_ability_label","startWindowIcon":"$media:app_icon","startWindowBackground":"$color:start_window_background","exported":true,"skills":[{"entities":["entity.system.home"],"actions":["action.system.home"]}]}],"requestPermissions":[]}}模块级字段
name
"name":"entry"模块名称。entry是主模块（入口模块）。
type
"type":"entry"模块类型：
entry：应用入口模块feature：功能模块shared：共享库模块
mainElement
"mainElement":"EntryAbility"模块的入口 Ability 名称。应用启动时首先加载此 Ability。
deviceTypes
"deviceTypes":["phone","tablet"]支持的设备类型：
phone：手机tablet：平板tv：电视wearable：穿戴设备car：车机
ImportantDays 支持手机和平板。
deliveryWithInstall
"deliveryWithInstall":true是否随应用安装时一起下载。true= 安装时即下载此模块。
installationFree
"installationFree":false是否支持免安装。false= 需要安装才能使用。
pages
"pages":"$profile:main_pages"页面路由配置文件引用。
语法：$profile:文件名→ 引用resources/base/profile/目录下的 JSON 文件。
main_pages.json 内容
{"src":["pages/MainEntry"]}定义了页面路由列表，MainEntry对应MainEntry.ets文件。
abilities 字段
"abilities":[{"name":"EntryAbility","srcEntry":"./ets/entryability/EntryAbility.ets","description":"$string:entry_ability_desc","icon":"$media:app_icon","label":"$string:entry_ability_label","startWindowIcon":"$media:app_icon","startWindowBackground":"$color:start_window_background","exported":true,"skills":[{"entities":["entity.system.home"],"actions":["action.system.home"]}]}]Ability 字段解析
name
"name":"EntryAbility"Ability 名称，必须与代码中的类名对应。
关联：
// EntryAbility.etsexportdefaultclassEntryAbilityextendsUIAbility{...}srcEntry
"srcEntry":"./ets/entryability/EntryAbility.ets"Ability 源文件路径。
icon / label
"icon":"$media:app_icon","label":"$string:entry_ability_label"Ability 的图标和名称（可以与应用级不同）。
startWindowIcon
"startWindowIcon":"$media:app_icon"启动窗口图标（应用启动时显示的图标）。
startWindowBackground
"startWindowBackground":"$color:start_window_background"启动窗口背景色。
语法：$color:资源名→ 引用resources/base/element/color.json中的颜色。
exported
"exported":true是否可以被其他应用调用。true= 允许外部调用。
skills
"skills":[{"entities":["entity.system.home"],"actions":["action.system.home"]}]声明 Ability 能响应的意图（Intent）。
entity.system.home+action.system.home：表示此 Ability 可以从桌面启动。这是应用入口 Ability 的标准配置。
requestPermissions
"requestPermissions":[]需要申请的权限列表。ImportantDays 当前为空数组。
注意：通知权限不需要在此声明，通过notificationManager.requestEnableNotification()动态请求即可。
如果需要其他权限（如位置、相机等），需要在此声明：
// 示例（项目中未使用）"requestPermissions":[{"name":"ohos.permission.LOCATION","reason":"$string:location_reason","usedScene":{"abilities":["EntryAbility"],"when":"always"}}]四、配置与代码的关联
启动流程
1. 系统读取 app.json5 → bundleName: "com.importantdays.app" → 确定应用身份 2. 系统读取 module.json5 → mainElement: "EntryAbility" → 确定入口 Ability 3. 系统加载 EntryAbility → srcEntry: "./ets/entryability/EntryAbility.ets" → 执行 EntryAbility 类 4. EntryAbility.onCreate() → 初始化数据 5. EntryAbility.onWindowStageCreate() → loadContent('pages/MainEntry') → 加载 MainEntry 页面 6. MainEntry 渲染 → Tabs 显示三个页面WantAgent 与配置的对应
// NotificationUtil 中的 WantAgent{bundleName:'com.importantdays.app',// ← app.json5 的 bundleNameabilityName:'EntryAbility',// ← module.json5 的 abilities[0].nameaction:'action.system.home'// ← module.json5 的 skills[0].actions[0]}三者必须完全一致，否则通知点击无法跳转。
资源引用体系
$media:app_name → resources/base/media/app_icon.png $string:app_name → resources/base/element/string.json → {"name": "app_name", "value": "重要日"} $color:start_window → resources/base/element/color.json → {"name": "start_window_background", "value": "#FFFFFF"} $profile:main_pages → resources/base/profile/main_pages.json资源引用语法
| 前缀 | 资源类型 | 示例 |
|---|---|---|
$media: | 图片 | $media:app_icon |
$string: | 字符串 | $string:app_name |
$color: | 颜色 | $color:start_window_background |
$profile: | 配置文件 | $profile:main_pages |
五、版本管理
versionCode 与 versionName
"versionCode":1000000,"versionName":"1.0.0"版本号规则
versionName: 1.0.0 │ │ │ │ │ └── 修订号（bug修复） │ └──── 次版本号（新功能） └────── 主版本号（重大变更） versionCode: 1000000 │ │ │ │ │ └── 修订号 × 1 │ └──── 次版本号 × 1000 └────── 主版本号 × 1000000版本升级示例
| versionName | versionCode | 说明 |
|---|---|---|
| 1.0.0 | 1000000 | 初始版本 |
| 1.0.1 | 1000001 | 修复 bug |
| 1.1.0 | 1001000 | 新增功能 |
| 2.0.0 | 2000000 | 重大更新 |
六、设备适配
deviceTypes 配置
"deviceTypes":["phone","tablet"]ImportantDays 支持手机和平板两种设备。
响应式设计考量
虽然配置支持平板，但项目的 UI 主要针对手机设计：
- 使用固定宽度（如 56vp 色条）
- 固定高度（如 52vp 日期格）
- 未使用断点适配
在平板上应用可以正常运行，但可能无法充分利用大屏幕。未来可以通过 ArkUI 的断点机制实现响应式布局。
七、构建配置
build-profile.json5
{"app":{"signingConfigs":[],"products":[{"name":"default","signingConfig":"default","compatibleSdkVersion":"5.0.3(15)","runtimeOS":"HarmonyOS"}]}}| 配置 | 说明 |
|---|---|
compatibleSdkVersion | 兼容的 SDK 版本 |
runtimeOS | 运行时操作系统 |
oh-package.json5
{"dependencies":{"dayjs":"^1.11.x"}}声明项目依赖的第三方库。
八、配置检查清单
开发 ImportantDays 时需要确保以下配置一致：
| 检查项 | 位置 | 值 |
|---|---|---|
| bundleName | app.json5 | com.importantdays.app |
| bundleName | WantAgent | com.importantdays.app |
| abilityName | module.json5 | EntryAbility |
| abilityName | WantAgent | EntryAbility |
| srcEntry | module.json5 | ./ets/entryability/EntryAbility.ets |
| 实际文件 | 文件系统 | ets/entryability/EntryAbility.ets |
| mainElement | module.json5 | EntryAbility |
| loadContent | EntryAbility.ets | pages/MainEntry |
| pages | main_pages.json | pages/MainEntry |
| 实际文件 | 文件系统 | ets/pages/MainEntry.ets |
九、总结
HarmonyOS 应用配置文件体现了以下设计：
- 分层配置：app.json5（全局）+ module.json5（模块级）
- 资源引用：
$前缀语法引用资源 - 声明式：Ability、权限、设备都通过配置声明
- 一致性：配置与代码必须严格对应
- 版本管理：versionCode + versionName 双重版本控制
- 设备适配：通过 deviceTypes 声明支持设备
配置文件是应用与系统之间的"契约"，理解配置文件是开发鸿蒙应用的基础。
