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

Stay organized with collections Save and categorize content based on your preferences.
圖 1:模擬在手機上使用預測返回手勢的操作情形

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

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

如要支援預測返回手勢,您必須使用 OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) 以上版本的 API,或是新的 OnBackInvokedCallback 平台 API 更新應用程式。

本次更新為不再支援的返回導覽 API 提供了遷移路徑,也就是 KeyEvent.KEYCODE_BACK 和含有 onBackPressed 方法的任何類別,例如 ActivityDialog

程式碼研究室

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

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

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

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

如果應用程式有實作自訂返回行為,則視其是否使用 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. 如要停止攔截系統 Back 操作,可以停用所有先前啟用的 OnBackPressedCallback 執行個體,也可以一律不啟用任何回呼。

  3. 請務必升級至 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"
    
  4. 應用程式順利遷移後,請按照本頁所述選擇啟用預測返回手勢

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

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

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

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

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

  3. 為了確保能完善支援日後對系統 Back 導覽的強化功能,您的應用程式必須取消註冊 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/view/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. 應用程式順利遷移後,請按照下一節所述選擇啟用預測返回手勢。

選擇啟用預測返回手勢

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

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

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

如未提供值,這個標記會預設為 false,並停用預測返回手勢。

測試預測返回手勢動畫

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

如要測試這個動畫,請完成下列步驟:

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

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

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