新增對預測返回手勢的支援

預測返回這項手勢操作功能可讓使用者預覽向後滑動會前往的位置。

舉例來說，使用返回手勢時，您可以看到應用程式後方主畫面的動畫預覽，如圖 1 中的模擬操作情形所示。

自 Android 15 起，系統不再提供預測返回動畫的開發人員選項。如果應用程式已全面或在活動層級選擇加入預測返回手勢，現在會顯示返回主畫面、跨任務和跨活動等系統動畫。

您可以測試這個返回主畫面動畫，詳情請參閱本頁後續章節。

如要支援預測返回手勢，您必須使用 AndroidX Activity 1.6.0 以上版本 API 中具有回溯相容性的 OnBackPressedCallback，或新的 OnBackInvokedCallback 平台 API 更新應用程式。大多數應用程式都會使用具有回溯相容性的 AndroidX API。

這項更新提供遷移路徑，可正確攔截返回瀏覽，包括在 KeyEvent.KEYCODE_BACK 和任何使用 onBackPressed 方法的類別 (例如 Activity 和 Dialog) 中，將返回攔截替換為新的系統 Back API。

程式碼研究室和 Google I/O 大會影片

除了使用本頁的說明文件，您還可以試用我們的程式碼研究室。它提供使用 AndroidX 活動 API 處理預測返回手勢的 WebView 常見用途實作。

您也可以觀看 Google I/O 大會影片，其中涵蓋實作 AndroidX 和平台 API 的更多範例。

在 Compose 中處理自訂返回手勢

Compose 提供 PredictiveBackHandler 可組合函式，用於處理自訂返回手勢。這個 API 可讓您回應返回手勢，並提供 BackEventCompat 物件的 Flow，可用於在使用者滑動時實作自訂動畫或轉場效果。

如要使用 PredictiveBackHandler，請確認應用程式包含 androidx.activity:activity-compose 依附元件 (1.8.0 以上版本)：

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}

PredictiveBackHandler(enabled = isBackHandlerEnabled) { progress: Flow<BackEventCompat> ->
    try {
        progress.collect { backEvent ->
            // Update your UI or animation based on backEvent.progress.
        }
        // Handle the final back action (e.g., navigate back).
    } catch (e: CancellationException) {
        // Back gesture was cancelled, reset your UI.
    }
}
PredictiveBackSnippets.kt

如果只需要攔截返回手勢，而不必追蹤進度，請使用 BackHandler。

更新使用預設返回瀏覽功能的應用程式

預設會啟用預測返回功能。

如果應用程式使用 Fragment 或 Navigation 元件，也請升級至 AndroidX Activity 1.6.0 以上版本。

更新使用自訂返回瀏覽功能的應用程式

如果應用程式有實作自訂返回行為，則視其是否使用 AndroidX 以及處理返回瀏覽的方式而定，遷移路徑各有不同。

遷移 AndroidX 返回瀏覽實作

這是最常見的用途，也是最建議的做法。這種做法適用於使用 OnBackPressedDispatcher 實作自訂手勢操作處理的全新或現有應用程式，詳情請參閱「提供自訂返回瀏覽功能」一文。

為確保已使用 OnBackPressedDispatcher 的 API (例如 Fragments 和 Navigation 元件) 可與預測返回手勢完美搭配運作，請升級至 AndroidX Activity 1.6.0 以上版本。

// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

將含有不支援的返回導覽 API 的 AndroidX 應用程式遷移至 AndroidX API

如果應用程式使用 AndroidX 程式庫，但實作或參照不支援的返回瀏覽 API，您必須改用 AndroidX API 來支援新行為。

如何將不支援的 API 遷移至 AndroidX API：

1. 實作 OnBackPressedCallback 即可將系統 Back 處理邏輯遷移至 AndroidX 的 OnBackPressedDispatcher。如需詳細指南，請參閱「提供自訂返回瀏覽功能」。

2. 在準備好停止攔截返回手勢時，停用 OnBackPressedCallback。

3. 停止使用 OnBackPressed 或 KeyEvent.KEYCODE_BACK 攔截返回事件。

4. 請務必升級至 AndroidX Activity 1.6.0 以上版本。

   // In your build.gradle file:
   dependencies {
       // Add this in addition to your other dependencies
       implementation "androidx.activity:activity:1.6.0"
   }
   

停用預測返回

如要選擇停用這項功能，請在 AndroidManifest.xml 的 <application> 標記中將 android:enableOnBackInvokedCallback 標記設為 false。

<application
    ...
    android:enableOnBackInvokedCallback="false"
    ... >
...
</application>

如果將這個屬性設為 false，會發生以下情況：

• 停用預測返回手勢系統動畫。
• 忽略 OnBackInvokedCallback，但 OnBackPressedCallback 呼叫繼續運作。

在活動層級選擇停用

android:enableOnBackInvokedCallback 旗標可讓您在活動層級選擇不採用預測系統動畫。透過這個行為，您可以更輕鬆管理將大型多活動應用程式遷移至預測返回手勢的過程。

以下程式碼示範如何設定 enableOnBackInvokedCallback，啟用 MainActivity 的「返回主畫面」系統動畫：

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

        <activity
            android:name=".MainActivity"
            android:enableOnBackInvokedCallback="true"
            ...
        </activity>
        <activity
            android:name=".SecondActivity"
            android:enableOnBackInvokedCallback="false"
            ...
        </activity>
    </application>
