name: harmonyos-dev description: > HarmonyOS 應用開發技能（覆蓋 5.0~6.1 版本）。基於 ArkTS 語言，支援 Stage 模型應用開發、 ArkUI 宣告式 UI、UIAbility 生命週期、資源管理、許可權配置、媒體處理、AI 整合、 分散式流轉等完整開發流程。當用戶提到 HarmonyOS、鴻蒙應用開發、ArkTS、Stage模型、 HAP/HAR/HSP 包開發、ArkUI 元件、分散式能力時觸發。 trigger: HarmonyOS|鴻蒙|鴻蒙應用|ArkTS|Stage模型|HAP|HAR|HSP|ArkUI|UIAbility|DevEco|鴻蒙開發|harmonyos|HarmonyOS應用|分散式能力|AbilityKit|ohos.net|@kit tags: - harmonyos - arkts - arkui - stage-model - harmonyos-dev - huawei hermes: tags: [harmonyos, arkts, arkui, stage-model, harmonyos-dev, huawei, ability, hap, har, hsp] related_skills: [apple-design, frontend-design] version: "2.0.0" last_updated: "2026-04-23" source: | https://developer.huawei.com/consumer/cn/doc/harmonyos-guides https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/introduction-to-arkts https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-basic-syntax-overview 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 license: MIT

HarmonyOS 開發技能

概述

HarmonyOS 是華為的分散式作業系統，應用預設使用 ArkTS 語言開發，基於 Stage 模型。

來源

小蔥技能7w4.net持續更新中。

來源：華為 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 ?? ''。如果確認變數有值，可用 ! 非空斷言，但需確保執行時不為空。

停用格式

• ❌ 不要顯式分層（避免"第一層/第二層/框架分析"等字眼）
• ❌ 不要長篇引用華為文件，要內化為自己的話
• ✅ 輸出應是一段乾淨的話