uni-app x Cross-Platform Getting Started and Practice: Develop HarmonyOS 5 Applications

苏杰豪 — Fri, 27 Jun 2025 10:29:47 +0000

uni-app x Cross-Platform Getting Started and Practice: Develop HarmonyOS 5 Applications

Course Introduction

What You Will Gain

Core logic of uni-app x for developing native HarmonyOS applications
Multi-platform interface adaptation thinking and code compatibility practice
Complete a publishable cross-platform application from 0 to 1
Acquire multi-platform application development capabilities (HarmonyOS Next/Android/iOS/WeChat Mini Program/Web)

Target Audience

HarmonyOS application development engineers who want to enter the cross-platform field
Technology enthusiasts who want to learn HarmonyOS and mini program development but lack practical cases
Partners who have learned uni-app and want to advance to the next-generation uni-app x technology stack
Mobile development engineers who want one codebase to cover multiple platforms
Enterprise developers or startup teams who need to quickly develop multi-platform applications

Course Overview

This course uses "Random Jokes" as a practical case to comprehensively analyze the cross-platform development process based on uni-app x. Through full-chain practice from environment setup, feature development to multi-platform adaptation, students will master the core syntax of uni-app x, cross-platform component invocation, screen adaptation techniques, and multi-platform (HarmonyOS Next/Android/iOS/WeChat Mini Program/Web) packaging and deployment capabilities. The course combines real development scenarios such as Huawei foldable screen adaptation and cloud packaging, focusing on practical implementation and cutting-edge technology coverage, helping developers quickly get started with cross-platform application development and accumulate project experience.

Course Highlights

Practice-driven, learn and apply immediately: Using complete open-source projects as carriers, covering the full process from requirement analysis to online deployment, avoiding pure theoretical stacking, focusing on code implementation and problem solving (such as foldable screen adaptation, multi-platform style compatibility).
Multi-platform adaptation core technology breakdown: In-depth analysis of uni-app x cross-platform principles, mastering differentiated adaptation strategies for different devices and platforms through hands-on practice like Huawei foldable screen adaptation, HarmonyOS platform signing configuration, and compatibility handling.
Cutting-edge technology and ecosystem coverage: Combining HarmonyOS (HarmonyOS Next) development, Uni TypeScript syntax, SCSS style preprocessing and other technologies, adapting to current cross-platform development trends.

Platform Compatibility

HarmonyOS NEXT / HarmonyOS 5 ✅
Android ✅
iOS ✅
WeChat Mini Program ✅
Web (Browser) ✅

Running Effects

iPhone, Android, HarmonyOS Mate X (Unfolded), WeChat Mini Program

)

iPhone, Android, HarmonyOS Mate X (Folded), WeChat Mini Program

Technology Stack

UniApp X
Uni TypeScript
Vue 3

Development Tools

Operating System: MacOS 15.4.1
Editor: HBuilder X 4.65
HarmonyOS Development Environment: DevEco Studio 5.0.4 Release
Android Development Environment: Android Studio (version 2024.2)
iOS Development Environment: Xcode Version 16.1 (16B40)
Browser: Chrome 135.0.7049.85

uni-app x

uni-app x Introduction

uni-app x is the next-generation uni-app, a cross-platform application development engine that now supports compilation into HarmonyOS Next native applications (4.61+)

uni-app x includes the uvue rendering engine, uts language, uni components and APIs, and extension mechanisms.

uvue Rendering Engine

Quickly write pages using the vue3 framework, ultimately compiling into high-performance pure native interfaces for different platforms.

Template-based writing
Data two-way binding
Component mechanism

On the HarmonyOS Next platform, uni-app x projects are compiled entirely into ArkTS + ArkUI code, essentially native HarmonyOS applications written with vue syntax.

uts Language

uts stands for uni typescript, a strongly-typed modern programming language. It supports cross-platform and will ultimately be compiled into native languages for different platforms, such as:

