DEV Community: shaohushuo

HarmonyOS Native Development Notes: 05-Things Beyond Development

shaohushuo — Wed, 25 Jun 2025 03:05:44 +0000

Introduction

The entire application from development to listing requires a series of work, including domain name registration, ICP filing, opening a developer account, App filing, development, testing, listing, review and promotion, etc.

Domain Name

Registering and purchasing domain names from domain name service providers, individuals or companies should give priority to .com domain names, and be cautious when purchasing specific domain names such as .org. Filings must have corresponding qualifications or approval conditions, and some suffix domain names may not be able to be filed. For special domain names, it is recommended to check the website of the Ministry of Industry and Information Technology to verify whether filing is supported.

Filing

First, choose personal filing or corporate filing. Real-name authentication is required after the domain name is purchased, and the authentication information must be consistent with the filing. If the two are different, the domain name real-name information needs to be changed first.

There are many types of filing, including domain name filing, App filing, mini-program filing, etc. HarmonyOS Yuan Service filing is currently processed according to App filing, and the two processes are consistent.
Here is how to file a company record. Log in to the operator's record system, such as Alibaba Cloud, enter the record, fill in the company information, corporate legal person ID information and ID photo, website/App person in charge ID information and ID photo, and verify two mobile phone numbers at the same time.
If it is an App record, you need to fill in the application information, application name, package name, icon, fingerprint and signature information, etc. It should be noted that the name and package name should be consistent with the listed one, otherwise the review will be rejected.
After submitting the information, the record service provider will call to verify the information, and Alibaba Cloud will ask for the last six digits of your ID number.

After the service provider passes the review, it will submit the record information to the Ministry of Industry and Information Technology. At that time, you will receive a text message. At this time, log in to the Ministry of Industry and Information Technology's website, fill in the last 6 digits of the corporate legal person ID number and the last 6 digits of the person in charge, as well as this verification code, and it will be verified.

The requirements of the management bureaus in different regions are different. Some regions require that the person in charge of the website/App must be himself, while others do not make requirements. You can ask the record service provider.

Equipment

Huawei phones are expensive. For some developers, if the main phone is not Huawei, it may be a considerable expense. Here you need to make a decision based on your own situation.

If you only use ArkTs to develop native HarmonyOS applications, you can consider using an emulator. Most common ones can meet the requirements and the emulator has high availability.

If you are used to cross-end development frameworks, such as Flutter, or if you are designed to interact with the underlying system API or operate hardware, you need to consider equipping a real machine.

For devices, the mate60 series is preferred, including mate60, mate60pro, etc. If you are not price sensitive, consider mate70 and new models. Secondly, consider the nova series and then consider MatePad, etc. If you think the new phone is expensive, you can consider Xianyu second-hand. Before purchasing the phone, confirm that it can be upgraded to NEXT normally. Check the upgrade plan on the developer's official website to ensure that the model supports Next, and ask the seller if the system is unlocked and can be upgraded normally.

At present, most applications are adapted to mobile phones first, and there are fewer applications on matepad. Even if they are used for development, there are certain differences in perception between the two. It is especially important to pay attention to screen size adaptation, which will inevitably be rejected during the review process.

Development and testing

To improve development efficiency, you can use the preview function to preview the currently developed page or component in real time. After the module development is completed, debug it with an emulator or real device.

Enable hot reload. The default IDE is not enabled. If you need to use it, first modify the operation configuration, and then manually click the H hot reload icon. If you want to refresh automatically when saving, find Auto Save in the settings and enable it.

If the application needs to access the network, configure network access rights in the module.json5 file. For meta-services, you also need to enable "Exemption from control for meta-services in development" in the developer options of the device. When listing, configure the request domain name in the project configuration of AGC.

Listing review

When listing, if you check the tablet adaptation, make sure you have tested it on the tablet, or you have enough confidence that there is no adaptation problem. The reviewer will use a tablet to carefully check your app. If any problem is found, the app will not be put on the shelf.

You can provide a self-test screen recording to improve the review pass rate. If the app has special features in design or use, it is best to explain the reason in detail in the remarks so that the reviewer can fully understand.

Fill in all information truthfully when putting it on the shelf, and the application classification and labeling should be appropriate. Use the production certificate for packaging, and do not make mistakes when uploading packages and checking them. Even if the software packages not used on AGC are deleted, avoid confusion. When filling in the information, click Save to avoid information loss due to web page jumps during boot.

After successful submission, the system will first conduct a pre-review, which is a machine review. It takes about one or two hours to wait. You will receive a notification email whether the review is passed or not. Then it will enter a relatively long review waiting period. The review time is generally on weekdays, including Saturdays and Sundays. Based on this, you can reasonably arrange the review time and submit it for review in advance.

The public beta version and the official version have the same review process and are independent of each other.

Each time an application is submitted, the reviewer may be different, and the problems found may be different, which varies from person to person and from time to time.

The review is relatively loose when the application is first launched, and it may be more stringent when it is upgraded and reviewed again.

References

https://domain.miit.gov.cn/

HarmonyOS Native Development Notes: 04-A Complete Meta-Service Case

shaohushuo — Wed, 25 Jun 2025 03:04:04 +0000

Cinema Hot Screening

Share a complete meta-service case, which is a high imitation of Douban's mini program.

Introduction

