# harmonyos-dev

> Complete HarmonyOS app development guide with ArkTS, Stage model, and ArkUI. Use when:
  - Creating new HarmonyOS projects ("Set up a new HarmonyOS project")
  - Developing UI with ArkUI components and state management
  - Integrating system capabilities (window, file, background tasks)
  - Adding media services (audio, video, camera)
  - Deploying to multiple devices with responsive layouts
  - Building cross-device collaboration features

  Use with harmonyos-design-guidelines for complete design+development workflow.

- Author: Kirky-X
- Repository: Kirky-X/DevCraft-AI
- Version: 20260115150227
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/Kirky-X/DevCraft-AI
- Web: https://mule.run/skillshub/@@Kirky-X/DevCraft-AI~harmonyos-dev:20260115150227

---

---
name: harmonyos-dev
description: |
  Complete HarmonyOS app development guide with ArkTS, Stage model, and ArkUI. Use when:
    - Creating new HarmonyOS projects ("Set up a new HarmonyOS project")
    - Developing UI with ArkUI components and state management
    - Integrating system capabilities (window, file, background tasks)
    - Adding media services (audio, video, camera)
    - Deploying to multiple devices with responsive layouts
    - Building cross-device collaboration features
  
    Use with harmonyos-design-guidelines for complete design+development workflow.
---

# HarmonyOS开发速览

## 典型开发场景

| 场景 | 推荐章节 | 关键步骤 |
|------|----------|----------|
| 新建项目 | [01快速入门](references/01-quickstart.md) | 环境检查 → 创建工程 → 运行验证 |
| 页面开发 | [03应用框架](references/03-application-framework.md) | 布局 → 组件 → 状态管理 → 导航 |
| 数据持久化 | [04系统能力](references/04-system-capabilities.md) | 偏好数据 → 文件管理 → 数据库 |
| 媒体功能 | [05媒体服务](references/05-media-services.md) | 音频播放 → 视频播放 → 相机拍照 |
| 多设备适配 | [09多端部署](references/09-multi-device-deployment.md) | 响应式布局 → 资源限定词 → 测试验证 |
| 跨设备流转 | [10自由流转](references/10-free-flow.md) | 分布式数据 → 跨设备拉起 → 任务流转 |
| 测试发布 | [14测试发布](references/14-testing-release.md) | 单元测试 → UI测试 → 签名打包 → 上架 |

## 设计+开发闭环

**开发前** → 参考 [harmonyos-design-guidelines](../harmonyos-design-guidelines/)：
- [视觉风格](references/visual-style.md) - 色彩、字体、图标规范
- [控件设计规范](references/component-specs.md) - 组件样式、交互规范
- [布局规范](references/layout-specs.md) - 布局原则、响应式设计
- [多设备设计](references/multi-device.md) - 手机/平板/折叠屏适配

**开发中** → harmonyos-dev：
- ArkTS 编码规范和语法
- ArkUI 组件使用和状态管理
- 系统能力集成和 API 调用

## 核心概念

| 领域 | 关键点 |
|------|--------|
| 语言 | ArkTS（TypeScript超集，声明式UI首选） |
| UI框架 | ArkUI（声明式开发范式） |
| 应用模型 | Stage模型（主推） |
| 包管理 | HAP（应用包）/ HSP（共享包） |
| 构建工具 | Hvigor（基于Gradle） |

## 14章节速查

| # | 章节 | 主题 | 适用场景 |
|---|------|------|----------|
| 01 | [快速入门](references/01-quickstart.md) | 环境搭建、首个应用 | 新项目启动 |
| 02 | [ArkTS基础](references/02-arkts-basics.md) | 类型、类、接口、泛型 | 语言基础 |
| 03 | [应用框架](references/03-application-framework.md) | Stage、ArkUI组件、状态管理 | UI开发核心 |
| 04 | [系统能力](references/04-system-capabilities.md) | 窗口、后台任务、文件 | 系统功能 |
| 05 | [媒体服务](references/05-media-services.md) | 音频、视频、相机 | 多媒体 |
| 06 | [图形服务](references/06-graphics-services.md) | 2D绘图、动画 | 自定义绘制 |
| 07 | [应用服务](references/07-application-services.md) | 位置、网络、推送 | 网络和连接 |
| 08 | [AI能力](references/08-ai-capabilities.md) | ML、语音、NLP | 智能功能 |
| 09 | [多端部署](references/09-multi-device-deployment.md) | 响应式布局、资源限定词 | 多设备适配 |
| 10 | [自由流转](references/10-free-flow.md) | 分布式数据、跨设备 | 设备协同 |
| 11 | [NDK开发](references/11-ndk-development.md) | C++、CMake、NAPI | 原生开发 |
| 12 | [资源管理](references/12-resource-management.md) | 资源定义、访问 | 资源适配 |
| 13 | [开发工具](references/13-development-tools.md) | DevEco Studio、命令行 | 开发效率 |
| 13a | [高级调试](references/13a-advanced-debugging.md) | HiTrace、跨语言调试 | 进阶调试 |
| 13b | [性能工具](references/13b-performance-tools.md) | AppAnalyzer、Profiler | 性能优化 |
| 13c | [命令行工具](references/13c-cli-tools.md) | hdc、ohpm、codelinter | CI/CD |
| 14 | [测试发布](references/14-testing-release.md) | 单元测试、签名发布 | 上架发布 |

