HarmonyOS 鸿蒙开发完整指南

# 🚀 HarmonyOS 鸿蒙开发完整指南

适合人群：移动开发工程师、前端开发者、对鸿蒙生态感兴趣的技术人员
学习时间：2-3个月
前置知识：JavaScript/TypeScript基础、移动开发概念

HarmonyOS（鸿蒙操作系统）是华为开发的分布式操作系统，旨在为不同设备提供统一的操作系统体验。本指南将带你从零开始学习鸿蒙应用开发。

# 📚 你将学到什么

HarmonyOS 基础概念 - 理解鸿蒙生态和架构
ArkTS 语言 - 掌握鸿蒙开发语言
ArkUI 框架 - 学会构建用户界面
开发工具链 - 熟练使用 DevEco Studio
实际项目开发 - 完成完整的应用开发

# 🎯 学习路径建议

graph TD A[环境搭建] --> B[ArkTS基础] B --> C[ArkUI组件] C --> D[状态管理] D --> E[网络与数据] E --> F[设备能力] F --> G[性能优化] G --> H[项目实战]

# 🤖 什么是 HarmonyOS？

HarmonyOS 是华为开发的分布式操作系统，具有以下特点：

分布式架构：支持多设备协同工作
统一开发：一套代码，多端运行
高性能：优化的渲染引擎和内存管理
安全可靠：企业级安全特性

# 核心概念

ArkTS：基于 TypeScript 的鸿蒙开发语言
ArkUI：声明式 UI 开发框架
Ability：应用的基本组成单元
HAP：HarmonyOS Ability Package，应用包格式

# 🛠️ 开发环境搭建

# 1. DevEco Studio 安装

下载地址：华为开发者官网 (opens new window)

系统要求：

Windows 10/11 (64位)
macOS 10.15 或更高版本
内存：8GB 以上
硬盘：10GB 以上可用空间

安装步骤：

下载 DevEco Studio 安装包
运行安装程序，按提示完成安装
首次启动时配置 SDK 路径
安装鸿蒙 SDK 和工具链

# 2. SDK 配置

# 设置环境变量（hdc 在 SDK toolchains；hvigor/ohpm 依赖 DevEco 自带 node）
export DEVECO=/Applications/DevEco-Studio.app/Contents
export NODE_HOME=$DEVECO/tools/node
export PATH=$DEVECO/tools/node/bin:$DEVECO/tools/hvigor/bin:$DEVECO/tools/ohpm/bin:$DEVECO/sdk/default/openharmony/toolchains:$PATH

# 验证安装
hdc -v               # hdc 版本
hvigorw --version    # hvigor 版本
ohpm -v              # ohpm 版本

1
2
3
4
5
6
7
8
9

# 3. 模拟器配置

创建模拟器：

打开 DevEco Studio
选择 Tools → Device Manager
点击 Create Device
选择设备类型和系统版本
下载并启动模拟器

模拟器类型：

Phone：手机模拟器
Tablet：平板模拟器
TV：智慧屏模拟器
Wearable：智能手表模拟器

# 4. 真机调试配置

开发者选项开启：

设置 → 关于手机 → 版本号（连续点击7次）
返回设置 → 系统和更新 → 开发者选项
开启"USB调试"和"仅充电模式下允许ADB调试"

连接调试：

# 查看连接的设备
hdc list targets

# 进入设备shell
hdc shell

# 安装应用
hdc install -p your_app.hap

1
2
3
4
5
6
7
8

# 5. ohpm 包管理器

ohpm（OpenHarmony Package Manager）是鸿蒙生态的包管理工具，类似于 npm，管理工程的三方库依赖（oh-package.json5 → oh_modules）。随 DevEco Studio 发布（位于 tools/ohpm/bin），不要用 npm 安装，配置好 PATH 即可（见上方 SDK 配置）。

ohpm install                 # 最常用：安装全部依赖

📖 ohpm 完整速查手册：ohpm —— 全部 19 个命令详解、oh-package.json5 工程配置（含 overrides 依赖统一）、registry/缓存管理、发布流程（publish_id + SSH key 认证）、npm↔ohpm 对照表与实测踩坑。

