HarmonyOs应用《重要日》开发第30篇 - HarmonyOS 应用配置详解

本文解析 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}}字段解析bundleNamebundleName:com.importantdays.app应用的唯一包名全局唯一。用途应用在系统中的唯一标识WantAgent 中使用bundleName: com.importantdays.app安装和卸载的标识命名规范反向域名格式com.公司名.应用名vendorvendor:importantdays应用供应商名称。versionCodeversionCode:1000000版本号数字用于版本比较。规则必须是整数新版本必须大于旧版本1000000 1.0.0 的编码1 × 1000000versionNameversionName:1.0.0版本名称字符串显示给用户。格式主版本.次版本.修订号iconicon:$media:app_icon应用图标资源引用。语法$media:资源名→ 引用resources/base/media/目录下的资源。labellabel:$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:[]}}模块级字段namename:entry模块名称。entry是主模块入口模块。typetype:entry模块类型entry应用入口模块feature功能模块shared共享库模块mainElementmainElement:EntryAbility模块的入口 Ability 名称。应用启动时首先加载此 Ability。deviceTypesdeviceTypes:[phone,tablet]支持的设备类型phone手机tablet平板tv电视wearable穿戴设备car车机ImportantDays 支持手机和平板。deliveryWithInstalldeliveryWithInstall:true是否随应用安装时一起下载。true 安装时即下载此模块。installationFreeinstallationFree:false是否支持免安装。false 需要安装才能使用。pagespages:$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 字段解析namename:EntryAbilityAbility 名称必须与代码中的类名对应。关联// EntryAbility.etsexportdefaultclassEntryAbilityextendsUIAbility{...}srcEntrysrcEntry:./ets/entryability/EntryAbility.etsAbility 源文件路径。icon / labelicon:$media:app_icon,label:$string:entry_ability_labelAbility 的图标和名称可以与应用级不同。startWindowIconstartWindowIcon:$media:app_icon启动窗口图标应用启动时显示的图标。startWindowBackgroundstartWindowBackground:$color:start_window_background启动窗口背景色。语法$color:资源名→ 引用resources/base/element/color.json中的颜色。exportedexported:true是否可以被其他应用调用。true 允许外部调用。skillsskills:[{entities:[entity.system.home],actions:[action.system.home]}]声明 Ability 能响应的意图Intent。entity.system.homeaction.system.home表示此 Ability 可以从桌面启动。这是应用入口 Ability 的标准配置。requestPermissionsrequestPermissions:[]需要申请的权限列表。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 与 versionNameversionCode:1000000,versionName:1.0.0版本号规则versionName: 1.0.0 │ │ │ │ │ └── 修订号bug修复 │ └──── 次版本号新功能 └────── 主版本号重大变更 versionCode: 1000000 │ │ │ │ │ └── 修订号 × 1 │ └──── 次版本号 × 1000 └────── 主版本号 × 1000000版本升级示例versionNameversionCode说明1.0.01000000初始版本1.0.11000001修复 bug1.1.01001000新增功能2.0.02000000重大更新六、设备适配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 时需要确保以下配置一致检查项位置值bundleNameapp.json5com.importantdays.appbundleNameWantAgentcom.importantdays.appabilityNamemodule.json5EntryAbilityabilityNameWantAgentEntryAbilitysrcEntrymodule.json5./ets/entryability/EntryAbility.ets实际文件文件系统ets/entryability/EntryAbility.etsmainElementmodule.json5EntryAbilityloadContentEntryAbility.etspages/MainEntrypagesmain_pages.jsonpages/MainEntry实际文件文件系统ets/pages/MainEntry.ets九、总结HarmonyOS 应用配置文件体现了以下设计分层配置app.json5全局 module.json5模块级资源引用$前缀语法引用资源声明式Ability、权限、设备都通过配置声明一致性配置与代码必须严格对应版本管理versionCode versionName 双重版本控制设备适配通过 deviceTypes 声明支持设备配置文件是应用与系统之间的契约理解配置文件是开发鸿蒙应用的基础。