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

HarmonyOS应用模块配置详解：从入门到精通

news 2026/6/28 15:32:56

HarmonyOS应用模块配置详解：从入门到精通

【免费下载链接】harmony-utilsharmony-utils 一款功能丰富且极易上手的HarmonyOS工具库，借助众多实用工具类，致力于助力开发者迅速构建鸿蒙应用。其封装的工具涵盖了APP、设备、屏幕、授权、通知、线程间通信、弹框、吐司、生物认证、用户首选项、拍照、相册、扫码、文件、日志，异常捕获、字符、字符串、数字、集合、日期、随机、base64、加密、解密、JSON等一系列的功能和操作，能够满足各种不同的开发需求。项目地址: https://gitcode.com/tongzhanglao/harmony-utils

HarmonyOS应用开发中，module.json5配置文件是每个应用模块的核心身份证明。它定义了模块的基本信息、能力声明、权限请求等关键配置，掌握其配置技巧对应用开发至关重要。

什么是module.json5？

module.json5是HarmonyOS应用开发中的核心配置文件，它采用JSON5格式，相比传统JSON支持更灵活的语法，包括注释、尾随逗号等特性。每个应用模块都必须包含这个配置文件，它告诉系统这个模块是谁、能做什么、需要什么权限。

模块配置基础结构

每个module.json5文件都遵循相同的结构模式：

{ "module": { "name": "entry", "type": "entry", "deviceTypes": ["phone", "tablet", "2in1"], "abilities": [/* 能力定义数组 */], "requestPermissions": [/* 权限申请数组 */] } }

核心配置项详解

模块基本信息配置

配置项	类型	必填	说明	示例值
name	string	是	模块名称，需唯一	"entry"
type	string	是	模块类型	"entry", "har", "feature"
description	string	否	模块描述	"$string:module_desc"
deviceTypes	array	是	支持的设备类型	["phone", "tablet", "2in1"]

入口模块特殊配置

对于entry类型的模块，需要配置以下关键信息：

{ "module": { "name": "entry", "type": "entry", "srcEntry": "./ets/abilitystage/MyAbilityStage.ets", "mainElement": "EntryAbility", "pages": "$profile:main_pages", "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "description": "$string:EntryAbility_desc", "icon": "$media:ic_launcher", "label": "$string:EntryAbility_label", "exported": true, "skills": [ { "entities": ["entity.system.home"], "actions": ["action.system.home"] } ] } ] } }

Ability能力配置详解

Ability是HarmonyOS应用的核心组件，负责应用的界面展示和业务逻辑处理。

EntryAbility配置示例

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; import { AppUtil } from '@pura/harmony-utils'; import { DialogHelper } from '@pura/harmony-dialog'; import { ArkWebHelper } from '@pura/harmony-web'; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { AppUtil.init(this.context); ArkWebHelper.init(this.context, true); DialogHelper.setDefaultConfig((config) => { config.uiAbilityContext = this.context; config.autoCancel = false; config.backCancel = false; config.actionCancel = true; config.alignment = DialogAlignment.Center; }); } }

Ability生命周期配置

onCreate: Ability创建时调用
onWindowStageCreate: 窗口创建时调用
onForeground: Ability切换到前台时调用
onBackground: Ability切换到后台时调用
onDestroy: Ability销毁时调用

权限申请配置最佳实践

权限申请是应用开发中的重要环节，合理的权限配置能提高应用通过率。

网络权限配置

"requestPermissions": [ { "name": "ohos.permission.INTERNET" }, { "name": "ohos.permission.GET_NETWORK_INFO", "reason": "$string:permission_GET_NETWORK_INFO", "usedScene": { "abilities": ["EntryAbility"] } } ]

常用权限分类表

权限类别	权限名称	说明
网络权限	ohos.permission.INTERNET	允许应用访问网络
设备权限	ohos.permission.CAMERA	使用摄像头
存储权限	ohos.permission.READ_IMAGEVIDEO	读取图片视频
位置权限	ohos.permission.LOCATION	获取位置信息
生物识别	ohos.permission.ACCESS_BIOMETRIC	生物特征识别

权限申请注意事项

按需申请: 只申请应用真正需要的权限
明确用途: 提供清晰的权限使用场景说明
合理说明: 给出用户能够理解的原因描述

设备类型适配策略

HarmonyOS支持多种设备类型，合理的设备适配能扩大应用覆盖范围。

多设备支持配置

"deviceTypes": [ "phone", // 手机 "tablet", // 平板 "2in1", // 二合一设备 ]

设备适配最佳实践

渐进式适配: 先支持phone，再扩展其他设备
资源分离: 为不同设备提供不同的资源文件
能力检测: 运行时检查设备能力，动态调整功能

模块类型详解

1. Entry模块（入口模块）

Entry模块是应用的入口点，包含主Ability和启动配置。

2. HAR模块（静态共享包）

HAR模块适合封装工具类、组件库等可复用代码。

{ "module": { "name": "harmony_utils", "type": "har", "deviceTypes": ["default", "tablet", "2in1"], "requestPermissions": [] } }

HAR模块特点：

代码共享，减少重复开发
编译时依赖，性能更优
适合工具类、组件库封装

3. Feature模块（动态特性模块）

{ "module": { "name": "premium_features", "type": "feature", "deviceTypes": ["phone"], "deliveryWithInstall": false, "installationFree": true } }

页面路由配置

页面路由配置定义了应用的页面结构和导航关系。

主页面配置

@Entry @Component struct Index { private tabsController: TabsController = new TabsController(); @State index: number = 0; build() { Tabs({ barPosition: BarPosition.End, index: this.index, controller: this.tabsController }) { TabContent() { UtilsPage() } .tabBar(this.tabBuilder(0, $r('app.media.icon_tab_utils'), "工具")) } }