将 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 的背景颜色。

在 AndroidManifest.xml 文件中注册了 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 更改初始路由。以下示例演示了如何启动一个最初在 Flutter 中呈现自定义路由的 FlutterActivity。

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 而不是创建一个新的。为此，请使用 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。

除非另有说明，否则本网站上的文档反映了 Flutter 的最新稳定版本。页面上次更新于 2024-10-31。 查看源代码 或 报告问题.