在 HarmonyOS Stage 模型中module.json5是每个模块Module的核心配置文件。它定义了模块的基本信息、Ability 配置、页面路由、设备适配等关键信息。本篇将通过日记项目的module.json5文件逐字段解析其含义和最佳实践。完整配置文件{ module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [ phone, tablet ], 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: [ { entities: [ entity.system.home ], actions: [ action.system.home ] } ] } ] } }模块级配置详解name — 模块名称name: entry模块的唯一标识名称。在 HAPHarmonyOS Ability Package包中每个模块的name必须唯一。常见的命名有entry入口模块、feature特性模块等。type — 模块类型type: entry模块类型决定了模块在应用中的角色类型说明entry应用入口模块每个应用只有一个feature动态特性模块可按需加载shared共享库模块供其他模块引用日记应用使用entry类型作为应用的唯一入口。description — 模块描述description: $string:module_desc模块描述信息。这里使用了资源引用语法$string:module_desc实际内容定义在resources/base/element/string.json中{string:[{name:module_desc,value:diary module}]}为什么要用资源引用支持多语言国际化集中管理字符串便于维护符合 HarmonyOS 资源管理规范mainElement — 主入口元素mainElement: EntryAbility指定模块启动时的首个 Ability。当用户点击桌面图标时系统会启动这个 Ability。它必须与abilities数组中某个 Ability 的name一致。deviceTypes — 设备类型deviceTypes: [ phone, tablet ]声明模块支持的设备类型设备类型说明phone手机tablet平板tv智慧屏wearable智能穿戴car车机default通用设备日记应用支持手机和平板两种设备。deliveryWithInstall — 安装时交付deliveryWithInstall: true设置为true表示模块在应用安装时一并下载安装。对于entry类型模块必须为true。installationFree — 免安装installationFree: false是否支持免安装特性。false表示不支持。免安装允许应用在不安装的情况下使用适用于服务卡片等场景。pages — 页面路由配置pages: $profile:main_pages指向页面路由配置文件。资源引用$profile:main_pages对应resources/base/profile/main_pages.json{src:[pages/Index,pages/DiaryEdit,pages/DiaryDetail]}这里列出了应用中所有可通过router导航的页面路径。未在此声明的页面无法被路由访问。Ability 级配置详解name — Ability 名称name: EntryAbilityAbility 的唯一标识在模块内不能重复。与代码中的类名不需要一致但通常保持对应关系。srcEntry — 源码入口srcEntry: ./ets/entryability/EntryAbility.etsAbility 的源码路径相对于模块根目录。指向EntryAbility.ets文件其中定义了EntryAbility类。icon 与 labelicon: $media:app_icon, label: $string:EntryAbility_labeliconAbility 的图标显示在桌面和应用列表中labelAbility 的显示名称字符串资源引用对应资源定义// string.json{name:EntryAbility_label,value:每日日记}startWindowIcon 与 startWindowBackgroundstartWindowIcon: $media:app_icon, startWindowBackground: $color:start_window_background启动窗口闪屏的配置startWindowIcon启动时显示的图标startWindowBackground启动窗口背景色颜色资源定义在color.json中{name:start_window_background,value:#FFFFFF}exported — 是否可被外部调用exported: true设置为true表示该 Ability 可以被其他应用调用。对于入口 Ability通常需要设置为true以便系统能够启动它。skills — 意图过滤器skills: [ { entities: [ entity.system.home ], actions: [ action.system.home ] } ]skills定义了 Ability 能响应的意图Wantentities声明实体类型entity.system.home表示这是一个桌面入口actions声明动作类型action.system.home表示响应桌面启动这个配置让应用图标出现在桌面上。如果缺少skills配置应用将无法从桌面启动。配置资源引用体系HarmonyOS 的资源引用使用$前缀语法前缀资源类型文件位置示例$string:字符串resources/base/element/string.json$string:app_name$color:颜色resources/base/element/color.json$color:start_window_background$media:媒体resources/base/media/$media:app_icon$profile:配置resources/base/profile/$profile:main_pages日记项目的资源体系resources/base/ ├── element/ │ ├── color.json → 颜色资源8种颜色定义 │ └── string.json → 字符串资源3条字符串 └── profile/ └── main_pages.json → 页面路由配置color.json 定义的色彩体系{color:[{name:start_window_background,value:#FFFFFF},{name:primary_color,value:#FF6B6B},{name:bg_color,value:#F5F5F5},{name:card_bg_color,value:#FFFFFF},{name:text_primary,value:#333333},{name:text_secondary,value:#999999},{name:text_hint,value:#CCCCCC},{name:divider_color,value:#EEEEEE}]}实际代码中的资源使用虽然配置文件中使用了资源引用但在日记应用的 ArkTS 代码中颜色和文字大多使用了硬编码值// 硬编码方式当前项目使用Text(我的日记).fontSize(22).fontColor(#333)// 资源引用方式推荐Text($r(app.string.app_name)).fontSize(22).fontColor($r(app.color.text_primary))最佳实践建议在实际项目中应优先使用资源引用以便支持多语言和主题切换。小结module.json5是 HarmonyOS Stage 模型的核心配置文件它定义了模块基本信息名称、类型、设备适配Ability 配置入口、图标、名称、生命周期源码路径页面路由通过$profile:main_pages引用页面列表意图过滤通过skills声明可响应的启动意图资源体系通过$前缀引用字符串、颜色、媒体等资源理解module.json5是掌握 HarmonyOS 应用开发的基础每个字段的配置都直接影响应用的运行行为。
HarmonyOs应用《日记本》开发第3篇 - module.json5 模块配置详解
在 HarmonyOS Stage 模型中module.json5是每个模块Module的核心配置文件。它定义了模块的基本信息、Ability 配置、页面路由、设备适配等关键信息。本篇将通过日记项目的module.json5文件逐字段解析其含义和最佳实践。完整配置文件{ module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [ phone, tablet ], 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: [ { entities: [ entity.system.home ], actions: [ action.system.home ] } ] } ] } }模块级配置详解name — 模块名称name: entry模块的唯一标识名称。在 HAPHarmonyOS Ability Package包中每个模块的name必须唯一。常见的命名有entry入口模块、feature特性模块等。type — 模块类型type: entry模块类型决定了模块在应用中的角色类型说明entry应用入口模块每个应用只有一个feature动态特性模块可按需加载shared共享库模块供其他模块引用日记应用使用entry类型作为应用的唯一入口。description — 模块描述description: $string:module_desc模块描述信息。这里使用了资源引用语法$string:module_desc实际内容定义在resources/base/element/string.json中{string:[{name:module_desc,value:diary module}]}为什么要用资源引用支持多语言国际化集中管理字符串便于维护符合 HarmonyOS 资源管理规范mainElement — 主入口元素mainElement: EntryAbility指定模块启动时的首个 Ability。当用户点击桌面图标时系统会启动这个 Ability。它必须与abilities数组中某个 Ability 的name一致。deviceTypes — 设备类型deviceTypes: [ phone, tablet ]声明模块支持的设备类型设备类型说明phone手机tablet平板tv智慧屏wearable智能穿戴car车机default通用设备日记应用支持手机和平板两种设备。deliveryWithInstall — 安装时交付deliveryWithInstall: true设置为true表示模块在应用安装时一并下载安装。对于entry类型模块必须为true。installationFree — 免安装installationFree: false是否支持免安装特性。false表示不支持。免安装允许应用在不安装的情况下使用适用于服务卡片等场景。pages — 页面路由配置pages: $profile:main_pages指向页面路由配置文件。资源引用$profile:main_pages对应resources/base/profile/main_pages.json{src:[pages/Index,pages/DiaryEdit,pages/DiaryDetail]}这里列出了应用中所有可通过router导航的页面路径。未在此声明的页面无法被路由访问。Ability 级配置详解name — Ability 名称name: EntryAbilityAbility 的唯一标识在模块内不能重复。与代码中的类名不需要一致但通常保持对应关系。srcEntry — 源码入口srcEntry: ./ets/entryability/EntryAbility.etsAbility 的源码路径相对于模块根目录。指向EntryAbility.ets文件其中定义了EntryAbility类。icon 与 labelicon: $media:app_icon, label: $string:EntryAbility_labeliconAbility 的图标显示在桌面和应用列表中labelAbility 的显示名称字符串资源引用对应资源定义// string.json{name:EntryAbility_label,value:每日日记}startWindowIcon 与 startWindowBackgroundstartWindowIcon: $media:app_icon, startWindowBackground: $color:start_window_background启动窗口闪屏的配置startWindowIcon启动时显示的图标startWindowBackground启动窗口背景色颜色资源定义在color.json中{name:start_window_background,value:#FFFFFF}exported — 是否可被外部调用exported: true设置为true表示该 Ability 可以被其他应用调用。对于入口 Ability通常需要设置为true以便系统能够启动它。skills — 意图过滤器skills: [ { entities: [ entity.system.home ], actions: [ action.system.home ] } ]skills定义了 Ability 能响应的意图Wantentities声明实体类型entity.system.home表示这是一个桌面入口actions声明动作类型action.system.home表示响应桌面启动这个配置让应用图标出现在桌面上。如果缺少skills配置应用将无法从桌面启动。配置资源引用体系HarmonyOS 的资源引用使用$前缀语法前缀资源类型文件位置示例$string:字符串resources/base/element/string.json$string:app_name$color:颜色resources/base/element/color.json$color:start_window_background$media:媒体resources/base/media/$media:app_icon$profile:配置resources/base/profile/$profile:main_pages日记项目的资源体系resources/base/ ├── element/ │ ├── color.json → 颜色资源8种颜色定义 │ └── string.json → 字符串资源3条字符串 └── profile/ └── main_pages.json → 页面路由配置color.json 定义的色彩体系{color:[{name:start_window_background,value:#FFFFFF},{name:primary_color,value:#FF6B6B},{name:bg_color,value:#F5F5F5},{name:card_bg_color,value:#FFFFFF},{name:text_primary,value:#333333},{name:text_secondary,value:#999999},{name:text_hint,value:#CCCCCC},{name:divider_color,value:#EEEEEE}]}实际代码中的资源使用虽然配置文件中使用了资源引用但在日记应用的 ArkTS 代码中颜色和文字大多使用了硬编码值// 硬编码方式当前项目使用Text(我的日记).fontSize(22).fontColor(#333)// 资源引用方式推荐Text($r(app.string.app_name)).fontSize(22).fontColor($r(app.color.text_primary))最佳实践建议在实际项目中应优先使用资源引用以便支持多语言和主题切换。小结module.json5是 HarmonyOS Stage 模型的核心配置文件它定义了模块基本信息名称、类型、设备适配Ability 配置入口、图标、名称、生命周期源码路径页面路由通过$profile:main_pages引用页面列表意图过滤通过skills声明可响应的启动意图资源体系通过$前缀引用字符串、颜色、媒体等资源理解module.json5是掌握 HarmonyOS 应用开发的基础每个字段的配置都直接影响应用的运行行为。
