欢迎加入开源鸿蒙PC社区

https://harmonypc.csdn.net/

 源码仓库

https://atomgit.com/qq_33247427/englishProject.git

第1篇：环境搭建与项目创建

前言

本系列教程共 10 篇，将带你从零开始开发一个运行在鸿蒙 PC（2in1 / MatePad）上的【英研习】应用，包含极速划词、手写默写、百度 OCR 识别等功能。本篇是第一篇，主要介绍开发环境的搭建、项目的创建以及首次运行调试。

在鸿蒙 PC（华为 MatePad Pro 2in1）上运行效果截图

视频

一、系列教程目录

篇号	标题	核心内容
01	环境搭建与项目创建	DevEco Studio 安装、SDK 配置、项目结构
02	数据模型与单词仓库	TypeScript 接口定义、Repository 模式
03	主入口页面与导航结构	页面路由、功能入口卡片
04	极速划词页面实现	Tab 导航、单词卡片、列表渲染
05	手写画布实现	Canvas 2D、触摸绑图、防卡顿
06	百度 OCR 手写识别接入	API 对接、PixelMap 处理
07	答案比对与反馈 UI	文本标准化、浮层反馈
08	单词切换与底部导航	状态管理、按钮交互
09	词根分解与水印展示	Chip 组件、条件渲染
10	项目总结与优化方向	架构回顾、性能优化

二、开发环境准备

2.1 硬件要求

在开始之前，请确保你的开发机器满足以下最低配置：

项目	最低要求	推荐配置
操作系统	macOS 12+ / Windows 10 (64-bit)	macOS 14+
内存	8 GB	16 GB+
磁盘空间	20 GB 可用	SSD 50 GB+
分辨率	1280×800	1920×1080+

2.2 安装 DevEco Studio

DevEco Studio 是华为官方的 HarmonyOS 集成开发环境，基于 IntelliJ 平台。

下载地址：华为开发者官网 - DevEco Studio

安装步骤：

1. 下载对应平台的安装包（macOS 选择 .dmg，Windows 选择 .exe）
2. 双击安装包，按向导完成安装
3. 首次启动时，DevEco 会引导你配置 SDK

2.3 配置 HarmonyOS SDK

首次启动 DevEco Studio 后：

1. 进入 Settings → HarmonyOS SDK
2. 选择 SDK 安装路径（建议放在非系统盘）
3. 勾选以下组件：

• • API Version 23
  • ArkTS SDK
  • Toolchains

1. 点击 Apply，等待下载完成（约 5-10 分钟）

# SDK 默认安装路径
# macOS: ~/Library/Huawei/Sdk
# Windows: C:\Users\<用户名>\AppData\Local\Huawei\Sdk

2.4 配置 Node.js 环境

DevEco Studio 的构建工具 hvigor 依赖 Node.js：

• DevEco Studio 6.0+ 自带 Node.js，通常无需额外安装
• 如需手动指定，进入 Settings → Build → Node.js，选择 v18+ 版本

验证安装：

node --version
# 输出 v18.x.x 或更高即可

2.5 真机调试准备

本项目目标设备为华为平板（MatePad）或 2in1 设备。

开启开发者模式：

1. 打开设备 设置 → 关于平板
2. 连续点击 版本号 7 次
3. 返回设置，找到 开发者选项
4. 开启 USB 调试

连接设备：

# 检查设备连接状态
hdc list targets

# 正常输出类似：
# 1234567890ABCDEF

如果设备未识别，尝试：更换 USB 线 → 重启 hdc 服务（hdc kill → hdc start）→ 重新插拔设备。

---

三、理解 electron 项目结构

本项目基于 electron 框架，它将 Electron 的核心能力（多窗口、进程管理等）移植到了 HarmonyOS 平台。

3.1 顶层目录结构

ohos_hap/
├── AppScope/                  # 应用级配置
│   ├── app.json5             # 应用名称、版本、包名
│   └── resources/            # 应用级资源（图标等）
├── electron/                  # 主模块（核心代码）
│   ├── src/main/ets/        # ArkTS 源码目录
│   ├── src/main/resources/  # 模块资源
│   ├── src/main/module.json5 # 模块配置（权限、Ability）
│   └── libs/                 # Native 库（.so 文件）
├── web_engine/               # Web 引擎模块
├── build-profile.json5       # 构建配置
├── hvigorfile.ts             # 构建脚本
└── oh-package.json5          # 依赖管理

3.2 源码目录详解

我们的业务代码全部在 electron/src/main/ets/ 下：

