HarmonyOS APP＜玩转React＞开源教程一：开发环境搭建与项目创建

大雷神

171人浏览 · 2026-03-09 21:26:20

大雷神 · 2026-03-09 21:26:20 发布

第1次：开发环境搭建与项目创建

如果需要看上架项目可以在华为应用市场搜索《玩转React》，也有姐妹篇《vue开发教程》
本次课程将带你完成 HarmonyOS 开发环境的搭建，创建第一个项目，并了解项目的基本结构。这是整个教程的起点，请确保每一步都正确完成。

学习目标

了解 HarmonyOS 开发生态
安装并配置 DevEco Studio 开发工具
创建第一个 HarmonyOS 项目
理解项目目录结构
掌握基本的运行与调试方法

1.1 HarmonyOS 开发环境介绍

什么是 HarmonyOS？

HarmonyOS（鸿蒙操作系统）是华为开发的面向万物互联时代的分布式操作系统。它具有以下特点：

分布式架构：支持多设备协同
一次开发，多端部署：代码可运行在手机、平板、智能穿戴等设备
流畅安全：确定时延引擎和高安全性设计

开发语言：ArkTS

ArkTS 是 HarmonyOS 的主力开发语言，它基于 TypeScript 扩展而来，具有以下特点：

TypeScript 语法基础
    ↓
+ 声明式 UI 语法
    ↓
+ 状态管理装饰器
    ↓
= ArkTS

开发框架：ArkUI

ArkUI 是 HarmonyOS 的 UI 开发框架，采用声明式编程范式：

// 声明式 UI 示例
@Entry
@Component
struct HelloWorld {
  build() {
    Column() {
      Text('Hello, HarmonyOS!')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
    }
  }
}

1.2 DevEco Studio 安装与配置

下载 DevEco Studio

访问华为开发者官网：https://developer.huawei.com/consumer/cn/deveco-studio/
下载最新版本的 DevEco Studio（建议 6.0 或以上版本）
根据你的操作系统选择对应版本（Windows/macOS）

Windows 安装步骤

运行安装程序
- 双击下载的 .exe 安装文件
- 选择安装路径（建议使用英文路径，避免中文）

选择安装组件

☑ DevEco Studio
☑ HarmonyOS SDK
☑ 模拟器（可选，建议安装）

配置环境变量
安装程序会自动配置，如需手动配置：
```
DEVECO_SDK_HOME = C:\Users\{用户名}\AppData\Local\Huawei\Sdk
```
完成安装
- 安装完成后启动 DevEco Studio
- 首次启动会自动下载必要的 SDK 组件

macOS 安装步骤

打开下载的 .dmg 文件
将 DevEco Studio 拖入 Applications 文件夹
首次打开时，右键选择"打开"以绑过安全限制
按提示完成 SDK 下载

首次启动配置

首次启动 DevEco Studio 时，需要完成以下配置：

同意许可协议
SDK 配置
- 选择 SDK 安装路径
- 等待 SDK 下载完成（可能需要 10-30 分钟）
登录华为账号（可选但推荐）
- 登录后可使用云端模拟器
- 可同步个人设置
界面主题选择
- Light（浅色）
- Darcula（深色）- 推荐

1.3 创建第一个 HarmonyOS 项目

创建新项目

启动 DevEco Studio
- 点击 “Create Project” 或 “File → New → Create Project”

选择项目模板

Choose Your Ability Template
├── Application
│   ├── Empty Ability  ← 选择这个
│   ├── [ArkTS] Empty Ability
│   └── ...
└── Atomic Service

配置项目信息

配置项	值	说明
Project name	ReactTutorial	项目名称
Bundle name	com.example.reacttutorial	包名
Save location	自选路径	项目保存位置
Compile SDK	6.0.0(API 20)	SDK 版本
Model	Stage	应用模型
Language	ArkTS	开发语言
Compatible SDK	6.0.0(API 20)	兼容版本
Device type	Phone	设备类型

点击 Finish 完成创建

等待项目初始化

项目创建后，DevEco Studio 会自动：

下载项目依赖
构建项目索引
同步 Gradle 配置

右下角会显示进度，等待完成即可。

1.4 项目目录结构详解

创建完成后，项目结构如下：

ReactTutorial/
├── .hvigor/                    # 构建缓存目录
├── AppScope/                   # 应用级配置
│   ├── app.json5              # 应用配置文件
│   └── resources/             # 应用级资源
│       └── base/
│           ├── element/       # 字符串等元素
│           └── media/         # 图片资源
├── entry/                      # 主模块（重点关注）
│   ├── src/
│   │   └── main/
│   │       ├── ets/           # ArkTS 源代码
│   │       │   ├── entryability/
│   │       │   │   └── EntryAbility.ets  # 应用入口
│   │       │   └── pages/
│   │       │       └── Index.ets         # 首页
│   │       ├── resources/     # 模块资源
│   │       └── module.json5   # 模块配置
│   ├── build-profile.json5    # 构建配置
│   └── oh-package.json5       # 依赖配置
├── hvigor/                     # 构建工具配置
├── oh-package.json5           # 项目依赖
└── build-profile.json5        # 项目构建配置