</manifest>

使用 android:enableOnBackInvokedCallback 旗標時，請注意下列事項：

• 設定 android:enableOnBackInvokedCallback=false 會根據標記的設定位置，在活動層級或應用程式層級關閉預測返回動畫，並指示系統忽略對 OnBackInvokedCallback 平台 API 的呼叫。不過，由於 OnBackPressedCallback 具有回溯相容性，且會呼叫 onBackPressed API (Android 13 以下版本不支援此 API)，因此對 OnBackPressedCallback 的呼叫會繼續執行。
• 在應用程式層級設定 enableOnBackInvokedCallback 旗標，會為應用程式中的所有活動建立預設值。您可以在活動層級設定旗標，覆寫每項活動的預設值，如上述程式碼範例所示。

回呼指南

使用支援的系統返回回呼時，請遵循下列指南：PredictiveBackHandler 或 BackHandler (適用於 Compose)、OnBackPressedCallback 或 OnBackInvokedCallback。

決定能啟用及停用每個回呼的 UI 狀態

UI 狀態是一種用來描述 UI 的屬性。建議您按照以下概略步驟操作。

1. 決定能啟用及停用每個回呼的 UI 狀態。

2. 使用可觀測的資料容器類型 (例如 StateFlow 或 Compose State) 定義狀態，並在狀態變更時啟用或停用回呼。

如果應用程式先前已將返回邏輯與條件陳述式建立關聯，這可能表示您是在返回事件發生後才做出回應。請避免在較新的回呼中使用這個模式。如果可以，請將回呼移至條件陳述式之外，並改將回呼與可觀測的資料容器類型建立關聯。

將系統返回回呼用於 UI 邏輯

UI 邏輯會決定 UI 顯示方式。請使用系統返回回呼執行 UI 邏輯，例如顯示對話方塊或執行動畫。

如果應用程式使用 PRIORITY_DEFAULT 或 PRIORITY_OVERLAY 啟用 OnBackPressedCallback 或 OnBackInvokedCallback，預測返回動畫就不會執行，您也必須處理返回事件。請勿建立這些回呼來執行商業邏輯或記錄。

如果應用程式必須在使用者向後滑動時執行商業邏輯或記錄，請採用下列方法：

• 在 Compose 中：在與 Compose 目的地相關聯的 ViewModel 的 onCleared() 回呼中記錄。這是瞭解 Compose 目的地何時從返回堆疊中彈出並刪除的最佳信號。
• Android 16 以上版本：請搭配使用 OnBackInvokedCallback 和 PRIORITY_SYSTEM_NAVIGATION_OBSERVER。這會建立不消耗返回事件的觀察器回呼。舉例來說，當使用者從根活動向後滑動 (離開應用程式) 時，您可以註冊這個回呼，記錄返回事件或執行商業邏輯，同時仍允許播放返回主畫面的動畫。
• 在以 View 為基礎的應用程式中：在生命週期或返回堆疊回呼中記錄，而不是使用返回事件：
  • 如果是活動轉換，請檢查 isFinishing 在 Activity.onDestroy() 內是否為 true。
  • 如果是片段轉場，請檢查 isRemoving 在 Fragment 的檢視畫面生命週期 onDestroy() 中是否為 true，或使用 FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted/onBackStackChangeCommitted)。

建立單一責任回呼

您可以對調度工具新增多個回呼，回呼會新增至堆疊中，堆疊內最近新增的已啟用回呼會處理下一個返回手勢，而每個返回手勢都有一個回呼。

如果回呼只有單一責任，就更容易管理回呼的啟用狀態。例如：

圖 2 顯示如何在堆疊中加入多個回呼，每個回呼負責一項工作。在 Compose 中，系統會從最內層到最外層的可組合函式評估回呼，且只有在堆疊中前面的回呼停用時，才會執行回呼：

• 「你確定…」當使用者在表單中輸入資料時，系統會啟用 PredictiveBackHandler，否則會停用。啟用後，系統會攔截返回手勢，顯示確認對話方塊或自訂應用程式內動畫。
• 如果前一個回呼已停用，系統會執行畫面層級的 BackHandler。在本範例中，這項功能已停用。
• 如果先前的自訂回呼已停用，NavHost 回呼會處理返回瀏覽，從返回堆疊中彈出目的地。
• 最後，如果上述所有回呼都已停用，系統會處理返回手勢。當返回堆疊位於根層級目的地時，系統會觸發系統層級動畫，例如返回主畫面、跨活動和跨任務。

View 應用程式也適用相同的堆疊行為：最後新增的已啟用 OnBackPressedCallback 優先，接著是 FragmentManager，最後是系統返回處理。

測試預測返回手勢動畫

從 Android 15 開始，如果應用程式支援預測返回導覽，系統會預設啟用返回主畫面、跨任務和跨活動等系統動畫。不再需要透過開發人員選項啟用。

在搭載 Android 13 或 Android 14 的裝置上，您可以啟用開發人員選項，測試圖 1 所示的返回主畫面動畫：

1. 在裝置上，依序前往「設定」>「系統」>「開發人員選項」。

2. 選取「預測返回操作動畫」。

3. 啟動更新後的應用程式，然後使用返回手勢查看實際運作情形。