将 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 路由为“/”。不能使用 Intent 更改 Dart 入口点，但可以使用 Intent 更改初始路由。以下示例演示了如何启动一个 FlutterActivity，该 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。接下来讨论使用缓存的 FlutterEngine 的 FlutterActivity。

使用预热的、缓存的 FlutterEngine 后，您现在需要指示您的 FlutterActivity 使用缓存的 FlutterEngine，而不是创建一个新的 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。