HarmonyOS ——应用 / 组件级配置｜我边看文档边理解的那版
这篇是我啃 HarmonyOS 文档里「应用/组件级配置」时记的笔记， 主要搞清楚：一个 App 想“被系统认识”，到底要在哪些地方“写名片”。
1. 应用包名：bundleName 就是你在系统里的“身份证”
- 配置位置：
AppScope/app.json5 - 字段：
bundleName - 作用：标识应用 唯一性，就跟身份证号一样。
官方推荐命名规则：反域名形式
com.example.demo
↑ ↑ ↑
域名 应用所属组织/个人 应用名
通常建议：
- 第一级：
com这种域名后缀； - 第二级：厂商 / 个人名；
- 第三级：应用名（可以再多级细分）。
这一项一定要想清楚再定，后面生态里都是拿这个识别你。
2. 应用图标 & 名称：icon + label 的来源和优先级
图标和名称是在两个地方配置的：
app.json5：应用级module.json5：模块级（每个 HAP 一个）
从 DevEco Studio 5.0.3.800 版本开始：
module.json5里的icon/label：不再强制要求；app.json5里的icon/label：仍然是必选参数。
简单理解优先级：
- 一般情况下，应用级的 icon / label 是主入口；
- 模块级可以单独覆盖（比如某个模块需要展示不同名称或图标）；
- 如果模块级没配，就用 app.json5 里的默认配置。
要发应用时，最起码保证：
app.json5里的icon和label配全。
3. 应用版本声明：versionCode + versionName
配置位置：AppScope/app.json5
3.1 versionCode：用来“比大小”的纯数字
- 字段：
versionCode - 类型：32 位非负整数
- 用途：只用来判断 哪个版本更新 数值越大 → 版本越新。
比如：
"versionCode": 10001
不要求和字面版本字符串对应，但习惯上会有自己的规则，比如：
- 前两位：大版本；
- 中间两位：小版本；
- 最后几位：内部构建号。
3.2 versionName：给人看的版本号字符串
- 字段：
versionName - 类型：字符串
- 用途：展示给用户看的版本描述，例如：
"versionName": "1.0.1"
可以记成： Code 让系统比较，Name 让用户看得懂。
4. Module 支持的设备类型：deviceTypes
配置位置：module.json5
字段：deviceTypes
作用：声明这个 Module 支持在哪些设备上运行。
比如：
"deviceTypes": [
"phone",
"tablet",
"2in1"
]
- 如果某个设备类型没加进去 → 系统默认这个 Module 不支持在该设备上跑。
适合的用法：
- 比如卡片模块只想在手机上使用，就限制 deviceTypes；
- 某个专为 PC / 2in1 设计的模块，可以只写
["2in1"]。
5. Module 权限：requestPermissions
配置位置：module.json5
字段：requestPermissions
作用：声明 访问系统 / 其他应用受保护能力 所需的权限，包括：
- 申请的权限名；
- 申请理由（为什么用）；
- 使用场景（在哪些功能中会用到）。
示意：
"requestPermissions": [
{
"name": "ohos.permission.READ_CONTACTS",
"reason": "$string:perm_read_contacts_desc",
"usedScene": {
"abilities": [ "EntryAbility" ],
"when": "inuse"
}
}
]
这一块既影响用户弹框体验，也关系到应用上架合规性，文案要写清楚。
6. 应用启动模式：startMode（多 UIAbility 时才有意义）
从 API version 20 开始，支持通过 startMode 字段，控制 点击应用图标时的启动行为。
配置位置：app.json5 → app 字段下。
前提条件：
launchType必须是 单实例模式；- 应用里存在 多个 UIAbility，否则就没必要切换模式。
6.1 可选值与含义
-
默认值：
"mainTask"- 表现：点击图标总是打开应用主 UIAbility 就算之前你在子页面 / 另一个 UIAbility 中停留，点击图标也会回到主 UIAbility。
-
可选值：
"recentTask"- 表现：点击图标打开最近使用的 UIAbility 哪个 UIAbility 最后在前台，点击图标就回到那个。
示例：
{
"app": {
"bundleName": "com.example.demo",
"versionCode": 10001,
"versionName": "1.0.1",
"icon": "$media:app_icon",
"label": "$string:app_name",
"startMode": "mainTask" // 或 "recentTask"
}
}
小结：我现在脑子里对“配置”的整体图是这样
-
app.json5（应用级）
bundleName：应用唯一标识；icon/label：应用图标、名称（必填）；versionCode/versionName：版本声明；startMode：多 UIAbility 下，点击图标的启动模式。
-
module.json5（模块级 / HAP 级）
deviceTypes：这个模块支持哪些设备运行；requestPermissions：模块需要申请的权限；- （可选）
icon/label：如需覆盖模块级图标和名称，可以写。
