将 Flutter module 集成到 Android 项目

Flutter 可以作为 Gradle 子项目源码或者 AAR 嵌入到现有的 Android 应用程序中。

Flutter can be embedded into your existing Android application piecemeal, as a source code Gradle subproject or as AARs.

开发者可以使用带有 Flutter 插件 的 Android Studio 或手动完成整个集成流程。

The integration flow can be done using the Android Studio IDE with the Flutter plugin or manually.

使用 Android Studio

Using Android Studio

直接使用 Android Studio 是在现有应用中自动集成 Flutter 模块比较便捷的方法。在 Android Studio 中,你可以在一个项目中同时编写 Android 代码和 Flutter 代码,还可以继续使用各种常用的 IntelliJ Flutter 插件功能,例如 Dart 代码自动补全、热重载和 widget 检查器等。

The Android Studio IDE is a convenient way of integrating your Flutter module automatically. With Android Studio, you can co-edit both your Android code and your Flutter code in the same project. You can also continue to use your normal IntelliJ Flutter plugin functionalities such as Dart code completion, hot reload, and widget inspector.

只有在 Android Studio 3.6 及以上的版本,配合 42 以上版本的 IntelliJ Flutter 插件 才能直接通过 Android Studio 执行集成流程,并且,Android Studio 目前仅支持以 Gradle 子项目源码的方式集成,而不能以 AAR 方式集成。有关这两种方式的区别及更多详细信息,请参见下文。

Add-to-app flows with Android Studio are only supported on Android Studio 3.6 with version 42+ of the Flutter plugin for IntelliJ. The Android Studio integration also only supports integrating using a source code Gradle subproject, rather than using AARs. See below for more details on the distinction.

在 Android Studio 打开现有的 Android 项目并点击菜单按钮 File > New > New Module… ,这样就可以创建出一个可以集成的新 Flutter 模块,或者选择导入已有的 Flutter 模块。

Using the File > New > New Module… menu in Android Studio in your existing Android project, you can either create a new Flutter module to integrate, or select an existing Flutter module that was created previously.

如果你想创建一个新的 Flutter 模块,则可以直接在向导窗口中填写模块名称、路径等信息。

If you create a new module, you can use a wizard to select the module name, location, and so on.

此时,Android Studio 插件就会自动为这个 Android 项目配置添加 Flutter 模块作为依赖项,这时集成应用就已准备好进行下一步的构建。

The Android Studio plugin automatically configures your Android project to add your Flutter module as a dependency, and your app is ready to build.

现在,应用程序已经包含了 Flutter 模块作为依赖项,你可以跳转至 向 Android 应用中添加 Flutter 页面 执行后续步骤。

Your app now includes the Flutter module as a dependency. You can jump to the Adding a Flutter screen to an Android app to follow the next steps.

手动集成

Manual integration

如果想要在不使用 Flutter 的 Android Studio 插件的情况下手动将 Flutter 模块与现有的 Android 应用集成,可以参考以下步骤:

To integrate a Flutter module with an existing Android app manually, without using Flutter’s Android Studio plugin, follow these steps:

创建 Flutter 模块

Create a Flutter module

假设你在 some/path/MyApp 路径下已有一个 Android 应用,并且你希望 Flutter 项目作为同级项目:

Let’s assume that you have an existing Android app at some/path/MyApp, and that you want your Flutter project as a sibling:

$ cd some/path/
$ flutter create -t module --org com.example my_flutter

这会创建一个 some/path/my_flutter/ 的 Flutter 模块项目,其中包含一些 Dart 代码来帮助你入门以及一个隐藏的子文件夹 .android/.android 文件夹包含一个 Android 项目,该项目不仅可以帮助你通过 flutter run 运行这个 Flutter 模块的独立应用,而且还可以作为封装程序来帮助引导 Flutter 模块作为可嵌入的 Android 库。

This creates a some/path/my_flutter/ Flutter module project with some Dart code to get you started and an .android/ hidden subfolder. The .android folder contains an Android project that can both help you run a barebones standalone version of your Flutter module via flutter run and it’s also a wrapper that helps bootstrap the Flutter module an embeddable Android library.

引入 Java 8

Java 8 requirement

Flutter Android 引擎需要使用到 Java 8 中的新特性。

The Flutter Android engine uses Java 8 features.

在尝试将 Flutter 模块项目集成到宿主 Android 应用之前,请先确保宿主 Android 应用的 build.gradle 文件的 android { } 块中声明了以下源兼容性,例如:

Before attempting to connect your Flutter module project to your host Android app, ensure that your host Android app declares the following source compatibility within your app’s build.gradle file, under the android { } block, such as:

android {
  //...
  compileOptions {
    sourceCompatibility 1.8
    targetCompatibility 1.8
  }
}

将 Flutter module 作为依赖项

Add the Flutter module as a dependency

接下来,将 Flutter 模块添加为 Gradle 中宿主应用程序的依赖项。主要有两种方法实现。 AAR 机制可以为每个 Flutter 模块创建 Android AAR 作为依赖媒介。当你的宿主应用程序开发者不想安装 Flutter SDK 时,这是一个很好方案,但是,如果你想要经常编译,那么每次都需要重新编译一次,该步骤不可避免。

