当前位置：首页 > news >正文

HarmonyOS之module.json5功能详解

news 2025/8/11 7:18:21

module.json5 是 HarmonyOS 应用的模块级配置文件，用于定义模块的基本信息、设备适配规则、UIAbility/ExtensionAbility 配置、权限管理及性能优化策略。以下是其核心功能的模块化分类与配置说明。

一、🧩 模块基本信息

{"module": {"name": "entry","type": "entry","description": "$string:module_desc","mainElement": "EntryAbility"}
}

name: 模块唯一标识符（如 entry），需符合命名规则（字母、数字、下划线，最大31字节）。
type: 模块类型（entry/feature/har/shared）。entry 模块必须包含 mainElement 和 pages。
description: 模块描述信息，支持多语言资源索引（如 $string:module_desc）。
mainElement: 指定模块的入口组件（如 EntryAbility）。

二、📱 设备适配与分发

{"module": {"deviceTypes": ["phone", "tablet"],"deliveryWithInstall": true,"installationFree": false}
}

deviceTypes: 支持的设备类型（如 phone、tablet），需覆盖目标设备，否则模块无法运行。
deliveryWithInstall: 是否随应用安装（true 随安装，false 动态下载）。
installationFree: 是否支持免安装（元服务必须设为 true）。

三、🎨 UIAbility 配置

{"abilities": [{"name": "EntryAbility","srcEntry": "./ets/entryability/EntryAbility.ts","launchType": "singleton","skills": [{"actions": ["ohos.want.action.home"],"entities": ["entity.system.home"]}]}]
}

name: UIAbility 唯一名称（如 EntryAbility）。
srcEntry: 入口代码路径（如 ./ets/entryability/EntryAbility.ts）。
launchType: 启动模式（singleton/multiton/standard）。
skills: 定义能接收的 Want 特征（Action、Entity、URI）。

四、🔧 ExtensionAbility 配置

{"extensionAbilities": [{"name": "FormAbility","srcEntry": "./form/FormAbility.ts","type": "form","metadata": [{"name": "ohos.extension.form","resource": "$profile:form_config"}]}]
}

type: ExtensionAbility 类型（如 form、workScheduler）。
metadata: 自定义元信息（如服务卡片配置）。

五、🛡️ 权限与安全

{"requestPermissions": [{"name": "ohos.permission.CAMERA","reason": "$string:camera_permission_reason","usedScene": {"abilities": ["EntryAbility"],"when": "inuse"}}]
}

requestPermissions: 声明运行时权限及使用场景（如 CAMERA）。

六、⚡ 性能优化

{"isolationMode": "nonisolationFirst","compressNativeLibs": false,"extractNativeLibs": true
}

isolationMode: 多进程运行模式（如 nonisolationFirst）。
compressNativeLibs: 是否压缩 Native 库（false 表示不压缩）。
extractNativeLibs: 安装时是否解压 Native 库（true 表示解压）。

七、🌍 云端分发策略

{"distributionFilter": {"screenDensity": {"policy": "exclude","value": ["ldpi", "xldpi"]},"countryCode": {"policy": "include","value": ["CN"]}}
}

screenDensity: 按屏幕密度过滤分发（如排除 ldpi）。
countryCode: 按国家地区分发（如仅在中国分发）。

八、🖼️ 页面与窗口配置

{"pages": "$profile:main_pages"
}

pages: 引用页面路由配置文件（如 main_pages.json）。

main_pages.json 示例：

{"src": ["pages/index/mainPage","pages/second/payment"],"window": {"designWidth": 720,"autoDesignWidth": false}
}

九、📋 快捷方式与右键菜单

{"fileContextMenu": "$profile:menu"
}

fileContextMenu: PC/2in1 设备的右键菜单配置（引用 menu.json）。

menu.json 示例：

{"fileContextMenu": [{"abilityName": "EntryAbility","menuItem": "$string:open_with_app","menuHandler": "openFile"}]
}

✅ 总结

功能模块	关键配置项	作用
🧩 模块基本信息	`name`、`type`	标识模块唯一性及类型。
📱 设备适配	`deviceTypes`	确保模块在目标设备上运行。
🛡️ 权限管理	`requestPermissions`	声明运行时权限及使用场景。
🖼️ 页面配置	`pages`	定义页面路由及窗口设计基准。
🌍 云端分发	`distributionFilter`	按设备特性精准分发。
⚡ 性能优化	`isolationMode`	控制多进程行为，提升性能。