鸿蒙HarmonyOS学习手册_入门篇_鸿蒙系统手册

鸿蒙HarmonyOS学习手册_入门篇

入门

快速入门

开发准备

本文档适用于HarmonyOS应用开发的初学者。通过构建一个简单的具有页面跳转/返回功能的应用（如下图所示），快速了解工程目录的主要文件，熟悉HarmonyOS应用开发流程。

在开始之前，您需要了解有关HarmonyOS应用的一些基本概念：UI框架的简单说明、应用模型的基本概念。

基本概念

UI框架

HarmonyOS提供了一套UI开发框架，即方舟开发框架（ArkUI框架）。方舟开发框架可为开发者提供应用UI开发所必需的能力，比如多种组件、布局计算、动画能力、UI交互、绘制等。

方舟开发框架针对不同目的和技术背景的开发者提供了两种开发范式，分别是基于ArkTS的声明式开发范式（简称“声明式开发范式”）和兼容JS的类Web开发范式（简称“类Web开发范式”）。以下是两种开发范式的简单对比。

更多UI框架的开发内容及指导，详见UI开发。

应用模型

应用模型是HarmonyOS为开发者提供的应用程序所需能力的抽象提炼，它提供了应用程序必备的组件和运行机制。有了应用模型，开发者可以基于一套统一的模型进行应用开发，使应用开发更简单、高效。请见应用模型的构成要素。

随着系统的演进发展，HarmonyOS先后提供了两种应用模型：

• FA（Feature Ability）模型： HarmonyOS API 7开始支持的模型，已经不再主推。FA模型开发可见FA模型开发概述。
• Stage模型： HarmonyOS API 9开始新增的模型，是目前主推且会长期演进的模型。在该模型中，由于提供了AbilityStage、WindowStage等类作为应用组件和Window窗口的“舞台”，因此称这种应用模型为Stage模型。Stage模型开发可见Stage模型开发概述。

FA模型和Stage模型的整体架构和设计思想等更多区别，请见应用模型解读。

快速入门提供了一个含有两个页面的开发实例，并使用了不同的开发语言或不同的应用模型进行开发，以便开发者理解以上基本概念及应用开发流程。

工具准备

1. 安装最新版DevEco Studio。
2. 请参考配置开发环境，完成DevEco Studio的安装和开发环境配置。

完成上述操作及基本概念的理解后，可参照构建第一个ArkTS应用（Stage模型）、构建第一个ArkTS应用（FA模型）、构建第一个JS应用（FA模型）中的任一章节进行下一步体验和学习。

构建第一个ArkTS应用（Stage模型）-快速入门-入门

说明

为确保运行效果，本文以使用DevEco Studio 3.1 Release版本为例，点击此处获取下载链接。

创建ArkTS工程

1. 若首次打开DevEco Studio，请点击Create Project创建工程。如果已经打开了一个工程，请在菜单栏选择File > New > Create Project来创建一个新工程。

2. 选择Application应用开发（本文以应用开发为例，Atomic Service对应为元服务开发），选择模板“Empty Ability”，点击Next进行下一步配置。

   

3. 进入配置工程界面，Compile SDK选择“3.1.0(API 9)”，Model 选择“Stage”，其他参数保持默认设置即可。

   

   说明

   支持使用ArkTS低代码开发方式。

   低代码开发方式具有丰富的UI界面编辑功能，通过可视化界面开发方式快速构建布局，可有效降低开发者的上手成本并提升开发者构建UI界面的效率。

   如需使用低代码开发方式，请打开上图中的Enable Super Visual开关。

4. 点击Finish，工具会自动生成示例代码和相关资源，等待工程创建完成。

ArkTS工程目录结构（Stage模型）

• AppScope > app.json5：应用的全局配置信息。
• entry
  • src > main > ets：用于存放ArkTS源码。
  • src > main > ets > entryability：应用/服务的入口。
  • src > main > ets > pages：应用/服务包含的页面。
  • src > main > resources：用于存放应用/服务所用到的资源文件，如图形、多媒体、字符串、布局文件等。关于资源文件，详见资源分类与访问。
  • src > main > module.json5：Stage模型模块配置文件。主要包含HAP包的配置信息、应用/服务在具体设备上的配置信息以及应用/服务的全局配置信息。具体的配置文件说明，详见module.json5配置文件。
  • build-profile.json5：当前的模块信息、编译信息配置项，包括buildOption、targets配置等。其中targets中可配置当前运行环境，默认为HarmonyOS。
  • hvigorfile.ts：模块级编译构建任务脚本，开发者可以自定义相关任务和代码实现。
• oh_modules：用于存放三方库依赖信息。关于原npm工程适配ohpm操作，请参考历史工程迁移。
• build-profile.json5：应用级配置信息，包括签名、产品配置等。
• hvigorfile.ts：应用级编译构建任务脚本。