The entire meta-service is divided into 4-5 pages. The homepage is a list page, which shows the popular movies in the current theater. Clicking it is a detailed introduction page, which contains movie details, cast list, related movie recommendations, and popular posters. Opening the poster is a complete poster display page, and you can click it to see a large picture.
In addition, there is an introduction page about us.

Design

The meta-service does not use the bottom tab, but places the about us at the bottom of the page, showing it in a more euphemistic way.

Code

Check the entry/src/main/etc/pages/ directory, and the entire application is divided into four pages. Its routes are configured in entry/src/main/resources/base/profile/main_pages.json, and the route name corresponds to the file name one by one. In the directory where main_pages.json is located, you can see a form_config.json file, which is used to configure the service card. I will not discuss it here.

The page mostly uses row and column layout, and various spacings are specified by using Blank() first.

In the Album page, a grid layout is used. When you click on one of the images, a slideshow will be played. The @lyb/media-preview third-party library is used here. The following is the core code:

Grid() {
ForEach(this.items, (item: Photo, index: number) => {
GridItem() {
Image(item.image.normal.url)
.width('100%')
.height(140)
.objectFit(ImageFit.Cover)
.clickEffect({ level: ClickEffectLevel.MIDDLE, scale: 1.1 })
.visibility(index == this.index ? Visibility.Hidden : Visibility.Visible)
.onClick((event) => {
this.options
.setInitIndex(index)
.setMedias(this.getPreviewResources())
.setIndicator(false)
MediaPreview.open(this.getUIContext(), this.options)
})
}
})
}
.columnsTemplate('1fr 1fr 1fr')
.columnsGap(2)
.rowsGap(2)
.scrollBar(BarState.Off)

The common directory stores some global variables, such as the Constants.ets file, where static variables are used. There is also a simple encapsulation of the request class, which also uses a static class as a singleton.

In order to make the import code more concise and "high cohesion and low coupling", an index file is used to export the classes and methods in this directory.

The methods in Request use generics, so that they can be automatically deserialized according to the passed type, reducing the amount of boilerplate code.

components component directory. This is where the encapsulated widgets are stored. This case contains 4 widgets: cast list, copyright statement, poster list, and related recommendations.

Copyright is a simple widget that is displayed in the footer.

