HarmonyOS Application Development with uni-app

uni-app is a framework that uses Vue.js to develop all front-end applications. Developers can write a single set of code and publish it to multiple platforms, including iOS, Android, Web, various mini-programs (WeChat/Alipay/Baidu/Toutiao/Feishu/QQ/Kuaishou/DingTalk/Taobao), quick apps, HarmonyOS, etc.

HBuilderX is the development tool for uni-app, which enables developers to conveniently build various cross-platform applications based on Vue.js.
● Starting from HBuilderX 4.24+, it supports running on the HarmonyOS platform.
● HarmonyOS development only supports Vue3 and does not support Vue2.
● The HarmonyOS runtime package built with HBuilderX 4.31+ does not support the x86_64 platform, which affects the inability to use the HarmonyOS emulator on Windows systems and some Mac systems. Real-device debugging is required.
● Versions prior to HBuilderX 4.31 support the x86_64 platform. Here, we use HBuilderX 4.29.

HarmonyOS Development Preparation: Configuring HBuilderX's Settings.json

To develop HarmonyOS applications with uni-app in HBuilderX, you need to configure the Settings.json file to ensure proper support for the HarmonyOS platform. Below is the recommended configuration:

HBuilderX relies on the HarmonyOS toolchain included in DevEco Studio, so your computer must have DevEco Studio installed with the required version.

Open HBuilderX, click Tools > Settings in the top menu, then click Runtime Configuration. In the HarmonyOS runtime configuration, set the installation path of DevEco Studio.

Creating a uni-app Project

1. Open HBuilderX Editor, go to File -> New -> Project.

2. Fill in the following:

Project Name: Use a short, descriptive name without spaces, Chinese characters, or special symbols (e.g., my-uni-app).
Save Path: Avoid deep directories. For better compatibility, save the project in the root directory of your drive (e.g., D:/projects/).
Select Vue3 Version: Ensure you choose Vue 3 as the framework version.

Running the Project on HarmonyOS

First Run: When running the project for the first time, a harmony-configs directory will be generated in the project root to store HarmonyOS configuration files.
Project Code Location: The HarmonyOS project code is generated under unpackage\debug. You can open it with DevEco Studio.

Running to HarmonyOS Emulator (unstable functionality)

Launch the HarmonyOS emulator
Run the project to the HarmonyOS device

Running to HarmonyOS Physical Device (Stable)

Connect the HarmonyOS physical device to the computer via USB
Run the project to the HarmonyOS device
Select the physical device

Physical device requires signature configuration

Copy the unpackage\debug\app-harmony@1.3.7 folder in the uniapp project to the desktop and rename it to app_harmony.
Open the app_harmony folder with DevEco Studio.
Use DevEco Studio to automatically sign the project (for physical device debugging).
Copy the signature information to the signingConfigs node in harmony-configs\build-profile.json5 of the uniapp project.

Compatibility Handling for First-time Compilation of New Projects

1. Incompatible Dependencies with Target Device

When running a uni-app project on HarmonyOS, you may encounter:
"Dependencies are incompatible with the target device."

Missing Permissions Authorization

Runtime permissions required by the app are not included in the signing profile.

2. Runtime Permissions Not Authorized in Signing Profile

https://uniapp.dcloud.net.cn/tutorial/harmony/runbuild.html#permissions-failed

uni-app Project Structure Explanation

uni.scss Global Style Sheet

https://uniapp.dcloud.net.cn/collocation/uni-scss.html

pages.json Page Routing

https://uniapp.dcloud.net.cn/collocation/pages.html#pages-json-%E9%A1%B5%E9%9D%A2%E8%B7%AF%E7%94%B1

uni-app UI Components Explanation

uni-app provides three types of components. Refer to the documentation for details:

Built-in Components - Compatible with HarmonyOS
uniUI Extended Components - Compatible with HarmonyOS
Third-party Components (downloaded from the plugin market) - Not all components are compatible with HarmonyOS; testing is required