构建第一个页面

1. 使用文本组件。

   工程同步完成后，在“Project”窗口，点击“entry > src > main > ets > pages”，打开“Index.ets”文件，可以看到页面由Text组件组成。“Index.ets”文件的示例如下：

   // Index.ets
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18

2. 添加按钮。

   在默认页面基础上，我们添加一个Button组件，作为按钮响应用户点击，从而实现跳转到另一个页面。“Index.ets”文件的示例如下：

   // Index.ets
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18

3. 在编辑窗口右上角的侧边工具栏，点击Previewer，打开预览器。第一个页面效果如下图所示：

   

构建第二个页面

1. 创建第二个页面。

   • 新建第二个页面文件。在“Project”窗口，打开“entry > src > main > ets ”，右键点击“pages”文件夹，选择“New > ArkTS File”，命名为“Second”，点击“Finish”。可以看到文件目录结构如下：

     

     说明

     开发者也可以在右键点击“pages”文件夹时，选择“New > Page”，则无需手动配置相关页面路由。

   • 配置第二个页面的路由。在“Project”窗口，打开“entry > src > main > resources > base > profile”，在main_pages.json文件中的“src”下配置第二个页面的路由“pages/Second”。示例如下：

     {
       "src": [
         "pages/Index",
         "pages/Second"
       ]
     }
     1
     2
     3
     4
     5
     6