@Component
export struct Copyright {
build() {
Row() {
Image($r('app.media.nutpi')).width(32)
Blank().width(8)
Text('Nutpi').fontWeight(FontWeight.Bold).fontColor(Color.Gray)
}.justifyContent(FlexAlign.Center)
.width('100%')
.onClick((event) => {
router.pushUrl({ url: 'pages/About' })
})
}
}```

quickactions/pages/QuickActionCard.ets is the page for serving cards. Here, the UI of the card is described. Click events are monitored and triggered through Formlink


typescript
FormLink({
action: this.ACTION_TYPE,
abilityName: this.ABILITY_NAME,
params: {
action: this.MESSAGE
}
}) {
Row() {
Text('Hot Movies in Theaters').fontSize(14)
.fontColor($r('app.color.card_label'))
Image($r('app.media.icon'))
.width(32)
}
.justifyContent(FlexAlign.SpaceBetween)
.height(this.FULL_HEIGHT_PERCENT)
.width('100%')
.padding({
top: 10,
left: 12,
right: 12,
bottom: 10
})
.backgroundColor($r('app.color.background_color'))
}

In the above code, a row layout is described, with an icon on the left and the application name on the right.

5.viewmodels is the view data model. This case has 5 models, namely AppInfo, Celebrities, Movie, Photos, Relative.


typescript
export class AppInfo {
logo: string = '';
appName: string = '';
appLinking: string = '';
appId: string = '';
desc: string = '';
type: string = '';
}

AppInfo is a simple application information class, including logo, application name, applink, description and application type.

Application screenshots

Home	My	Help

Notes

Enable Meta Service Exemption Control: System-Developer Options-Developing Meta Service Exemption Control

Others

For application creation, service cards, package signatures, listing review, etc., you can view previous articles or the reference materials below.

Complete code

For the complete code, see the code repository
https://gitee.com/zacks/arkts-ohos-demo

References

HarmonyOS Native Development Notes: 03-The Whole Process of Meta Service Development

shaohushuo — Wed, 25 Jun 2025 02:59:21 +0000

Introduction

This article provides a very detailed introduction to the full process of meta-service development and listing, including meta-service introduction, creation, service cards, signatures, development and testing, signature packaging, listing review, etc.

Metaservice Introduction

Metaservice is a new way of providing services
Simple development, no installation, easy to obtain and use
Compared with mini programs, it is native to the system and smooth and fluent

Lightweight application form, with features such as instant opening, pure and refreshing; service companionship, just in time; ready to use, account accompanying; one body with two sides, embedded operation; native intelligence, global search; efficient development, born to be trusted, etc.

Features

Open in seconds: ready to use, no splash screen ads
Service companion: fulfillment reminder, service closed loop
Use and go: exit without pop-up window, service synchronized with account
Native intelligence: Xiaoyi intelligence, precise reach Global search: system search box
Efficient development: UX component set, scenario templates, etc.

Create meta-service

Create project

Open DevEco
New -> Create Project
Select Atmoic Service

The first time, we will be prompted to log in with a Huawei account. Click here to log in. Note that the account logged in here is the developer account, which is the account used for listing. If you are an enterprise, you should log in with the company's developer account.

Click to log in, and you will be redirected to the browser. Log in to the developer account on the web page and authorize it.

The web page shows that the login is successful, and then we can return to Deveco.

If it is the first time to use, the project has not been created yet. At this time, you need to click Register App ID to create a new project

Fill in the meta service name. It is important to note that the name cannot be duplicated, must be recognizable, and cannot be a generalized category to avoid misleading users. For specific requirements, see the review guide in the reference material, otherwise the listing review will be rejected.

Click Next, select the project to which it belongs. If the project has not been created yet, enter the project name and click Confirm to create it.

Complete APPID registration.

It is urgent to create a meta service. Click Finish, and the sample code will be generated.

Icon generation

Right-click the module or file in the project

New -> Image Asset

Make a 1024 x 1024 px square icon and automatically generate a circle around it

Write a page

@Entry indicates that the custom component is an entry component, which means that the current page is a page

@Component indicates a custom component

@State indicates the state variable in the component. Changes in the state variable will trigger a UI refresh

aboutToAppear is the life cycle, after the component is instantiated and before build()

build() is the UI description method

Note: Meta services have exactly the same technology stack as HarmonyOS native applications, only the available API sets are different, and the functions are relatively simple

Notes on writing meta services

Many API/Kit Cannot be used in meta-services.

Open the API reference, you can check on the left to filter the meta-service API set

Service card

Static card interaction component FormLink

Used for interaction between static cards and provider applications

action: router is used for redirection, and the UIAbility side receives parameters through params

Receive parameter transmission

EntryAbility.ets

Receive parameters through want?.parameters?.params in onCreate and onNewWant

onCreate: UIAbility instance creation

onNewWant: UIAbility instance returns to the foreground from the background, hot start

onWindowStageCreate: After UIAbility is created, before entering the foreground, WindowStage will be created

Development and testing

Simulator
Previewer
Real machine debugging
Hot reload

DevEco Testing

Stability test
Performance and power consumption test
Regression test
Basic quality test
Device projection

Support the meta-services of tablets and ensure that compatibility testing has been carried out, otherwise it will affect the listing review.

This part is described in detail in "HarmonyOS Flutter Practice: 13-HarmonyOS Application Packaging and Listing Process".

Create a Key Store in DevEco
Generate Key and CSR
Add a new certificate in Huawei AGC, upload CSR, and obtain the Cer certificate file
Create a Profile file
Configure the signature file
Packaging (Build/Huild Apps)

Return to AGC, complete the application information, and upload the icon
Upload the software package
Complete the application introduction, fill in the privacy policy and user agreement
If it is an APP, you need to prepare the filing and software copyright in advance (it is recommended to use an electronic copyright certificate)
Submit for review

References

HarmonyOS Native Development Notes: 02 - Service Card Development

shaohushuo — Tue, 24 Jun 2025 14:42:54 +0000

Introduction

Service cards are desktop widgets that can be placed on the desktop and other locations, and can be reached at a touch.

Service cards are divided into two categories: static cards and dynamic cards. This article introduces static cards.

Create

Back to DevEco, right-click in the directory entry, click Create Service Widget, select Static Widget, and click Next.

Enter a name, select a supported card size, and click OK to create the card.

2*2 represents 2 rows and 2 columns, and 1*2 represents 1 row and 2 columns.

Write the card interface

Interaction

Click event parameter transmission

Here ArkUI is used to write the interface, but click events cannot be used. Instead, FormLink should be used. The related events are received on the formability side. Through different parameters, router.push is called to open different pages.

FormLink({ 
action: this.ACTION_TYPE, 
abilityName: this.ABILITY_NAME, 
params: { 
action: this.MESSAGE 
} 
}) { 
... 
}

Parameter reception

In the onCreate and onNewWant life cycles in entryability, to receive parameters

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 

if(want?.parameters?.params) { 
let params: Record<string, Object> = JSON.parse(want.parameters.params as string); 
this.selectPage = params.action as string; 
console.log("selectPage", this.selectPage); 
} 
} 

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { console.log('onNewWant');
if (want?.parameters?.params) {
// want.parameters.params corresponds to the content of params in postCardAction()
let params: Record<string, Object> = JSON.parse(want.parameters.params as string);
this.selectPage = params.action as string;
hilog.info(DOMAIN_NUMBER, TAG, `onNewWant selectPage: ${this.selectPage}`);
}
if (this.currentWindowStage !== null) {
this.onWindowStageCreate(this.currentWindowStage);
}
}

Notes

When running, please use normal mode. Service cards do not support HotReload, and cards cannot be displayed normally in hot reload mode.

References

Service Card Documentation

HarmonyOS Native Development Notes: 01-Meta-Service Development

shaohushuo — Tue, 24 Jun 2025 14:29:02 +0000

Introduction

Meta-service is a lightweight application form in HarmonyOS, which can be run directly without downloading. It is similar to WeChat applet, but different from applet, meta-service is more lightweight.

Meta-service is developed by native and provided at the system level. It is better than applet in terms of ease of use, performance and experience.

Create meta-service

Use DevEco, click Create, select Atomic Service in the template on the left, and select Empty Ability in the template on the right. Click Next according to the prompts.

Icon generation

After the icon is designed, you can use DevEco's built-in generation tool to generate an icon that meets the meta-service specification. In the src/main/resources/media directory, right-click New->Image Asset

A production dialog box will pop up. Select the designed icon and check the main color to generate the meta-service icon.

Write page

Open the src/main/ets/pages/index.ets page. The writing method is consistent with the ArkUI application. Start writing the page code here.

API restrictions

It should be noted that some APIs cannot be used in meta-services. In the HarmonOS document, open the API reference and check Filter meta-service API set on the left to see which APIs may be used in meta-services.

Permission restrictions

There are more permission restrictions in meta-services. In the API documentation, the permissions that support the use of meta-services will be registered at Meta-service API.

Restricted open permissions

Dark mode

In the src/main/resources directory, create a new dark directory, right-click in the resources directory, select Resource Directory, select Color Mode on the left side of the dialog box,
and then click OK

In portable code, referencing color variables through lines such as $r('app.color.primary_button_color') will reference resources/dart/element/color.json in dark mode. In the file, find the corresponding color variable. For other assets, such as images, the same method is used.

Service card

Meta-services can add service cards. For details, see "HarmonyOS Native Development Notes: 02-Service Card Development"

Development and testing

Click Run in DevEco. On the device, you can click the "Search" button above the negative one screen to enter my meta-service list. You can see the newly installed meta-service in the recent.

Listing

For details, see "HarmonyOS Flutter Practice: 13-HarmonyOS Application Packaging and Listing Process". First add the application project, then add the meta-service.

Notes

Click failure problem in the navigation bar. When using RelativeContainer, it is found that if the button is in the same row as the button on the right side of the meta-service at the top, the click event is not triggered. In this case, do not use the RelativeContainer component, and use other components such as Column instead.

References

HarmonyOS Flutter Repository Stops Updates

shaohushuo — Fri, 13 Jun 2025 13:47:10 +0000

Stop Updates

Friends who are familiar with Flutter Harmony development should know that Flutter 3.7.12 Harmony SDK has been released in the open source Harmony community for almost a year. The Harmony adaptation of Flutter 3.22.x has been provided by the Harmony Commando Repository. Recently, some friends reported that it has not stopped updating for more than 2 months, and many people thought that maintenance has stopped.

This is not the case.

Migration and merging

Flutter's Harmony adaptation work has been ongoing. The article Harmony Flutter Practice: 15-Flutter Engine Impeller Harmonyization, Performance Optimization and Future details the adaptation work content and future plans. The author mentioned in the previous article The original open source Harmony warehouse stopped updating that with the collective migration of the open source Harmony warehouse to gitcode, the 3.22.x version of Flutter SDK maintained by the Harmony Commando has also been merged into the Open Source Harmony Flutter Main Repository, and currently exists in the form of branch 3.22.0-ohos.

So far, the initial integration of Flutter Harmony has been completed, and two major versions are maintained simultaneously using one repository.

Summary Review

Flutter Harmony SDK is still active, and the last update was 4 days ago. If you need to use FVM to install the 3.22 version of the SDK, you can use the following command:

git clone -b 3.22.0-ohos https://gitcode.com/openharmony-sig/flutter_flutter.git custom_3.22.0

If you need to use FVM to install the 3.7.12 version of the SDK, you can use the following command:

git clone -b br_3.7.12-ohos-1.0.6 https://gitcode.com/openharmony-sig/flutter_flutter.git custom_3.7.12

The following are all the warehouse addresses related to Flutter Harmony:

Flutter sdk https://gitcode.com/openharmony-sig/flutter_flutter
Flutter engine https://gitee.com/openharmony-sig/flutter_engine
Flutter packages https://gitcode.com/openharmony-sig/flutter_packages
Flutter sample sample library https://gitcode.com/openharmony-sig/flutter_samples

For other third-party libraries under gitee/openharmony-sig, just replace the domain name, such as flutter inappwebview migrated to https://gitcode.com/openharmony-sig/flutter_inappwebview

In addition, some friends are using Flutter 3.7.12 version, then the SDK also needs to switch the source address, just change the domain name.

Which HarmonyOS native applications are using Flutter

shaohushuo — Fri, 13 Jun 2025 13:46:41 +0000

Background

On August 4, 2023, Huawei released HarmonyOS NEXT at the "2023 Huawei Developer Conference" and announced that the system would be open to cooperative enterprise developers.

HarmonyOS NEXT, also known as HarmonyOS 5.0, is the largest update version in the history of Harmony. Harmony is no longer compatible with Android and uses its own kernel (Harmony kernel), which completely replaces the original system functions in terms of kernel, operating system, and application layer. Harmony has completely gotten rid of the title of "Android shell".

Harmony native

For Everbright's application manufacturers and developers, all applications must be redeveloped and adapted. So what is the so-called native Harmony development? This article will discuss the following aspects:

Bottom-level adaptation

The original application needs to be rewritten, such as using ArkUI to completely re-adapt, or based on some cross-platform frameworks for Harmony adaptation. Some of the original Android system services also need to be replaced with HarmonyOS Kit, such as Huawei's one-click login, payment, advertising, Webview, etc. APIs involving system functions need to be adapted and developed, and the best application will run on the Harmony system.

Harmony characteristics

In addition to bottom-level adaptation, it is also necessary to start from the characteristics of Harmony and customize the development of functions exclusive to Harmony, such as service cards, meta-services, live windows, Xiaoyi, etc. Service cards can add various quick services on the desktop to display commonly used information; meta-services can use high-frequency quick services without installing the application or opening the application itself, such as recharging phone bills, checking express delivery, and ordering food; the live window is similar to the function of iOS, but it is more flexible and requires customized development; in order to better improve the user experience, the application can also be integrated with Xiaoyi. Through the intent framework, image and text dragging, etc., users can better use Xiaoyi Assistant, integrate application services, and recommend more valuable information to each user.

HarmonyOS has many features that may not be available in other systems, such as distributed features, which can achieve seamless application flow, from one device to another; in addition, there are one-touch transmission, unified code scanning, etc.

Business logic transformation

In addition, in terms of business logic, HarmonyOS native applications also need to be transformed. Unlike the previous Android, which directly requested various permissions when the App was started, the HarmonyOS system provides various security controls and System Picker can achieve safe and fast access to user data without requesting permissions, for example

One-to-many adaptation

Harmony system naturally supports systems of various devices, whether it is mobile phones, tablets, folding p screens, smart screens, or Harmony PCs, so it is natural to develop Harmony applications and adapt to multiple devices.

The so-called "one-to-many" refers to "one-time development, multi-terminal deployment".

Whether using ArkUI, or Flutter, React Native, Uniapp and other frameworks, you can adapt to multiple terminals well. By identifying the screen ratio and size, the application can be flexibly laid out, or monitoring screen change events to trigger the application to re-layout, etc., due to the large number of devices and different ratios, these require a lot of work.

Which applications are using Flutter

Flutter is a cross-platform development framework developed by Google and is used for development on Android, iOS, Linux, MacOS, Windows and other platforms. With the efforts of the open source Harmony community, Flutter also supports Harmony native development. So, which top applications use Flutter in Harmony native development? After data collection and research and analysis, the author has sorted out some of the top applications.

Serial number	Application	Download volume
1	WeChat	4.18 million
2	Xianyu	1.78 million
3	UC	1.5 million
4	DingTalk	1.38 million
5	Quark	1.07 million
6	Enterprise WeChat	850,000
7	Shell	530,000
8	Douban	320,000
9	Alibaba Cloud Disk	140,000
10	Soul	-

Download data as of May 5, 2025

Many Alibaba applications use Flutter, including UC, Xianyu, Quark, DingTalk, etc. Among the contributors to the open source Harmony Flutter repository, UC can also be seen.

For WeChat, Flutter also appeared. As early as before the launch of Harmony WeChat, there were reports of screenshots of Moments using Flutter. "The technology selection of WeChat Moments turned out to be..."). At the same time, earlier, WeChat launched a new mini-program rendering engine Skyline, and during the test, someone caught Skyline and flutter related logs, plus two articles released by WeChat after WeChat Harmony was officially launched, What do you need to go through to develop WeChat Harmony version? , these evidences show that WeChat is using Flutter.

HarmonyOS Flutter Practice: 25-Hybrid Development Detailed Explanation-5-Jump to Flutter Page

shaohushuo — Fri, 13 Jun 2025 13:46:11 +0000

Overview

In the previous chapter, we introduced how to initialize the Flutter engine. This article focuses on how to add and jump to the Flutter page.

Jump Principle

The jump principle is as follows:

Essentially, it jumps from a native page A to another native page B, but the difference is that page B is a page container with embedded Flutter content.

At the same time, before opening page B, we need to notify Flutter to switch pages in advance. Here, the communication mechanism provided by Flutter is used, that is, EventChannel.

Add FlutterPage

In order to display Flutter content, we need to create a native page as a container to host Flutter.

Add a page in the entry/src/main/etc/pages directory, for example, name it FlutterContainerPage, right-click the ohos/entry/src/main/ets/pages directory, select New->Page->Empty Page, change PageName to FlutterContainerPage, click Finish, and then modify the page content as follows:

import { FlutterEntry, FlutterPage, FlutterView } from '@ohos/flutter_ohos'

@Entry
@Component
struct Index {

private flutterEntry?: FlutterEntry;
private flutterView?: FlutterView;

aboutToAppear() {
this.flutterEntry = new FlutterEntry(getContext(this));
this.flutterEntry.aboutToAppear();
this.flutterView = this.flutterEntry.getFlutterView();
}

aboutToDisappear() {
this.flutterEntry?.aboutToDisappear();
}

onPageShow() {
this.flutterEntry?.onPageShow();
}

onPageHide() {
this.flutterEntry?.onPageHide();
}

build() {
RelativeContainer() {
FlutterPage({ viewId: this.flutterView?.getId()})
}
}
}

FlutterPage is a component provided by OpenHarmony Flutter SDK, which is used to render Flutter pages in ArkUI. The principle is to use XComponent in ArkUI to customize the rendering content.

Modify the native page

import { router } from '@kit.ArkUI';

@Entry
@Component
struct Index {
build() {
Column() {
Text('Hello World').fontSize('50fp').fontWeight(FontWeight.Bold)
Blank().height(80)
Button('Jump to Flutter').onClick(() => {
router.pushUrl({ url: 'pages/FlutterContainerPage'})
})
}.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Center)
.width('100%')
.height('100%')
}
}

We add a button to the native page and jump to the Flutter page when the button is clicked.

In the above example, the Flutter page opened each time is fixed. Next, we will explore how to dynamically jump to the Flutter page.

References

HarmonyOS Flutter Practice: 24-Hybrid Development Detailed Explanation-4-Initialize Flutter

shaohushuo — Fri, 13 Jun 2025 13:45:41 +0000

Overview

After adding the Flutter module to the host Harmony project, you need to implement page jump, message communication and other functions. This article focuses on how to initialize Flutter.

Project configuration

Add dependencies

Edit the ohos_app/oh-package.json file

If you import the Flutter module through the Har package, you need to add the following content

"dependencies": {
"@ohos/flutter_module": "file:har/my_flutter_module.har",
"@ohos/flutter_ohos": "file:har/my_flutter.har"
},
"overrides" {
"@ohos/flutter_ohos": "file:har/flutter.har",
}

If you import the Flutter module through source code, you need to add the following content:

"dependencies": {
"@ohos/flutter_module": "./flutter_module",
"@ohos/flutter_ohos": "./har/flutter.har"
},

Initialize the Flutter engine

Edit ohos_app/entry/src/main/ets/entryability/EntryAbility.ts file, modify it as follows:

-import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
-import { hilog } from '@kit.PerformanceAnalysisKit';
-import { window } from '@kit.ArkUI';
+import { FlutterAbility, FlutterEngine } from '@ohos/flutter_ohos';
+import { GeneratedPluginRegistrant } from '@ohos/flutter_module';

-const DOMAIN = 0x0000;
-
-export default class EntryAbility extends UIAbility {
- onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
- this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
- hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
- }
-
- onDestroy(): void {
- hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
- }
-
- onWindowStageCreate(windowStage: window.WindowStage): void {
- // Main window is created, set main page for this ability
- hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
-
- windowStage.loadContent('pages/Index', (err) => {
- if (err.code) {
- hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
- return;
- }
- hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
- });
- }
-
- onWindowStageDestroy(): void {
- // Main window is destroyed, release UI related resources
- hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
- }
-
- onForeground(): void {
- // Ability has brought to foreground
- hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
- }
-
- onBackground(): void {
- // Ability has back to background
- hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
+export default class EntryAbility extends FlutterAbility {
+ configureFlutterEngine(flutterEngine: FlutterEngine) {
+ super.configureFlutterEngine(flutterEngine)
+ GeneratedPluginRegistrant.registerWith(flutterEngine); 
}
}

The final EntryAbility.ts file content is as follows:

import { FlutterAbility, FlutterEngine } from '@ohos/flutter_ohos';
import { GeneratedPluginRegistrant } from '@ohos/flutter_module';

export default class EntryAbility extends FlutterAbility { 
configureFlutterEngine(flutterEngine: FlutterEngine) { super.configureFlutterEngine(flutterEngine)
GeneratedPluginRegistrant.registerWith(flutterEngine);
}
}

EntryAbility inherits from FlutterAbility, and FlutterAbility inherits from UIAbility, which adds the following features to UIAbility:

Engine management
Initialize Flutter engine (FlutterEngine)
Handle Flutter and native capability binding through Delegate
Manage window lifecycle (create/destroy)
UI interaction
Create FlutterView view container
Handle system configuration changes (dark mode/font scaling)
Implement multi-language/accessibility service adaptation
Lifecycle coordination
Forward native lifecycle events to the Flutter layer (onForeground/onBackground)
Handle exception recovery (appRecovery.restartApp)
Extension support
Provide plugin management interface (addPlugin)
Support hot reload configuration synchronization (onConfigurationUpdate)

Summary

This section mainly introduces how to initialize the Flutter engine and initialize the Flutter Module. In the next section, we will introduce how to jump from native to Flutter and display the interface.

References

HarmonyOS Flutter Practice: 23-Hybrid Development Detailed Explanation-3-Source Code Mode Introduction

shaohushuo — Fri, 13 Jun 2025 13:45:15 +0000

Introduction

In the previous article Hybrid Development Detailed Explanation-2-Har Package Mode Introduction, we introduced how to package the Flutter module into a Har package and introduce it into the native Harmony project. In this article, we will introduce how to introduce the Flutter module into the native Harmony project through source code dependency.

Create work

Create a root directory

mkdir ohos_flutter_module_demo

This directory is used to store flutter projects and Harmony projects.

Create a Flutter module

First, create a Flutter module. We choose the same directory as the ohos_app project

flutter create --template=module my_flutter_module

If fvm is used, first make sure that the flutter version used in the current directory is the Harmony SDK version. For example, you can use fvm use custom_3.22.0 to set it, and then add fvm before the flutter command. The above command becomes fvm flutter create --template=module my_flutter_module

The following output appears on the command line:

Creating project my_flutter_module...
Resolving dependencies in `my_flutter_module`...
Downloading packages...
Got dependencies in `my_flutter_module`.
Wrote 12 files.

All done!
Your module code is in my_flutter_module/lib/main.dart.

Create Flutter After the module is successfully created, the directory structure is as follows:

Create a DevEco project

Use DevEco to create a new project named ohos_app in the ohos_flutter_module_demo directory.

Note that the saved directory is xxxx/ohos_flutter_module_demo/ohos_app

After the DevEco project is created, sign the project as follows.

Open the my_flutter_module/.ohos project in DevEco Studio and configure the debug signature (File -> Project Structure -> Signing Configs, check Automatically generate signature), then click Apply and OK.

After successful creation, the entire directory structure is as follows:

As you can see, we put the Flutter module at the same level as the ohos_app project. The .ohos directory is automatically created in my_flutter_module, which is also a simple Harmony project, but it will contain a module named flutter_module.

Configure source code dependencies

.ohos soft link to the main project

Since the solution given in the Open Source Harmony Official Document is not ideal, here we use the soft link solution to achieve source code-based linkage development.

Under normal circumstances, after my_flutter_module is successfully created, it will contain a .ohos directory, which is a Harmony project (containing the flutter_module module), which can be used as the host of Flutter. However, this host project is not the ohos_app we expected. The two projects have no connection, so they cannot be developed in conjunction.

So we do the following:

# ⚠️First, you need to copy flutter_module to the Harmony host project to avoid the error "Error: Parse ohos module.json5 error: Error: Can not found module.json5 at"
cp -r my_flutter_module/.ohos/flutter_module ohos_app/

# Enter the directory my_flutter_module and create a soft link here
cd my_flutter_module
# Delete the .ohos directory
rm -rf .ohos
# Create a soft link to the Harmony host project and change the directory name as needed
ln -s ../ohos_app .ohos

Through the above operations, we replace the .ohos directory with the ohos_app Harmony project in a soft link. In this way, when we run the Flutter code, ohos_app will be used as the host, which realizes the linkage source code development and supports hot reload.

Update the project

After the above operation, we run flutter run to let Flutter automatically update the project configuration

# Run the flutter code to update the Harmony project directory
flutter run

Check the ohos_app/build-profile.json5 file, you can see that the command automatically adds the module configuration:

"modules": [
...
+ {
+ "name": "flutter_module",
+ "srcPath": "./flutter_module"
+ }
]

Also check the ohos_app/har directory, you can see that the flutter.har file is automatically generated.

You can see that when running flutter run, the console outputs the following:

Launching lib/main.dart on FMR0224904009635 in debug mode...
start hap build...
...
Running Hvigor task assembleHap... 95.7s
✓ Built ../ohos_app/entry/build/default/outputs/default/entry-default-signed.hap.
installing hap. bundleName: com.shaohushuo.ohos_app

After a while of waiting, our App is running. The application displays a native page, and the Flutter engine and Flutter page are not loaded. We will introduce these implementations in the next chapter.

References

HarmonyOS Flutter Practice: 22- Detailed Explanation of Hybrid Development-2-Introduction of Har Package Mode

shaohushuo — Fri, 13 Jun 2025 13:20:31 +0000

Load it into the HarmonyOS project as a Har package

Create work

Create a root directory

mkdir ohos_flutter_module_demo

This directory is used to store flutter projects and Harmony projects.

Create a Flutter module

First, create a Flutter module. We choose the same directory as the ohos_app project

flutter create --template=module my_flutter_module

If fvm is used, first make sure that the flutter version used in the current directory is the Harmony SDK version. For example, you can use fvm use custom_3.22.0 to set it, and then add fvm before the flutter command. The above command becomes fvm flutter create --template=module my_flutter_module

The following output appears on the command line:

Creating project my_flutter_module...
Resolving dependencies in `my_flutter_module`...
Downloading packages...
Got dependencies in `my_flutter_module`.
Wrote 12 files.

All done!
Your module code is in my_flutter_module/lib/main.dart.

Create Flutter After the module is successfully created, the directory structure is as follows:

Create a DevEco project

Use DevEco to create a new project named ohos_app in the ohos_flutter_module_demo directory.

Note that the saved directory is xxxx/ohos_flutter_module_demo/ohos_app

After successful creation, the entire directory structure is as follows:

Package the Flutter module into a Har package

Next, we use the flutter build har command to package the Flutter module into a Har package.

Before packaging, first configure the signature, open the .ohos directory with DevEco, and then sign the project. The operation is as follows:

DevEco Studio opens the my_flutter_module/.ohos project and configures the debug signature (File -> Project Structure -> Signing Configs, check Automatically generate signature)

flutter build har --debug

The following output appears on the command line:

Running Hvigor task assembleHar... 47.5s

Consuming the Module
1. Open <host project>/oh-package.json5
2. Add flutter_module to the dependencies list:

"dependencies": {
"@ohos/flutter_module": "file:path/to/har/flutter_module.har"
}

3. Override flutter and plugins dependencies:

"overrides" {
"@ohos/flutter_ohos": "file:path/to/har/flutter.har",
}

Observe the directory my_flutter_module/.ohos/har, you can see that the Har package of the Flutter module has been generated, and two files are generated in it, namely flutter_module.har and flutter.har.

Note that the generated flutter_module.har is the default name and has nothing to do with the project name. If you want to change the generated name, you can modify the package name in the my_flutter_module/.ohos/flutter_module/oh-package.json5 file.

Introduce Har package into ohos project

Next, we copy the generated har package to the host project ohos, and then return to the ohos project project to add the generated Har package to the dependency configuration.

Copy the Har package

cp -r my_flutter_module/.ohos/har/* ohos/har/

Edit the ohos_app/oh-package.json5 file:

"dependencies": {
"@ohos/flutter_module": "file:har/my_flutter_module.har",
"@ohos/flutter_ohos": "file:har/my_flutter.har"
},
"overrides" {
"@ohos/flutter_ohos": "file:har/flutter.har",
}

Note: If you do not want to use the method of copying the Har package, you can also directly import the original Har location through a relative path. You can use the following method to import:

"dependencies": {
"@ohos/flutter_module": "file:../my_flutter_module/.ohos/har/flutter_module.har",
"@ohos/flutter_ohos": "file:../my_flutter_module/.ohos/har/flutter.har"
},
"overrides": {
"@ohos/flutter_ohos": "file:../my_flutter_module/.ohos/har/flutter.har"
},

Overrides need to be configured here to solve the dependency conflict problem, because @ohos/flutter_module depends on @ohos/flutter_ohos, but because a relative directory is used, it will cause loading failure, so overrides are used here to re-specify the path of @ohos/flutter_ohos.

In addition, unlike the above tips or official documents, we also added @ohos/flutter_ohos in dependencies. This is for IDE prompts. If not, the following error message will appear

Cannot find module '@ohos/flutter_ohos' or its corresponding type declarations. <ArkTSCheck>

Finally, sign the ohos project again and run the DevEco project.

Now we just introduce the Har package into the ohos project. In the next article Jump to Flutter Page, we will introduce how to initialize the Flutter engine in the ohos native project and jump to open the Flutter page in the appropriate place.

Summary

This mode is suitable for larger project teams. A common scenario is that colleagues responsible for Flutter development develop designated modules and deliver them to the Harmony native development team in the form of Har packages.
In this mode, the Harmony native development team does not need to pay too much attention to the Flutter content, and does not even need to install the Flutter development environment, which can better separate responsibilities.
Disadvantages: Since the Flutter module is packaged into a Har package and exists as an so file, Flutter cannot be hot-reloaded.

References

HarmonyOS Flutter Practice: 21- Detailed Explanation of Hybrid Development-1-Overview

shaohushuo — Fri, 13 Jun 2025 13:17:52 +0000

Introduction

In the previous series of articles, we started with building the development environment, talked about how to use and integrate third-party plug-ins, how to transform existing projects into Harmony, and how to review them; we also took the use of Amap's HarmonyOS SDK as an example to explain how to integrate Amap into the project.

Hybrid Development

In addition to using Flutter projects as the main project development, there is another common development method, namely hybrid development. The main project project is the HarmonyOS project, and the Flutter project exists in the form of a module, which is loaded into the main project project in a dependent manner, and finally realizes hybrid development.

Presumably, hybrid development will not be unfamiliar, because we have also briefly introduced the two forms of hybrid development of Harmony Flutter projects.

Starting from this chapter, we will go deeper and explore these two hybrid development methods based on principles and engineering practice.

Two ways of hybrid development

Loading to HarmonyOS project as Har package

HAR (Harmony Archive) is a static shared package that can contain code, C++ libraries, resources and configuration files. HAR can be used to share ArkUI components, resources and other related codes among multiple modules or multiple projects.

This development method is to compile and package the Flutter module into a HAR package, and introduce this module package in the native Harmony project as a Har package to achieve hybrid development.

Loading to HarmonyOS project as source code

From the introduction of method 1, it can be found that each update of the Flutter module needs to be recompiled into a Har package and repackaged into the native Harmony project, which is very troublesome. So there is a way of source code dependency, that is,

Let the native Harmony project depend on the source code of the Flutter module, so that when the Flutter code changes, it does not need to be repackaged into a Har package, and hot updates can be implemented during the development process to refresh the interface in real time.

Development process

General directory

For the convenience of management/demonstration, the directory name of this example is ohos_flutter_module_demo. We create both the native Harmony project and the Flutter module in this directory.

Create a native Harmony project

This is the host project. Here we use DevEco Studio to create a native Harmony project under the ohos_flutter_module_demo directory. The project name in this article is ohos_app.

Create a Flutter module

The process is the same. We can use the following command to create a Flutter module:

flutter create --template=module my_flutter_module

The final project directory structure is as follows:

ohos_flutter_module_demo
├── my_flutter_module
├── ohos_app

In this way, for easy maintenance, the Flutter module is created outside the host project and is at the same level as the host project. In this article, the parent directory is ohos_flutter_module_demo, and there are two subdirectories under it, namely ohos_app (host project) and my_flutter_module (Flutter module).

Compile Flutter module

If you want to use the Har package mode, you need to compile the Flutter module into a Har package first; if you want to use the source code dependency method, this step is not required.

Use the following command to compile the Flutter module into a Har package:

flutter build har --debug

Configure the native Harmony project

If you use the Har package mode, you can add the Har package to the dependency file:

First, copy the built Har package to the ohos Harmony project:

cp -r my_flutter_module/.ohos/har/* ohos_app/har/

"dependencies": {
"@ohos/flutter_module": "file:har/flutter_module.har",
"@ohos/flutter_ohos": "file:har/flutter.har"
},
"overrides" {
"@ohos/flutter_ohos": "file:har/flutter.har",
}

If you use the source code mode, you need to add the source code of the Flutter module to the dependency file:

"dependencies": {
"@ohos/flutter_module": "../flutter_module"
}

Modify the entry file (optional) Modify the entry file and copy the EntryAbility.ets and Index.ets files in the .ohos directory generated by the Flutter module to the host project for replacement

cp my_flutter_module/.ohos/entry/src/main/ets/entryability/EntryAbility.ets ohos_app/entry/src/main/ets/entryability/EntryAbility.ets
cp my_flutter_module/.ohos/entry/src/main/ets/pages/Index.ets ohos_app/entry/src/main/ets/pages/Index.ets