将 Flutter 屏幕添加到 Android 应用

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

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

<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 系统控件（如 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 路由是 '/'。无法通过 Intent 更改 Dart 入口点，但可以通过 Intent 更改初始路由。以下示例演示了如何启动一个 FlutterActivity，该 Activity 最初渲染 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，该 Activity 会在内部创建自己的 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。接下来将讨论使用带缓存的 FlutterEngine 的 FlutterActivity。

使用预热的、缓存的 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。