web/mini program platforms, compiled to JavaScript
HarmonyOS next platform, compiled to ArkTS
Android platform, compiled to Kotlin
iOS platform, compiled to Swift

uts is very similar to ts, but for cross-platform compatibility, uts has some constraints and platform-specific additions. See uts Language Introduction for details

Note: In ts, object types are often defined through interface or type, but in uts, you need to use type to define object types. Because interface has differences in kotlin and swift.

uni Components

uni-app x components are mainly divided into three categories:

Built-in basic components: such as view, text, image, scroll-view, input... etc., see Component List for details
Custom components: Components encapsulated by developers using vue syntax.
uts component plugins: Third-party components that can be downloaded through the Plugin Market.

Preparation

Development Environment Setup

Download and install HBuilderX editor
Create uni-app x project through HbuilderX

Project Directory Structure

├─pages             Directory for storing business page files
│  └─index
│     └─index.uvue  index page
├─static            Directory for storing local static resources referenced by the application (Note: static resources can only be stored here)
├─unpackage         Non-project code, generally stores compilation results for running or publishing
├─index.html        H5 page
├─main.uts          Vue initialization entry file
├─App.uvue          Application configuration, used to configure App global styles and listeners
├─pages.json        Configure page routing, navigation bar, tab bar and other page information
├─manifest.json     Configure application name, appid, logo, version and other packaging information
└─uni.scss          Built-in common style variables for uni-app

Compile and Run

Install uni-app x compiler plugin
Compile and run HarmonyOS native application

Project Practice

Effect Preview

Material Download

Project Image Materials.zip

Structure and Styling

Use uni-app x component library to implement basic project layout.

Layout Key Points:

view component defaults to flex mode with vertical column direction
uni-app x styles are not inherited, text needs to be wrapped with text and styled separately

Reference Code:

<template>
  <view class="container">
    <!-- Card container -->
    <view class="card">
      <!-- Header title -->
      <view class="header">
        <text class="header-text">Random Jokes</text>
      </view>
      <!-- Scroll content area -->
      <scroll-view class="scroll-content">
        <text class="scroll-content-text">Loading jokes...</text>
      </scroll-view>
      <!-- Footer button -->
      <view class="footer">
        <button class="footer-button">Next One</button>
      </view>
    </view>
  </view>
</template>

<style lang="scss">
.container {
  /* Note 1: view defaults to flex with column direction */
  /* display: flex; */
  /* flex-direction: column;  */
  /* Note 2: uni-app x styles are not inherited, text needs to be wrapped with text and styled separately */
  /* font-size: 100rpx; */
  flex: 1;
  justify-content: center;
  align-items: center;
  background-color: #f6f6f6;
}

.card {
  width: 90%;
  border-radius: 20rpx;
  /* 1. Box shadow: X offset, Y offset, blur radius and color */
  box-shadow: 0 10rpx 30rpx #a7b3f9;
  /* iOS has compatibility issues, needs to be set to white actively */
  background-color: #fff;
}

.header {
  background-color: #1534f5;
  height: 110rpx;
  padding: 0 30rpx;
  /* iOS border-radius is not constrained by parent, needs to be set actively */
  border-radius: 20rpx 20rpx 0 0;

  /* 2. Center vertically on main axis */
  justify-content: center;

  /* 3. After adding lang="scss" to style, supports class nesting */
  /* 4. Text cannot inherit, need to define class names for text modifications */
  .header-text {
    font-size: 28rpx;
    font-weight: 700;
    color: #fff;
  }
}

.scroll-content {
  padding: 40rpx 30rpx;
  /* 5. Minimum height */
  min-height: 300rpx;

  .scroll-content-text {
    font-size: 30rpx;
    color: #3204ac;
    line-height: 45rpx;
  }
}

