鸿蒙(HarmonyOS)应用开发指南

1. 概述

1.1 简介

鸿蒙（即 HarmonyOS ，开发代号 Ark，正式名称为华为终端鸿蒙智能设备操作系统软件）是华为公司自 2012 年以来开发的一款可支持鸿蒙原生应用和兼容 AOSP 应用的分布式操作系统。该系统利用“分布式”技术将手机、电脑、平板、电视、汽车和智能穿戴等多款设备融合成一个“超级终端”，使用户便于操作和共享各种设备的资源。

1.2 本文读者收获

• 帮助开发者全面了解 HarmonyOS 系统

• 引导开发者从 0 到 1 上手 HarmonyOS 应用开发

1.3 鸿蒙开发基础

1.3.1 鸿蒙应用开发框架概述

鸿蒙应用开发框架是鸿蒙系统提供的一套开发工具和框架，用于帮助开发者快速构建鸿蒙应用。它提供了一系列的 API 和组件，使开发者可以方便地进行应用的开发、测试和发布。鸿蒙应用开发框架支持多种开发语言，包括 Java、C++、JavaScript、ArkTS 等，开发者可以根据自己的需求选择合适的开发语言进行开发。

1.3.2 鸿蒙应用开发框架的主要特点

跨平台开发：鸿蒙应用开发框架支持多种平台，包括手机、平板、电视、汽车等，开发者可以使用同一套代码开发适配不同平台的应用，大大提高了开发效率。

模块化开发：鸿蒙应用开发框架采用模块化的设计，开发者可以根据需要选择所需的功能模块进行开发，避免了不必要的代码冗余，提高了代码的可维护性和可重用性。

灵活的布局和界面设计：鸿蒙应用开发框架提供了丰富的布局和界面设计工具，开发者可以灵活地设计应用的界面，实现丰富多样的交互效果，提升用户体验。

强大的性能优化和调试工具：鸿蒙应用开发框架提供了一系列的性能优化和调试工具，开发者可以通过这些工具对应用进行性能优化和调试，提高应用的运行效率和稳定性。

1.3.3 语言和开发范式概念

当我们首次创建鸿蒙程序时，会面临模型的选择，如下图：

HarmonyOS 中的两种开发范式：

名称	语言生态	UI 更新方式	适用场景	适用人群
声明式开发范式	ArkTS	数据驱动更新	复杂度较大、团队合作度较高的程序	移动系统应用开发人员、系统应用开发人员
类 Web 开发范式	JS	数据驱动更新	界面较为简单的程序应用和卡片	Web 前端开发人员

语言选择

• ArkTS：只支持 Stage 模型

• JS：支持 Stage 模型 和 FA 模型

模型概念

HarmonyOS 的两种模型，是历史的产物，可以理解为设计模式。

FA（Feature Ability）模型：HarmonyOS API 7 开始支持的模型，已经不再主推。FA 模型开发可见 FA 模型开发概述。

Stage 模型：HarmonyOS API 9 开始新增的模型，是目前主推且会长期演进的模型。在该模型中，由于提供了 AbilityStage、WindowStage 等类作为应用组件和 Window 窗口的“舞台”，因此称这种应用模型为 Stage 模型。Stage 模型开发可见Stage 模型开发概述。Stage 模型架构如下图：

Stage模型概念图

• 目前官方主推 Stage 模型

• 针对 Stage 模型衍生出的声明式开发更优的开发框架

• ArkTS 优于 JS

• 我们认为，以上选型是目前（SDK 3.1.0 API 9）最优解/最佳实践即：Stage 模型+ArkTS+声明式。

2. 鸿蒙应用开发环境搭建

2.1 安装鸿蒙 DevEco Studio

步骤 1：下载 DevEco Studio SDK https://developer.harmonyos.com/cn/develop/deveco-studio#download

2.2 配置开发环境

2.2.1 （可选）配置 Proxy

步骤 2：网络不能直接访问 Internet，可通过设置代理服务器进行访问。如果无需代理即可访问 Internet，将跳过该步骤。

2.2.2 安装 Node.js 和 ohpm

步骤 3：指定本地已安装的 Node.js/ohpm，或在线下载安装 Node.js 与 ohpm。可以指定本地已安装的 Node.js 或 ohpm（Node.js 版本要求为 v14.19.1 及以上，且低于 v17.0.0；对应的 npm 版本要求为 6.14.16 及以上）路径位置；如果本地没有合适的版本，可以选择 Install 按钮，选择下载源和存储路径后，进行在线下载，单击 Next 进入下一步。

2.2.3 下载 HarmonyOS SDK

2.2.4 创建鸿蒙应用

2.2.5 运行项目

单击 DevEco Studio 工具栏中的按钮 ▶️ 运行工程，或使用默认快捷键 Shift+F10（ macOS 为 Control+R )运行工程。

3. 开发指南

3.1 项目与配置

3.1.1 项目结构

项目结构

3.1.2 配置文件含义

AppScope > app.json5：应用的全局配置信息。

entry：HarmonyOS 工程模块，编译构建生成一个 HAP 包。

• 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：应用级编译构建任务脚本。

3.2 ArkUI 框架

3.2.1 ArkUI 定义

ArkTS 是 HarmonyOS 优选的主力应用开发语言，在 TS 基础上发