## Kit导入速查

### 应用框架
```typescript
import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { Context, bundleManager } from '@kit.AbilityKit';
```

### UI组件
```typescript
import { router, promptAction } from '@kit.ArkUI';
import { Component, State, Prop, Link, Provide, Consume, Observed, ObjectLink } from '@kit.ArkUI';
```

### 基础服务
```typescript
import { BusinessError } from '@kit.BasicServicesKit';
import { preferences, relationalStore } from '@kit.ArkData';
```

### 媒体服务
```typescript
import { audio, media, image } from '@kit.MultimediaKit';
```

### 性能追踪
```typescript
import { hiTraceMeter } from '@kit.HmsHutrace';
import { hiAppEvent } from '@kit.HmsHiview';
```

## 开发命令

### 构建
```bash
# Debug 构建
hvigorw assembleApp --debug

# Release 构建
hvigorw assembleApp --release

# 清理构建
hvigorw clean

# 模块构建
hvigorw assembleHap -p entry
```
详细命令和CI/CD集成：参见 [命令行工具](references/13c-cli-tools.md)

### 安装与运行
```bash
# 安装 HAP
hdc install entry.hap

# 卸载应用
hdc uninstall com.example.app

# 启动应用
hdc shell aa start -b com.example.app -a EntryAbility
```
设备管理命令：参见 [命令行工具](references/13c-cli-tools.md)

### 调试
```bash
# 查看日志
hdc shell hilog

# 实时日志
hdc shell "hilog | grep com.example.app"

# 查看设备列表
hdc list targets

# 截图
hdc shell snapshotdisplay -m 0 -f /data/local/tmp/screen.png"
hdc file pull /data/local/tmp/screen.png
```
高级调试技术：参见 [高级调试工具](references/13a-advanced-debugging.md)

### 测试
```bash
# 代码检查
codelinter --path ./project --fix

# 单元测试
hvigorw test

# UI测试
hvigorw uitest
```
代码检查详情：参见 [命令行工具](references/13c-cli-tools.md)

### 包管理
```bash
# 安装依赖
ohpm install <package>

# 更新依赖
ohpm update <package>

# 发布包
ohpm publish
```
包管理详细用法：参见 [命令行工具](references/13c-cli-tools.md)

## 快速开始

### 新手路径（推荐）
```
1. 阅读 01-quickstart.md → 创建第一个项目
2. 阅读 02-arkts-basics.md → 掌握 ArkTS 基础
3. 阅读 03-application-framework.md → 学习 UI 开发
4. 实践：完成一个简单的页面功能
```

### 有经验开发者
- 直接查阅对应章节
- 参考 03-application-framework.md 进行 UI 开发
- 参考 14-testing-release.md 进行发布准备

## 常见问题

### 编译问题
- **依赖下载失败**：检查网络代理配置
- **API 不存在**：确认 SDK 版本和目标设备兼容性
- **类型错误**：使用 TypeScript 严格模式检查

### 运行时问题
- **白屏**：检查路由配置和页面路径
- **卡顿**：使用 LazyForEach 优化长列表
- **内存泄漏**：及时释放媒体资源和定时器

### 性能优化
- 状态管理：使用 @State/@Prop 而非全量更新
- 列表优化：LazyForEach + @RecycleListItem
- 图片处理：使用 ImagePacker 进行压缩
- 资源释放：onPageHide/onBackground 中释放资源

完整文档：[development-guide.md](references/development-guide.md)