HarmonyOS 开发技能

概述

HarmonyOS 是华为的分布式操作系统，应用默认使用 ArkTS 语言开发，基于 Stage 模型。

来源

> 来源：华为 HarmonyOS 开发者文档（2026-04-23 访问）

> - 文档中心：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides

> - ArkTS 语言：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/introduction-to-arkts

> - ArkUI 框架：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-basic-syntax-overview

> - Stage 模型：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-configuration-file-stage

> - 资源管理：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/resource-categories-and-access

>

> 更新频率：随 HarmonyOS 版本迭代（当前覆盖 5.0~6.1）

快速开发路径

1. 环境：DevEco Studio（方舟开发编辑器）
2. 语言：ArkTS（TypeScript 超集，静态类型+声明式 UI）
3. 框架：ArkUI（声明式 UI 框架）
4. 模型：Stage 模型（推荐）

文档导航

入门

• 快速入门
• 应用开发导读
• 开发基础知识

ArkTS 语言

• 初识 ArkTS
• ArkTS 语言介绍 — 完整语法参考
• ArkTS 编程规范
• ArkTS 迁移指导（从 TypeScript）
• ArkTS 高性能编程

应用框架

• 应用程序包概述 — HAP/HAR/HSP
• 应用配置文件 Stage 模型
• 资源分类与访问

ArkUI

• ArkUI 基本语法概述
• ArkUI 组件参考

ArkTS 语言基础

核心概念速查

ArkTS vs TypeScript 关键差异（API version 10+）

ArkTS 在 TS 基础上做了以下限制：

1. 强制静态类型 — 所有变量必须有确定类型，禁止运行期改变对象布局
2. 禁止 Structural Typing — 不支持按结构匹配类型
3. 限制运算符语义 — 一元加法仅能作用于数字
4. 所有类型默认非空 — let x: number = null 编译错误，需声明为 number | null

Module 类型（HAP/HAR/HSP）

资源目录结构

resources/
├── base/
│   ├── element/      # 字符串、颜色、尺寸等元素资源
│   ├── media/        # 图片、音视频等媒体资源
│   └── profile/      # 自定义配置文件
├── zh_CN/            # 限定词目录（语言_地区-横竖屏-设备类型-颜色模式-屏幕密度）
├── dark/             # 深色模式
└── rawfile/          # 原始文件，不编译

资源访问：$r('app.type.name') 或 $rawfile('path/file.png')

系统资源：$r('sys.type.name')

典型开发流程

典型开发流程

1. 创建工程：DevEco Studio 新建项目，选 Stage 模型 + ArkTS
2. 编写 UI：.ets 文件，用 @Component + build() 声明 UI
3. 配置 Ability：在 module.json5 中注册 UIAbility/EntryAbility
4. 管理资源：在 resources/ 下按限定词组织资源文件
5. 构建调试：DevEco Studio 内置 hvigor 构建系统
6. 发布应用：签名打包 HAP，通过 AppGallery Connect 发布

完整页面示例（ArkUI + MVVM）

// Model
interface User {
  id: number;
  name: string;
  email: string;
}

// ViewModel（使用 TaskPool 进行网络请求）
import { taskpool } from '@kit.ArkTS';

@Concurrent
async function fetchUsersFromServer(): Promise<User[]> {
  // 模拟网络请求
  const response = await http.createHttp();
  const result = await response.request('https://api.example.com/users');
  return JSON.parse(result.result as string) as User[];
}

// ViewModel
class UserListViewModel {
  @State users: User[] = [];
  @State isLoading: boolean = false;
  @State error: string = '';

  async loadUsers() {
    this.isLoading = true;
    this.error = '';
    try {
      const task = new taskpool.Task(fetchUsersFromServer);
      this.users = await taskpool.execute(task) as User[];
    } catch (e) {
      this.error = (e as Error).message;
    } finally {
      this.isLoading = false;
    }
  }
}

// View
@Entry
@Component
struct UserListPage {
  @State viewModel: UserListViewModel = new UserListViewModel();

