HarmonyOS之module.json5功能详解

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

一、🧩 模块基本信息

json 复制代码

{
  "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）。

二、📱 设备适配与分发

json 复制代码

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

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

三、🎨 UIAbility 配置

json 复制代码

{
  "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 配置

json 复制代码

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

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

五、🛡️ 权限与安全

json 复制代码

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

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

六、⚡ 性能优化

json 复制代码

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

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

七、🌍 云端分发策略

json 复制代码

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

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

八、🖼️ 页面与窗口配置

json 复制代码

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

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

main_pages.json 示例 ：

json 复制代码

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

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

json 复制代码

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

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

menu.json 示例 ：

json 复制代码

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

✅ 总结

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