欢迎加入开源鸿蒙PC社区
源码仓库
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
安装步骤：
- 下载对应平台的安装包（macOS 选择
.dmg，Windows 选择.exe） - 双击安装包，按向导完成安装
- 首次启动时，DevEco 会引导你配置 SDK
2.3 配置 HarmonyOS SDK
首次启动 DevEco Studio 后：
- 进入 Settings → HarmonyOS SDK
- 选择 SDK 安装路径（建议放在非系统盘）
- 勾选以下组件：
-
- API Version 23
- ArkTS SDK
- Toolchains
-
点击 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 设备。
开启开发者模式：
- 打开设备 设置 → 关于平板
- 连续点击 版本号 7 次
- 返回设置，找到 开发者选项
- 开启 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。检查以下几点：
- 底部状态栏：确认 Sync 成功（无红色错误）
- SDK 版本 ：
build-profile.json5中的compileSdkVersion与已安装 SDK 匹配 - 签名配置：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 选择目标设备
- 顶部工具栏选择目标设备（真机或模拟器）
- 如果是真机，确保已通过 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 开发打好数据基础。