HarmonyOS应用开发实战：猫猫大作战-Ability 注册规则、skills 意图过滤、deviceTypes 多设备适配，以及与 app.json

前言在 HarmonyOS 应用中module.json5是每个模块下必不可少的配置文件——它定义了模块的名称、类型、支持的设备、Ability 注册、页面路径、权限声明等关键信息。不理解这个文件就无法理解应用是如何被系统识别和启动的。本文以「猫猫大作战」的entry/src/main/module.json5为锚点逐字段拆解其含义深入讲解 Ability 注册规则、skills 意图过滤、deviceTypes 多设备适配以及与 app.json5 的协作关系。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1–75 篇。本篇是阶段三第 76 篇。一、项目中的 module.json51.1 完整配置{ module: { name: entry, type: entry, deviceTypes: [ tablet, phone, wearable ], deliveryWithInstall: true, installationFree: false, pages: $profile:main_pages, abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, description: $string:EntryAbility_desc, icon: $media:app_icon, label: $string:EntryAbility_label, startWindowIcon: $media:app_icon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { actions: [ action.system.home ] } ] } ] } }1.2 顶层字段速查字段值说明nameentry模块名称HAP 包名的一部分typeentry模块类型entry/feature/har/hspdeviceTypes[tablet,phone,wearable]支持的设备类型deliveryWithInstalltrue是否随应用安装下发installationFreefalse是否支持免安装pages$profile:main_pages页面路由配置引用二、module.type 模块类型2.1 四种模块类型类型说明典型场景entry应用主模块一个应用只能有一个猫猫大作战的主 HAPfeature应用的特性模块可有多个排行榜独立模块、设置模块har静态共享库公共 UI 组件库hsp动态共享库按需下载的功能包2.2 猫猫大作战的多模块设想[ { module: { name: entry, type: entry } // 主游戏模块 }, { module: { name: ranking_feature, type: feature, deviceTypes: [tablet, phone], abilities: [ { name: RankingAbility, srcEntry: ./ets/rankingability/RankingAbility.ets } ] } // 排行榜独立 feature 模块 } ]三、abilities 注册详解3.1 Ability 配置字段字段必填说明name✅Ability 名称系统通过此名称识别srcEntry✅Ability 源码路径相对 entry/src/main/description❌描述引用$string资源icon❌图标引用$media资源label❌标签/名称引用$string资源startWindowIcon❌启动窗口图标startWindowBackground❌启动窗口背景色exported❌是否允许其他应用启动skills❌意图过滤器标记 Ability 能响应的操作launchType❌启动模式singleton/standard/multiton3.2 exported 的作用{ abilities: [ { name: EntryAbility, exported: true, // 允许 Launcher 启动 skills: [ { actions: [action.system.home] } ] } ] }exported外部能否启动使用场景true✅ 可以入口 Ability、分享目标、DeepLinkfalse❌ 不可以内部页面、仅应用内部跳转3.3 skills 意图过滤{ skills: [ { actions: [action.system.home], // 桌面图标入口 entities: [entity.system.home], uris: [] // 可处理的 URI } ] }skills 字段说明值示例actionsAbility 能响应的操作action.system.home桌面启动entities意图类别entity.system.home主屏幕uris能处理的 URI 模式[{ scheme: catscheme, host: ranking }]多 skills 示例{ abilities: [ { name: EntryAbility, exported: true, skills: [ { // 桌面图标启动 actions: [action.system.home], entities: [entity.system.home] }, { // DeepLink 深度链接启动 actions: [action.system.view], uris: [ { scheme: catscheme, host: ranking, pathPrefix: /player } ] } ] } ] }四、deviceTypes 多设备适配4.1 猫猫大作战支持的设备{ deviceTypes: [ tablet, phone, wearable ] }4.2 设备类型枚举设备类型说明适配要点phone手机默认竖屏、触摸操作tablet平板分栏布局、更宽可视区wearable手表极小屏、简化交互tv电视遥控器操作、远距离car车机驾驶安全限制、语音优先2in1二合一设备键鼠触摸双模式4.3 多设备配置示例{ deviceTypes: [phone, tablet], abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets } ] }当应用在平板上安装时如果deviceTypes没有包含tablet应用将无法在平板上搜索或安装。五、pages 页面路由配置{ pages: $profile:main_pages }$profile:main_pages指向resources/base/profile/main_pages.json{ src: [ pages/Index ] }配置含义$profile:main_pages引用resources/base/profile/main_pages.jsonpages/Index页面路径相对于ets/目录多个页面[pages/Index, pages/Detail, pages/Settings]注意pages字段也可以直接写成pages: [pages/Index]但不推荐——使用$profile引用更方便管理和扩展。六、常见踩坑6.1 坑一srcEntry 路径错误// 错误srcEntry 路径不对 { srcEntry: entryability/EntryAbility.ets // ❌ 缺少 ./ets/ } // ✅ 正确 { srcEntry: ./ets/entryability/EntryAbility.ets }srcEntry路径从src/main/开始计算所以./ets/entryability/EntryAbility.ets对应实际目录src/main/ets/entryability/EntryAbility.ets。6.2 坑二忘记配置 skills// 缺少 skills → Launcher 找不到入口 { abilities: [ { name: EntryAbility, exported: true // ❌ 没有 skills桌面没有图标 } ] }表现应用安装成功但桌面上找不到图标。解决必须添加skills并设置action.system.homeskills: [ { actions: [action.system.home], entities: [entity.system.home] } ]6.3 坑三module.json5 位置错误// ✅ 正确位置 entry/src/main/module.json5 // 错误位置 entry/module.json5 AppScope/module.json5七、module.json5 与 app.json5 的协作7.1 职责分离文件位置作用域主要配置app.json5AppScope/整个应用bundleName、versionCode、全局图标/标签module.json5entry/src/main/单个模块模块类型、Ability 注册、设备类型7.2 app.json5 配置{ app: { bundleName: com.maomaodazuozhan.game, vendor: maomaodazuozhan, versionCode: 1000000, versionName: 1.0.0, icon: $media:app_icon, label: $string:app_name, description: $string:app_desc } }字段值说明bundleNamecom.maomaodazuozhan.game应用的唯一标识vendormaomaodazuozhan开发者/组织名称versionCode1000000版本号仅比较大小versionName1.0.0展示给用户的版本7.3 $引用资源规则// $string:xxx → 引用 resources/base/element/string.json 中的字符串 // $media:xxx → 引用 resources/base/media/ 中的媒体文件 // $color:xxx → 引用 resources/base/element/color.json 中的颜色值 // $profile:xxx → 引用 resources/base/profile/ 中的 JSON 文件八、module.json5 配置检查清单name与模块目录名一致type正确entry/feature/har/hspdeviceTypes包含目标设备abilities[].srcEntry路径正确./ets/...abilities[].exported按需设置entry 模块的 EntryAbility 配置了skillsaction.system.homepages引用正确的 profile 文件$string/$media/$color资源都已在相应目录存在九、总结module.json5是 HarmonyOS 模块的“身份证“定义了模块是什么类型、在哪些设备上运行、包含哪些 Ability、如何响应系统意图。理解其配置规则是正确构建和发布应用的基础。核心要点type: entry是主模块feature是特性模块一个应用只有一个 entrydeviceTypes限制了应用安装的目标设备abilities[]注册所有 Abilityexported控制能否被外部启动skills中的action.system.home是桌面图标入口的必须配置srcEntry路径相对于src/main/需加上./ets/前缀$profile:main_pages引用路由配置$string/$media引用资源下一篇预告第 77 篇将深入app.json5全局配置——bundleName、版本管理、图标标签与签名配置。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源module.json5 配置文档Ability 配置与启动多设备类型开发指南应用包结构与配置skills 意图过滤器开源鸿蒙跨平台社区第 75 篇onForeground/onBackground第 77 篇app.json5 全局配置