OpenHarmony应用开发零基础入门 课件 第2章 OpenHarmony应用的工程结构

倪红军OpenHarmony应用开发

零基础入门第二章OpenHarmony应用的工程结构

2.1创建OpenHarmony工程

2.2OpenHarmony工程目录结构倪红军制作2.1创建OpenHarmony工程本节要点1.掌握创建OpenHarmony工程的步骤2.掌握在OpenHarmony工程中添加Module及在Module中添加Ability的方法3.掌握运行OpenHarmony项目的方法4.掌握OpenHarmony应用程序包的组成部分及每个组成部分的功能倪红军制作2.1.1第一个OpenHarmony工程1．创建OpenHarmony工程安装配置完DevEcoStudio开发环境，第一次启动DevEcoStudio时，会打开如右图所示的WelcometoDevEcoStudio欢迎页面。单击CreateProject（创建工程）选项，打开如下图所示的创建CreateProject对话框；或如果DevEcoStudio开发环境中已经打开了一个工程，在菜单栏依次选择“File→New→CreateProject”菜单命令后，也会打开下图所示的CreateProject对话框。倪红军制作2.1.1第一个OpenHarmony工程1．创建OpenHarmony工程在CreateProject对话框中，开发者需要首先选择工程类型（Application为应用开发，需要安装后才能访问；AtomicService为元服务开发，不需要安装就能访问），然后选择需要的Ability工程模板。选择了Application工程类型和EmptyAbility模板后，单击“Next”按钮，打开如右图所示的OpenHarmony工程配置信息对话框，在该对话框中配置完成工程信息后，单击“Finish”按钮，DevEcoStudio会自动生成示例代码和相关资源，直至OpenHarmony工程创建完成。倪红军制作2.1.1第一个OpenHarmony工程1．创建OpenHarmony工程（1）ProjectName：工程名称，可以由大小写字母、数字和下划线组成；（2）BundleName：包名，用于标识工程的唯一性，默认情况下应用ID也会使用该名称，应用发布时对应的ID需要保持一致；（3）Savelocation：工程本地存储路径，由大小写字母、数字和下划线等组成；（4）CompileSDK：应用/服务编译的API版本，在编译构建时，DevEcoStudio会根据指定的CompileAPI版本进行编译打包；API4~7和API8~9的构建工具和构建插件不同，API4~7构建体系是由Gradle构建工具和构建插件组成，API8~9构建体系是由Hvigor构建工具和构建插件组成。如果选择API9及以上版本，则没有Language选项；如果选择API8版本，则Language选项可以选择ArkTS或JS语言；如果选择API7及以下版本，则Language选项可以选择Java或JS语言。（5）CompatibleSDK：兼容的最低API版本。（6）Modulename：默认工程模块名称。（7）Model：应用支持的模式，包括Stage和FA两种；（8）EnableSuperVisual：支持低代码开发模式，部分模板支持低代码开发；（9）Devicetype：该工程支持的设备类型。倪红军制作2.1.1第一个OpenHarmony工程1．创建OpenHarmony工程从右图可以看出，当前创建的HelloWorld_ArkTS工程仅有一个页面，该页面对应的文件为Index.ets。如果需要为该工程中添加一个新页面，可以用鼠标右击图中pages文件夹，选择“New→Page”菜单命令，在NewPage对话框中输入新页面名称（例如，Home），单击“Finish”按钮后，就可以在pages文件夹下新建一个页面文件（例如，Home.ets）。OpenHarmony工程创建完成后，打开entry/build-profile.json5文件，将targets中的runtimeOS字段值修改为“OpenHarmony”，然后点击右上角提示框的“SyncNow”命令重新同步工程环境后，就可以进行OpenHarmony应用开发。倪红军制作2.1.1第一个OpenHarmony工程2．在工程中添加ModuleModule是应用/服务的基本功能单元，包含了源代码、资源文件、第三方库及应用/服务配置文件，每一个Module都可以独立进行编译和运行。一个应用/服务通常会包含一个或多个Module，也就是说在一个工程中可以创建多个Module，每个Module分为Ability和Library两种类型。在工程中添加Module的步骤如下所示。右击工程名称，在弹出的菜单栏依次选择“New→Module”菜单命令；或在DevEcoStudio窗口的菜单栏选择“File→New→Module”菜单命令，打开如右上图所示的NewProjectModule对话框。在NewProjectModule界面中，选择需要创建的模板，单击“Next”按钮，打开右下图所示的Module配置对话框，在Moduel配置对话框中配置。倪红军制作2.1.1第一个OpenHarmony工程3．在Module中添加AbilityAbility是应用/服务所具备的能力抽象，一个Module可以包含一个或多个Ability。选中需要添加Ability组件对应的Module，单击鼠标右键，在弹出的快捷菜单中选择依次选择“New→Ability”菜单命令。打开下图所示的NewAbility（ConfigureYourAbility）对话框，在该对话框中需要设置Ability名称（Abilityname）、选择编程语言（Language，默认为ArkTS），在完成设置后，单击“Finish”按钮后，就可在src/main/ets目录下创建以Ability名称命名的目录及ts文件。倪红军制作2.1.1第一个OpenHarmony工程4．运行OpenHarmony项目应用创建完成后，一般需要真机设备进行运行和调试，但实际开发中，也可以直接使用HarmonyOS的开发环境进行运行和调试。倪红军制作2.1.2OpenHarmony应用程序包应用程序泛指运行在操作系统之上，为用户提供特定服务的程序，通常简称为“应用”。一个应用所对应的软件包文件称为应用程序包。在开发态，一个应用包含一个或多个Module，Module是应用/服务的基本功能单元，包含了源代码、资源文件、第三方库及应用/服务的配置文件，每一个Module都可以独立进行编译和运行。Module分为Ability和Library两种类型。Ability类型的Module对应于编译后的HAP（HarmonyAbilityPackage）；Library类型的Module对应于HAR（HarmonyArchive）或者HSP（HarmonySharedPackage）。一个Module可以包含一个或多个UIAbility组件，App、Module、UIAbility及Page之间的关系如图所示。倪红军制作2.1.2OpenHarmony应用程序包开发者用DevEcoStudio集成开发环境把OpenHarmony应用编译为一个或者多个.hap后缀的文件，即HAP。HAP是应用安装的基本单位，包含了编译后的代码、资源、三方库及配置文件。HAP可分为Entry和Feature两种类型。（1）Entry类型的HAP：它是应用的主模块，在module.json5配置文件中的type标签配置为“entry”类型。在同一个应用中，同一设备类型只支持一个Entry类型的HAP，通常用于实现应用的入口界面、入口图标、主特性功能等。（2）Feature类型的HAP：它是应用的动态特性模块，在module.json5配置文件中的type标签配置为“feature”类型。一个应用程序包可以包含一个或多个Feature类型的HAP，也可以不包含；Feature类型的HAP通常用于实现应用的特性功能，可以配置成按需下载安装，也可以配置成随Entry类型的HAP一起下载安装（由module.json5配置文件中的deliveryWithInstall标签配置，true表示按需下载安装）。倪红军制作2.1.2OpenHarmony应用程序包每个应用可以包含多个.hap文件，一个应用中的.hap文件打包成一个.app文件（称为Bundle），由bundleName标识。需要特别说明的是：在应用上架到应用市场时，需要把应用包含的所有.hap文件（即Bundle）打包为一个.app后缀的文件用于上架，这个.app文件称为AppPack（ApplicationPackage）基于Stage模型开发的应用，经编译打包后，其应用程序包结构如图所示，打包后的HAP包结构包括ets、libs、resources等文件夹和resources.index、module.json、等文件，具体功能如下。倪红军制作2.1.2OpenHarmony应用程序包（1）ets目录：用于存放应用代码编译后的字节码文件。（2）libs目录：用于存放库文件。库文件是应用依赖的第三方代码（.so二进制文件）。（3）resources目录：用于存放应用的资源文件（字符串、图片等）。（4）resources.index：资源索引表文件，由IDE编译工程时生成。（5）module.json：HAP的配置文件，内容由工程配置中的module.json5和app.json5组成，该文件是HAP中必不可少的文件。IDE会自动生成一部分默认配置，开发者可以根据需要修改其中的配置。（6）：Bundle中用于描述每个HAP属性的文件。例如，app中的bundleName和versionCode信息、module中的name、type和abilities等信息，由IDE工具构建Bundle包时自动生成。倪红军制作2.2OpenHarmony工程目录结构本节要点1.掌握OpenHarmony工程的工程级目录结构内容2.掌握OpenHarmony工程的模块级目录结构内容3.掌握OpenHarmony工程中的资源分类与引用方法4.掌握ArkTS语言的基本结构倪红军制作2.2.1工程级目录结构1．.hvigor目录：用于存放工程项目的构建配置文件，由系统自动生成，一般情况下不需要修改。2．.idea目录：用于存放工程项目的配置信息。3．AppScope目录：用于存放工程项目全局的公共资源，该目录结构如下图所示。其中，resources目录用于存放工程项目所用到的图形、多媒体、字符串、布局文件等资源文件；app.json5文件是工程项目的全局配置文件，用于存放工程项目的全局配置信息，通常包含Bundle名称、开发厂商、版本号等基本信息及特定设备类型的配置信息，其关键代码及功能说明见下页。倪红军制作2.2.1工程级目录结构倪红军制作2.2.1工程级目录结构4．entry目录：模块级目录结构，用于存放应用模块的代码、资源等。5．hvigor目录：用于存放构建工程项目的配置文件信息，hvigor是一款基于TypeScript实现的前端构建任务编排工具。6．oh_modules目录：用于存放工程依赖的第三方库源文件。7．.gitignore：是Git版本管理需要忽略的文件。8．build-profile.json5：工程级配置文件，声明包括签名、产品配置等工程对应的编译构建参数，其关键代码及功能说明如下所示。倪红军制作2.2.1工程级目录结构9．hvigorfile.ts：工程级编译构建脚本。10．hvigorw和hvigorw.bat：ohpm编译构建工具。11．perties：用于存储本地属性的文件。12．oh-package.json5：工程级依赖配置文件，用于设置记录引入包的配置信息。倪红军制作2.2.2模块级目录结构entry是OpenHarmony工程项目的默认模块，编译构建生成一个HAP包。模块级目录结构如图所示，其包含的主要目录及文件的功能如下所示。1．build目录：由当前模块编译后自动生成，用于存放最终编译完成后的应用程序包，也就是HAP包。HAP包中包含了项目中用到的图片、代码及各种资源等。2．src/main/ets目录：用于存放ArkTS源代码。3．src/main/ets/entryability目录：用于存放模块的入口Ability文件，以便对当前Ability应用逻辑和生命周期进行管理。4．src/main/ets/pages目录：用于存放模块UI界面对应的页面文件，默认会自动生成1个以Index.ets命名的页面。5．src/main/resources目录：用于存放模块所用到的图形、多媒体、字符串、布局文件等资源文件。倪红军制作2.2.2模块级目录结构6．src/main/module.json5文件：模块配置文件，每一个模块都有1个module.json5。该文件用于存放对应Module的基本配置信息，主要包含Module名称、类型、描述信息、支持的设备类型等基本信息及应用组件信息、应用运行过程中所需的权限信息。其关键代码及功能说明如下所示。倪红军制作2.2.2模块级目录结构6．src/main/module.json5文件：模块配置文件，每一个模块都有1个module.json5。该文件用于存放对应Module的基本配置信息，主要包含Module名称、类型、描述信息、支持的设备类型等基本信息及应用组件信息、应用运行过程中所需的权限信息。其关键代码及功能说明如下所示。倪红军制作2.2.2模块级目录结构7．build-profile.json5文件：模块级配置文件，声明包括buildOption、targets等模块对应的编译构建参数；其关键代码及功能说明如下所示。8．hvigorfile.ts文件：模块级编译构建任务脚本。9．oh-package.json5文件：模块级依赖配置文件。倪红军制作2.2.3资源分类与引用1．系统资源系统资源指开发者可以直接使用系统预置的资源定义。通过使用系统资源，不同的开发者可以开发出具有相同视觉风格的应用。引用系统资源的代码格式如下所示。sys代表系统资源；type代表资源类型（如color、float、string、media）；resource_id代表资源id。2．应用资源应用资源借助资源文件能力，开发者在应用中可以自定义应用资源。开发者引用的应用资源只有放入特定的子目录中，才便于使用和维护。Stage模型工程项目下多模块共享的应用资源文件保存在“AppScope/resources”目录中，各模块的应用资源文件保存在“模块名/src/main/resources”目录中。这两个resources目录下都可以包括base目录、限定词目录和rawfile目录。倪红军制作2.2.3资源分类与引用2．应用资源（1）base目录base目录是默认目录。当应用的resources目录中没有与设备状态匹配的限定词目录时，会自动引用该目录中的资源文件。base目录的二级子目录为资源目录，用于存放字符串、颜色、布尔值等基础元素及媒体、动画、布局等资源文件，资源目录及功能说明如表所示。倪红军制作2.2.3资源分类与引用2．应用资源（1）base目录base目录中的资源文件会被编译成二进制文件，并赋予资源文件ID，通过指定资源类型（type）和资源名称（name）来引用。引用应用资源的代码格式如下所示。上述代码中的app代表是应用内resources目录中定义的资源；type代表资源类型（如color、float、string、plural、media）或资源的存放位置；name代表资源名称，由开发者定义资源时确定。倪红军制作2.2.3资源分类与引用2．应用资源（2）限定词目录应用使用资源时，系统会根据当前设备状态优先从相匹配的限定词目录中寻找该资源。限定词目录中的资源文件会被编译成二进制文件，并赋予资源文件ID，通过指定资源类型（type）和资源名称（name）来引用。例如，en_US和zh_CN是默认存在的两个限定词目录，如果设备的语言环境是美式英文时，优先匹配en_US目录下的资源；如果设备的语言环境是简体中文时，优先匹配zh_CN目录下的资源。限定词目录由一个或多个表征应用场景或设备特征的限定词组合而成，包括国家码、移动网络码、语言、文字、国家或地区、横竖屏、设备类型、颜色模式和屏幕密度等维度，限定词之间通过下划线（_）或者中划线（-）连接。可以根据应用程序的使用场景和设备特征选择其中的一类或几类组成目录名称。例如，zh_CN-vertical-car-mdpi限定词目录中的zh表示中文、CN表示中国、vertical表示竖屏、car表示车机设备、mdpi表示中规模屏幕密度，合起来表示如果是中国中文竖屏中分辨率的车机设备，就可以适配此子目录中的资源文件。倪红军制作2.2.3资源分类与引用2．应用资源（3）rawfile目录在rawfile目录中可以创建多层子目录，子目录名称可以自定义，文件夹内可以自由放置各类资源文件。rawfile目录中的文件不会根据设备状态去匹配不同的资源。目录中的资源文件会被直接打包进应用，不经过编译，也不会被赋予资源文件ID。通过指定文件路径和文件名来引用。引用rawfile目录下的应用资源代码格式如下所示。【范例2-1】在文本组件Text上显示红色的“南京师范大学泰州学院”。倪红军制作2.2.4ArkTS语言的基本结构OpenHarmony工程创建完成后在entry/src/main/ets/pages目录下自动生成Index.ets文件，该文件为该工程的默认入口页面文件，通常由装饰器、自定义组件、UI描述、系统组件（内置组件）、事件方法和属性方法等组成。Index.ets的默认代码如下所示。装饰器用来装饰类、结构、方法及变量，并赋予其特殊的含义。如上述第1、2和4行代码中的@Entry、@Component和@State是装饰器。其中@Entry表示该自定义组件为入口组件；@Component表示自定义组件，即第3行代码定义的structIndex为自定义组件；@State表示组件中的状态变量，状态变量变化会触发UI刷新。倪红军制作2.2.4ArkTS语言的基本结构OpenHarmony工程创建完成后在entry/src/main/ets/pages目录下自动生成Index.ets文件，该文件为该工程的默认入口页面文件，通常由装饰器、自定义组件、UI描述、系统组件（内置组件）、事件方法和属性方法等组成。Index.ets的默认代码如下所示。自定义组件是可以复用的UI单元，可以与其他组件组合，如上述@Component装饰的structIndex。UI描述表示用声明式来描述UI的结构，上述第5～15行代码中build（）中的代码块。系统组件是ArkUI框