HarmonyOS7 module.json5 配置全解：Ability 注册与权限

文章目录前言文件长什么样逐字段讲解注册一个新 Ability 的正确步骤代码实现权限怎么加才规范核心代码常见误区小白必踩完整可运行示例module.json5 真配置完整示例写在最后前言module.json5是每个 HarmonyOS 模块的身份证。Ability 怎么注册、图标长啥样、要哪些权限全写在这一个文件里。我刚学时最怕动它生怕写错一个字段 app 就起不来。后来发现它其实很有规律。这篇文章我把最常用的配置项逐个拆开讲你照着改就行不用背。文件长什么样{ module: { name: entry, type: entry, mainElement: EntryAbility, deviceTypes: [phone, tablet], abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ts, description: $string:EntryAbility_desc, icon: $media:icon, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [entity.system.home], actions: [action.system.home] } ] } ], requestPermissions: [ { name: ohos.permission.INTERNET, reason: $string:internet_reason, usedScene: { abilities: [EntryAbility], when: always } } ] } }逐字段讲解字段作用说明name模块名一般entrytype模块类型entry入口/feature特性mainElement启动 Ability写你入口 Ability 名deviceTypes支持设备phone/tablet/tv等abilities[].nameAbility 名要和代码里类名一致abilities[].srcEntry代码路径指到你的 .ts 文件abilities[].exported是否可被外部拉起入口一般trueabilities[].skills启动能力entity.system.home表示桌面图标入口requestPermissions申请的权限列表每个权限要写理由注册一个新 Ability 的正确步骤我踩过只建了文件却忘了注册的坑结果跳转直接报错。正确流程在ets/下建SecondAbility.ts类名为SecondAbility。在module.json5的abilities数组里加一项name写SecondAbilitysrcEntry指到文件路径。如果要从别的 app 拉起它exported设true否则false更安全。代码实现{ name: SecondAbility, srcEntry: ./ets/secondability/SecondAbility.ts, exported: false }漏了注册是最常见的Ability 找不到错误。记住建 Ability 文件 ≠ 能用必须在 json5 里登记。权限怎么加才规范权限分普通和敏感。敏感权限如定位、通讯录光在requestPermissions写还不够运行时还要弹窗动态申请下一篇讲。这里先说配置核心代码requestPermissions: [ { name: ohos.permission.INTERNET, reason: $string:net_reason }, { name: ohos.permission.LOCATION, reason: $string:loc_reason, usedScene: { abilities: [EntryAbility], when: inuse } } ]reason是给用户看的申请理由写清楚为什么需要否则上架会被拒。when: inuse表示仅使用时申请always表示安装/启动时。尽量用inuse对用户更友好。常见误区小白必踩误区说明建了 Ability 不登记只建.ts文件忘了在module.json5的abilities里注册跳转直接报找不到。exported乱设能被外部拉起的设true否则false更安全设错可能桌面上找不到图标或被人乱拉起。敏感权限不写reason上架会被拒每个权限都要写清为什么需要。下面这段代码可以直接复制到 DevEco Studio 里运行。建议你边读边敲改一改文末「动手改一改」里的参数亲眼看看效果。完整可运行示例module.json5 真配置这是「Ability 注册 权限声明」的最小可用配置。和代码一起看才完整。完整示例// entry/src/main/module.json5节选关键字段 { module: { name: entry, type: entry, abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ts, description: $string:EntryAbility_desc, icon: $media:icon, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [entity.system.home], actions: [action.system.home] } ] } ], requestPermissions: [ { name: ohos.permission.INTERNET }, { name: ohos.permission.CAMERA } ] } }你会看到什么这段配置注册了一个名为EntryAbility的入口声明了桌面图标、启动窗口背景并预申请了「联网」和「相机」两个权限。编译后应用图标出现在桌面且首次用到相机时会弹出系统授权框。动手改一改删掉requestPermissions里的INTERNET再发起网络请求观察报错——理解「声明即契约」。把exported改成false其它应用将无法拉起这个 Ability。在abilities里复制一份并改名体验「一个模块多个入口」。写在最后module.json5看着吓人其实就是登记册Ability 来登记一下权限来登记一下。你只要记住建了 Ability 必须登记、敏感权限要写理由基本不会再踩配置坑。建议把你项目的 json5 打开对着上面的表格逐项核对一遍——尤其exported和skills这两处错一个app 就可能起不来或桌面上找不到图标。