核心文件说明

1. AppScope/app.json5 - 应用配置

{
  "app": {
    "bundleName": "com.example.reacttutorial",  // 应用包名
    "vendor": "example",                         // 开发者
    "versionCode": 1000000,                      // 版本号
    "versionName": "1.0.0",                      // 版本名
    "icon": "$media:app_icon",                   // 应用图标
    "label": "$string:app_name"                  // 应用名称
  }
}

2. entry/src/main/module.json5 - 模块配置

{
  "module": {
    "name": "entry",                    // 模块名
    "type": "entry",                    // 模块类型
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",      // 入口 Ability
    "deviceTypes": ["phone"],           // 支持设备
    "pages": "$profile:main_pages",     // 页面配置
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["ohos.want.action.home"]
          }
        ]
      }
    ]
  }
}

3. entry/src/main/ets/pages/Index.ets - 首页

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    RelativeContainer() {
      Text(this.message)
        .id('HelloWorld')
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Center },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
    }
    .height('100%')
    .width('100%')
  }
}

4. entry/src/main/resources/base/profile/main_pages.json - 页面路由

{
  "src": [
    "pages/Index"
  ]
}

1.5 运行与调试基础

方式一：使用预览器（Preview）

最快速的预览方式，适合 UI 开发：

打开 Index.ets 文件
点击右上角的 “Preview” 按钮
右侧会显示实时预览效果

优点：速度快，实时刷新
缺点：部分 API 不支持

方式二：使用模拟器（Emulator）

完整的运行环境：

启动模拟器
- 点击菜单 Tools → Device Manager
- 选择或创建一个模拟器
- 点击启动按钮
运行项目
- 点击工具栏的绿色运行按钮 ▶
- 或使用快捷键 Shift + F10
等待安装
- 首次运行会编译并安装应用
- 安装完成后自动启动

方式三：使用真机调试

最真实的运行环境：

开启开发者模式
- 手机设置 → 关于手机 → 连续点击版本号 7 次
- 返回设置，进入"开发者选项"
- 开启"USB 调试"
连接设备
- 使用 USB 数据线连接手机和电脑
- 手机上允许调试授权
选择设备运行
- DevEco Studio 会自动识别设备
- 选择设备后点击运行

调试技巧

查看日志

// 在代码中添加日志
console.info('这是一条信息日志');
console.warn('这是一条警告日志');
console.error('这是一条错误日志');

在 DevEco Studio 底部的 “Log” 面板查看输出。

断点调试

在代码行号处点击，添加断点（红点）
使用 Debug 模式运行（虫子图标）
程序会在断点处暂停
可查看变量值、单步执行等

1.6 实操：创建 ReactTutorial 项目并成功运行

现在，让我们动手创建本教程的实战项目。

步骤 1：创建项目

按照 1.3 节的步骤创建项目，使用以下配置：

配置项	值
Project name	ReactTutorial
Bundle name	com.example.reacttutorial
Compile SDK	5.0.0(API 12)
Model	Stage
Language	ArkTS

步骤 2：修改首页代码

打开 entry/src/main/ets/pages/Index.ets，替换为以下代码：

/**
 * React 学习教程 App - 首页
 * 第1次课程实操代码
 */
@Entry
@Component
struct Index {
  @State message: string = 'React 学习教程';
  @State subTitle: string = '由浅入深，系统掌握 React';

  build() {
    Column() {
      // 应用图标
      Text('⚛️')
        .fontSize(80)
        .margin({ top: 100 })

      // 主标题
      Text(this.message)
        .fontSize(28)
        .fontWeight(FontWeight.Bold)
        .fontColor('#1a1a2e')
        .margin({ top: 20 })

      // 副标题
      Text(this.subTitle)
        .fontSize(16)
        .fontColor('#495057')
        .margin({ top: 8 })

      // 开始按钮
      Button('开始学习')
        .width(200)
        .height(48)
        .fontSize(16)
        .fontColor('#ffffff')
        .backgroundColor('#61DAFB')
        .borderRadius(24)
        .margin({ top: 60 })
        .onClick(() => {
          console.info('点击了开始学习按钮');
          this.message = '欢迎开始学习！';
        })

      // 版本信息
      Text('v1.0.0')
        .fontSize(12)
        .fontColor('#adb5bd')
        .margin({ top: 40 })
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#f8f9fa')
    .justifyContent(FlexAlign.Start)
    .alignItems(HorizontalAlign.Center)
  }
}

步骤 3：运行项目

点击预览按钮，查看效果
启动模拟器，运行完整应用
点击"开始学习"按钮，观察文字变化

预期效果

运行成功后，你将看到：

┌─────────────────────────┐
│                         │
│          ⚛️             │
│                         │
│    React 学习教程        │
│  由浅入深，系统掌握 React │
│                         │
│     ┌──────────────┐    │
│     │   开始学习    │    │
│     └──────────────┘    │
│                         │
│        v1.0.0           │
│                         │
└─────────────────────────┘

点击按钮后，标题会变为"欢迎开始学习！"