将 Flutter 屏幕添加到 Android 应用

本指南介绍如何将单个 Flutter 屏幕添加到现有的 Android 应用。Flutter 屏幕可以作为正常的、不透明的屏幕添加，也可以作为透明的、半透明的屏幕添加。本指南将介绍这两种选项。

Flutter 提供了 FlutterActivity 以在 Android 应用中显示 Flutter 体验。与任何其他 Activity 一样，FlutterActivity 必须在 AndroidManifest.xml 中注册。将以下 XML 添加到 AndroidManifest.xml 文件中的 application 标签下

<activity
  android:name="io.flutter.embedding.android.FlutterActivity"
  android:theme="@style/LaunchTheme"
  android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
  android:hardwareAccelerated="true"
  android:windowSoftInputMode="adjustResize"
  />

对 @style/LaunchTheme 的引用可以替换为任何您希望应用于 FlutterActivity 的 Android 主题。主题的选择决定了应用于 Android 系统 chrome（例如 Android 导航栏）的颜色，以及 Flutter UI 首次渲染之前 FlutterActivity 的背景颜色。

在清单文件中注册 FlutterActivity 后，添加代码以便在应用中您希望的任何位置启动 FlutterActivity。以下示例显示了从 OnClickListener 启动 FlutterActivity 的情况。

MyButton(onClick = {
    startActivity(
        FlutterActivity.createDefaultIntent(this)
    )
})

@Composable
fun MyButton(onClick: () -> Unit) {
    Button(onClick = onClick) {
        Text("Launch Flutter!")
    }
}

myButton.setOnClickListener {
  startActivity(
    FlutterActivity.createDefaultIntent(this)
  )
}

myButton.setOnClickListener(new OnClickListener() {
  @Override
  public void onClick(View v) {
    startActivity(
      FlutterActivity.createDefaultIntent(currentActivity)
    );
  }
});

前面的示例假设您的 Dart 入口点名为 main()，并且您的初始 Flutter 路由为 '/'。Dart 入口点不能使用 Intent 更改，但初始路由可以使用 Intent 更改。以下示例演示了如何启动一个 FlutterActivity，使其最初在 Flutter 中渲染一个自定义路由。

MyButton(onClick = {
  startActivity(
    FlutterActivity
      .withNewEngine()
      .initialRoute("/my_route")
      .build(this)
  )
})

@Composable
fun MyButton(onClick: () -> Unit) {
    Button(onClick = onClick) {
        Text("Launch Flutter!")
    }
}

myButton.setOnClickListener {
  startActivity(
    FlutterActivity
      .withNewEngine()
      .initialRoute("/my_route")
      .build(this)
  )
}

myButton.addOnClickListener(new OnClickListener() {
  @Override
  public void onClick(View v) {
    startActivity(
      FlutterActivity
        .withNewEngine()
        .initialRoute("/my_route")
        .build(currentActivity)
      );
  }
});

将 "/my_route" 替换为您想要的初始路由。

使用 withNewEngine() 工厂方法会配置一个 FlutterActivity，该活动会在内部创建自己的 FlutterEngine 实例。这会带来不小的初始化时间开销。另一种方法是指示 FlutterActivity 使用预热的缓存 FlutterEngine，这可以最大限度地减少 Flutter 的初始化时间。接下来将讨论这种方法。

默认情况下，每个 FlutterActivity 都会创建自己的 FlutterEngine。每个 FlutterEngine 都有一个不小的预热时间。这意味着启动标准的 FlutterActivity 会在 Flutter 体验变得可见之前出现短暂的延迟。为了最大限度地减少这种延迟，您可以在到达 FlutterActivity 之前预热 FlutterEngine，然后使用预热的 FlutterEngine。

要预热 FlutterEngine，请在您的应用中找到一个合适的位置来实例化 FlutterEngine。以下示例任意地在 Application 类中预热 FlutterEngine

class MyApplication : Application() {
  lateinit var flutterEngine : FlutterEngine

  override fun onCreate() {
    super.onCreate()

    // Instantiate a FlutterEngine.
    flutterEngine = FlutterEngine(this)

    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.dartExecutor.executeDartEntrypoint(
      DartExecutor.DartEntrypoint.createDefault()
    )

    // Cache the FlutterEngine to be used by FlutterActivity.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine)
  }
}

public class MyApplication extends Application {
  public FlutterEngine flutterEngine;
  
  @Override
  public void onCreate() {
    super.onCreate();
    // Instantiate a FlutterEngine.
    flutterEngine = new FlutterEngine(this);

    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.getDartExecutor().executeDartEntrypoint(
      DartEntrypoint.createDefault()
    );

    // Cache the FlutterEngine to be used by FlutterActivity.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine);
  }
}

传递给 FlutterEngineCache 的 ID 可以是您想要的任何值。请确保将相同的 ID 传递给任何应该使用缓存 FlutterEngine 的 FlutterActivity 或 FlutterFragment。接下来将讨论如何将 FlutterActivity 与缓存的 FlutterEngine 配合使用。

