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.json5
1.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 顶层字段速查
| 字段 | 值 | 说明 |
|---|---|---|
name |
entry |
模块名称，HAP 包名的一部分 |
type |
entry |
模块类型：entry/feature/har/hsp |
deviceTypes |
["tablet","phone","wearable"] |
支持的设备类型 |
deliveryWithInstall |
true |
是否随应用安装下发 |
installationFree |
false |
是否支持免安装 |
pages |
$profile:main_pages |
页面路由配置引用 |
二、module.type 模块类型
2.1 四种模块类型
| 类型 | 说明 | 典型场景 |
|---|---|---|
entry |
应用主模块，一个应用只能有一个 | 猫猫大作战的主 HAP |
feature |
应用的特性模块，可有多个 | 排行榜独立模块、设置模块 |
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/multiton |
3.2 exported 的作用
{
"abilities": [
{
"name": "EntryAbility",
"exported": true, // 允许 Launcher 启动
"skills": [
{ "actions": ["action.system.home"] }
]
}
]
}
| exported | 外部能否启动 | 使用场景 |
|---|---|---|
true |
✅ 可以 | 入口 Ability、分享目标、DeepLink |
false |
❌ 不可以 | 内部页面、仅应用内部跳转 |
3.3 skills 意图过滤
{
"skills": [
{
"actions": ["action.system.home"], // 桌面图标入口
"entities": ["entity.system.home"],
"uris": [] // 可处理的 URI
}
]
}
| skills 字段 | 说明 | 值示例 |
|---|---|---|
actions |
Ability 能响应的操作 | 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.json |
"pages/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.home：
"skills": [
{
"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.json5 |
AppScope/ | 整个应用 | bundleName、versionCode、全局图标/标签 |
module.json5 |
entry/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"
}
}
| 字段 | 值 | 说明 |
|---|---|---|
bundleName |
com.maomaodazuozhan.game |
应用的唯一标识 |
vendor |
maomaodazuozhan |
开发者/组织名称 |
versionCode |
1000000 |
版本号（仅比较大小） |
versionName |
1.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/hsp） -
deviceTypes包含目标设备 -
abilities[].srcEntry路径正确（./ets/...） -
abilities[].exported按需设置 - entry 模块的 EntryAbility 配置了
skills+action.system.home -
pages引用正确的 profile 文件 -
$string/$media/$color资源都已在相应目录存在
九、总结
module.json5 是 HarmonyOS 模块的"身份证"，定义了模块是什么类型、在哪些设备上运行、包含哪些 Ability、如何响应系统意图。理解其配置规则是正确构建和发布应用的基础。
核心要点：
type: entry是主模块，feature是特性模块，一个应用只有一个 entrydeviceTypes限制了应用安装的目标设备abilities[]注册所有 Ability，exported控制能否被外部启动skills中的action.system.home是桌面图标入口的必须配置srcEntry路径相对于src/main/，需加上./ets/前缀$profile:main_pages引用路由配置，$string/$media引用资源
下一篇预告：第 77 篇将深入 app.json5 全局配置——bundleName、版本管理、图标标签与签名配置。
如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！
相关资源：
讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。
更多推荐
6
0- 0
已为社区贡献72条内容
所有评论(0)