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

Android 13 (API 級別 33) 在手機、大螢幕裝置和折疊式裝置等 Android 裝置上推出了預測返回手勢，這也是我們努力多年的成果之一。在完整實作下，這項功能可讓使用者在完成返回手勢前先預覽目的地畫面或其他結果，再決定要繼續完成返回手勢或停留在目前的檢視畫面。

舉例來說，使用返回手勢時，您可以看到應用程式背後主畫面的動畫預覽，如圖 1 中的模擬操作情形所示。從 Android 13 開始，只要啟用開發人員選項，即可測試這個返回首頁動畫，詳情請參閱本頁說明。

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

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

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

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

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

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

如果應用程式未實作任何自訂返回行為 (也就是將返回程序交由系統處理)，更新應用程式就能直接支援這項功能。如本頁所述，只要選擇啟用這項功能即可。

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

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

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

應用程式使用 AndroidX	應用程式處理返回導覽的方式	建議的遷移路徑 (本頁上的連結)
是	AndroidX API	遷移現有的 AndroidX 返回實作
	不支援的平台 API	將含有不支援的返回導覽 API 的 AndroidX 應用程式遷移至 AndroidX API
否	不支援的平台 API，可遷移	將使用不支援的返回導覽 API 的應用程式遷移至平台 API
	不支援的平台 API，但無法遷移	延遲啟用，直到返回導覽成為必要功能為止

遷移 AndroidX 返回導覽實作

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

如果您的應用程式符合此類別，請按照下列步驟操作，讓應用程式支援預測返回手勢：

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

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

2. 按照本頁所述選擇啟用預測返回手勢。

將含有不支援的返回導覽 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-alpha05。

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

5. 應用程式順利遷移後，請按照本頁所述選擇啟用預測返回手勢。

將使用不支援的返回導覽 API 的應用程式遷移至平台 API

如果應用程式無法使用 AndroidX 程式庫，而是改用不支援的 API 實作或參照自訂 Back 導覽，就必須遷移至 OnBackInvokedCallback 平台 API。

如要將不支援的 API 遷移至平台 API，請完成下列步驟：

1. 在搭載 Android 13 以上版本的裝置上使用新的 OnBackInvokedCallback API。如果是搭載 Android 12 以下版本的裝置，則使用不支援的 API。

2. 透過 onBackInvokedDispatcher，在 OnBackInvokedCallback 中註冊自訂返回邏輯。這樣可以避免結束目前的活動，讓回呼有機會在使用者完成系統 Back 導覽後回應 Back 動作。

3. 在準備好停止攔截返回手勢後，取消註冊 OnBackInvokedCallback。否則，使用者在使用系統 Back 導覽時，可能會遇到不想要的行為，例如無法在檢視畫面之間「順暢轉換」，因而必須強制退出應用程式。

   以下範例說明如何從 onBackPressed 中遷出邏輯：

   Kotlin

   @Override
   fun onCreate() {
       if (BuildCompat.isAtLeastT()) {
           onBackInvokedDispatcher.registerOnBackInvokedCallback(
               OnBackInvokedDispatcher.PRIORITY_DEFAULT
           ) {
               /**
                * onBackPressed logic goes here. For instance:
                * Prevents closing the app to go home screen when in the
                * middle of entering data to a form
                * or from accidentally leaving a fragment with a WebView in it
                *
                * Unregistering the callback to stop intercepting the back gesture:
                * When the user transitions to the topmost screen (activity, fragment)
                * in the BackStack, unregister the callback by using
                * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
                * (https://developer.android.com/reference/kotlin/android/window/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
                */
           }
       }
   }
   

   Java

   @Override
   void onCreate() {
     if (BuildCompat.isAtLeastT()) {
       getOnBackInvokedDispatcher().registerOnBackInvokedCallback(
           OnBackInvokedDispatcher.PRIORITY_DEFAULT,
           () -> {
             /**
              * onBackPressed logic goes here - For instance:
              * Prevents closing the app to go home screen when in the
              * middle of entering data to a form
              * or from accidentally leaving a fragment with a WebView in it
              *
              * Unregistering the callback to stop intercepting the back gesture:
              * When the user transitions to the topmost screen (activity, fragment)
              * in the BackStack, unregister the callback by using
              * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
              * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
              */
           }
       );
     }
   }
   

4. 針對 Android 13 以上版本，停止透過 OnBackPressed 或 KeyEvent.KEYCODE_BACK 攔截返回事件。

5. 應用程式順利遷移後，請按照本頁所述選擇啟用預測返回手勢，讓 OnBackInvokedCallback 生效。

選擇啟用預測返回手勢

當您根據自己的情況決定應用程式更新方式後，就能輕鬆讓應用程式支援預測返回手勢。

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

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

如未提供值，這個旗標會預設為 false，並執行下列動作：

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

回呼最佳做法

使用 BackHandler (適用於 Compose)、OnBackPressedCallback 或 OnBackInvokedCallback 等支援的系統返回回呼時，請參考以下最佳做法。

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

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

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

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

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

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

UI 邏輯會決定 UI 顯示方式。請使用系統返回回呼執行 UI 邏輯，例如顯示彈出式視窗或執行動畫。

如果應用程式啟用系統返回回呼，預測動畫就不會執行，您也必須處理返回事件。請勿建立僅執行非 UI 邏輯的回呼。

舉例來說，如果攔截返回事件只是為了記錄資料，請改為在活動或片段生命週期內記錄資料。

• 若是活動對活動或片段對活動的情況，請在 onDestroy 中的 isFinishing 於活動生命週期內為 true 時記錄資料。
• 若是片段對片段的情況，請在 Fragment 的檢視畫面生命週期內，當 onDestroy 中的 isRemoving 為 true 時記錄資料；或使用 FragmentManager.OnBackStackChangedListener 中的 onBackStackChangeStarted 或 onBackStackChangeCommitted 方法進行記錄。

建立單一責任回呼

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

測試預測返回手勢動畫

從 Android 13 的最終版本開始，只要啟用開發人員選項，應該就能測試圖 1 中的返回主畫面動畫。

如要測試這個動畫，請完成下列步驟：

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

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

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