  build() {
    Column() {
      // 标题栏
      Row() {
        Text('用户列表')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
        Blank()
        if (this.viewModel.isLoading) {
          ProgressView()
            .width(24)
            .height(24)
        }
      }
      .width('100%')
      .padding(16)
      .backgroundColor(Color.White)

      // 错误提示
      if (this.viewModel.error) {
        Text(`错误: ${this.viewModel.error}`)
          .fontColor(Color.Red)
          .fontSize(14)
          .padding(16)
      }

      // 用户列表
      List({ space: 10 }) {
        ForEach(this.viewModel.users, (user: User) => {
          ListItem() {
            this.UserItem(user)
          }
          .swipeAction({ end: this.DeleteAction(user.id) })
        }, (user: User) => user.id.toString())
      }
      .width('100%')
      .layoutWeight(1)
      .padding(16)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
    .onAppear(() => {
      this.viewModel.loadUsers();
    })
  }

  @Builder
  UserItem(user: User) {
    Row({ space: 12 }) {
      Column() {
        Text(user.name)
          .fontSize(17)
          .fontWeight(FontWeight.Medium)
        Text(user.email)
          .fontSize(14)
          .fontColor('#666666')
      }
      .alignItems(HorizontalAlign.Start)
      Blank()
      Text(`#${user.id}`)
        .fontSize(12)
        .fontColor('#999999')
    }
    .width('100%')
    .padding(16)
    .backgroundColor(Color.White)
    .borderRadius(12)
  }

  @Builder
  DeleteAction(id: number) {
    Button('删除')
      .type(ButtonType.Normal)
      .height('100%')
      ..width(80)
      .backgroundColor(Color.Red)
      .onClick(() => {
        // 删除逻辑
        const index = this.viewModel.users.findIndex(u => u.id === id);
        if (index >= 0) {
          this.viewModel.users.splice(index, 1);
        }
      })
  }
}

EntryAbility 配置（module.json5）

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone", "tablet"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "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"]
          }
        ]
      }
    ]
  }
}

资源文件（resources/base/element/string.json）

{
  "string": [
    {
      "name": "module_desc",
      "value": "用户列表演示应用"
    },
    {
      "name": "EntryAbility_desc",
      "value": "主入口Ability"
    },
    {
      "name": "EntryAbility_label",
      "value": "用户列表"
    }
  ]
}

架构与网络

架构模式

ArkUI MVVM 架构

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│    View     │ ←── │  ViewModel  │ ←── │   Model    │
│  (@Component)│     │ (@State/@Link)│     │ (interface) │
└─────────────┘     └──────────────┘     └─────────────┘
     build()              @State             数据结构
     @Builder            @Link               函数

数据流向：

1. View 通过 @State/@Link 绑定 ViewModel 的状态
2. ViewModel 处理业务逻辑，调用 Service/Repository
3. Model 定义数据结构（interface）
4. 状态变化自动触发 UI 重新渲染

状态管理对比

网络层封装

// 统一网络服务
class HttpService {
  private baseUrl = 'https://api.example.com';

  async request<T>(config: RequestConfig): Promise<T> {
    const http = http.createHttp();
    try {
      const response = await http.request(this.baseUrl + config.url, {
        method: config.method || 'GET',
        header: config.headers,
        extraData: config.body,
        connectTimeout: 30000,
        readTimeout: 30000
      });
      http.destroy();
      return JSON.parse(response.result as string) as T;
    } catch (e) {
      http.destroy();
      throw e;
    }
  }

  get<T>(url: string): Promise<T> {
    return this.request<T>({ url, method: 'GET' });
  }

  post<T>(url: string, body: object): Promise<T> {
    return this.request<T>({ url, method: 'POST', body });
  }
}

// 使用
const httpService = new HttpService();
const users = await httpService.get<User[]>('/users');

持久化方案

// AppStorage 使用
AppStorage.setOrCreate('username', 'John');
const username = AppStorage.get<string>('username');

// 持久化存储
import { userinfoStore } from '@kit.ArkData';

let context = getContext(this);
const store = await userinfoStore.getUserinfoStorageInstance(context);
await store.insert('user', { name: 'John', age: 30 });
const result = await store.query('user', []);

路由管理

import router from '@ohos.router';

// 路由配置（main_pages.json）
{
  "src": [
    {
      "name": "Home",
      "pageSourceFile": "./ets/pages/Home/Home.ets",
      "window": { "designWidth": 720 }
    },
    {
      "name": "Detail",
      "pageSourceFile": "./ets/pages/Detail/Detail.ets"
    }
  ]
}

// 路由跳转
router.pushUrl({ url: 'pages/Detail/Detail', params: { id: 123 } });

// 获取参数
const params = router.getParams() as { id: number };

依赖注入（Kit 方式）

// 方式一：直接导入
import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';

