03 module.json5 配置文件全解能力声明、权限申请与设备支持前言图03 module.json5 配置文件全解能力声明、权限申请与设备支持 运行效果截图HarmonyOS NEXT在 HarmonyOS NEXT Stage 模型中module.json5是每个模块Module的户口本——它向系统声明了这个模块有什么能力Ability、请求了什么权限、支持什么设备。配置错误可能导致应用无法安装、权限申请失败或 HAP 在不兼容设备上崩溃。本文以鹿鹿·笔迹心理分析的完整module.json5配置为例逐字段解析每个配置项的含义、类型、可选值和实际影响。官方文档·module.json5 配置说明developer.huawei.com项目源码仓库harmony-appGitHub图module.json5 核心配置层级——module → abilities / extensionAbilities / requestPermissions一、module.json5 文件位置与作用1.1 文件位置entry/ └── src/main/ └── module.json5 ← 就是这个文件每个 Moduleentry/feature/hsp都有一个独立的module.json5它描述了该 Module 的元数据。1.2 与 app.json5 的区别配置文件位置作用范围主要内容AppScope/app.json5AppScope 目录整个应用全局应用包名、版本号、图标、标签entry/module.json5每个 Module单个 ModuleAbility、权限、设备类型、页面路由二、module.json5 完整配置解析2.1 顶层结构{module:{name:entry,type:entry,description:$string:module_desc,mainElement:EntryAbility,deviceTypes:[phone],deliveryWithInstall:true,installationFree:false,pages:$profile:main_pages,abilities:[...],extensionAbilities:[...],requestPermissions:[...]}}2.2 基础字段说明字段类型说明项目值namestringModule 名称需唯一entrytypestringModule 类型entry入口模块descriptionstring模块描述支持资源引用$string:module_descmainElementstring应用启动时的入口 AbilityEntryAbilitydeviceTypesstring[]支持的设备类型列表[phone]deliveryWithInstallboolean是否随应用安装一起下载trueinstallationFreeboolean是否免安装原子化服务falsepagesstring页面路由配置文件引用$profile:main_pages2.3 deviceTypes 设备类型deviceTypes数组决定了应用支持的设备范围// 仅支持手机deviceTypes:[phone]// 支持手机平板deviceTypes:[phone,tablet]// 支持手机平板智慧屏deviceTypes:[phone,tablet,2in1,tv]支持的设备类型值值设备phone智能手机tablet平板电脑2in1二合一设备折叠屏/平板键盘tv智慧屏/TVwearable可穿戴设备手表等car车机提示鹿鹿项目当前仅支持phone。若要在平板上适配需要额外实现响应式布局和多窗口支持。三、abilities 配置详解3.1 abilities 数组abilities数组定义了 Module 中所有的UIAbilityabilities:[{name:EntryAbility,srcEntry:./ets/EntryAbility.ets,description:$string:EntryAbility_desc,icon:$media:app_icon,label:$string:EntryAbility_label,startWindowIcon:$media:startIcon,startWindowBackground:$color:start_window_background,exported:true,launchType:singleton,skills:[{entities:[entity.system.home],actions:[action.system.home]}]}]3.2 Ability 字段逐项说明字段必须说明示例值name✅Ability 名称需唯一EntryAbilitysrcEntry✅源码相对路径./ets/EntryAbility.etsdescription推荐Ability 描述本地化$string:EntryAbility_descicon推荐任务栏图标$media:app_iconlabel推荐任务栏标签应用名$string:EntryAbility_labelstartWindowIcon推荐启动白屏时显示的图标$media:startIconstartWindowBackground推荐启动白屏背景色$color:start_window_backgroundexported推荐是否允许其他应用拉起true桌面入口launchType可选启动模式singleton默认单实例3.3 skills能力标签skills声明了 Ability 能够响应的 Intent意图。桌面图标入口必须声明skills:[{entities:[entity.system.home],actions:[action.system.home]}]entity.system.home表示这是桌面入口action.system.home表示响应桌面启动操作桌面图标skills 匹配entity.system.home ✅action.system.home ✅启动 EntryAbility3.4 launchType 启动模式模式含义适用场景singleton单实例默认主入口 Ability全局唯一standard标准多实例需要多个独立实例的场景specified指定实例按条件选择或创建实例四、requestPermissions 权限声明4.1 鸿蒙权限模型鸿蒙采用静态声明 动态授权的两阶段权限模型normal 普通权限system_basic 系统基础权限system_core 系统核心权限module.json5 静态声明应用安装时系统校验权限等级?安装即自动授予运行时弹窗请求用户授权需要系统签名普通应用不可用用户同意 → 权限生效用户拒绝 → 功能降级4.2 项目权限声明完整示例requestPermissions:[{name:ohos.permission.CAMERA,reason:$string:camera_permission_reason,usedScene:{abilities:[EntryAbility],when:inuse}},{name:ohos.permission.READ_IMAGEVIDEO,reason:$string:storage_permission_reason,usedScene:{abilities:[EntryAbility],when:inuse}},{name:ohos.permission.WRITE_IMAGEVIDEO,reason:$string:write_storage_permission_reason,usedScene:{abilities:[EntryAbility],when:inuse}},{name:ohos.permission.NFC_TAG,reason:$string:nfc_permission_reason,usedScene:{abilities:[EntryAbility],when:inuse}}]4.3 权限字段逐项说明字段必须说明name✅权限名称官方定义的字符串常量reason✅system_basic 级别必须权限申请原因用户可见必须使用$string:资源引用usedScene.abilities可选使用该权限的 Ability 列表usedScene.when可选inuse前台使用或always后台也需要4.4 项目用到的权限一览权限级别用途使用时机ohos.permission.CAMERAsystem_basic拍照功能进入 CapturePage 时ohos.permission.READ_IMAGEVIDEOsystem_basic从相册选图使用相册功能时ohos.permission.WRITE_IMAGEVIDEOsystem_basic保存图片到相册导出分析图片时ohos.permission.NFC_TAGnormalNFC 碰一碰使用配对功能时五、$profile 资源引用机制5.1 main_pages 引用pages: $profile:main_pages中的$profile:前缀用于引用resources/base/profile/目录下的配置文件entry/src/main/resources/base/profile/ └── main_pages.json ← $profile:main_pages 指向此文件// main_pages.json 完整示例{src:[pages/LoginPage,pages/HomePage,pages/CapturePage,pages/AnalyzingPage,pages/ReportDetailPage]}5.2 其他 $ 前缀资源引用引用格式作用示例$string:xxx引用字符串资源$string:app_name$media:xxx引用媒体资源图片、SVG$media:app_icon$color:xxx引用颜色资源$color:start_window_background$profile:xxx引用 profile JSON 配置文件$profile:main_pages// resources/base/element/color.json{color:[{name:start_window_background,value:#F1ECE2}]}六、完整的 module.json56.1 项目完整配置{module:{name:entry,type:entry,description:$string:module_desc,mainElement:EntryAbility,deviceTypes:[phone],deliveryWithInstall:true,installationFree:false,pages:$profile:main_pages,abilities:[{name:EntryAbility,srcEntry:./ets/EntryAbility.ets,description:$string:EntryAbility_desc,icon:$media:app_icon,label:$string:EntryAbility_label,startWindowIcon:$media:startIcon,startWindowBackground:$color:start_window_background,exported:true,launchType:singleton,skills:[{entities:[entity.system.home],actions:[action.system.home]}]}],requestPermissions:[{name:ohos.permission.CAMERA,reason:$string:camera_permission_reason,usedScene:{abilities:[EntryAbility],when:inuse}},{name:ohos.permission.READ_IMAGEVIDEO,reason:$string:storage_permission_reason,usedScene:{abilities:[EntryAbility],when:inuse}},{name:ohos.permission.WRITE_IMAGEVIDEO,reason:$string:write_storage_permission_reason,usedScene:{abilities:[EntryAbility],when:inuse}},{name:ohos.permission.NFC_TAG,reason:$string:nfc_permission_reason,usedScene:{abilities:[EntryAbility],when:inuse}}]}}6.2 配置常见错误错误场景原因解决方案应用安装后桌面无图标skills未声明entity.system.home检查 abilities 中的 skills 配置权限弹窗未出现module.json5 中未声明权限在 requestPermissions 中添加对应权限Camera 功能崩溃权限申请了但未在代码中动态请求使用requestPermissionsFromUser动态申请模拟器上运行正常真机崩溃模拟器跳过了某些权限检查确保所有权限都已声明并动态申请七、动态权限申请代码7.1 在代码中动态请求权限仅在module.json5中声明权限还不够system_basic级别的权限必须在代码中再次动态申请// CapturePage.ets — 进入相机前检查并申请权限import{abilityAccessCtrl,Permissions}fromkit.AbilityKit;privateasynccheckAndRequestPermissions():Promiseboolean{constpermissions:Permissions[][ohos.permission.CAMERA,ohos.permission.READ_IMAGEVIDEO];constatManagerabilityAccessCtrl.createAtManager();// 检查权限状态constgrantStatusawaitatManager.checkAccessToken(this.context.tokenID,ohos.permission.CAMERA);if(grantStatusabilityAccessCtrl.GrantStatus.PERMISSION_GRANTED){returntrue;// 已有权限}// 请求权限constresultawaitatManager.requestPermissionsFromUser(this.context,permissions);returnresult.authResults[0]abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;}八、注意事项与常见问题8.1 开发注意事项在实际开发过程中需特别注意以下几点API 兼容性部分接口仅在特定 HarmonyOS NEXT 版本中可用需做版本条件判断权限模型采用静态声明module.json5 动态申请requestPermissionsFromUser的两阶段授权生命周期合理使用aboutToAppear()和aboutToDisappear()管理资源初始化与释放状态同步跨页面数据通过 AppStorage 共享组件内状态使用State/Prop/Link装饰器8.2 常见错误与解决方案常见问题快速排查表问题类型排查方向参考方法应用崩溃查看 hilog 错误日志hilog.error(TAG, ..., e.message)状态丢失检查 AppStorage 键名拼写统一使用常量管理键名动画不流畅避免在 animateTo 回调中执行 I/O动画与数据操作分离总结module.json5是鸿蒙应用模块的核心配置文件关键要点基础字段name、type、mainElement、deviceTypes是必须正确填写的基础配置abilities 配置每个 UIAbility 都需要在此声明桌面入口必须配置正确的skills权限声明所有需要的权限必须先在requestPermissions中静态声明再在代码中动态申请**p r o f i l e 引用 ∗ ∗ 通过 ‘ profile 引用**通过 profile引用∗∗通过‘profile:main_pages 引用页面路由配置实现配置与代码分离下一篇预告第04篇 oh-package.json5 与依赖管理如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源module.json5 配置说明abilities 配置详解requestPermissions 说明权限申请开发指南第02篇 Stage模型第04篇 oh-package.json5第05篇 路由配置HarmonyOS 应用配置最佳实践
