將 SystemUiMode 的預設值設為 edge-to-edge

Edge-to-edge 模式是 Android 15 及以上版本的預設顯示行為。 在 Android 15 中，你可以選擇退出此行為，但自 Android 16 起便無法退出。 若要了解此變更的更多資訊， 請參閱 Android 16 發行說明。

在 Android 16 或更新版本上使用退出 edge-to-edge 的機制 可能會導致應用程式崩潰，但你可以透過使用特定版本的資源來避免此問題； 詳情請參閱遷移指南。

若要了解如何規劃應用程式結構以避免此問題， 建議你閱讀 LeanCode 的文章：Mastering Edge-To-Edge in Flutter: A Deep Dive Into the System Navigation Bar in Android。 你也可以在 GitHub 的 Issue 168635 中找到更多討論。

如果你的 Flutter 應用程式目標為 Android SDK 版本 15， 你的應用程式將自動以 edge-to-edge 模式顯示， 詳見 SystemUiMode API 文件頁面。 若要維持非 edge-to-edge 的應用程式行為 （包括未設定 SystemUiMode）， 請依照遷移指南進行。

預設情況下，Android 會對所有目標為 Android 15 或以上的應用程式強制啟用 edge-to-edge 模式。 若要了解此變更的更多資訊，請參閱 Android 15 發行說明。 這會影響運行於 Android SDK 15+ 或 API 35+ 的裝置。

在 Flutter 3.27 之前，Flutter 應用程式預設目標為 Android 14， 不會自動啟用 edge-to-edge 模式，但 當你選擇將應用程式目標設為 Android 15 時，_仍然_會受到影響。 如果你的應用程式目標為 flutter.targetSdkVersion（預設即如此）， 那麼從 Flutter 3.27 開始就會以 Android 15 為目標， 並自動啟用 edge-to-edge 模式。

如果你的應用程式已明確設定 SystemUiMode.edgeToEdge， 並透過呼叫 SystemChrome.setEnabledSystemUIMode 以 edge-to-edge 模式運行， 那麼你的應用程式已完成遷移。需要更多時間遷移至 edge-to-edge 模式的應用程式， 必須依照下列步驟，在運行 Android SDK 15 的裝置上選擇退出。

請注意下列事項：

1. Android 計劃僅暫時提供此處所述的解決方法。
2. Flutter 計劃在今年內與 Android（以及 iOS）保持一致， 預設支援 edge-to-edge，因此 請在作業系統移除退出選項前完成 edge-to-edge 模式的遷移。

若要在 SDK 15 上選擇退出 edge-to-edge， 請在每個需要的 activity 中指定新的 style 屬性。 如果你有父層 style，且子 style 也需要選擇退出， 你可以只修改父層 style。 以下範例中， 請更新由 flutter create 產生的 style 設定。

預設情況下，Flutter 應用程式所使用的 style 設定於 Android manifest 檔案（your_app/android/app/src/main/AndroidManifest.xml）中。 一般來說，style 以 @style 表示，並協助主題化你的應用程式。 請在 manifest 檔案中修改這些預設 style：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application ...>
        <activity ...>
            <!-- Style to modify: -->
            <meta-data
              android:name="io.flutter.embedding.android.NormalTheme"
              android:resource="@style/NormalTheme"
            />
        </activity>
    </application>
</manifest>

在以下位置找到樣式（style）定義： your_app/android/app/src/main/res/values/styles.xml。

在適當的樣式中新增以下屬性：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <style name="LaunchTheme" parent="@android:style/Theme.Light.NoTitleBar">
        ...
        <!-- Add the following line: -->
        <item name="android:windowOptOutEdgeToEdgeEnforcement">true</item>
    </style>
    ...
    <style name="NormalTheme" parent="@android:style/Theme.Light.NoTitleBar">
        ...
	      <!-- Add the following line: -->
        <item name="android:windowOptOutEdgeToEdgeEnforcement">true</item>
    </style>
</resources>

請確保在夜間模式樣式檔案中也套用相同的變更： your_app/android/app/src/main/res/values-night/styles.xml。

請確保這兩個檔案中的樣式都已一致更新。

這個修改後的樣式會讓你的應用程式在 目標為 Android SDK 15 的情況下退出 edge-to-edge 模式。

從 Flutter 3.27 開始，Flutter 應用程式預設會以 Android 15 為目標， 因此如果你希望使用這個版本，且不想手動將 Flutter 應用程式的目標 SDK 版本設為較低版本， 請依照前述的遷移步驟操作， 以維持未設定或非 edge-to-edge 的 SystemUiMode。

納入版本：3.26.0-0.0.pre
穩定版發佈：3.27

• 支援的 Flutter SystemUiMode
• Android 15 edge-to-edge 行為變更指南
• Android 16 edge-to-edge 行為變更指南