1 开发环境与开发工具

DevEco Studio：面向应用开发者，基于 IntelliJ 平台，提供 ArkTS/ArkUI 工程模板、布局预览、模拟器、断点调试、性能分析与应用签名发布。建议始终使用与目标系统版本匹配的 Studio 版本。

应用开发完整工具链：
在这里插入图片描述
DevEco Studio（开发）→ OHPM（依赖）→ Hvigor（构建）→ Ark Compiler（编译）→ HAP(Harmony Ability Package)（打包）→ HDC（部署）→ HiLog / Debugger / Profiler（调试分析）

开发工具：

工具 / 技术英文全称或英文名称中文名称主要作用
DevEco StudioDevice Ecosystem Studio（名称释义）华为集成开发环境应用开发、编译、调试
ArkTSArk TypeScript方舟 TypeScript 语言编写应用业务逻辑及 UI
ArkUIArk User Interface方舟 UI 开发框架提供组件、布局、状态管理及渲染能力
OHPMOpenHarmony Package Manager开源鸿蒙包管理器管理和安装项目依赖
HvigorHarmony Vigor（名称来源）鸿蒙应用自动化构建工具管理并执行构建任务
Ark CompilerArk Compiler方舟编译器编译 ArkTS 等代码
HAP 打包工具Harmony Ability Package Packaging ToolHAP 应用包打包工具生成 HAP 模块包
签名工具Signing Tool数字签名工具为应用安装包签名
HDCHarmonyOS Device Connector鸿蒙设备连接工具设备连接、文件传输、安装与调试
HiLogHarmonyOS Logging（名称释义）鸿蒙日志系统输出、管理和查看日志
DebuggerDebugger调试器断点调试、单步执行、变量检查
ProfilerProfiler性能分析工具分析 CPU、内存和应用性能
Local EmulatorLocal 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.json5

2.2 核心业务代码目录 entry/

在这里插入图片描述

2.2.1 entry/src/main :应用主体

在这里插入图片描述

① ets/：真正编写 ArkTS 的地方

EntryAbility.ets 是应用重要的生命周期入口。系统服务的生命周期由samgr(System Ability Manger)管理,同时samgr还有实现进程间通信的功能。
EntryAbility.ets 内容示例如下：

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内容示例如下：

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 文件描述页面及交互

@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

内容示例如下：

{
  "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

代码示例入下：

{
  "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++的对应关系：

HarmonyOSPythonC/C++
oh-package.json5requirements.txt / pyproject.tomlvcpkg.json / Conan 配置
ohpmpipvcpkg / Conan
oh_modules/第三方依赖安装位置依赖库安装目录
oh-package-lock.json5poetry.lock / uv.lock锁定依赖版本的 lockfile

OHPM 是 OpenHarmony Package Manager，负责安装和管理三方依赖

2.4.2 oh-package-lock.json5

它记录依赖解析后的锁定信息，包括具体依赖版本及其依赖关系等

2.4.3 oh_modules/

该目录用于存放工程依赖
在这里插入图片描述

  • .ohpm/：OHPM 管理依赖所用的内部目录
  • @ohos/：@ohos 命名空间下的依赖包
Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

cover

Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 motion

avatar 开源鸿蒙跨平台开发者社区
cover

开源鸿蒙平台 CMP 三方库「compose-macos-26-ui」适配全流程

avatar 开源鸿蒙跨平台开发者社区
cover

开源鸿蒙平台 CMP 三方库「compose-shadow-alternative」适配全流程

avatar 开源鸿蒙跨平台开发者社区