.footer {
  /* 6. Align horizontally to the right */
  align-items: flex-end;
  padding-bottom: 20rpx;
  padding-right: 20rpx;

  .footer-button {
    background-color: #1534f5;
    color: #fff;
    font-size: 26rpx;
    border-radius: 50rpx;
    padding: 6rpx 30rpx;
  }
}
</style>

Business Logic

Joke API: https://hmajax.itheima.net/api/randjoke
Network Request API: https://doc.dcloud.net.cn/uni-app-x/api/request.html
Request networking tutorial: https://doc.dcloud.net.cn/uni-app-x/tutorial/request.html

Reference Code:

<script setup lang="uts">
import { ref } from 'vue'

const jokeText = ref('Loading jokes...')

// Note: uni-app x needs to use type to define object types, using interface has compatibility issues
type ServiceData = {
  message : string
  data : string
}

function getJoke() {
  // Specify the backend return data type through generics
  uni.request<ServiceData>({
    url: 'https://hmajax.itheima.net/api/randjoke',
    method: 'GET',
    success: (res) => {
      // Android-compatible type writing
      const jokeStr = res.data?.data
      if (jokeStr !== null) {
        jokeText.value = jokeStr
      }
    },
    fail: () => {
      jokeText.value = 'Data retrieval failed, please check network...'
    }
  })
}
</script>

<template>
  <view class="container">
    <view class="card">
      <view class="header">
        <text class="header-text">Random Jokes</text>
      </view>
      <scroll-view class="scroll-content">
        <text class="scroll-content-text">{{ jokeText }}</text>
      </scroll-view>
      <view class="footer">
        <button class="footer-button" @click="getJoke()">Next One</button>
      </view>
    </view>
  </view>
</template>

Lifecycle

Page Lifecycle

Page Lifecycle: https://doc.dcloud.net.cn/uni-app-x/page.html#lifecycle

Composition API	Options API	Description
onLoad	onLoad	Lifecycle callback listening for page load. Triggered when page loads. A page is only called once, parameters from the path opening current page can be obtained in onLoad parameters.
onPageShow	onShow	Lifecycle callback listening for page show. Triggered when page shows/enters foreground.
onReady	onReady	Lifecycle callback listening for page initial render completion. Triggered when page initial render is complete. A page is only called once, representing that the page is ready and can interact with the view layer.
onPageHide	onHide	Lifecycle callback listening for page hide. Triggered when page hides/enters background. Such as `navigateTo` or bottom `tab` switching to other pages, application entering background, etc.
onUnload	onUnload	Lifecycle callback listening for page unload. Triggered when page unloads. Such as `redirectTo` or `navigateBack` to other pages.
onResize	onResize	Triggered when page size changes
onBackPress	onBackPress	Listen for page return

Reference Code:

<script setup lang="uts">
// ...previous code omitted

// When page loads
onLoad(() => {
  // Get joke
  getJoke()
})
</script>

Foldable Screen Adaptation

Get window information: https://doc.dcloud.net.cn/uni-app-x/api/get-window-info.html

Notes:

vh unit can only be used on WeChat Mini Program and Web platforms, HarmonyOS, Android, iOS platforms do not support it
Properties like max-height, min-height can only use numbers or px units for multi-platform compatibility

Effect Preview:

Reference Code:

<script setup lang="uts">
// ...other code omitted

// Synchronously get window information, returned unit is px
const windowInfo = uni.getWindowInfo()
</script>

<template>
  <view class="container">
    <view class="card">
      <view class="header">
        <text class="header-text">Random Jokes</text>
      </view>
      <!-- Scroll content area -->
      <scroll-view
        class="scroll-content"
        :style="{ maxHeight: windowInfo.screenHeight * 0.66 + 'px' }"
      >
        <text class="scroll-content-text">{{ jokeText }}</text>
      </scroll-view>
      <view class="footer">
        <button class="footer-button" @click="getJoke()">Next One</button>
      </view>
    </view>
  </view>
</template>

