將 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。