HarmonyOS Flutter in action: 14 - Existing Flutter projects support HarmonyOS II

Introduction

In the previous article HarmonyOS Flutter Practice: 09 - Existing Flutter Projects Support HarmonyOS, how to transform the project and adapt to the HarmonyOS platform.

The overall concept and thinking are described in this article, and this article goes a step further and details how to implement it in combination with practical project code.

Through modularization, HarmonyOS shell engineering, combined with FVM to manage multiple versions of the Flutter SDK, finally, the original Flutter code is kept pure, modifications are minimized, and the adaptation example of HarmonyOS is completed.

Address of this project code: https://gitee.com/zacks/flutter-ohos-demo

Preparation

1. Install FVM and melos

Install FVM, for more installation methods, please refer to the official fvm documentation

curl -fsSL https://fvm.app/install.sh | bash

Installing Melos

dart pub global activate melos

2.Install the Flutter SDK using FVM

Install the official version 3.22 and the 3.22.0 (https://gitee.com/harmonycommando_flutter/flutter) version of the HarmonyOS community

3.Build a Flutter development environment

Refer to the article "HarmonyOS Flutter Practice: 01 - Building a Development Environment"

Build the project structure

Create a directory

# Create a project directory
mkdir flutter-ohos-demo

Set the version of the Flutter SDK to use
It is recommended to execute the following command in the command line of VsCode, which will create a .fvm directory, a .vscode/setting.json file, and a .fvmrc file

fvm use 3.22.0

Initialize the workspace

Create a directory with the project structure as follows:

.
├── packages
│ ├── apps # This directory is used to store the application shell projects on each end
│ ├── Common # This directory is used to store public libraries, which are pure DART code and do not depend on native implementations such as ios/android
│ │ ├── domains # domain objects, which store all kinds of entity files, such as enums, models, vos, events, etc
│ │ ├── extensions # Stores the extension class file, the extension method/attribute of the class
│ │ ├── services # Services: such as request service, authorization service, cache service, platform call service, routing service, tool, etc
│ │ └── widgets # Generic small widgets, Flutter UI components written by pure dart
│ ├── components # Encapsulated component libraries, which can depend on third-party libraries/third-party plugins, or on plugins in plugins
│ │ ├── image_uploader
│ │ └── player
│ ├── modules
│ │ ├── address
│ │ ├── home
│ │ ├── me
│ │ ├── message
│ │ ├── order
│ │ ├── shop
│ │ └── support
│ └── plugins # plugin library, self-encapsulated plugin library, relying on the code of the native platform (ios/android).
│ └── printer
├── README.md
├── melos.yaml
└── pubspec.yaml

Run melos bootstrap

melos bootstrap

Start writing code

Initialize the code in each package, e.g. in the 'packages/common/domains' directory

fvm flutter create --template package .

Create a shell project

Create two new shell projects, one for app and one for ohos_app

App Shell Engineering

Go to the 'package/apps/app' directory and create an app project, which is an app project for packaging on various platforms (ios/android/mac, etc., excluding HarmonyOS).

fvm flutter create --template app --org com.shaohushuo.flutter app

Add dependencies

Modify pubspec.yaml to add the following:

  services:
    path: '../../common/services'
  domains:
    path:  '../../common/domains'
  widgets:
    path: '../../common/widgets'

  home:
    path: '../../modules/home'
  me:
    path: '../../modules/me'
  support:
    path: '../../modules/support'

Install dependencies

Run the following command to install the dependency:

fvm flutter pub get

Hongmeng shell project

Toggle the HarmonyOS Flutter SDK

First, switch the Flutter version to the HarmonyOS version at the root of the flutter-ohos-demo project

fvm use custom_3.22.0

After > SDK changes, you will need to restart the IDE (or Dart:Restart Analysis Server) for the Flutter plugin to restart

Create a ohos_app project

Go to the packages/apps directory and create a ohos_app project

fvm flutter create --template app --platforms ohos --org com.shaohushuo.flutter ohos_app

Add dependencies

Go to pubspec.yaml in the packages/apps/ohos_app directory and add the dependencies as well

  services:
    path: '../../common/services'
  domains:
    path:  '../../common/domains'
  widgets:
    path: '../../common/widgets'

  home:
    path: '../../modules/home'
  me:
    path: '../../modules/me'
  support:
    path: '../../modules/support'

Adaptation of the three-party library Hongmeng

1. If FVM is used, edit the pubspec.yaml file, add the following configuration, and replace the HarmonyOS third-party library with dependency_overrides, pay attention to the HarmonyOS library and the original database, and keep the version unified

# # HarmonyOS adaptation
dependency_overrides:
  flutter_inappwebview:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      path: "flutter_inappwebview"

After editing and running 'melos bootstrap', update the pubspec_overrides.yaml and add the same dependency_overrides content to it.

1. If you are not using FVM, edit the pubspec_overrides.yaml file directly, or create it manually if you don't, add the following:

# # HarmonyOS adaptation
dependency_overrides:
  flutter_inappwebview:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git
      path: "flutter_inappwebview"

After editing, run 'flutter pub get' to install the dependency.

After the above two methods are successfully executed, you can observe the pubspec.lock file, and you can find that a plug-in dependency similar to xxx_ohos has been added, and the example in this article is 'flutter_inappwebview_ios'

1. Federated plug-in mode

In addition to the above two ways of using dependency_overrides to configure the HarmonyOS adaptation library, if the third-party plug-in itself uses the form of a federated plug-in, you can also add the implementation of the HarmonyOS platform in the following way:

dependencies:

  image_picker: ^1.1.2
  image_picker_ohos:
    git:
      url: "https://gitcode.com/openharmony-sig/flutter_packages.git"
      path: "packages/image_picker/image_picker_ohos"

This is called "unintegrated federation plugins" (https://docs.flutter.cn/packages-and-plugins/developing-packages#non-endorsed-federated-plugin), and in the above configuration,
image_picker is a federation plugin, here directly use the latest version of the official community, observe the pubspec.yaml file of the plugin, through its structure you can find the characteristics of the federation plugin, the dependencies of the plugin are:

dependencies:
  image_picker_platform_interface: ^2.10.0
  ...
  image_picker_android: ^0.8.7
  image_picker_ios: ^0.8.8

'image_picker_platform_interface' is an abstraction layer, which defines the platform-related interfaces, the following is the implementation of each platform, by splitting it into packages, loading in a dependent way, then the same principle, you can add another implementation package of the HarmonyOS platform, you can complete the HarmonyOS adaptation, that is, the 'image_picker_ohos' in the above example:

  image_picker_ohos:
    git:
      url: "https://gitcode.com/openharmony-sig/flutter_packages.git"
      path: "packages/image_picker/image_picker_ohos"

Run the debug

Open the apps/ohos_app/ohos directory with Deveco.

In the upper left corner of Deveco, open File -> Project Structure..., click Siging Configs, and check Automatically generate signature to sign the HarmonyOS project.

In the ohos_app directory, use the fvm flutter run, or click the run button to run the flutter project.

Precautions

1. 'sdkPath: .fvm/flutter_sdk' in the melos.yaml file is configured with the flutter SDK version used by melos, i.e. the current project version configured by FVM

2. Every time you switch the Flutter SDK, the .fvm/, vscode/settings.json files are modified

3. ohos_app/pubsec.yaml in the dependency_overrides, and only add the third-party libraries that need to be Harmony

4. ohos-3.22 At the time of build, some har packages may be true, it is recommended to keep the ohos-Flutter version up-to-date, if it still doesn't work, you can consider manually copying the har package (built with 3.7)

How to determine whether the third-party library needs to be Hongmeng, in short, if the third-party library is implemented by pure Dart, it does not need to be adapted separately and used directly; If the third-party library depends on the underlying implementation of the system, it needs to be adapted to harmony.

For the adaptation of the third-party library, you can check Gitee/Github, or check the table Flutter third-party library adaptation plan

1. Known plugin deletion issues, if you delete the plugin, you may need to manually modify the code in ohos to remove related dependencies

ohos/oh-package.json5

Summary

1. Manage multiple Flutter SDK versions through FVM, and switch to ohos-flutter SDK only when HarmonyOS commissioning and packaging
2. Through the apps shell project, the code adapted to HarmonyOS will be completed in the ohos_app project as much as possible. Through the 'dependency_overrides' configuration managed by the pub package, the third-party libraries of Hongmeng are replaced one by one
3. Manage multi-package projects through melos, and Flutter projects are modularized, componentized, and plugged into plug-ins, with separation of responsibilities, platform abstraction, and combination and packaging of different platforms, effectively solving the problem of platform inconsistency

References

• Harmony Flutter Practice: 01-Build Development Environment
• Harmony Flutter Practice: 09 - Existing Flutter Project Support Harmony Learning
• Flutter Tripartite Library Adaptation Plan
• flutter-ohos-demo project code