Next, add the Flutter module as a dependency of your existing app in Gradle. There are two ways to achieve this. The AAR mechanism creates generic Android AARs as intermediaries that packages your Flutter module. This is good when your downstream app builders don’t want to have the Flutter SDK installed. But, it adds one more build step if you build frequently.

直接将 Flutter 模块的源码作为子项目的依赖机制是一种便捷的一键式构建方案,但此时需要另外安装 Flutter SDK,这是目前 Android Studio IDE 插件使用的机制。

The source code subproject mechanism is a convenient one-click build process, but requires the Flutter SDK. This is the mechanism used by the Android Studio IDE plugin.

方案 A - 依赖 Android Archive (AAR)

Option A - Depend on the Android Archive (AAR)

这种方式会将 Flutter 库打包成由 AAR 和 POM artifacts 组成的本地 Maven 存储库。这种方案可以使你的团队不需要安装 Flutter SDK 即可编译宿主应用。之后,你可以从本地或远程存储库中分发更新 artifacts。

This option packages your Flutter library as a generic local Maven repository composed of AARs and POMs artifacts. This option allows your team to build the host app without installing the Flutter SDK. You can then distribute the artifacts from a local or remote repository.

假设你在 some/path/my_flutter 下构建 Flutter 模块,执行如下命令:

Let’s assume you built a Flutter module at some/path/my_flutter, and then run:

$ cd some/path/my_flutter
$ flutter build aar

然后,根据屏幕上的提示完成集成操作。

Then, follow the on-screen instructions to integrate.

详细地说,该命令应用于创建(默认情况下创建 debug/profile/release 所有模式)本地存储库,主要包含以下文件:

More specifically, this command creates (by default all debug/profile/release modes) a local repository, with the following files:

build/host/outputs/repo
└── com
    └── example
        └── my_flutter
            ├── flutter_release
            │   ├── 1.0
            │   │   ├── flutter_release-1.0.aar
            │   │   ├── flutter_release-1.0.aar.md5
            │   │   ├── flutter_release-1.0.aar.sha1
            │   │   ├── flutter_release-1.0.pom
            │   │   ├── flutter_release-1.0.pom.md5
            │   │   └── flutter_release-1.0.pom.sha1
            │   ├── maven-metadata.xml
            │   ├── maven-metadata.xml.md5
            │   └── maven-metadata.xml.sha1
            ├── flutter_profile
            │   ├── ...
            └── flutter_debug
                └── ...

要依赖 AAR,宿主应用必须能够找到这些文件。

To depend on the AAR, the host app must be able to find these files.

为此,需要在宿主应用程序中修改 app/build.gradle 文件,使其包含本地存储库和上述依赖项:

To do that, edit app/build.gradle in your host app so that it includes the local repository and the dependency:

android {
  // ...
}

repositories {
  maven {
    url 'some/path/my_flutter/build/host/outputs/repo'
    // This is relative to the location of the build.gradle file
    // if using a relative path.
  }
  maven {
    url 'https://storage.googleapis.com/download.flutter.io'
  }
}

dependencies {
  // ...
  debugImplementation 'com.example.flutter_module:flutter_debug:1.0'
  profileImplementation 'com.example.flutter_module:flutter_profile:1.0'
  releaseImplementation 'com.example.flutter_module:flutter_release:1.0'
}

你的应用程序现在添加了 Flutter 模块作为依赖项,下面,你可以按照 向 Android 应用中添加 Flutter 页面 中的后续步骤继续操作。

Your app now includes the Flutter module as a dependency. You can follow the next steps in the Adding a Flutter screen to an Android app.

方案 B - 依赖模块的源码

Option B - Depend on the module’s source code

该方式可以使你的 Android 项目和 Flutter 项目能够同步一键式构建。当你需要同时在这两个项目中进行快速迭代时,这种方案非常方便,但是此时,你的团队必须安装 Flutter SDK 才能构建宿主应用程序。

This option enables a one-step build for both your Android project and Flutter project. This option is convenient when you work on both parts simultaneously and rapidly iterate, but your team must install the Flutter SDK to build the host app.

将 Flutter 模块作为子项目添加到宿主应用的 settings.gradle 中:

Include the Flutter module as a subproject in the host app’s settings.gradle:

// Include the host app project.
include ':app'                                    // assumed existing content
setBinding(new Binding([gradle: this]))                                // new
evaluate(new File(                                                     // new
  settingsDir.parentFile,                                              // new
  'my_flutter/.android/include_flutter.groovy'                         // new
))                                                                     // new

假设 my_flutterMyApp 是同级目录。

Assuming my_flutter is a sibling to MyApp.

binding 和 evaluation 脚本可以使 Flutter 模块将其自身(如 :flutter)和该模块使用的所有 Flutter 插件(如 :package_info:video_player 等)都包含在 settings.gradle 的评估的上下文中。

The binding and script evaluation allows the Flutter] module to include itself (as :flutter) and any Flutter plugins used by the module (as :package_info, :video_player, etc) in the evaluation context of your settings.gradle.

在你的应用中引入对 Flutter 模块的依赖:

Introduce an implementation dependency on the Flutter module from your app:

dependencies {
  implementation project(':flutter')
}

此时,你的应用程序已将 Flutter 模块添加为依赖项,下面,你可以按照 向 Android 应用中添加 Flutter 页面 中的后续步骤继续操作。

Your app now includes the Flutter module as a dependency. You can follow the next steps in the Adding a Flutter screen to an Android app.