2. 添加文本及按钮。

   参照第一个页面，在第二个页面添加Text组件、Button组件等，并设置其样式。“Second.ets”文件的示例如下：

   // Second.ets
   @Entry
   @Component
   struct Second {
     @State message: string = 'Hi there'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           Button() {
             Text('Back')
               .fontSize(25)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30

实现页面间的跳转

页面间的导航可以通过页面路由router来实现。页面路由router根据页面url找到目标页面，从而实现跳转。使用页面路由请导入router模块。

1. 第一个页面跳转到第二个页面。

   在第一个页面中，跳转按钮绑定onClick事件，点击按钮时跳转到第二页。“Index.ets”文件的示例如下：

   // Index.ets
   // 导入页面路由模块
   import router from '@ohos.router';
   
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           // 添加按钮，以响应用户点击
           Button() {
             Text('Next')
               .fontSize(30)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
           // 跳转按钮绑定onClick事件，点击时跳转到第二页
           .onClick(() => {
             console.info(`Succeeded in clicking the 'Next' button.`)
             // 跳转到第二页
             router.pushUrl({ url: 'pages/Second' }).then(() => {
               console.info('Succeeded in jumping to the second page.')
             }).catch((err) => {
               console.error(`Failed to jump to the second page.Code is ${err.code}, message is ${err.message}`)
             })
           })
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44

2. 第二个页面返回到第一个页面。

   在第二个页面中，返回按钮绑定onClick事件，点击按钮时返回到第一页。“Second.ets”文件的示例如下：

   // Second.ets
   // 导入页面路由模块
   import router from '@ohos.router';
   
   @Entry
   @Component
   struct Second {
     @State message: string = 'Hi there'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           Button() {
             Text('Back')
               .fontSize(25)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
           // 返回按钮绑定onClick事件，点击按钮时返回到第一页
           .onClick(() => {
             console.info(`Succeeded in clicking the 'Back' button.`)
             try {
               // 返回第一页
               router.back()
               console.info('Succeeded in returning to the first page.')
             } catch (err) {
               console.error(`Failed to return to the first page.Code is ${err.code}, message is ${err.message}`)
             }
           })
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44

3. 打开“Index.ets”文件，点击预览器中的按钮进行刷新。效果如下图所示：

   

使用真机运行应用

运行HarmonyOS应用可以使用远程模拟器和物理真机设备，区别在于使用远程模拟器运行应用不需要对应用进行签名。接下来将以物理真机设备为例，介绍HarmonyOS应用的运行方法，关于模拟器的使用请参考使用Remote Emulator运行应用/服务。

1. 将搭载HarmonyOS系统的真机与电脑连接。具体指导及要求，可查看使用本地真机运行应用/服务。

2. 点击File > Project Structure… > Project > SigningConfigs界面勾选“Support HarmonyOS”和“Automatically generate signature”，点击界面提示的“Sign In”，使用华为帐号登录。等待自动签名完成后，点击“OK”即可。如下图所示：

   

3. 在编辑窗口右上角的工具栏，点击按钮运行。效果如下图所示：

   

恭喜您已经使用ArkTS语言开发（Stage模型）完成了第一个HarmonyOS应用，快来探索更多的HarmonyOS功能吧。

构建第一个ArkTS应用（FA模型）

创建ArkTS工程

1. 若首次打开DevEco Studio，请点击Create Project创建工程。如果已经打开了一个工程，请在菜单栏选择File > New > Create Project来创建一个新工程。

2. 选择Application应用开发（本文以应用开发为例，Atomic Service对应为元服务开发），选择模板“Empty Ability”，点击Next进行下一步配置。

   

3. 进入配置工程界面，Compile SDK选择“3.0.0(API 8)”（Compile SDK选择“3.1.0(API 9)”时注意同步选择 Model 为“FA”，此处以选择“3.0.0(API 8)”为例），Language选择“ArkTS”其他参数保持默认设置即可。

   

   说明

   DevEco Studio V3.0 Beta3及更高版本支持使用ArkTS低代码开发方式。

   低代码开发方式具有丰富的UI界面编辑功能，通过可视化界面开发方式快速构建布局，可有效降低开发者的上手成本并提升开发者构建UI界面的效率。

   如需使用低代码开发方式，请打开上图中的Enable Super Visual开关。

4. 点击Finish，工具会自动生成示例代码和相关资源，等待工程创建完成。

ArkTS工程目录结构（FA模型）

• entry：HarmonyOS工程模块，编译构建生成一个HAP包。
  • src > main > ets：用于存放ets源码。
  • src > main > ets > MainAbility：应用/服务的入口。
  • src > main > ets > MainAbility > pages：MainAbility包含的页面。
  • src > main > ets > MainAbility > pages > index.ets：pages列表中的第一个页面，即应用的首页入口。
  • src > main > ets > MainAbility > app.ets：承载Ability生命周期。
  • src > main > resources：用于存放应用/服务所用到的资源文件，如图形、多媒体、字符串、布局文件等。关于资源文件，详见资源分类与访问。
  • src > main > config.json：模块配置文件。主要包含HAP包的配置信息、应用/服务在具体设备上的配置信息以及应用/服务的全局配置信息。具体的配置文件说明，详见应用配置文件（FA模型）。
  • build-profile.json5：当前的模块信息、编译信息配置项，包括buildOption、targets配置等。其中targets中可配置当前运行环境，默认为HarmonyOS。
  • hvigorfile.ts：模块级编译构建任务脚本，开发者可以自定义相关任务和代码实现。
• build-profile.json5：应用级配置信息，包括签名、产品配置等。
• hvigorfile.ts：应用级编译构建任务脚本。

构建第一个页面

1. 使用文本组件。

   工程同步完成后，在“Project”窗口，点击“entry > src > main > ets > MainAbility > pages”，打开“index.ets”文件，可以看到页面由Text组件组成。“index.ets”文件的示例如下：

   // index.ets
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18

2. 添加按钮。

   在默认页面基础上，我们添加一个Button组件，作为按钮响应用户点击，从而实现跳转到另一个页面。“index.ets”文件的示例如下：

   // index.ets
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           // 添加按钮，以响应用户点击
           Button() {
             Text('Next')
               .fontSize(30)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31

3. 在编辑窗口右上角的侧边工具栏，点击Previewer，打开预览器。第一个页面效果如下图所示：

   

构建第二个页面

1. 创建第二个页面。

   • 新建第二个页面文件。在“Project”窗口，打开“entry > src > main > ets > MainAbility”，右键点击“pages”文件夹，选择“New > ArkTS File”，命名为“second”，点击“Finish”。可以看到文件目录结构如下：

     

     说明

     开发者也可以在右键点击“pages”文件夹时，选择“New > Page”，则无需手动配置相关页面路由。

   • 配置第二个页面的路由。在config.json文件中的“module - js - pages”下配置第二个页面的路由“pages/second”。示例如下：

     {
       "module": {
         "js": [
           {
             "pages": [
               "pages/index",
               "pages/second"
             ]
             }
         ]
       }
     }
     1
     2
     3
     4
     5
     6
     7
     8
     9
     10
     11
     12

2. 添加文本及按钮。

   参照第一个页面，在第二个页面添加Text组件、Button组件等，并设置其样式。“second.ets”文件的示例如下：

   // second.ets
   @Entry
   @Component
   struct Second {
     @State message: string = 'Hi there'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           Button() {
             Text('Back')
               .fontSize(25)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30

实现页面间的跳转

页面间的导航可以通过页面路由router来实现。页面路由router根据页面url找到目标页面，从而实现跳转。使用页面路由请导入router模块。

1. 第一个页面跳转到第二个页面。

   在第一个页面中，跳转按钮绑定onClick事件，点击按钮时跳转到第二页。“index.ets”文件的示例如下：

   // index.ets
   // 导入页面路由模块
   import router from '@ohos.router';
   
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           // 添加按钮，以响应用户点击
           Button() {
             Text('Next')
               .fontSize(30)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
           // 跳转按钮绑定onClick事件，点击时跳转到第二页
           .onClick(() => {
             router.push({ url: 'pages/second' })
             // 若为API 9工程，则可使用以下接口
             // router.pushUrl({ url: 'pages/second' })
           })
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40

2. 第二个页面返回到第一个页面。

   在第二个页面中，返回按钮绑定onClick事件，点击按钮时返回到第一页。“second.ets”文件的示例如下：

   // second.ets
   // 导入页面路由模块
   import router from '@ohos.router';
   
   @Entry
   @Component
   struct Second {
     @State message: string = 'Hi there'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
           Button() {
             Text('Back')
               .fontSize(25)
               .fontWeight(FontWeight.Bold)
           }
           .type(ButtonType.Capsule)
           .margin({
             top: 20
           })
           .backgroundColor('#0D9FFB')
           .width('40%')
           .height('5%')
           // 返回按钮绑定onClick事件，点击按钮时返回到第一页
           .onClick(() => {
             router.back()
           })
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37

3. 打开index.ets文件，点击预览器中的按钮进行刷新。效果如下图所示：

   

使用真机运行应用

运行HarmonyOS应用可以使用远程模拟器和物理真机设备，区别在于使用远程模拟器运行应用不需要对应用进行签名。接下来将以物理真机设备为例，介绍HarmonyOS应用的运行方法，关于模拟器的使用请参考使用Remote Emulator运行应用/服务。

1. 将搭载HarmonyOS系统的真机与电脑连接。具体指导及要求，可查看使用本地真机运行应用/服务。

2. 点击File > Project Structure… > Project > SigningConfigs界面勾选“Support HarmonyOS”和“Automatically generate signature”，点击界面提示的“Sign In”，使用华为帐号登录。等待自动签名完成后，点击“OK”即可。如下图所示：

   

3. 在编辑窗口右上角的工具栏，点击按钮运行。效果如下图所示：

   

恭喜您已经使用ArkTS语言开发（FA模型）完成了第一个HarmonyOS应用，快来探索更多的HarmonyOS功能吧。

构建第一个JS应用（FA模型）

创建JS工程

1. 若首次打开DevEco Studio，请点击Create Project创建工程。如果已经打开了一个工程，请在菜单栏选择File > New > Create Project来创建一个新工程。

2. 选择Application应用开发（本文以应用开发为例，Atomic Service对应为元服务开发），选择模板“Empty Ability”，点击Next进行下一步配置。

   

3. 进入配置工程界面，Compile SDK选择“3.0.0(API 8)”（Compile SDK选择“3.1.0(API 9)”时注意同步选择 Model 为“FA”，此处以选择“3.0.0(API 8)”为例），Language选择“JS”，其他参数保持默认设置即可。

   

   说明

   DevEco Studio V2.2 Beta1及更高版本支持使用JS低代码开发方式。

   低代码开发方式具有丰富的UI界面编辑功能，通过可视化界面开发方式快速构建布局，可有效降低开发者的上手成本并提升开发者构建UI界面的效率。

   如需使用低代码开发方式，请打开上图中的Enable Super Visual开关。

4. 点击Finish，工具会自动生成示例代码和相关资源，等待工程创建完成。

JS工程目录结构

• entry：HarmonyOS工程模块，编译构建生成一个HAP包。
  • src > main > js：用于存放js源码。
  • src > main > js > MainAbility：应用/服务的入口。
  • src > main > js > MainAbility > i18n：用于配置不同语言场景资源内容，比如应用文本词条、图片路径等资源。
  • src > main > js > MainAbility > pages：MainAbility包含的页面。
  • src > main > js > MainAbility > app.js：承载Ability生命周期。
  • src > main > resources：用于存放应用/服务所用到的资源文件，如图形、多媒体、字符串、布局文件等。关于资源文件，详见资源限定与访问。
  • src > main > config.json：模块配置文件。主要包含HAP包的配置信息、应用/服务在具体设备上的配置信息以及应用/服务的全局配置信息。具体的配置文件说明，详见应用配置文件（FA模型）。
  • build-profile.json5：当前的模块信息、编译信息配置项，包括buildOption、targets配置等。其中targets中可配置当前运行环境，默认为HarmonyOS。
  • hvigorfile.ts：模块级编译构建任务脚本，开发者可以自定义相关任务和代码实现。
• build-profile.json5：应用级配置信息，包括签名、产品配置等。
• hvigorfile.ts：应用级编译构建任务脚本。

构建第一个页面

1. 使用文本组件。

   工程同步完成后，在“Project”窗口，点击“entry > src > main > js > MainAbility > pages> index”，打开“index.hml”文件，设置Text组件内容。“index.hml”文件的示例如下：

   <!-- index.hml -->
   <div class="container">
       <text class="title">
           Hello World
       </text>
   </div>
   1
   2
   3
   4
   5
   6

2. 添加按钮，并绑定onclick方法。

   在默认页面基础上，我们添加一个button类型的input组件，作为按钮响应用户点击，从而实现跳转到另一个页面。“index.hml”文件的示例代码如下：

   <!-- index.hml -->
   <div class="container">
       <text class="title">
           Hello World
       </text>
   
   <!-- 添加按钮，值为Next，并绑定onclick方法-->
       <input class="btn" type="button" value="Next" onclick="onclick"></input>
   </div>
   1
   2
   3
   4
   5
   6
   7
   8
   9

3. 设置页面样式。

   在“Project”窗口，点击“entry > src > main > js > MainAbility > pages> index”，打开“index.css”文件，可以对页面中文本、按钮设置宽高、字体大小、间距等样式。“index.css”文件的示例如下：

   /* index.css */
   .container {
       display: flex;
       flex-direction: column;
       justify-content: center;
       align-items: center;
       left: 0px;
       top: 0px;
       width: 100%;
       height: 100%;
   }
   
   .title {
       font-size: 100px;
       font-weight: bold;
       text-align: center;
       width: 100%;
       margin: 10px;
   }
   
   .btn {
       font-size: 60px;
       font-weight: bold;
       text-align: center;
       width: 40%;
       height: 5%;
       margin-top: 20px;
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28

4. 在编辑窗口右上角的侧边工具栏，点击Previewer，打开预览器。第一个页面效果如下图所示：

   

构建第二个页面

1. 创建第二个页面。

   在“Project”窗口，打开“entry > src > main > js > MainAbility”，右键点击“pages”文件夹，选择“New > Page”，命名为“second”，点击“Finish”，即完成第二个页面的创建。可以看到文件目录结构如下：

   

2. 添加文本及按钮。

   参照第一个页面，在第二个页面添加文本、按钮及点击按钮绑定页面返回等。“second.hml”文件的示例如下：

   <!-- second.hml -->
   <div class="container">
       <text class="title">
           Hi there
       </text>
   
   <!-- 添加按钮，值为Back，并绑定back方法-->
       <input class="btn" type="button" value="Back" onclick="back"></input>
   </div>
   1
   2
   3
   4
   5
   6
   7
   8
   9

3. 设置页面样式**。**“second.css”文件的示例如下：

   /* second.css */
   .container {
       display: flex;
       flex-direction: column;
       justify-content: center;
       align-items: center;
       left: 0px;
       top: 0px;
       width: 100%;
       height: 100%;
   }
   
   .title {
       font-size: 100px;
       font-weight: bold;
       text-align: center;
       width: 100%;
       margin: 10px;
   }
   
   .btn {
       font-size: 60px;
       font-weight: bold;
       text-align: center;
       width: 40%;
       height: 5%;
       margin-top: 20px;
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28

实现页面间的跳转

页面间的导航可以通过页面路由router来实现。页面路由router根据页面url找到目标页面，从而实现跳转。使用页面路由请导入router模块。

1. 第一个页面跳转到第二个页面。

   在第一个页面中，跳转按钮绑定onclick方法，点击按钮时跳转到第二页。“index.js”示例如下：

   // index.js
   // 导入页面路由模块
   import router from '@ohos.router';
   
   export default {
       onclick: function () {
           router.push({
               url: "pages/second/second"
           })
       }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11

2. 第二个页面返回到第一个页面。

   在第二个页面中，返回按钮绑定back方法，点击按钮时返回到第一页。“second.js”示例如下：

   // second.js
   // 导入页面路由模块
   import router from '@ohos.router';
   
   export default {
       back: function () {
           router.back()
       }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9

3. 打开index文件夹下的任意一个文件，点击预览器中的按钮进行刷新。效果如下图所示：

   

使用真机运行应用

运行HarmonyOS应用可以使用远程模拟器和物理真机设备，区别在于使用远程模拟器运行应用不需要对应用进行签名。接下来将以物理真机设备为例，介绍HarmonyOS应用的运行方法，关于模拟器的使用请参考使用Remote Emulator运行应用/服务。

1. 将搭载HarmonyOS系统的真机与电脑连接。具体指导及要求，可查看使用本地真机运行应用/服务。

2. 点击File > Project Structure… > Project > SigningConfigs界面勾选“Support HarmonyOS”和“Automatically generate signature”，点击界面提示的“Sign In”，使用华为帐号登录。等待自动签名完成后，点击“OK”即可。如下图所示：

   

3. 在编辑窗口右上角的工具栏，点击按钮运行。效果如下图所示：

   

恭喜您已经使用JS语言开发（FA模型）完成了第一个HarmonyOS应用，快来探索更多的HarmonyOS功能吧。

开发基础知识

应用程序包基础知识

应用程序包概述

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

HarmonyOS提供了应用程序包开发、安装、查询、更新、卸载的管理机制，方便开发者开发和管理HarmonyOS应用，具体如下：

• 应用软件所涉及的文件多种多样，开发者可通过HarmonyOS提供的集成开发工具将其开发的可执行代码、资源、三方库等文件整合到一起制作成HarmonyOS应用程序包，便于开发者对应用程序的部署。
• 应用软件所涉及的设备类型多种多样，开发者可通过HarmonyOS提供的应用程序包配置文件指定其应用程序包的分发设备类型，便于应用市场对应用程序包的分发管理。
• 应用软件所包含的功能多种多样，将不同的功能特性按模块来划分和管理是一种良好的设计方式。HarmonyOS提供了同一应用程序的多包管理的机制，开发者可以将不同的功能特性聚合到不同的包中，方便后续的维护与扩展。
• 应用软件涉及的芯片平台多种多样，有x86、ARM等，还有32位、64位之分，HarmonyOS为应用程序包屏蔽了芯片平台的差异，使应用程序包在不同的芯片平台都能够安装运行。
• 应用软件涉及的软件信息多种多样，有应用版本、应用名称、组件、申请权限等的信息，HarmonyOS包管理为开发者提供了这些信息的查询接口，方便开发者在程序中查询所需要的包信息。
• 应用软件涉及的资源多种多样，有媒体资源、原生资源、字符资源以及国际化的资源等，HarmonyOS包管理将不同的资源归档到不同的目录中，并集成资源索引文件，方便应用对资源的查找和使用。

应用程序包结构

Stage模型应用程序包结构

基于Stage模型开发的应用，经编译打包后，其应用程序包结构如下图**应用程序包结构（Stage模型）**所示。开发者需要熟悉应用程序包结构相关的基本概念。

• 在开发态，一个应用包含一个或者多个Module，可以在DevEco Studio工程中创建一个或者多个Module。Module是HarmonyOS应用/服务的基本功能单元，包含了源代码、资源文件、第三方库及应用/服务配置文件，每一个Module都可以独立进行编译和运行。Module分为“Ability”和“Library”两种类型，“Ability”类型的Module对应于编译后的HAP（Harmony Ability Package）；“Library”类型的Module对应于HAR（Harmony Archive），或者HSP（Harmony Shared Package）。

  一个Module可以包含一个或多个UIAbility组件，如下图所示。

  图1 Module与UIAbility组件关系示意图

  

  全文中介绍到的Module默认指的是“Ability”类型的Module。

• 开发者通过DevEco Studio把应用程序编译为一个或者多个.hap后缀的文件，即HAP。HAP是HarmonyOS应用安装的基本单位，包含了编译后的代码、资源、三方库及配置文件。HAP可分为Entry和Feature两种类型。

  • Entry类型的HAP：是应用的主模块，在module.json5配置文件中的type标签配置为“entry”类型。在同一个应用中，同一设备类型只支持一个Entry类型的HAP，通常用于实现应用的入口界面、入口图标、主特性功能等。
  • Feature类型的HAP：是应用的动态特性模块，在module.json5配置文件中的type标签配置为“feature”类型。一个应用程序包可以包含一个或多个Feature类型的HAP，也可以不包含；Feature类型的HAP通常用于实现应用的特性功能，可以配置成按需下载安装，也可以配置成随Entry类型的HAP一起下载安装（请参见module对象内部结构中的“deliveryWithInstall”）。

• 每个HarmonyOS应用可以包含多个.hap文件，一个应用中的.hap文件合在一起称为一个Bundle，而bundleName就是应用的唯一标识（请参见app.json5配置文件中的bundleName标签）。需要特别说明的是：在应用上架到应用市场时，需要把应用包含的所有.hap文件（即Bundle）打包为一个.app后缀的文件用于上架，这个.app文件称为App Pack（Application Package），其中同时包含了描述App Pack属性的pack.info文件；在云端（服务器）分发和终端设备安装时，都是以HAP为单位进行分发和安装的。

• 打包后的HAP包结构包括ets、libs、resources等文件夹和resources.index、module.json、pack.info等文件。

  • ets目录用于存放应用代码编译后的字节码文件。
  • libs目录用于存放库文件。库文件是HarmonyOS应用依赖的第三方代码（.so二进制文件）。
  • resources目录用于存放应用的资源文件（字符串、图片等），便于开发者使用和维护，详见资源分类与访问。
  • resources.index是资源索引表，由IDE编译工程时生成。
  • module.json是HAP的配置文件，内容由工程配置中的module.json5和app.json5组成，该文件是HAP中必不可少的文件。IDE会自动生成一部分默认配置，开发者按需修改其中的配置。详细字段请参见应用配置文件。
  • pack.info是Bundle中用于描述每个HAP属性的文件，例如app中的bundleName和versionCode信息、module中的name、type和abilities等信息，由IDE工具生成Bundle包时自动生成。

  图2 应用程序包结构（Stage模型）

  [外链图片转存中…(img-XvD15jEc-1704894464549)]

FA模型应用程序包结构

基于FA模型开发的应用，其应用程序包结构如下图**应用程序包结构（FA模型）**所示。开发者需要熟悉应用程序包结构相关的基本概念。

FA模型与Stage模型不同之处在于HAP内部文件存放位置不同，FA模型将所有的资源文件、库文件和代码文件都放在assets文件夹中，在文件夹内部进一步区分。

• config.json是应用配置文件，IDE会自动生成一部分模块代码，开发者按需修改其中的配置。详细字段请参见应用配置文件。
• assets是HAP所有的资源文件、库文件和代码文件的集合，内部可以分为entry和js文件夹。entry文件夹中存放的是resources目录和resources.index文件。
• resources目录用于存放应用的资源文件（字符串、图片等），便于开发者使用和维护，详见资源分类与访问。
• resources.index是资源索引表，由IDE调用SDK工具生成。
• js文件夹中存放的是编译后的代码文件。
• pack.info是Bundle中用于描述每个HAP属性的文件，例如app中的bundleName和versionCode信息、module中的name、type和abilities等信息，由IDE工具生成Bundle包时自动生成。

图1 应用程序包结构（FA模型）

[外链图片转存中…(img-tu5I5CA2-1704894464550)]

应用程序包多HAP机制

多HAP机制设计目标

• 方便开发者模块化的管理应用，好的应用一般都是模块化管理，模块之间属于松耦合关系。多HAP方便了开发者将业务划分成多个模块，每个模块放到独立的HAP中。例如支付类应用，有统一的主界面，主界面管理“扫一扫”、“收付款”、“消息”、“理财”等各个模块。其中主界面管理其他模块的逻辑在Entry包中实现，而“扫一扫”、“收付款”、“消息”和“理财”等模块在不同的Feature包中实现。可以同时开发多个Feature包，能够实现Feature包单独的开发测试，最终由Entry包统一集成Feature包的特性。
• 方便开发者将多HAP合理地组合并部署到不同的设备上。例如应用程序包含一个Entry包和两个Featrue包（Feature1和Feature2）。其中Entry包可以部署到设备A和设备B，Feature1只能部署到设备A，Feature2包只部署到设备B上，那么开发者就可以方便的组合Entry和Feature1部署到设备A上，组合Entry和Feature2部署到设备B上。
• 方便开发者按需加载所需模块，减少包大小。开发者可以将一个应用的某些HAP配置成按需加载。应用在启动阶段初始用不到的特性，可以配置暂不加载，当用户用到这些特性的时候，可由应用自动下载这些特性HAP，一定程度上减少应用包的大小。
• 方便应用资源共享，减少程序包大小。多个HAP都需要用到的资源（包括公共资源文件、公共页面等）以及so（shared object）文件可以放到单独的HAP中，其他HAP可以到该HAP中访问资源和so文件，也一定程度上可以减少应用程序包大小。

多HAP构建视图

IDE支持在一个应用工程中进行多个HAP的开发与构建，如下图所示。

图1 多HAP构建视图

[外链图片转存中…(img-TVwtH37d-1704894464550)]

1. IDE开发态视图

   • AppScope目录

     • app.json5：配置应用全局描述信息，例如应用包名、版本号、应用图标、应用名称和依赖的SDK版本号等。

     • resources目录：放置应用的图标资源和应用名称字符串资源。

       说明：

       • 该目录由IDE自动生成，名称不可更改。
       • AppScope目录下面的文件名与Entry、Feature模块下面的文件名不能重复，否则IDE会报错。

   • entry或者feature目录（名称可由开发者自定义）

     • 由IDE引导开发者创建的Module，在该Module中实现应用的业务逻辑；可以创建多个Module，图中entry和feature即是创建的两个Module。
     • resources目录：放置该Module中所使用到的资源。
     • ets目录：开发者的业务逻辑。
     • module.json5：配置该Module的描述信息，如：Module的名称、Module的入口代码路径、包含的组件信息等。

2. 编译打包后的视图

   • 一个开发态的Module编译后生成一个部署态的HAP，Module和HAP一一对应。
   • HAP中的module.json由开发视图中的app.json5和module.json5合成。
   • 所有的HAP最终会编译到一个App Pack中（以.app为后缀的包文件），用于发布到应用市场。

多HAP的开发调试与发布部署流程

多HAP的开发调试与发布部署流程如下图所示。

图1 多HAP的开发调试与发布部署流程

[外链图片转存中…(img-0S6vEwMt-1704894464552)]

开发

开发者通过DevEco Studio工具按照业务的需要创建多个Module，在相应的Module中完成自身业务的开发。

调试

通过DevEco Studio编译打包，生成单个或者多个HAP，即可基于HAP进行调试。如需根据不同的部署环境、目标人群、运行环境等，将同一个HAP定制编译为不同版本，请参见定制编译指导。

在调试前，需要先安装或更新HAP，以下介绍具体做法。

• 使用DevEco Studio进行调试

  使用指导可参考应用程序包调试方法，其中包括了单HAP与多HAP通过DevEco Studio工具的安装调试方法。

• 使用hdc工具(可通过HarmonyOS SDK获取，在SDK的toolchains目录下)进行调试

  在调试前，需要先安装或更新HAP，此处有两种方式。

1. 直接使用hdc安装、更新HAP。

   HAP的路径为开发平台上的文件路径，以Windows开发平台为例，命令参考如下：

   // 安装、更新，多HAP可以指定多个文件路径
   hdc install C:\entry.hap C:\feature.hap
   // 执行结果
   install bundle successfully.
   // 卸载
   hdc uninstall com.example.myapplication
   // 执行结果
   uninstall bundle successfully.
   1
   2
   3
   4
   5
   6
   7
   8

2. 先执行hdc shell，再使用bm工具安装、更新HAP。

   HAP的文件路径为真机上的文件路径，命令参考如下：

   // 先执行hdc shell才能使用bm工具
   hdc shell
   // 安装、更新，多HAP可以指定多个文件路径
   bm install -p /data/app/entry.hap /data/app/feature.hap
   // 执行结果
   install bundle successfully.
   // 卸载
   bm uninstall -n com.example.myapplication
   // 执行结果
   uninstall bundle successfully.
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10

   完成HAP安装或更新后，即可参考相关调试命令进行调试。

发布

当开发的程序包满足发布要求时，可以在工具中打包编译生成App包。将该App包上架到应用市场云端，应用市场会对上架的App包校验签名，校验签名通过后会将App包中的HAP拆分出来，同时对拆分出的HAP重新添加签名，然后对HAP进行分发。

部署

用户在设备上的应用市场客户端能够看到各种各样的应用，这些应用均由云端分发而来，有些是多HAP应用，有些是单HAP应用。用户选择某个应用后，应用市场将下载应用所包含的全部deliveryWithInstall设置为“true”的HAP。

应用在终端设备上的安装

下载完成后，应用市场客户端再调用系统中包管理服务的安装接口安装下载的HAP，包管理服务以应用为单位将其中所有HAP部署到指定目录下，以完成应用的安装。

多HAP使用规则

• App Pack包不能直接安装到设备上，只是上架应用市场的单元。
• App Pack包中所有HAP的配置文件中的bundleName标签必须一致。
• App Pack包中所有HAP的配置文件中的versionCode标签必须一致。
• App Pack包中同一设备类型的所有HAP中必须有且只有一个entry类型的HAP，feature类型的HAP可以有一个或者多个，也可以没有。
• App Pack包中的每个HAP必须配置moduleName标签，同一设备类型的所有HAP对应的moduleName标签必须唯一。
• 同一应用的所有HAP签名证书要保持一致。上架应用市场是以App Pack的形式上架，并对其进行了签名。应用市场分发时会将所有HAP从App Pack中拆分出来，同时对其中的所有HAP进行重签名，这样保证了所有HAP签名证书的一致性。在调试阶段，开发者通过命令行或IDE将HAP安装到设备上时要保证所有HAP签名证书一致，否则会出现安装失败的问题。

多HAP运行机制及数据通信方式

多HAP机制主要是为方便开发者进行模块化管理。HAP和应用运行时的进程并不是一一对应的，具体运行机制如下：

• 默认情况下，应用中（同一包名）的所有UIAbility、ServiceExtensionAbility、DataShareExtensionAbility运行在同一个独立进程中，其他同类型ExtensionAbility分别运行在单独的进程。
• HAP支持在module.json5（Stage模型）或者config.json（FA模型）中通过process标签配置单独的进程（仅系统应用支持，三方应用不支持）。配置了process的HAP，其组件运行在单独的process进程中，多个HAP可以配置相同的process，则这些HAP运行在相同进程中，process配置的详细说明请参见module.json5配置文件。
• 应用运行时，同一进程中的UIAbility组件被启动时，才加载对应HAP的资源和代码。

基于上述机制，多HAP数据通信方式如下：

• 同一进程内的数据通信，请参见线程间通信。
• 跨进程的数据通信，请参见进程间通信。
• 多HAP如果运行在同一进程，则多HAP间组件的通信方式与同一HAP内组件的通信方式相同。

应用程序包安装和卸载流程

开发者

开发者可以通过调试命令进行应用的安装和卸载，可参考多HAP的调试流程。

图1 应用程序包安装和卸载流程（开发者）

[外链图片转存中…(img-ZG3yaXP9-1704894464554)]

终端设备用户

开发者将应用上架应用市场后，终端设备用户可以在终端设备上使用应用市场进行应用的安装和卸载。

图2 应用程序包安装和卸载流程（终端设备用户）

[外链图片转存中…(img-9mTCnEVz-1704894464555)]

应用程序包更新流程

HarmonyOS包管理