Comprehensive Guide to Developing Applications on HarmonyOS (Huawei)

1. Overview

HarmonyOS (also known as HarmonyOS, development codename Ark) is Huawei's distributed operating system that supports native HarmonyOS apps and AOSP‑compatible apps, enabling phones, tablets, TVs, cars, and wearables to function as a single "super terminal" for seamless resource sharing.

1.1 Introduction

HarmonyOS is a distributed OS that integrates multiple device types into one ecosystem, allowing developers to build cross‑device applications.

1.2 What Readers Will Gain

Comprehensive understanding of the HarmonyOS system.

Step‑by‑step guidance to start developing HarmonyOS applications from scratch.

1.3 HarmonyOS Development Basics

1.3.1 Framework Overview

The HarmonyOS application development framework provides APIs and components for rapid app creation, supporting Java, C++, JavaScript, and ArkTS.

1.3.2 Main Features

Cross‑platform development : One codebase can target phones, tablets, TVs, cars, etc.

Modular development : Choose only needed modules to avoid code bloat.

Flexible layout and UI design : Rich layout tools enable diverse interactions.

Performance optimization and debugging tools : Built‑in utilities help improve efficiency and stability.

1.3.3 Language and Development Paradigm

Two development paradigms are supported:

Name

Language Ecosystem

UI Update Method

Suitable Scenarios

Target Developers

Declarative paradigm

ArkTS

Data‑driven updates

Complex, team‑based programs

Mobile and system app developers

Class‑Web paradigm

JS

Data‑driven updates

Simple UI pages and cards

Web front‑end developers

Language selection:

ArkTS : Supports only the Stage model.

JS : Supports both Stage and FA models.

The Stage model (introduced in API 9) is the officially recommended model for new projects.

2. Setting Up the HarmonyOS Development Environment

2.1 Install DevEco Studio

Download the DevEco Studio SDK from the official website.

2.2 Configure the Development Environment

2.2.1 (Optional) Proxy Configuration

If direct Internet access is unavailable, configure a proxy server; otherwise, skip this step.

2.2.2 Install Node.js and ohpm

Node.js version 14.19.1 – < 17.0.0 and npm ≥ 6.14.16 are required. Install locally or use the online installer.

2.2.3 Download HarmonyOS SDK

Follow the UI prompts in DevEco Studio to download the SDK.

2.2.4 Create a HarmonyOS Application

Use the "New Project" wizard to generate a starter project.

2.2.5 Run the Project

Click the ▶️ button on the toolbar or press Shift+F10 (macOS: Control+R ) to launch the app.

3. Development Guide

3.1 Project Structure and Configuration

Key directories:

src/main/ets : ArkTS source files.

src/main/ets/entryability : Entry points for abilities.

src/main/ets/pages : UI pages.

src/main/resources : Images, strings, layouts, etc.

src/main/module.json5 : Stage model module configuration.

build-profile.json5 : Build options and target devices.

hvigorfile.ts : Custom build scripts.

oh_modules : Third‑party library dependencies.

3.2 ArkUI Framework

ArkTS is the preferred language. The ArkUI declarative framework provides high‑performance, cross‑device UI components.

3.2.3 ArkTS Advantages

High development efficiency and excellent developer experience.

Superior performance.

Rapid ecosystem growth.

3.3 Component and Layout Summary (API 9)

ArkUI includes an XComponent bridge for C++ rendering (e.g., game engines) and HTML5/Web rendering.

XComponent({id:'',type:'texture',librayname:'nativerender'}).onload((context)=>{

}).onDestroy(()=>{

})

3.4 UI Development

3.4.1 Network Requests

Example using @ohos.net.http (API 6):

// Import package
import http from '@ohos.net.http';
let httpRequest = http.createHttp();
httpRequest.on('headersReceive', (header) => {
  console.info('header: ' + JSON.stringify(header));
});
httpRequest.request(
  "EXAMPLE_URL",
  {
    method: http.RequestMethod.POST,
    header: {'Content-Type': 'application/json'},
    extraData: {"data": "data to send"},
    expectDataType: http.HttpDataType.STRING,
    usingCache: true,
    priority: 1,
    connectTimeout: 60000,
    readTimeout: 60000,
    usingProtocol: http.HttpProtocol.HTTP1_1,
  },
  (err, data) => {
    if (!err) {
      console.info('Result:' + JSON.stringify(data.result));
      console.info('code:' + JSON.stringify(data.responseCode));
      console.info('header:' + JSON.stringify(data.header));
      console.info('cookies:' + JSON.stringify(data.cookies));
      httpRequest.off('headersReceive');
      httpRequest.destroy();
    } else {
      console.info('error:' + JSON.stringify(err));
      httpRequest.off('headersReceive');
      httpRequest.destroy();
    }
  }
);

