鸿蒙工程讲解

工程目录结构（Stage模型）

目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
├── AppScope > app.json5：应用的全局配置信息，详见app.json5配置文件。
├── entry：HarmonyOS工程模块，编译构建生成一个HAP包。（默认项目入口模块）
    ├── src > main > ets：用于存放ArkTS源码。
    ├── src > main > ets > entryability：应用/服务的入口。
    ├── src > main > ets > entrybackupability：应用提供扩展的备份恢复能力。
    ├── src > main > ets > pages：应用/服务包含的页面。
    
    ├── src > main > resources：用于存放应用/服务所用到的资源文件，如图形、多媒体、字符串、布局文件等。关于资源文件，详见资源分类与访问。
    ├── src > main > module.json5：模块配置文件。主要包含HAP包的配置信息、应用/服务在具体设备上的配置信息以及应用/服务的全局配置信息。具体的配置文件说明，详见module.json5配置文件。
    ├── build-profile.json5：当前的模块信息 、编译信息配置项，包括buildOption、targets配置等。
    ├── hvigorfile.ts：模块级编译构建任务脚本。
    ├── obfuscation-rules.txt：混淆规则文件。混淆开启后，在使用Release模式进行编译时，会对代码进行编译、混淆及压缩处理，保护代码资产。详见开启代码混淆。
    ├── oh-package.json5：用来描述包名、版本、入口文件（类型声明文件）和依赖项等信息。
├── oh_modules：用于存放三方库依赖信息。
├── build-profile.json5：工程级配置信息，包括签名signingConfigs、产品配置products等。其中products中可配置当前运行环境，默认为HarmonyOS。
├── hvigorfile.ts：工程级编译构建任务脚本。
├── oh-package.json5：主要用来描述全局配置，如：依赖覆盖（overrides）、依赖关系重写（overrideDependencyMap）和参数化配置（parameterFile）等

应用程序包

用户应用程序是指运行在设备操作系统之上，为用户提供特定服务的程序，简称“应用”。一个应用所对应的软件包文件，称为“应用程序包”。

多Module设计机制

  • 支持模块化开发： 一个应用通常包含多种功能，将不同的功能特性按模块来划分和管理是一种良好的设计方式。在开发过程中，开发者可以将每个功能模块作为一个独立的Module进行开发，Module中可以包含源代码、资源文件、第三方库、配置文件等，每一个Module可以独立编译，实现特定的功能。这种模块化、松耦合的应用管理方式有利于应用的开发、维护与扩展。
  • 支持多设备适配： 一个应用往往需要适配多种设备类型，在采用多Module设计的应用中，每个Module都会标注所支持的设备类型。Module支持的设备类型不同，有的支持全部类型，有的仅支持特定类型（例如平板）。在应用市场分发应用包时，可以根据设备类型进行精准筛选和匹配，从而合理组合和部署不同的包到对应的设备上。

Module类型

Module按照使用场景可以分为两种类型：

  • Ability类型的Module： 用于实现应用的功能和特性。每一个Ability类型的Module编译后，会生成一个以.hap为后缀的文件，称为HAP（Harmony Ability Package）包。HAP包可以独立安装和运行，是应用安装的基本单位，一个应用可以包含一个或多个HAP包，包含的HAP包分为以下两种类型。

    • entry类型的Module：应用的主模块，包含应用的入口界面、入口图标和主功能特性，编译后生成entry类型的HAP。每一个应用分发到同一类型的设备上的应用程序包，只能包含唯一一个entry类型的HAP，也可以不包含。
    • feature类型的Module：应用的动态特性模块，编译后生成feature类型的HAP。一个应用中可以包含一个或多个feature类型的HAP，也可以不包含。

  • Library类型的Module： 用于实现代码和资源的共享。同一个Library类型的Module可以被其他的Module多次引用，合理地使用该类型的Module，能够降低开发和维护成本。Library类型的Module分为Static和Shared两种类型，编译后生成共享包。

  • Library类型的Module

  • Static Library：静态共享库。编译后生成一个以.har为后缀的文件，即静态共享包HAR（Harmony Archive）。 注意：编译HAR时，建议开启混淆能力，保护代码资产。

  • Shared Library：动态共享库。编译后生成一个以.hsp为后缀的文件，即动态共享包HSP（Harmony Shared Package）。

说明

实际上，Shared Library编译后除了会生成一个.hsp文件，还会生成一个.har文件。这个.har文件中包含了HSP对外导出的接口，应用中的其他模块需要通过.har文件来引用HSP的功能。为了表述方便，通常认为编译Shared Library后会生成HSP。

Stage模型应用程序包结构

开发态包结构