# 项目结构

# 标准鸿蒙项目结构示例

MyHarmonyApp/
├── AppScope/                          # 应用级配置
│   ├── app.json5                      # 应用配置文件
│   └── resources/                     # 应用级资源
│       ├── base/
│       │   ├── element/               # 元素资源
│       │   ├── media/                 # 媒体资源
│       │   └── profile/               # 配置文件
│       └── rawfile/                   # 原始文件
├── entry/                             # 主模块
│   ├── src/
│   │   ├── main/
│   │   │   ├── ets/                   # ArkTS源码
│   │   │   │   ├── pages/             # 页面组件
│   │   │   │   │   ├── Index.ets      # 首页
│   │   │   │   │   ├── Detail.ets     # 详情页
│   │   │   │   │   └── Profile.ets    # 个人页
│   │   │   │   ├── components/        # 自定义组件
│   │   │   │   │   ├── CustomButton.ets
│   │   │   │   │   └── LoadingView.ets
│   │   │   │   ├── services/          # 服务层
│   │   │   │   │   ├── ApiService.ets
│   │   │   │   │   └── StorageService.ets
│   │   │   │   ├── utils/             # 工具类
│   │   │   │   │   ├── Constants.ets
│   │   │   │   │   └── Helper.ets
│   │   │   │   ├── models/            # 数据模型
│   │   │   │   │   ├── User.ets
│   │   │   │   │   └── Product.ets
│   │   │   │   └── app.ets            # 应用入口
│   │   │   ├── resources/             # 模块级资源
│   │   │   │   ├── base/
│   │   │   │   │   ├── element/
│   │   │   │   │   │   ├── color.json # 颜色配置
│   │   │   │   │   │   ├── float.json # 浮点数配置
│   │   │   │   │   │   └── string.json # 字符串配置
│   │   │   │   │   └── media/
│   │   │   │   │       ├── icon.png
│   │   │   │   │       └── logo.png
│   │   │   │   └── rawfile/
│   │   │   └── module.json5           # 模块配置
│   │   └── ohosTest/                  # 测试代码
│   │       └── ets/
│   │           └── test/
│   │               └── Index.test.ets
│   └── build-profile.json5            # 构建配置
├── features/                          # 功能模块
│   ├── feature1/                      # 功能模块1
│   │   ├── src/
│   │   │   └── main/
│   │   │       ├── ets/
│   │   │       │   ├── pages/
│   │   │       │   ├── components/
│   │   │       │   └── services/
│   │   │       └── resources/
│   │   └── build-profile.json5
│   └── feature2/                      # 功能模块2
│       ├── src/
│       │   └── main/
│       │       ├── ets/
│       │       └── resources/
│       └── build-profile.json5
├── shared/                            # 共享模块
│   ├── src/
│   │   └── main/
│   │       ├── ets/
│   │       │   ├── components/        # 共享组件
│   │       │   ├── utils/             # 共享工具
│   │       │   └── constants/         # 共享常量
│   │       └── resources/
│   └── build-profile.json5
├── oh_modules/                        # 依赖模块（自动生成）
├── build/                             # 构建输出
├── .gitignore                         # Git忽略文件
├── .ohpmrc                            # ohpm配置文件
├── oh-package.json5                   # 项目配置文件
└── README.md                          # 项目说明

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# 关键配置文件说明

oh-package.json5 - 项目主配置文件：

