将 Flutter module 集成到 Android 项目

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

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

集成 Flutter 模块

#

Integrate with Android Studio

#

使用 Android Studio 集成

#

直接使用 Android Studio 是在现有应用中自动集成 Flutter 模块比较便捷的方法。在 Android Studio 中,你可以在一个项目中同时编写 Android 代码和 Flutter 代码。

你还可以继续使用各种常用的 IntelliJ Flutter 插件功能,例如 Dart 代码自动补全、热重载和 widget 检查器等。

为了构建你的应用, Android Studio 插件会配置你的 Android 项目,来将 Flutter 模块添加为依赖。

  1. 在 Android Studio 中打开你的 Android 项目。

  2. 前往 File > New > New Project...,此时 New Project 弹窗会显示。

  3. 选择 Flutter

  4. 填写你的 Flutter SDK path 并点击 Next 继续。

  5. 完成你的 Flutter 模块配置。

    • 如果你的项目是已有的:

      1. 点击 Project location 右侧的 ... 选择现有的项目。

      2. 前往你的 Flutter 项目的目录所在位置。

      3. 点击 打开

    • 如果你需要创建一个新的 Flutter 项目:

      1. 完成配置弹窗的内容。

      2. Project type 菜单中,选择 Module

  6. 点击完成。

不使用 Android Studio 进行集成

#

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

创建 Flutter 模块

#

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

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

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

Java 版本要求

#

Flutter 需要使用 Java 11 的特性。

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

MyApp/app/build.gradle
groovy
android {
  //...
  compileOptions {
    sourceCompatibility 11 // The minimum value
    targetCompatibility 11 // The minimum value
  }
}

Centralize repository settings

#

Starting with Gradle 7, Android recommends using centralized repository declarations in settings.gradle instead of project or module level declarations in build.gradle files.

Before attempting to connect your Flutter module project to your host Android app, make the following changes.

  1. Remove the repositories block in all of your app's build.gradle files.

    groovy
    // Remove the following block, starting on the next line
        repositories {
            google()
            mavenCentral()
        }
    // ...to the previous line
  2. Add the dependencyResolutionManagement displayed in this step to the settings.gradle file.

    groovy
    dependencyResolutionManagement {
      repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
      repositories {
        google()
        mavenCentral()
      }
    }
## Add the Flutter module as a dependency

将 Flutter module 作为依赖项

#

主要有两种方法将 Flutter 模块添加为 Gradle 中宿主应用程序的依赖项。

  1. AAR 集成 AAR 机制可以为每个 Flutter 模块创建 Android AAR 作为依赖媒介。当你的宿主应用程序开发者不想安装 Flutter SDK 时,这是一个很好方案。但是每次修改都需要重新编译。

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

Depend on the Android Archive (AAR)

#

依赖 Android Archive (AAR)

#

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

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

cd some/path/flutter_module
flutter build aar

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

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

build/host/outputs/repo
└── com
    └── example
        └── flutter_module
            ├── 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,宿主应用必须能够找到这些文件。

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

groovy
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
  repositories {
    google()
    mavenCentral()

  // Add the new repositories starting on the next line...
    maven {
      url 'some/path/flutter_module/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'
    }
  // ...to before this line  
  }
}

基于 Kotlin DSL 的 Android 项目

#

在基于 Kotlin DSL Android 项目的 aar 构建完成后,请按照以下步骤添加 flutter_module。

在 Android 项目的 app/build.gradle 文件中将 flutter module 列为依赖项。

MyApp/app/build.gradle.kts
kotlin
android {
    buildTypes {
        release {
          ...
        }
        debug {
          ...
        }
        create("profile") {
            initWith(getByName("debug"))
        }
}
dependencies {
  // ...
  debugImplementation "com.example.flutter_module:flutter_debug:1.0"
  releaseImplementation 'com.example.flutter_module:flutter_release:1.0'
  add("profileImplementation", "com.example.flutter_module:flutter_profile:1.0")
}

profileImplementation ID 是在宿主项目的 app/build.gradle 文件中实施的自定义 configuration

host-project/app/build.gradle.kts
kotlin
configurations {
    getByName("profileImplementation") {
    }
}
MyApp/settings.gradle.kts
kotlin
include(":app")

dependencyResolutionManagement {
    repositories {
        maven(url = "https://storage.googleapis.com/download.flutter.io")
        maven(url = "some/path/flutter_module_project/build/host/outputs/repo")
    }
}

依赖模块的源码

#

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

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

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

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

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

MyApp/app/build.gradle
groovy
dependencies {
    implementation project(':flutter')
}
Your app now includes the Flutter module as a dependency.

此时,你的应用程序已将 Flutter 模块添加为依赖项,

接下来你可以按照 向 Android 应用中添加 Flutter 页面 继续进一步的集成。