有了预热的缓存 FlutterEngine，您现在需要指示您的 FlutterActivity 使用缓存的 FlutterEngine，而不是创建一个新的。为此，请使用 FlutterActivity 的 withCachedEngine() 构建器

myButton.setOnClickListener {
  startActivity(
    FlutterActivity
      .withCachedEngine("my_engine_id")
      .build(this)
  )
}

myButton.addOnClickListener(new OnClickListener() {
  @Override
  public void onClick(View v) {
    startActivity(
      FlutterActivity
        .withCachedEngine("my_engine_id")
        .build(currentActivity)
      );
  }
});

使用 withCachedEngine() 工厂方法时，请传入您缓存所需 FlutterEngine 时使用的相同 ID。

现在，当您启动 FlutterActivity 时，Flutter 内容的显示延迟将显著减少。

当使用新的 FlutterEngine 配置 FlutterActivity 或 FlutterFragment 时，初始路由的概念是可用的。但是，当使用缓存引擎时，FlutterActivity 和 FlutterFragment 不提供初始路由的概念。这是因为缓存引擎预计已经运行了 Dart 代码，这意味着配置初始路由为时已晚。

希望其缓存引擎以自定义初始路由开始的开发者可以在执行 Dart 入口点之前，配置其缓存的 FlutterEngine 以使用自定义初始路由。以下示例演示了在缓存引擎中使用初始路由的方法

class MyApplication : Application() {
  lateinit var flutterEngine : FlutterEngine
  override fun onCreate() {
    super.onCreate()
    // Instantiate a FlutterEngine.
    flutterEngine = FlutterEngine(this)
    // Configure an initial route.
    flutterEngine.navigationChannel.setInitialRoute("your/route/here");
    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.dartExecutor.executeDartEntrypoint(
      DartExecutor.DartEntrypoint.createDefault()
    )
    // Cache the FlutterEngine to be used by FlutterActivity or FlutterFragment.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine)
  }
}

public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    // Instantiate a FlutterEngine.
    flutterEngine = new FlutterEngine(this);
    // Configure an initial route.
    flutterEngine.getNavigationChannel().setInitialRoute("your/route/here");
    // Start executing Dart code to pre-warm the FlutterEngine.
    flutterEngine.getDartExecutor().executeDartEntrypoint(
      DartEntrypoint.createDefault()
    );
    // Cache the FlutterEngine to be used by FlutterActivity or FlutterFragment.
    FlutterEngineCache
      .getInstance()
      .put("my_engine_id", flutterEngine);
  }
}

通过设置导航通道的初始路由，关联的 FlutterEngine 会在首次执行 runApp() Dart 函数时显示所需的路由。

在 runApp() 首次执行后更改导航通道的初始路由属性将无效。希望在不同的 Activity 和 Fragment 之间使用相同的 FlutterEngine 并在这些显示之间切换路由的开发者需要设置一个方法通道，并明确指示其 Dart 代码更改 Navigator 路由。

大多数全屏 Flutter 体验都是不透明的。然而，有些应用希望部署一个看起来像模态的 Flutter 屏幕，例如对话框或底部表单。Flutter 开箱即用支持半透明的 FlutterActivity。

要使您的 FlutterActivity 半透明，请对创建和启动 FlutterActivity 的常规过程进行以下更改。

Android 要求对以半透明背景渲染的 Activity 使用特殊主题属性。创建或更新一个具有以下属性的 Android 主题

<style name="MyTheme" parent="@style/MyParentTheme">
  <item name="android:windowIsTranslucent">true</item>
</style>

然后，将半透明主题应用于您的 FlutterActivity。

<activity
  android:name="io.flutter.embedding.android.FlutterActivity"
  android:theme="@style/MyTheme"
  android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
  android:hardwareAccelerated="true"
  android:windowSoftInputMode="adjustResize"
  />

您的 FlutterActivity 现在支持半透明。接下来，您需要以明确的透明度支持启动您的 FlutterActivity。

要以透明背景启动您的 FlutterActivity，请将适当的 BackgroundMode 传递给 IntentBuilder

// Using a new FlutterEngine.
startActivity(
  FlutterActivity
    .withNewEngine()
    .backgroundMode(FlutterActivityLaunchConfigs.BackgroundMode.transparent)
    .build(this)
);

// Using a cached FlutterEngine.
startActivity(
  FlutterActivity
    .withCachedEngine("my_engine_id")
    .backgroundMode(FlutterActivityLaunchConfigs.BackgroundMode.transparent)
    .build(this)
);

// Using a new FlutterEngine.
startActivity(
  FlutterActivity
    .withNewEngine()
    .backgroundMode(FlutterActivityLaunchConfigs.BackgroundMode.transparent)
    .build(context)
);

// Using a cached FlutterEngine.
startActivity(
  FlutterActivity
    .withCachedEngine("my_engine_id")
    .backgroundMode(FlutterActivityLaunchConfigs.BackgroundMode.transparent)
    .build(context)
);

您现在拥有一个带有透明背景的 FlutterActivity。