{
  "name": "my-harmony-app",
  "version": "1.0.0",
  "description": "A HarmonyOS application",
  "main": "entry/src/main/ets/app.ets",
  "author": "Your Name",
  "license": "Apache-2.0",
  "dependencies": {
    "@ohos/hypium": "1.0.13",
    "@ohos/router": "1.0.0",
    "@ohos/http": "1.0.0"
  },
  "devDependencies": {
    "@ohos/hvigor": "1.0.0",
    "@ohos/hvigor-ohos-plugin": "1.0.0"
  },
  "repository": "https://gitee.com/your-repo/my-harmony-app",
  "keywords": ["harmonyos", "arkts", "arkui"],
  "ohos": {
    "org": "example",
    "buildTool": "hvigor",
    "directoryLevel": "module"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

module.json5 - 模块配置文件：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "Main entry module",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "Main entry ability",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

app.json5 - 应用配置文件：

{
  "app": {
    "bundleName": "com.example.myharmonyapp",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "minPlatformVersion": 9,
    "targetPlatformVersion": 9,
    "apiReleaseType": "Release",
    "debug": {
      "enable": true
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 目录组织原则

模块化设计：按功能划分模块，每个模块独立开发
资源分离：应用级资源与模块级资源分离管理
组件复用：共享组件放在shared模块中
测试覆盖：每个模块包含对应的测试代码
配置集中：配置文件统一管理，便于维护

# 📝 ArkTS 语言基础

ArkTS 是鸿蒙生态的编程语言，基于 TypeScript 扩展（声明式 UI、并发增强），同时施加更严格的类型约束（禁用 any、对象字面量须有明确类型等）。

📖 ArkTS 完整速查手册：arkts —— 基础语法、V1/V2 状态装饰器对照（@State/@Prop/@Link 与 @ObservedV2/@Trace/@Computed 等）、组件与页面生命周期区分、$$ 双向绑定、事件覆盖式注册、手势与常见坑速查。

# ArkUI框架

# 布局系统

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-layout-development (opens new window)

Flex布局
Grid布局
Stack布局: 层叠布局
List布局

# 基础组件

文本组件
图像组件
按钮组件
输入组件

# 容器组件

Column容器
Row容器
Stack容器
Grid容器

# 导航组件

Tabs组件
Navigation组件
Router路由

# 状态管理

📖 详见 arkts §7 状态管理分层：应用级 AppStorage/PersistentStorage/Environment、页面级 LocalStorage、组件级 V1/V2 装饰器对照。

# 网络与数据

# HTTP请求

网络请求API
请求拦截器
响应处理
错误处理

# 数据存储

文件存储
数据库操作
缓存管理
数据同步

# 数据绑定

数据源管理
数据转换
数据验证
数据更新

# 鸿蒙工具链（DevEco Studio 实测版）

本章所有工具均在 DevEco Studio 5.x（macOS）上实测验证。旧版文档中的 arktsc、arkui build、hap-builder、signer、profiler、memory-analyzer、test-runner、ui-test、simulator、device-sim、doc-generator、lint、config 等"工具"并不存在（AI 生成内容），已全部移除，真实替代见文末对照表。

# 工具分布总览

位置	内容
`Contents/tools/`	hvigor（构建）、ohpm（包管理）、node（v18 运行时）、emulator（模拟器）、profiler/dic_server、UxTestService
`Contents/sdk/default/openharmony/toolchains/`	hdc、restool、syscap_tool、idl、hnpcli、ark_disasm、rawheap_translator、modulecheck 等
`Contents/sdk/default/openharmony/native/`	NDK：aarch64/armv7 clang 交叉编译器 + cmake + sysroot
`Contents/plugins/`	codelinter（代码检查）等 IDE 插件

PATH 配置（实测可用）：

export DEVECO=/Applications/DevEco-Studio.app/Contents
export NODE_HOME=$DEVECO/tools/node    # hvigorw 启动脚本需要
export PATH=$DEVECO/tools/node/bin:$DEVECO/tools/hvigor/bin:$DEVECO/tools/ohpm/bin:$DEVECO/sdk/default/openharmony/toolchains:$PATH

1
2
3

⚠️ node 版本踩坑（实测）：hvigor/ohpm 的启动脚本直接调 PATH 里的 node。若 PATH 里是老版本 node（如 v14），ohpm 会报 Cannot find module 'node:events'。务必把 DevEco 自带 node（v18）放在 PATH 最前。

# 1. hdc — 设备调试连接器

鸿蒙版 adb，能力域覆盖：设备连接、应用管理（bm/aa）、文件传输、日志 hilog、系统服务转储 hidumper、内存观测、输入注入（uinput/uitest）、端口转发、截屏。

📖 完整速查手册：hdc（含 hdc↔adb 对照表与实战踩坑配方）

# 2. ohpm — 包管理器（≈ npm）

管理工程三方库依赖（oh-package.json5 → oh_modules），与 hdc（设备侧）职责完全不同，两者互不包含、都需要。

📖 完整速查手册：ohpm（19 个命令全解、oh-package.json5 结构、发布流程、npm 对照表与踩坑）

# 3. hvigor — 构建工具（≈ gradle）

hvigor 是鸿蒙唯一的构建系统（无独立的 "ArkTS 编译器/打包工具" CLI——ArkTS 编译、打包都是 hvigor 任务）。

启动入口：项目根目录 hvigorw wrapper，或全局 tools/hvigor/bin/hvigorw（实测版本 6.22.3）
工程配置：hvigor/hvigor-config.json5（modelVersion、构建插件如 router/efix、daemon/并行/增量开关）
真实构建产物（实测工程）：entry/build/default/outputs/default/entry-default-signed.hap、-unsigned.hap、mapping/、pack.info

hvigorw --version
hvigorw assembleHap                                   # 构建 HAP（默认 debug）
hvigorw assembleHap --mode module -p product=default -p buildMode=release
hvigorw assembleApp                                   # 构建 App 包（上架，多 HAP 聚合）
hvigorw clean
hvigorw tasks                                         # 列出全部任务

1
2
3
4
5
6

# 4. 签名（无独立 signer CLI）

真实方式只有两条路：

IDE 自动签名：File → Project Structure → Signing Configs，勾选 Automatically generate signature（调试证书自动生成）
工程配置：build-profile.json5 的 signingConfigs（证书/Profile 文件路径 + 密钥），CI 构建时 hvigorw 据此打出 -signed.hap

# 5. SDK toolchains — 资源与校验工具

工具	用途
`restool`	资源编译（resources 目录 → 包内资源）
`syscap_tool`	系统能力（syscap）查询与裁剪
`idl`	IDL 接口编译（跨进程/跨语言接口）
`hnpcli`	native 包（so 分发）管理
`ark_disasm`	方舟字节码（.abc）反汇编
`rawheap_translator`	堆快照原始文件转换
`modulecheck` / `configcheck` / `rescheck` / `syscapcheck`	模块/配置/资源/系统能力校验

这些工具由 hvigor/IDE 在构建流程中自动调用，日常开发极少手动使用；知道它们在哪、干什么即可。

# 6. Native（NDK）

sdk/default/openharmony/native/ 下提供完整交叉编译链：

llvm/bin/aarch64-unknown-linux-ohos-clang（arm64）、armv7-unknown-linux-ohos-clang（arm32）
build-tools/cmake + sysroot（C/C++ 交叉编译环境）

IDE 的 Native 模板会自动接管 cmake/clang 配置，无需手动调用。

# 7. 测试

hypium：官方单测框架（oh-package.json5 的 devDependencies 引入 @ohos/hypium），测试代码在 src/ohosTest/
aa test：设备端执行用例（hdc shell aa test -b <bundle> ...）
uitest：UI 自动化注入与布局检查（设备端工具，见 hdc §8）
UxTestService：IDE 内置 UX 检测服务（tools/UxTestService，Python 实现）

# 8. 性能分析

IDE Profiler（内置）：实时内存/CPU/渲染帧率分析，底层服务 tools/profiler/dic_server
设备端：hiperf（CPU 剖析）、hidumper --mem（PSS）、hidumper --mem-jsheap（ArkTS 堆快照/泄漏对象）→ 见 hdc §6/§7

# 9. 模拟器与预览

Emulator：真实二进制位于 tools/emulator/Emulator（Qt 程序），由 IDE 的 Device Manager（Tools → Device Manager）创建和启动，日常无需手动调用
Previewer：IDE 内置双栏预览（SDK 内 previewer 目录），改代码即时看 UI

# 10. 代码检查

Code Linter：IDE 内置（plugins/codelinter），ArkTS 语法与规范检查，无独立 CLI

# 真实开发工作流

cd MyHarmonyApp

# 1. 构建
hvigorw assembleHap

# 2. 安装到设备
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap

# 3. 启动应用
hdc shell aa start -b com.example.app -a EntryAbility

# 4. 看日志
hdc shell hilog -T MyAppTag

# 5. 性能：IDE Profiler，或设备端 hidumper/hiperf（见 01.hdc.md）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# CI/CD 要点

构建：hvigorw assembleHap --mode module -p buildMode=release（纯命令行，无需 IDE）
签名：预置证书 + build-profile.json5 signingConfigs（CI 内注入证书路径）
设备侧：hdc 命令全部可脚本化；注意高频操作用设备端循环（见 hdc §4）

# 虚构工具 → 真实能力对照表

旧文档虚构工具	真实替代
`arktsc` / `arkui build`	`hvigorw`（ArkTS 编译是 hvigor 任务）
`hap-builder`	`hvigorw assembleHap` / `assembleApp`
`signer`	`build-profile.json5` signingConfigs + IDE 自动签名
`profiler` / `memory-analyzer`	IDE Profiler + `hidumper --mem` / `--mem-jsheap`
`test-runner`	`@ohos/hypium` + `aa test`
`ui-test`	`uitest`（设备端，`hdc shell uitest ...`）
`simulator` / `device-sim`	IDE Device Manager + Emulator
`doc-generator`	不存在
`lint`	Code Linter（IDE 内置）
`config`	不存在（环境变量自行配置，见上文 PATH）
`hpm`	App 开发不使用（那是 OpenHarmony 系统组件场景的工具）；App 统一用 ohpm

# 多媒体开发

# 图像处理

图像加载
图像缓存
图像压缩
图像滤镜

# 音频处理

音频播放
音频录制
音频格式转换
音频效果

# 视频处理

视频播放
视频录制
视频编辑
视频压缩

# 设备能力

# 传感器

加速度传感器
陀螺仪传感器
光线传感器
距离传感器

# 硬件接口

相机接口
麦克风接口
蓝牙接口
NFC接口

# 系统服务

通知服务
权限管理
系统信息
设备管理

# 分布式能力

# 设备发现

设备扫描
设备连接
设备认证
设备管理

# 数据同步

数据分发
数据同步
冲突解决
数据一致性

# 服务共享

服务发现
服务调用
服务注册
服务管理

# 性能优化

性能优化是鸿蒙应用开发的重要环节，主要包括启动优化、内存优化和渲染优化。

# 启动优化

冷启动优化：减少应用启动时间，优化启动流程
热启动优化：提升应用切换响应速度
启动时间监控：使用性能分析工具监控启动性能
启动策略：合理设计应用启动逻辑

# 内存优化

内存泄漏检测：定期检查内存使用情况
内存使用监控：实时监控内存占用
垃圾回收优化：合理管理对象生命周期
内存压缩：优化内存使用效率

# 渲染优化

渲染性能监控：监控UI渲染性能
渲染优化策略：优化组件渲染逻辑
帧率优化：保持60fps流畅体验
渲染管线优化：优化渲染流程

详细性能优化指南：请参考下方"性能优化建议"章节。

# 调试与测试

调试和测试是确保应用质量的关键环节。

# 调试工具

DevEco Studio调试：使用IDE内置调试器
日志系统：合理使用console.log输出日志
性能分析：使用性能分析工具监控应用性能
内存分析：检测内存泄漏和优化内存使用

# 测试策略

单元测试：测试单个组件和函数
集成测试：测试组件间的交互
端到端测试：测试完整的用户流程
兼容性测试：确保在不同设备上的兼容性

详细调试测试指南：请参考下方"调试和测试技巧"章节。

# 发布与部署

# 应用打包

应用签名
应用打包
资源优化
代码混淆

# 应用分发

应用商店发布
企业分发
测试分发
版本管理

# 应用更新

增量更新
全量更新
强制更新
更新策略

# 安全开发

# 数据安全

数据加密
数据脱敏
数据备份
数据恢复

# 应用安全

代码混淆
反调试
完整性校验
安全审计

# 权限管理

权限申请
权限检查
权限动态管理
权限最小化

# 最佳实践

# 代码规范

命名规范
注释规范
代码结构
代码审查
ohpm包规范

# ohpm最佳实践

📖 详见独立手册 ohpm：锁文件提交入库、多模块 --all 安装、overrides 统一传递依赖版本、ohpm clean 彻底重装、私有源配置等实践均在其中。

# 架构设计

模块化设计
组件化设计
分层架构
微服务架构
包依赖架构

# 性能调优

性能监控
性能分析
性能优化
性能测试

# 常见问题解决

# 开发环境问题

环境配置问题
编译错误
运行错误
调试问题
ohpm依赖问题

# ohpm常见问题解决

📖 详见独立手册 ohpm §9：node 版本导致 node:events 报错、换源与连通性测试、依赖冲突定位（list -d + overrides）、锁文件损坏重装、内网自签证书等实测解法。

# 性能问题

内存泄漏
卡顿问题
耗电问题
网络问题

# 兼容性问题

设备兼容性
系统兼容性
API兼容性
数据兼容性

# 扩展资源

# 官方文档

# 开发工具

DevEco Studio - 官方IDE
鸿蒙模拟器 - 设备模拟
真机调试工具 - 设备调试
性能分析工具 - 性能监控
ohpm包管理器 - 依赖管理

# 社区资源

完整学习资源：请参考文档末尾的"学习资源"章节。

# 实际应用案例

# 基础应用开发

计算器应用
待办事项应用
天气应用
新闻应用

# 多媒体应用

音乐播放器
视频播放器
图片编辑器
录音应用

# 社交应用

即时通讯
社交网络
直播应用
短视频应用

# 工具应用

文件管理器
系统工具
开发工具
测试工具
包管理工具

# 性能优化建议

# 开发阶段优化

代码质量优化：编写高质量、可维护的代码
资源使用优化：合理使用图片、音频等资源
算法优化：选择高效的算法和数据结构
架构优化：设计合理的应用架构
依赖优化：管理好第三方依赖

# 运行时优化

内存使用优化：避免内存泄漏，合理管理内存
CPU使用优化：减少不必要的计算，优化算法
网络使用优化：合理使用网络资源，实现缓存策略
电池使用优化：减少后台活动，优化耗电操作

# 用户体验优化

界面响应优化：保持UI流畅响应
操作流畅性优化：优化用户交互体验
错误处理优化：提供友好的错误提示
用户引导优化：设计清晰的使用引导

# 调试和测试技巧

# 调试技巧

断点调试：使用DevEco Studio的断点功能
日志调试：合理使用console.log输出调试信息
性能调试：使用性能分析工具监控应用性能
内存调试：检测内存泄漏和优化内存使用

# 测试技巧

功能测试：确保应用功能正常工作
性能测试：测试应用在不同场景下的性能表现
兼容性测试：确保应用在不同设备上的兼容性
安全测试：检查应用的安全漏洞

# 错误处理

异常捕获：合理使用try-catch处理异常
错误恢复：提供错误恢复机制
错误报告：记录和报告错误信息
错误分析：分析错误原因并优化代码

# 常见陷阱和解决方案

# 开发陷阱

内存泄漏陷阱
性能陷阱
安全陷阱
兼容性陷阱
依赖管理陷阱

# 解决方案

最佳实践
设计模式
架构模式
优化策略
依赖管理策略

# 相关技术

# 前端技术

TypeScript - ArkTS的基础语言
JavaScript - 前端开发基础
React Native - 跨平台开发参考
Flutter - 移动开发对比学习

# 包管理工具

npm/yarn - 前端包管理工具
ohpm - 鸿蒙生态包管理工具
Maven/Gradle - Android包管理工具

# 🚀 实践项目：待办事项应用

让我们通过一个完整的待办事项应用来实践鸿蒙开发：

# 项目结构

TodoApp/
├── entry/
│   └── src/
│       └── main/
│           ├── ets/
│           │   ├── pages/
│           │   │   ├── Index.ets          # 主页面
│           │   │   └── AddTodo.ets        # 添加待办页面
│           │   ├── components/
│           │   │   └── TodoItem.ets       # 待办项组件
│           │   ├── models/
│           │   │   └── Todo.ets           # 数据模型
│           │   └── utils/
│           │       └── Storage.ets        # 存储工具
│           └── resources/
└── oh-package.json5

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 数据模型

// models/Todo.ets
export class Todo {
  id: string
  title: string
  completed: boolean
  createdAt: Date

  constructor(title: string) {
    this.id = Date.now().toString()
    this.title = title
    this.completed = false
    this.createdAt = new Date()
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 主页面

// pages/Index.ets
import { Todo } from '../models/Todo'
import { TodoItem } from '../components/TodoItem'
import { Storage } from '../utils/Storage'

@Entry
@Component
struct Index {
  @State todos: Todo[] = []
  @State newTodoTitle: string = ""

  aboutToAppear() {
    Storage.init(getContext(this))    // 初始化 Preferences 实例（需页面上下文）
    this.loadTodos()
  }

  private loadTodos() {
    this.todos = Storage.getTodos()
  }

  private addTodo() {
    if (this.newTodoTitle.trim()) {
      const todo = new Todo(this.newTodoTitle.trim())
      this.todos.push(todo)
      this.newTodoTitle = ""
      Storage.saveTodos(this.todos)
    }
  }

  private toggleTodo(id: string) {
    const todo = this.todos.find(t => t.id === id)
    if (todo) {
      todo.completed = !todo.completed
      Storage.saveTodos(this.todos)
    }
  }

  private deleteTodo(id: string) {
    this.todos = this.todos.filter(t => t.id !== id)
    Storage.saveTodos(this.todos)
  }

  build() {
    Column({ space: 20 }) {
      // 标题
      Text("待办事项")
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 20 })

      // 添加待办输入框
      Row({ space: 10 }) {
        TextInput({ placeholder: "输入待办事项" })
          .layoutWeight(1)
          .onChange((value: string) => {
            this.newTodoTitle = value
          })
          .onSubmit(() => {
            this.addTodo()
          })

        Button("添加")
          .onClick(() => {
            this.addTodo()
          })
      }
      .width('100%')
      .padding({ left: 20, right: 20 })

      // 待办列表
      List() {
        ForEach(this.todos, (todo: Todo) => {
          ListItem() {
            TodoItem({
              todo: todo,
              onToggle: () => this.toggleTodo(todo.id),
              onDelete: () => this.deleteTodo(todo.id)
            })
          }
        }, (todo: Todo) => todo.id)    // keyGenerator：以 id 为键，提升 diff 性能
      }
      .layoutWeight(1)
      .width('100%')
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

# 待办项组件

// components/TodoItem.ets
import { Todo } from '../models/Todo'

@Component
export struct TodoItem {
  @Prop todo: Todo
  onToggle?: () => void
  onDelete?: () => void

  build() {
    Row({ space: 10 }) {
      // 完成状态复选框
      Checkbox({ name: 'todo', group: 'todoGroup' })
        .select(this.todo.completed)
        .onChange((value: boolean) => {
          this.onToggle?.()
        })

      // 待办内容
      Text(this.todo.title)
        .fontSize(16)
        .decoration({
          type: this.todo.completed ? TextDecorationType.LineThrough : TextDecorationType.None
        })
        .fontColor(this.todo.completed ? '#999' : '#333')
        .layoutWeight(1)

      // 删除按钮
      Button("删除")
        .fontSize(12)
        .backgroundColor('#FF6B6B')
        .onClick(() => {
          this.onDelete?.()
        })
    }
    .width('100%')
    .padding(10)
    .backgroundColor('#FFF')
    .borderRadius(8)
    .margin({ bottom: 5 })
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# 存储工具

// utils/Storage.ets
import { preferences } from '@kit.ArkData'
import { Context } from '@kit.AbilityKit'
import { Todo } from '../models/Todo'

// JSON 反序列化后的原始形状（Date 经 stringify 变为 ISO 字符串）
interface TodoJson {
  id: string
  title: string
  completed: boolean
  createdAt: string
}

export class Storage {
  // preferences 模块没有模块级 putSync/getSync，
  // 必须先 getPreferencesSync(context, options) 拿到实例再操作
  private static pref: preferences.Preferences | undefined = undefined

  static init(context: Context): void {
    this.pref = preferences.getPreferencesSync(context, { name: 'todo_store' })
  }

  static saveTodos(todos: Todo[]): void {
    try {
      this.pref?.putSync('todos', JSON.stringify(todos))
      this.pref?.flush()    // putSync 只写内存缓存，flush 才落盘
    } catch (error) {
      console.error('保存待办事项失败:', error)
    }
  }

  static getTodos(): Todo[] {
    try {
      const data = this.pref?.getSync('todos', '[]') as string
      const list = JSON.parse(data) as TodoJson[]
      return list.map((item: TodoJson): Todo => {
        const t = new Todo(item.title)
        t.id = item.id
        t.completed = item.completed
        t.createdAt = new Date(item.createdAt)
        return t
      })
    } catch (error) {
      console.error('加载待办事项失败:', error)
      return []
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# ❓ 常见问题解答

# Q1: 如何调试鸿蒙应用？

A: 调试方法：

使用 DevEco Studio 的调试器
在代码中添加 console.log() 输出日志
使用 hdc shell 查看设备日志
利用性能分析工具监控应用性能

# Q2: 如何处理网络请求？

A: 网络请求示例：

import http from '@ohos.net.http'

async function fetchData() {
  const httpRequest = http.createHttp()
  try {
    const response = await httpRequest.request('https://api.example.com/data', {
      method: http.RequestMethod.GET,
      header: {
        'Content-Type': 'application/json'
      }
    })
    return JSON.parse(response.result as string)
  } catch (error) {
    console.error('网络请求失败:', error)
  } finally {
    httpRequest.destroy()
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Q3: 如何实现页面导航？

A: 页面导航示例：

import router from '@ohos.router'

// 跳转到新页面
router.pushUrl({
  url: 'pages/DetailPage',
  params: {
    id: '123',
    title: '详情页'
  }
})

// 返回上一页
router.back()

// 替换当前页面
router.replaceUrl({
  url: 'pages/NewPage'
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Q4: 如何管理应用状态？

A: 状态管理策略：

组件级状态：使用 @State 装饰器
页面级状态：使用 LocalStorage
应用级状态：使用 AppStorage
持久化状态：使用 PersistentStorage

# Q5: 如何优化应用性能？

A: 性能优化建议：

合理使用 @State 和 @Prop
避免在 build() 方法中进行复杂计算
使用 LazyForEach 处理大列表
及时释放不需要的资源
使用图片缓存和懒加载

# 📚 学习资源

# 官方文档

鸿蒙开发者官网 (opens new window) - 官方开发文档和教程
ArkTS语言指南 (opens new window) - ArkTS语言详细文档
ArkUI开发指南 (opens new window) - ArkUI框架开发指南
other
- 行业实践与常见问题 (opens new window)

# 开发工具

DevEco Studio (opens new window) - 官方IDE下载
ohpm官方文档 (opens new window) - 包管理器文档与包浏览门户
ohpm官方源 (opens new window) - 官方 registry（ohpm 默认值）

# 社区资源

# 🎉 总结

通过本指南的学习，你已经掌握了：

HarmonyOS 基础概念 - 理解了鸿蒙生态和架构
开发环境搭建 - 熟练配置开发工具链
ArkTS 语言 - 掌握了鸿蒙开发语言特性
ArkUI 框架 - 学会了构建用户界面
实际项目开发 - 完成了完整的应用开发

继续深入学习，探索鸿蒙生态的更多可能性！🚀

#HarmonyOS #Android

上次更新: 2026/10/18, 22:14:48

← gson hdc 速查手册 — HarmonyOS 设备调试连接器→