ets/
├── Application/
│   └── AbilityStage.ets       # 应用生命周期
├── entryability/
│   └── EntryAbility.ets       # 入口 Ability
├── pages/                     # 页面文件
│   ├── NativeListPage.ets    # 主入口列表页
│   ├── SpeedVocabPage.ets    # 极速划词 + 默写
│   ├── DictationPage.ets     # 独立默写页
│   └── Index.ets             # 手写详情页
├── components/                # 可复用组件
│   └── HandwritingCanvas.ets # 手写画布组件
├── models/                    # 数据模型
│   └── VocabularyWord.ets    # 单词模型定义
├── data/                      # 数据层
│   └── SpeedWordRepository.ets # 单词数据仓库
├── services/                  # 服务层
│   └── BaiduOCRService.ets   # 百度 OCR 服务
└── utils/                     # 工具类
    └── CanvasManager.ets     # Canvas 管理器

3.3 关键配置文件说明

app.json5（应用配置）

{
  "app": {
    "bundleName": "com.example.vocablearning",  // 应用包名，全局唯一
    "vendor": "example",                         // 开发者
    "versionCode": 1000000,                      // 版本号（整数）
    "versionName": "1.0.0"                       // 版本名（展示用）
  }
}

module.json5（模块配置）

{
  "module": {
    "name": "electron",
    "type": "entry",                    // 入口模块
    "srcEntry": "./ets/Application/AbilityStage.ets",
    "mainElement": "EntryAbility",      // 主 Ability
    "deviceTypes": ["2in1", "tablet"],  // 目标设备类型
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" }  // 网络权限（OCR 需要）
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "launchType": "specified",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ]
  }
}

main_pages.json（路由注册）

所有页面必须在此注册才能通过 router.pushUrl() 跳转：

{
  "src": [
    "pages/NativeListPage",
    "pages/Index",
    "pages/DictationPage",
    "pages/SpeedVocabPage",
    "pages/SubWindow",
    "pages/StatusBarPage",
    "pages/EmbeddedWindow",
    "pages/WindowNode",
    "pages/Login",
    "pages/WebPage"
  ]
}

四、创建项目

4.1 从已有模板开始

如果你已经有 electron 的项目模板：

# 克隆项目
git clone <your-electron-repo> vocab-learning-app
cd vocab-learning-app/ohos_hap

# 用 DevEco Studio 打开
# File → Open → 选择 ohos_hap 目录

4.2 项目初始化检查

打开项目后，DevEco 会自动执行 Sync。检查以下几点：

1. 底部状态栏：确认 Sync 成功（无红色错误）
2. SDK 版本：build-profile.json5 中的 compileSdkVersion 与已安装 SDK 匹配
3. 签名配置：File → Project Structure → Signing Configs → 勾选 Automatically generate signature

4.3 依赖安装

项目依赖通过 oh-package.json5 管理：

{
  "name": "ohos_hap",
  "version": "1.0.0",
  "dependencies": {
    // electron 相关依赖会自动配置
  }
}

Sync 时会自动安装依赖到 oh_modules/ 目录。

五、首次运行

5.1 选择目标设备

1. 顶部工具栏选择目标设备（真机或模拟器）
2. 如果是真机，确保已通过 USB 连接并授权

5.2 编译运行

点击 Run 按钮（或快捷键 Shift+F10）

编译流程：
ArkTS 源码 → hvigor 构建 → HAP 包 → 安装到设备 → 启动应用

首次编译约 2-3 分钟，后续增量编译约 10-30 秒。

5.3 查看日志

使用 DevEco 底部的 Log 面板查看运行日志：

// 在代码中打印日志
console.log('App started successfully');
console.info('Current word:', this.currentWord?.english);
console.error('OCR failed:', errorMessage);

过滤技巧：在 Log 面板搜索框输入关键词（如 BaiduOCR）快速定位。

六、常见问题排查

6.1 编译错误

错误信息	原因	解决方案
Cannot find module	依赖未安装	重新 Sync 项目
compileSdkVersion mismatch	SDK 版本不匹配	修改 build-profile.json5
Signing config not found	未配置签名	Project Structure → 自动签名
ArkTS syntax error	语法错误	检查 .ets 文件语法

6.2 运行时错误

现象	原因	解决方案
白屏	页面未注册	检查 main_pages.json
闪退	空指针	检查 @State 初始化
网络失败	缺少权限	module.json5 添加 INTERNET 权限
设备未识别	USB 问题	重启 hdc，更换数据线

6.3 hdc 常用命令

# 查看连接设备
hdc list targets

# 安装 HAP 包
hdc install path/to/your.hap

# 查看实时日志
hdc hilog

# 重启 hdc 服务
hdc kill
hdc start

八、本篇小结

通过本篇教程，我们完成了：

• DevEco Studio 安装和 SDK 配置
• 真机调试环境准备
• electron 项目结构理解
• 关键配置文件解读
• 首次编译运行成功
• 常见问题排查方法
• ArkTS 基础语法了解

下一篇预告：我们将定义单词的数据模型（VocabularyWord），并创建本地数据仓库（Repository），为后续的 UI 开发打好数据基础。