工程结构主要包含的文件类型及用途如下(ModuleName指的是entry这类文件夹)：

  • 配置文件：包括应用级配置信息、以及Module级配置信息
    • AppScope > app.json5：app.json5配置文件，用于声明应用的全局配置信息，比如应用Bundle名称、应用名称、应用图标、应用版本号等。
    • ModuleName > src > main > module.json5：module.json5配置文件，用于声明Module基本信息、支持的设备类型、所含的组件信息、运行所需申请的权限等。
  • ArkTS源码文件
    • ModuleName > src > main > ets：用于存放Module的ArkTS源码文件（.ets文件）。
  • 资源文件：包括应用级资源文件、以及Module级资源文件，支持图形、多媒体、字符串、布局文件等，详见资源分类与访问
    • AppScope > resources ：用于存放应用需要用到的资源文件。
    • ModuleName > src > main > resources ：用于存放该Module需要用到的资源文件。
  • 其他配置文件：用于编译构建，包括构建配置文件、编译构建任务脚本、混淆规则文件、依赖的共享包信息等
    • build-profile.json5：工程级或Module级的构建配置文件，包括应用签名、产品配置等。
    • hvigorfile.ts：工程级或Module级的编译构建任务脚本，开发者可以自定义编译构建工具版本、控制构建行为的配置参数。
    • obfuscation-rules.txt：混淆规则文件。混淆开启后，在使用Release模式进行编译时，会对代码进行编译、混淆及压缩处理，保护代码资产。
    • oh-package.json5：用于存放依赖库的信息，包括所依赖的三方库和共享包。

编译态包结构

不同类型的Module编译后会生成对应的HAP、HAR、HSP等文件，开发态视图与编译态视图的对照关系如下
开发态与编译态的工程结构视图

HAP开发

HAP（Harmony Ability Package）是应用安装和运行的基本单元。HAP包是由代码、资源、第三方库、配置文件等打包生成的模块包

分类

  • entry类型的HAP：应用的主模块，包含应用的入口界面、入口图标和主功能特性，编译后生成entry类型的HAP。每一个应用分发到同一类型的设备上的应用程序包，只能包含唯一一个entry类型的HAP，也可以不包含。
  • feature类型的HAP：应用的动态特性模块，编译后生成feature类型的HAP。一个应用中可以包含一个或多个feature类型的HAP，也可以不包含。

约束限制

  • 不支持导出接口和ArkUI组件，给其他模块使用。
  • 多HAP场景下，App Pack包中同一设备类型的所有HAP中最多只能包含一个Entry类型的HAP，也可以不包含；Feature类型的HAP可以包含一个或者多个，也可以不包含。
  • 多HAP场景下，同一应用中的所有HAP的配置文件中的bundleName、versionCode、versionName、minCompatibleVersionCode、debug、minAPIVersion、targetAPIVersion、apiReleaseType相同，同一设备类型的所有HAP对应的moduleName标签必须唯一。HAP打包生成App Pack包时，会对上述参数配置进行校验。
  • 多HAP场景下，同一应用的所有HAP、HSP的签名证书要保持一致。上架应用市场是以App Pack形式上架，应用市场分发时会将所有HAP从App Pack中拆分出来，同时对所有HAP进行重签名，以保证签名证书的一致性。在调试阶段，开发者通过命令行或DevEco Studio将HAP安装到设备上时，要保证所有HAP签名证书一致，否则会出现安装失败的问题，签名操作请参考应用/元服务签名。

HAR开发

HAR（Harmony Archive）是静态共享包，可以包含代码、C++库、资源和配置文件。通过HAR可以实现多个模块或多个工程共享ArkUI组件、资源等相关代码。

约束限制

  • HAR不支持在设备上单独安装或运行，只能作为应用模块的依赖项被引用。
  • HAR不支持在配置文件中声明ExtensionAbility组件。从API version 14开始，支持在配置文件中声明UIAbility组件，配置UIAbility的方法参考在模块中添加Ability，拉起HAR中UIAbility的方式与启动应用内的UIAbility方法相同。
1
2
说明
如果使用startAbility接口拉起HAR中的UIAbility，接口参数中的moduleName取值需要为依赖该HAR的HAP/HSP的moduleName。
  • HAR不支持在配置文件中声明pages页面，但是可以包含pages页面，并通过Navigation跳转的方式进行跳转。
  • HAR不支持引用AppScope目录中的资源。在编译构建时，AppScope中的内容不会打包到HAR中，因此会导致HAR资源引用失败。
  • 由于HSP仅支持应用内共享，如果HAR依赖了HSP，则该HAR文件仅支持应用内共享，不支持发布到二方仓或三方仓供其他应用使用，否则会导致编译失败。
  • 多包（HAP/HSP）引用相同的HAR时，会造成多包间代码和资源的重复拷贝，从而导致应用包变大。
  • HAR可以依赖其他HAR或者HSP，但不支持循环依赖，也不支持依赖传递。
  • HAP引用HAR时，在编译构建过程中系统会自动合并两者的权限配置。因此开发者无需在HAP和HAR中重复申请相同权限。
1
2
3
说明
循环依赖：例如有三个HAR，HAR-A、HAR-B和HAR-C，循环依赖指HAR-A依赖HAR-B，HAR-B依赖HAR-C，HAR-C又依赖HAR-A。
依赖传递：例如有三个HAR，HAR-A、HAR-B和HAR-C，依赖关系是HAR-A依赖HAR-B，HAR-B依赖HAR-C。不支持传递依赖指HAR-A可以使用HAR-B的方法和组件，但是HAR-A不能直接使用HAR-C的方法和组件。
APP开发 > 工程
鸿蒙工程讲解
http://example.com/2025/08/21/25_08_21鸿蒙工程讲解/
作者
ZF ZHAO
发布于
2025年8月21日
许可协议