3.4.2 Data Storage

@ohos.data.storage – lightweight storage.

@ohos.data.rdb – relational database.

@ohos.data.distributedData – distributed data management.

3.4.3 Page Routing

export default {
  indexPushPage() {
    router.push({uri: 'pages/detail/detail'});
  }
}

3.5 Permission Management

All HarmonyOS apps run in a sandbox; permissions must be declared and requested.

3.5.3 Permission Declaration (JSON)

{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:permreason_camera",
        "usedScene": {
          "ability": ["com.mycamera.Ability", "com.mycamera.AbilityBackground"],
          "when": "always"
        }
      },
      ...
    ]
  }
}

3.5.4 Dynamic Request

if (verifySelfPermission("ohos.permission.CAMERA") != IBundleManager.PERMISSION_GRANTED) {
  if (canRequestPermission("ohos.permission.CAMERA")) {
    requestPermissionsFromUser(new String[]{"ohos.permission.CAMERA"}, MY_PERMISSIONS_REQUEST_CAMERA);
  } else {
    // Show rationale and direct user to settings
  }
} else {
  // Permission already granted
}

3.6 State Management

Decorators such as @State , @Prop , @Link , @Provide/@Consume , @Observed , and @ObjectLink enable one‑way and two‑way data binding across components.

@Component
struct MyComponent {
  @State count: number = 0;
  private increaseBy: number = 1;

  build() {}
}

@Component
struct Parent {
  build() {
    Column() {
      MyComponent({ count: 1, increaseBy: 2 })
    }
  }
}

3.7 Thread Communication

Use Emitter for event subscription and emission, and @ohos.worker for worker threads.

// Main thread creates a worker
import worker from '@ohos.worker';
let wk = new worker.ThreadWorker('entry/ets/workers/worker.ts');
wk.postMessage('message from main thread');
wk.onmessage = function(message) {
  console.info('message from worker: ' + message);
  wk.terminate();
};

3.8 Process Communication

Two mechanisms are available: IPC (Binder driver) and RPC (soft‑bus driver). Implementations involve extending IRemoteBroker , IRemoteStub / RemoteObject , and IRemoteProxy / RemoteProxy , then registering and obtaining the service.

3.9 Device Unique Identifiers

OAID – Huawei‑generated UUID, consistent across apps on the same device.

NetworkID – Changes after reboot.

DVID – Requires HarmonyOS account login.

UUID – Globally unique.

3.10 Adaptation

3.10.1 Internationalization (I18n)

import I18n from '@ohos.i18n';
let rtl = I18n.isRTL('ar'); // true for right‑to‑left languages
let language = I18n.System.getDisplayLanguage('en', 'zh-CN', false); // "英语"
let country = I18n.System.getDisplayCountry('US', 'zh-CN', false); // "美国"
let isSuggest = I18n.System.isSuggested('zh', 'CN'); // true

3.10.2 Screen Adaptation

Define UI dimensions in float.json and reference them with $r :

{
  "float": [
    {"name": "btn_height", "value": "40vp"},
    {"name": "value_height", "value": "28vp"}
  ]
}
Button($r('app.string.pixel_introduce'))
  .height($r('app.float.btn_height'))
  .width(Constants.FULL_PERCENT)
  .backgroundColor($r('app.color.blue_background'))
  .onClick(() => this.jumpPage(Constants.INTRODUCTION_PAGE_URL));

3.10.3 Dark Mode and Other Themes

Use the Resource File wizard to create color‑mode specific resources.

4. Application Testing

4.1 Test Standards

Performance, security, compatibility, stability, power consumption, flow, and game testing.

4.2 Test Frameworks

Unit testing is performed with hypium (HarmonyOS test framework).

"dependencies": {
  "@ohos/hypium": "1.0.6"
}

import { describe, it, expect } from '@ohos/hypium';
export default function abilityTest() {
  describe('ActsAbilityTest', function () {
    it('assertContain', 0, function () {
      let a = 'abc';
      let b = 'b';
      expect(a).assertContain(b);
      expect(a).assertEqual(a);
    });
  });
}

5. Application Publishing

The publishing flow includes app signing, security review, and submission to the Huawei AppGallery. A flowchart illustrates the steps.

6. References and Resources

https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/deveco_overview-0000001053582387-V3

https://developer.harmonyos.com/cn/develop/deveco-studio#download

https://nodejs.org/en