1 开发环境与开发工具
DevEco Studio：面向应用开发者，基于 IntelliJ 平台，提供 ArkTS/ArkUI 工程模板、布局预览、模拟器、断点调试、性能分析与应用签名发布。建议始终使用与目标系统版本匹配的 Studio 版本。
应用开发完整工具链：
DevEco Studio（开发）→ OHPM（依赖）→ Hvigor（构建）→ Ark Compiler（编译）→ HAP(Harmony Ability Package)（打包）→ HDC（部署）→ HiLog / Debugger / Profiler（调试分析）
开发工具：
| 工具 / 技术 | 英文全称或英文名称 | 中文名称 | 主要作用 |
|---|---|---|---|
| DevEco Studio | Device Ecosystem Studio（名称释义） | 华为集成开发环境 | 应用开发、编译、调试 |
| ArkTS | Ark TypeScript | 方舟 TypeScript 语言 | 编写应用业务逻辑及 UI |
| ArkUI | Ark User Interface | 方舟 UI 开发框架 | 提供组件、布局、状态管理及渲染能力 |
| OHPM | OpenHarmony Package Manager | 开源鸿蒙包管理器 | 管理和安装项目依赖 |
| Hvigor | Harmony Vigor（名称来源） | 鸿蒙应用自动化构建工具 | 管理并执行构建任务 |
| Ark Compiler | Ark Compiler | 方舟编译器 | 编译 ArkTS 等代码 |
| HAP 打包工具 | Harmony Ability Package Packaging Tool | HAP 应用包打包工具 | 生成 HAP 模块包 |
| 签名工具 | Signing Tool | 数字签名工具 | 为应用安装包签名 |
| HDC | HarmonyOS Device Connector | 鸿蒙设备连接工具 | 设备连接、文件传输、安装与调试 |
| HiLog | HarmonyOS Logging（名称释义） | 鸿蒙日志系统 | 输出、管理和查看日志 |
| Debugger | Debugger | 调试器 | 断点调试、单步执行、变量检查 |
| Profiler | Profiler | 性能分析工具 | 分析 CPU、内存和应用性能 |
| Local Emulator | Local Emulator | 本地模拟器 | 在开发机运行模拟设备 |
2 工程目录组成
2.1 完整工程目录树
example/
├── .hvigor/ # Hvigor 构建缓存和中间数据
│ ├── cache/
│ ├── dependencyMap/
│ ├── outputs/
│ └── report/
├── .idea/ # IDE 工作区配置
│ ├── .deveco/
│ ├── modules/
│ ├── previewer/
│ ├── modules.xml
│ └── workspace.xml
├── AppScope/ # 应用级配置
│ ├── resources/
│ └── app.json5
├── entry/ # 主业务模块
│ ├── .preview/
│ ├── build/
│ ├── src/
│ │ └── main/
│ │ ├── ets/
│ │ │ ├── entryability/
│ │ │ └── pages/
│ │ ├── resources/
│ │ └── module.json5
│ ├── .gitignore
│ ├── build-profile.json5
│ ├── hvigorfile.ts
│ ├── obfuscation-rules.txt
│ └── oh-package.json5
├── hvigor/
│ └── hvigor-config.json5
├── oh_modules/
│ ├── .ohpm/
│ └── @ohos/
├── .gitignore
├── build-profile.json5
├── code-linter.json5
├── hvigorfile.ts
├── local.properties
├── oh-package.json5
└── oh-package-lock.json52.2 核心业务代码目录 entry/
2.2.1 entry/src/main :应用主体
① ets/：真正编写 ArkTS 的地方
EntryAbility.ets 是应用重要的生命周期入口。系统服务的生命周期由samgr(System Ability Manger)管理,同时samgr还有实现进程间通信的功能。
EntryAbility.ets 内容示例如下：
typescript
import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
const DOMAIN = 0x0000;
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
}
onDestroy(): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
}
onWindowStageCreate(windowStage: window.WindowStage): void {
// Main window is created, set main page for this ability
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
return;
}
hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
});
try {
this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
} catch (err) {
hilog.error(DOMAIN, 'testTag', 'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
}
}
onWindowStageDestroy(): void {
// Main window is destroyed, release UI related resources
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
}
onForeground(): void {
// Ability has brought to foreground
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
}
onBackground(): void {
// Ability has back to background
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
}
}UIAbility 和 WindowStage 都是 ArkTS 中的类（Class）；UIAbility 管理应用组件的生命周期，WindowsStage 管理该组件关联的窗口环境，ArkUI 是UI开发框架，负责描述和渲染页面； `onWindowStageDestroy()`、`onWindowStageCreate()`用于管理`WindowsStage`对象，`onCreate`、`onDestroy`用于管理`UIAbility`对象，是 UIAbilaty 的回调方法接口解析：
onCreate()：UIAbility 实例创建时回调，主要处理 UIAbility 实例初始化onWindowStageCreate():窗口管理环境创建，示例中的WindowsStage是系统提供的WindowsStage对象。windowStage.loadContent('pages/Index')的作用是加载指定 ArkUI 页面。onWindowStageCreate()管理的是UIAbilaty窗口并不是每创建一个页面就执行一次onForeground()：生命周期回调方法(Method)，进入前台时回调onBackground()：生命周期回调方法,转到后台时回调onWindowStageDestroy():当 UIAbility 的 WindowStage 被销毁时，执行与窗口相关的清理工作onDestroy():在 UIAbility 实例正常结束 生命周期时执行清理工作，系统异常结束终止应用进程可能不会执行onDestroy()，所以重要数据不能只依赖这个回调保存
注意：它们不是应用每次启动时必然按固定顺序全部执行，而是由实际生命周期状态决定。
EntryBackupAbility 是用于应用数据备份与恢复的扩展能力（BackupExtensionAbility），响应系统发起的数据备份与恢复，不是负责界面显示的 UIAbility。
EntryBackupAbility.ets内容示例如下：
typescript
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
const DOMAIN = 0x0000;
export default class EntryBackupAbility extends BackupExtensionAbility {
async onBackup() {
hilog.info(DOMAIN, 'testTag', 'onBackup ok');
await Promise.resolve();
}
async onRestore(bundleVersion: BundleVersion) {
hilog.info(DOMAIN, 'testTag', 'onRestore ok %{public}s', JSON.stringify(bundleVersion));
await Promise.resolve();
}
}extends BackupExtensionAbility表示EntryBackupAbility继承系统提供的备份扩展基类；onBackup()系统发起应用数据备份时调用的回调,应用可以在这里执行必要的备份准备，例如使需要备份的数据保持一致;onRestore()系统执行应用数据恢复时调用的回调,shi
应用可以在这里完成数据恢复后的必要处理。
pages/Index.ets 通常是页面 UI 示例内容如下：
Index.ets 文件描述页面及交互
typescript
@Entry
@Component
struct Index {
@State message: string = 'Hello ArkTS';
build() {
RelativeContainer() {
Text(this.message)
.id('HelloWorld')
.fontSize($r('app.float.page_text_font_size'))
.fontWeight(FontWeight.Bold)
.alignRules({
center: { anchor: '__container__', align: VerticalAlign.Center },
middle: { anchor: '__container__', align: HorizontalAlign.Center }
})
.onClick(() => {
this.message = 'Welcome'; // this指向的式组件实例
})
}
.height('100%')
.width('100%')
}
}命令式思维：直接命令控件执行操作
声明式思维：描述界面结构与其状态之间的关系，由 @State 装饰的变量发生变化后更多的工作是由 ArcUI 框架完成的代码内容分析：
@Entry:入口组件修饰器（Decorator），告诉 ArkUI 框架这个组件可以作为当前页面的入口组件，当EntryAbility.ets中执行windowStage.loadContent('pages/Index'),框架加载Index页面@Component:自定义组件装饰器，用于装饰struct关键字声明的数据结构。struct被@Component装饰后才具备组件化的能力。struct Index:自定义的组件类型，当前定义的组件类型为 Index 类型@State message:声明式状态变量，@State是装饰声明式变量的装饰器，修改字符串界面会自己更新，messgae 是变量名称build()方法:用于描述当前自定义组件的 UI 结构RelativeContainer()：相对布局，是 ArkUI 提供的布局组件，子组件通过对齐规则，确定相对于容器或其他组件的位置。而Column与Row是线性布局组件,分别管理子组件的纵向结构和横向结构Text:也是 UIArk提供的一个组件，这个组件 中含有 click() 事件方法 、显示内容的方法、样式属性方法，同时组件的参数也可以作为属性方法传入
**组件之间是嵌套关系，@Entry装饰器的作用就是标识该组件为组件树的根节点 **
组件树如下：
Index（自定义组件）
└── RelativeContainer（内置组件）
└── Text（内置组件）在RelativeContainer组件内部描述子组件的相对位置
② resources/：资源文件目录
为每一种环境准备一套资源文件保存在resources/下的一个目录中，例如图片中展示的 base/ 目录和 dark/ 目录就保存了两套环境，在resource/目录下创建的目录名称有规则约束不是随便起名的。使用resource/下的资源时无需指定，系统会根据设备所处环境自动选择匹配环境，若没有与当前所处环境对应的版本则使用 base/目录下的资源
| 文件或目录 | 用途 |
|---|---|
element/ |
用于存放描述页面元素、颜色、样式等各种类型的值，每种类型的值都要定义在一个相应的.json文件中 |
string.json |
定义应用中的文字资源 |
color.json |
定义颜色 |
media/ |
存储图标、图片、视频、音频等，该目录下不能创建子目录;media/下资源的引用方法 $r('app.media.<filename>') ，filename 不需要带后缀，且$r()的返回值类型是 Resource类型 |
profile/main_pages.json |
声明页面路由配置，它的主要作用是告诉 ArkUI 这个模块有哪些页面，以及这些页面对应的路径是什么。例如：url: 'pages/Index' |
rawfile/ |
用于存储任意格式的原始文件，该目录下支持创建子目录，该目录中的资源引用方式：$Rawfile('path/to/your/file'),$Rawfile()的返回值同样为Resource类型，file 需要带后缀 |
③ module.json5：模块配置文件（重点）
位置：
entry/src/main/module.json5内容示例如下：
typescript
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"mainElement": "EntryAbility",
"deviceTypes": [
"phone"
],
"deliveryWithInstall": true,
"installationFree": false,
"pages": "$profile:main_pages",
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:layered_image",
"label": "$string:EntryAbility_label",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"entities": [
"entity.system.home"
],
"actions": [
"ohos.want.action.home"
]
}
]
}
],
"extensionAbilities": [
{
"name": "EntryBackupAbility",
"srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
"type": "backup",
"exported": false,
"metadata": [
{
"name": "ohos.extension.backup",
"resource": "$profile:backup_config"
}
],
}
]
}
}| 字段 | 作用 |
|---|---|
name |
模块名称 |
type |
模块类型，如 entry 或 feature |
description |
模块描述资源 |
mainElement |
指定主入口 Ability |
deviceTypes |
支持的设备类型 |
deliveryWithInstall |
是否随应用安装 |
installationFree |
是否支持免安装 |
pages |
页面路由资源 |
abilities |
声明 UIAbility |
requestPermissions |
声明模块所申请的系统权限，如：访问网络、使用摄像头、使用麦克风或获取位置信息 |
2.3 应用级配置：AppScope/
2.3.1AppScope/app.json5
代码示例入下：
typescript
{
"app": {
"bundleName": "com.example.myapplication",
"vendor": "example",
"versionCode": 1000000,
"versionName": "1.0.0",
"buildVersion": "1",
"icon": "$media:layered_image",
"label": "$string:app_name"
}
}| 字段 | 作用 | 类比 |
|---|---|---|
bundleName |
应用唯一标识 | Android package/applicationId |
vendor |
开发者或厂商信息 | 发布者 |
versionCode |
内部版本编号，用于升级判断 | 整数版本 |
versionName |
展示给用户的版本 | 1.0.0 |
icon |
应用图标 | 桌面图标 |
label |
应用名称 | APP 显示名称 |
2.4 依赖管理：oh-package.json5 和 oh_modules/
2.4.1 oh-package.json5
工程级文件主要管理全局依赖配置和依赖覆盖等；模块级文件用于描述模块基本信息及依赖
它与Python、C++的对应关系：
| HarmonyOS | Python | C/C++ |
|---|---|---|
oh-package.json5 |
requirements.txt / pyproject.toml |
vcpkg.json / Conan 配置 |
ohpm |
pip |
vcpkg / Conan |
oh_modules/ |
第三方依赖安装位置 | 依赖库安装目录 |
oh-package-lock.json5 |
poetry.lock / uv.lock |
锁定依赖版本的 lockfile |
OHPM 是 OpenHarmony Package Manager，负责安装和管理三方依赖
2.4.2 oh-package-lock.json5
它记录依赖解析后的锁定信息，包括具体依赖版本及其依赖关系等
2.4.3 oh_modules/
该目录用于存放工程依赖
.ohpm/：OHPM 管理依赖所用的内部目录@ohos/：@ohos命名空间下的依赖包