// 方式二：服务发现
import serviceDiscovery from '@kit.ArkUI';

// 方式三：@ohos 兼容方式（已废弃，不推荐）
import UIAbility from '@ohos.app.ability.UIAbility';

性能优化

任务池（TaskPool）

import { taskpool } from '@kit.ArkTS';

// 定义并发函数
@Concurrent
function heavyTask(numbers: number[]): number {
  return numbers.reduce((sum, n) => sum + n, 0);
}

// 执行任务
let task = new taskpool.Task(heavyTask, [[1, 2, 3, 4, 5]]);
let result = await taskpool.execute(task);

// 取消任务
taskpool.cancelTask(task);

测试策略

// 单元测试（import test from '@kit.ArkTS'）
import test from '@kit.ArkTS';

@Entry
@Component
struct Calc {
  @State result: number = 0;

  add(a: number, b: number): number {
    return a + b;
  }
}

// UI 测试：使用 DevEco Studio 内置测试框架
// 性能测试：使用 hdc hilog 抓取性能日志

调试技巧

// 日志打印
import hilog from '@ohos.hilog';

hilog.info(0x0000, 'UserModule', 'User login: %{public}s', username);

// 条件断点
// 在 DevEco Studio 中设置条件表达式

快速参考

ArkUI 常用组件速查

ArkTS 类型速查

HarmonyOS 权限速查

常用 API 速查

布局速查

// 垂直布局 Column
Column({ space: 10 }) {
  Text('Header')
  Row() { /* 内容 */ }
}
.width('100%')
.height('100%')
.alignItems(HorizontalAlign.Center)
.justifyContent(FlexAlign.Center)

// 水平布局 Row
Row({ space: 12 }) {
  Image('icon.png').width(24).height(24)
  Text('Label')
  Blank()
  Text('Value')
}
.width('100%')
.padding(16)

// 弹性布局 Flex
Flex({ direction: FlexDirection.Row, wrap: FlexWrap.Wrap }) {
  ForEach(items, (item) => {
    ItemComponent({ item: item })
      .width('30%')
      .margin(5)
  })
}

// 层叠布局 Stack
Stack() {
  Background()
  Content()
  FloatingButton()
}
.alignContent(Alignment.BottomEnd)

生命周期速查

版本兼容性速查

常见 ArkTS 模式

常见 ArkTS 模式

状态管理

@Entry
@Component
struct MyPage {
  @State message: string = 'Hello';
  build() {
    Column() {
      Text(this.message)
    }
  }
}

导入 HarmonyOS SDK

// 方式一：Kit 方式（推荐）
import { UIAbility, Ability, Context } from '@kit.AbilityKit';

// 方式二：直接模块
import UIAbility from '@ohos.app.ability.UIAbility';

动态导入

async function loadModule() {
  let module = await import('./Calc');
  module.add(3, 5);
}

参考文档

避坑指南

ArkTS 编译期强制规则

ArkUI 运行时注意

Stage 模型注意

版本陷阱

• ⚠️ API v22+ — HTTP 拦截器需要 API version 22+
• ⚠️ Kit 方式导入 — @kit.AbilityKit 是 API v22+ 推荐方式
• ⚠️ 注解限制 — 注解仅在 .ets/.d.ets 文件有效，release 混淆会被移除
• ⚠️ 注解字段类型 — 仅支持 boolean/number/string 及其数组
• ⚠️ Flex 布局 — 默认不换行，需要 wrap: FlexWrap.Wrap 才能换行
• ⚠️ Grid 循环 — ForEach 在 Grid 内必须配合 ListItem() 使用

输出格式规范

当使用本技能回答用户问题时，遵循以下格式：

回复结构

1. 直接回答 — 一段简洁的话给出核心答案
2. 代码示例 — ArkTS/ArkUI 示例代码（按需）
3. 避坑提醒 — 常见错误+正确做法
4. 文档链接 — 华为开发者文档相关链接（如适用）

示例回复（ArkTS 空安全）

> ArkTS 所有类型默认非空，let x: number = null 会编译错误。正确做法是声明为 let x: number | null = null。访问可空变量时用 ?? 合并操作符：this.nick ?? ''。如果确认变量有值，可用 ! 非空断言，但需确保运行时不为空。

禁用格式

• ❌ 不要显式分层（避免"第一层/第二层/框架分析"等字眼）
• ❌ 不要长篇引用华为文档，要内化为自己的话
• ✅ 输出应是一段干净的话