<style lang="scss">
.scroll-content {
  padding: 40rpx 30rpx;
  // 5. Minimum height
  min-height: 300rpx;
  // vh unit can only be used on WeChat Mini Program and Web platforms, max-height, min-height only support numbers or px units
  /* #ifdef MP-WEIXIN || WEB */
  max-height: 66vh; /* Maximum height, 66% of screen height */
  /* #endif */
}
</style>

HarmonyOS Application Signing Certificate

HarmonyOS debug certificate for real device debugging
HarmonyOS release certificate for publishing
AGC platform to create projects and applications
HBuilderX to configure HarmonyOS debug certificate

HarmonyOS Signing Certificate

DevEco Studio	Hbuilder	Notes
storeFile	Private key store file	.p12
storePassword	Private key store password	·······
keyAlias	Private key alias	debugKey / releaseKey
keyPassword	Private key password	·······
profile	Signing profile file	.p7b
certpath	Certificate file	.cer

AGC Platform Create Project and Application

There are many steps here, please patiently check each step until application creation is complete.

Log in to AppGallery Connect, click "Development & Services".
Click "Add Project" on the project page.

Enter the project name on the "Create Project" page, then click "Finish".

Select "Certificates, APP ID and Profile", select "APP ID" in the left navigation bar, after entering the page, click "New" in the upper right corner.

HarmonyOS Debug Certificate

Open the manifest.json file, select the "HarmonyOS App Configuration" menu, then click the "Configure" button for debug certificate.

In the debug certificate configuration, check that "Application Package Name" and "Running Device" are correct, then click the "Auto Apply for Debug Certificate" button.

HarmonyOS Release Certificate

HarmonyOS release certificates cannot be automatically generated, the process has many steps, please refer to the video explanation, patiently check each step until configuration is complete.

Release certificate files

Configure release certificate

Release certificate notes

Signing profile file .p7b cannot be reused because it contains package name information, other certificate files can be reused across multiple projects, please remember the private key alias and password.

DevEco Studio	Hbuilder	Notes
storeFile	Private key store file	.p12
storePassword	Private key store password	·······
keyAlias	Private key alias	debugKey / releaseKey
keyPassword	Private key password	·······
profile	Signing profile file	.p7b
certpath	Certificate file	.cer

HarmonyOS Application Packaging and Distribution

HarmonyOS Application Local Packaging

After configuring HarmonyOS release certificate, you can proceed with HarmonyOS application local packaging, ultimately generating a signed .app installation package.

HarmonyOS Application Publishing

Upload the signed .app installation package on the AGC platform, please refer to the video explanation or check the official documentation: Publishing HarmonyOS Applications (HarmonyOS NEXT)

Android Application Cloud Packaging (Additional)

Android applications can be directly packaged using cloud certificates, ultimately generating a signed .apk installation package.

Users can upload the apk to various Android app stores.

DEV Community: 苏杰豪

uni-app x Cross-Platform Getting Started and Practice: Develop HarmonyOS 5 Applications

uni-app x Cross-Platform Getting Started and Practice: Develop HarmonyOS 5 Applications

Course Introduction

What You Will Gain

Target Audience

Course Overview

Course Highlights

Platform Compatibility

Running Effects

Technology Stack

Development Tools

uni-app x

uni-app x Introduction

uvue Rendering Engine

uts Language

uni Components

Preparation

Development Environment Setup

Project Directory Structure

Compile and Run

Project Practice

Effect Preview

Material Download

Structure and Styling

Business Logic

Lifecycle

Page Lifecycle

Foldable Screen Adaptation

HarmonyOS Application Signing Certificate

HarmonyOS Signing Certificate

AGC Platform Create Project and Application

HarmonyOS Debug Certificate

HarmonyOS Release Certificate

HarmonyOS Application Packaging and Distribution

HarmonyOS Application Local Packaging

HarmonyOS Application Publishing

Android Application Cloud Packaging (Additional)