HarmonyOS开发实战：笔友-module.json5 模块能力声明与权限配置

前言在 HarmonyOS Stage 模型中module.json5是模块的核心清单文件。它声明了模块的能力abilities、权限requestPermissions、设备类型deviceTypes、入口组件mainElement等关键信息。系统通过读取这个文件来决定如何加载、运行和管控应用。本文将以开源鸿蒙笔友通信应用 xiexin 的module.json5为蓝本详细剖析模块清单的各个字段重点讲解 abilities 配置、skills 声明、权限申请以及与应用商店审核相关的内容。提示本文假设你已经了解 HarmonyOS Stage 模型基础。如果还不熟悉建议先阅读前三篇文章。一、module.json5 的定位module.json5是 HarmonyOS 模块清单文件每个模块HAP都对应一个module.json5。它告诉系统这个模块叫什么名字、是什么类型它支持哪些设备手机、平板、2in1它的入口能力Ability是什么它需要申请哪些权限它的页面路由表在哪里对于 xiexin 项目module.json5位于entry/src/main/module.json5这是entry模块主模块的清单文件。如果未来 xiexin 扩展出settings、share等独立模块每个模块都会有自己的module.json5。二、xiexin 的 module.json5 完整内容xiexin 的module.json5内容如下{ module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [ phone, tablet, 2in1 ], deliveryWithInstall: true, installationFree: false, pages: $profile:main_pages, abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, description: $string:EntryAbility_desc, icon: $media:layered_image, 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 } ] } }整个文件虽然只有 43 行却涵盖了模块声明的全部关键字段。下面我们逐一拆解。三、module 顶层字段详解3.1 name 与 type{ module: { name: entry, type: entry, // ... } }name模块名称必须与目录名一致。xiexin 的模块在entry/目录下所以 name 是entrytype模块类型可选值为entry主模块应用安装后第一个加载的模块feature功能模块按需加载shared共享模块提供 HAR/HSP 包给其他模块使用xiexin 当前只有主模块所以 type 是entry。3.2 descriptiondescription: $string:module_desc模块描述使用$string:引用resources/base/element/string.json中的字符串资源。提示模块描述会显示在系统的“应用信息“页面对用户可见。建议用简洁的语言描述模块用途如“主功能模块“、“账号管理“等。3.3 mainElementmainElement: EntryAbility模块入口能力的名称必须与abilities数组中某个 ability 的name字段一致。系统启动应用时会找到这个 ability 并加载它的 UI。如果mainElement指向一个不存在的 ability应用启动时会崩溃。3.4 deviceTypesdeviceTypes: [ phone, tablet, 2in1 ]模块支持的设备类型可选值设备类型说明phone手机tablet平板tv智慧屏car车机wearable智能穿戴2in1二合一设备笔记本/平板default通用设备xiexin 支持手机、平板和 2in1 三种设备类型这是主流鸿蒙应用的常见配置。提示声明不支持的设备类型应用市场会限制设备安装。例如只声明phone平板用户无法安装。3.5 deliveryWithInstalldeliveryWithInstall: true是否在应用安装时同步安装该模块。true随应用一起安装entry 模块必须为 truefalse按需安装feature 模块可用xiexin 是 entry 模块必须为true。3.6 installationFreeinstallationFree: false是否支持免安装特性。true支持免安装元服务能力false必须安装后才能使用xiexin 是普通应用不涉及元服务所以为false。提示如果设置installationFree: true模块将被视为元服务需要单独的元服务签名和审核流程。3.7 pagespages: $profile:main_pages页面路由表引用指向resources/base/profile/main_pages.json文件。提示这个字段的详细用法已在上一篇文章中讲解这里不再赘述。四、abilities 数组详解abilities数组是 module.json5 的核心声明模块中所有的 UIAbility。xiexin 只有一个 EntryAbilityabilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, description: $string:EntryAbility_desc, icon: $media:layered_image, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [entity.system.home], actions: [action.system.home] } ] } ]下面逐一解析每个字段。4.1 name 与 srcEntryname: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.etsnameAbility 名称在同一模块内必须唯一srcEntryAbility 实现文件路径相对于模块根目录entry/注意路径约定路径以./ets/开头不是./src/main/ets/必须包含.ets后缀路径分隔符使用/4.2 description、icon、labeldescription: $string:EntryAbility_desc, icon: $media:layered_image, label: $string:EntryAbility_label这三个字段都是资源引用descriptionAbility 描述对用户可见iconAbility 图标显示在桌面启动器labelAbility 名称显示在桌面图标下方xiexin 使用了layered_image资源类型。这是 HarmonyOS 提供的分层图标特性允许图标在不同主题下自适应。4.3 startWindowIcon 与 startWindowBackgroundstartWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background应用启动时的视觉元素startWindowIcon启动屏图标系统在应用加载完成前显示startWindowBackground启动屏背景色这两个字段是冷启动体验优化的关键。系统在调用 EntryAbility.onCreate 之前会先显示 startWindowIcon startWindowBackground 组成的启动屏避免用户看到白屏。提示startWindowIcon 建议使用简洁的纯色图标避免复杂的渐变和阴影因为系统可能不会精确还原设计细节。4.4 exportedexported: true是否允许其他应用通过隐式 Want 调用该 ability。true可被其他应用调用主入口 ability 必须为 truefalse仅限本应用内部调用提示从 API 9 开始所有 ability 默认不可被其他应用调用。如果需要跨应用调用必须显式声明exported: true并配置skills。4.5 skills 数组skills: [ { entities: [entity.system.home], actions: [action.system.home] } ]skills声明 ability 可以响应的隐式 Want 类型。每个 skill 包含entitiesWant 实体类别列表actionsWant 动作列表urisWant URI 匹配规则可选xiexin 配置的 skill 是entity.system.homeaction.system.home这是桌面启动器入口的固定配置。系统启动器会查找所有声明了这个 skill 的 ability并在桌面显示图标。点击图标即启动该 ability。五、requestPermissions 权限申请xiexin 申请了一个权限requestPermissions: [ { name: ohos.permission.INTERNET } ]ohos.permission.INTERNET是网络访问权限属于normal级别普通权限用户无需手动授权系统在应用安装时自动授予。5.1 权限的三个等级HarmonyOS 权限分为三个等级等级说明申请方式normal普通权限涉及风险低安装时自动授予system_basic系统基础权限涉及敏感数据运行时向用户申请system_core系统核心权限仅系统应用可用需签名配置5.2 完整的权限申请结构除了name权限申请还可以包含其他字段requestPermissions: [ { name: ohos.permission.READ_MEDIA, reason: $string:read_media_reason, usedScene: { abilities: [EntryAbility], when: inuse } } ]字段说明name权限名称必须reason申请权限的说明引用字符串资源system_basic 权限必须usedScene使用场景abilities使用该权限的 ability 名称列表when权限使用时机可选inuse使用时、always始终5.3 xiexin 未来需要申请的权限随着 xiexin 功能扩展未来可能需要申请的权限包括权限名称用途等级ohos.permission.READ_MEDIA读取相册选头像system_basicohos.permission.WRITE_MEDIA保存信件截图到相册system_basicohos.permission.NOTIFICATION_CONTROLLER推送新信提醒system_basicohos.permission.LOCATION笔友位置分享system_basic六、module.json5 与 main_pages.json 的协同module.json5 的pages字段指向路由表pages: $profile:main_pages这个引用建立了一条强契约编译期校验hvigor 会校验$profile:main_pages是否存在运行时加载系统在加载 entry 模块时读取 main_pages.json 注册路由路由查找router.pushUrl({ url: pages/ComposePage })在路由表中查找如果这条契约被打破如 main_pages.json 被删除应用启动时会崩溃。七、module.json5 与 EntryAbility 的契约module.json5 的abilities[0]建立了与 EntryAbility 的契约abilities: [ { name: EntryAbility, // 契约 1 srcEntry: ./ets/entryability/EntryAbility.ets, // 契约 2 skills: [ { entities: [entity.system.home], actions: [action.system.home] } // 契约 3 ] } ]契约 1name必须与 EntryAbility 类名对应虽然技术上不强制但这是约定契约 2srcEntry必须指向真实的.ets文件契约 3skills决定了桌面图标是否显示如果srcEntry指向的文件不存在或文件中没有export default class XxxAbility extends UIAbility应用无法启动。八、module.json5 的扩展实践让我们为 xiexin 添加一个设置 Ability展示如何扩展 abilities 数组。8.1 创建 SettingsAbility// entry/src/main/ets/entryability/SettingsAbility.ets import { UIAbility, AbilityConstant, Want } from kit.AbilityKit; import { window } from kit.ArkUI; import { hilog } from kit.PerformanceAnalysisKit; const TAG: string SettingsAbility; const DOMAIN: number 0xFF00; export default class SettingsAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { hilog.info(DOMAIN, TAG, %{public}s, SettingsAbility onCreate); } onWindowStageCreate(windowStage: window.WindowStage): void { windowStage.loadContent(pages/SettingsPage, (err) { if (err.code) { hilog.error(DOMAIN, TAG, Failed to load content: %{public}s, JSON.stringify(err) ?? ); } }); } }8.2 注册到 module.json5{ module: { abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, // ... skills: [ { entities: [entity.system.home], actions: [action.system.home] } ] }, { name: SettingsAbility, srcEntry: ./ets/entryability/SettingsAbility.ets, description: $string:SettingsAbility_desc, icon: $media:settings_icon, label: $string:SettingsAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: false } ] } }注意SettingsAbility没有skills所以桌面不会显示独立图标exported: false仅限本应用内部启动8.3 从 EntryAbility 启动 SettingsAbilityimport { common, Want } from kit.AbilityKit; // 在某个页面中 const context getContext(this) as common.UIAbilityContext; const want: Want { bundleName: com.xiexin.letter, abilityName: SettingsAbility }; context.startAbility(want);这样就完成了多 Ability 的扩展。九、module.json5 与应用市场审核module.json5 的某些字段直接影响应用市场审核结果。以下是几个关键点9.1 权限审核应用市场会严格审核权限申请必要性每个权限必须有合理用途最小化只申请必要的权限reason 字段system_basic 权限必须提供 reason提示如果权限用途无法解释清楚审核会被驳回。建议在 reason 中写明“用于[具体场景]“。9.2 deviceTypes 审核如果声明tablet但实际 UI 不适配平板应用市场会提示用户。建议声明所有测试通过的设备类型使用响应式布局适配不同尺寸9.3 图标与启动屏审核icon、startWindowIcon需要满足尺寸符合规范建议 192x192不含敏感内容不模仿系统应用图标十、module.json5 与签名配置module.json5 本身不包含签名信息签名信息在工程级build-profile.json5中// build-profile.json5 { app: { signingConfigs: [ { name: default, type: HarmonyOS, material: { certpath: ..., keyAlias: debugKey, keyPassword: ..., profile: ..., signAlg: SHA256withECDSA, storeFile: ..., storePassword: ... } } ] } }签名配置与 module.json5 的关系签名后的 HAP 包含一个 META-INF 目录存储签名信息系统在安装时验证签名未签名或签名错误的应用无法安装签名证书的bundleName必须与 AppScope/app.json5 的bundleName一致总结本文详细剖析了 HarmonyOS module.json5 模块清单文件的各个字段重点讲解了 abilities 配置、skills 声明、权限申请以及与应用市场审核相关的内容。理解 module.json5 的关键是把握“五个契约“与目录结构的契约、与 EntryAbility 的契约、与 main_pages.json 的契约、与系统启动器的契约、与应用市场的契约。这五个契约环环相扣共同构成了 HarmonyOS 应用模块声明的基础设施。下一篇文章我们将深入 AppScope/app.json5剖析应用级全局配置的实践。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.netHarmonyOS module.json5 配置https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-fileHarmonyOS app.json5 配置https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-configuration-fileHarmonyOS 应用配置文件概述https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-configuration-file-overview-stageHarmonyOS 声明权限https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/accesstoken-guidelinesHarmonyOS 访问控制概述https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/access-token-overviewHarmonyOS UIAbility 组件https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/uiabilityHarmonyOS 分层图标设计https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/layered-image