将 Flutter module 集成到 Android 项目

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

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

使用 Android Studio

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

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

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

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

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

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

手动集成

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

创建 Flutter 模块

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

$ 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 库。

引入 Java 11

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

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

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

将 Flutter module 作为依赖项

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

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

方案 A - 依赖 Android Archive (AAR)

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

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

$ cd some/path/my_flutter
$ flutter build aar

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

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

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,宿主应用必须能够找到这些文件。

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

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 页面 中的后续步骤继续操作。

方案 B - 依赖模块的源码

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

将 Flutter 模块作为子项目添加到宿主应用的 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 是同级目录。

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

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

dependencies {
  implementation project(':flutter')
}

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