Thêm khả năng hỗ trợ cho tính năng xem trước thao tác quay lại

Hình 1. Bản minh hoạ giao diện tính năng xem trước thao tác quay lại trên điện thoại

Android 14 (API cấp 34) hỗ trợ thêm ảnh động hệ thống và API để tạo ảnh động tuỳ chỉnh. Để biết thêm thông tin, hãy xem phần Thêm tính năng hỗ trợ cho ảnh động xem trước thao tác quay lại dạng tích hợp sẵn và tuỳ chỉnh.

Ví dụ: việc sử dụng cử chỉ quay lại có thể hiển thị bản xem trước dạng động của Màn hình chính đằng sau ứng dụng của bạn, như trình bày trong bản minh hoạ ở hình 1. Kể từ Android 13, bạn có thể kiểm thử ảnh động quay lại màn hình chính này bằng cách bật tuỳ chọn cho nhà phát triển (như mô tả trên trang này).

Nhằm hỗ trợ tính năng xem trước thao tác quay lại, bạn phải cập nhật ứng dụng bằng API OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) trở lên hoặc API nền tảng OnBackInvokedCallback mới có khả năng tương thích ngược. Hầu hết ứng dụng đều sử dụng API AndroidX có khả năng tương thích ngược.

Bản cập nhật này cung cấp một đường dẫn di chuyển để chặn thao tác quay lại sao cho đúng cách, thông qua việc thay thế tính năng chặn ngược từ KeyEvent.KEYCODE_BACK và bất kỳ lớp (class) nào bằng các phương thức onBackPressed như Activity và Dialog nhờ Back API (API Quay lại) mới của hệ thống.

Lưu ý: Android 13 không hiển thị tính năng xem trước thao tác quay lại với người dùng, nhưng cung cấp phiên bản sớm của giao diện người dùng dưới dạng tuỳ chọn kiểm thử dành cho nhà phát triển. Chúng tôi dự định cung cấp giao diện người dùng này cho người dùng ở bản phát hành Android trong tương lai. Trong thời gian chờ đợi, bạn nên cập nhật ứng dụng để đảm bảo nhận được các bản cập nhật mới nhất.

Lưu ý: KeyEvent.KEYCODE_BACK chưa ngừng hoạt động vì có một số trường hợp sử dụng KeyEvent.KEYCODE_BACK được hỗ trợ; tuy nhiên, tính năng chặn sự kiện quay lại từ KeyEvent.KEYCODE_BACK không còn được hỗ trợ nữa.

Lớp học lập trình và video về Google I/O

Ngoài việc sử dụng tài liệu này trên trang này, hãy thử tham khảo lớp học lập trình của chúng tôi. Lớp học này cung cấp cách triển khai trường hợp sử dụng phổ biến của WebView giúp xử lý tính năng xem trước thao tác quay lại bằng AndroidX Activity API.

Bạn cũng có thể xem video về Google I/O của chúng tôi, trong đó nêu thêm các ví dụ về việc triển khai AndroidX và API nền tảng.

Cập nhật một ứng dụng sử dụng tính năng điều hướng quay lại mặc định

Việc cập nhật ứng dụng để hỗ trợ tính năng này rất đơn giản nếu ứng dụng của bạn không triển khai hành vi quay lại tuỳ chỉnh nào (nói cách khác, ứng dụng sẽ để hệ thống phụ trách quá trình xử lý thao tác quay lại). Chọn sử dụng tính năng này bằng cách làm theo mô tả trong hướng dẫn này.

Nếu ứng dụng của bạn dùng Mảnh (Fragment) hoặc Thành phần điều hướng (Navigation component), hãy nâng cấp lên tối thiểu là AndroidX Activity 1.6.0-alpha05.

Cập nhật một ứng dụng dùng tính năng điều hướng quay lại tuỳ chỉnh

Nếu ứng dụng của bạn triển khai hành vi quay lại tuỳ chỉnh, thì sẽ có nhiều đường dẫn di chuyển tuỳ thuộc vào việc ứng dụng đó có sử dụng AndroidX hay không và cách xử lý thao tác điều hướng quay lại.

Ứng dụng của bạn sử dụng AndroidX	Cách ứng dụng của bạn xử lý tính năng điều hướng quay lại	Đường dẫn di chuyển đề xuất (đường liên kết trên trang này)
Có	API AndroidX	Di chuyển phương thức triển khai quay lại AndroidX hiện có
	API nền tảng không được hỗ trợ	Di chuyển ứng dụng AndroidX chứa API điều hướng quay lại không được hỗ trợ sang API AndroidX
Không	API nền tảng không được hỗ trợ, có thể di chuyển	Di chuyển ứng dụng dùng API điều hướng quay lại không được hỗ trợ sang API nền tảng
	Các API nền tảng không được hỗ trợ nhưng không thể di chuyển	Trì hoãn việc chọn tham gia cho đến khi đây là tính năng bắt buộc

Lưu ý quan trọng: Bạn nên triển khai tính năng điều hướng xem trước thao tác quay lại sớm nhất có thể. Nếu không, người dùng có thể gặp phải hành vi không mong muốn trong bản phát hành Android sau này.

Di chuyển cách triển khai tính năng điều hướng quay lại của AndroidX

Đây là trường hợp sử dụng phổ biến nhất (và được đề xuất nhiều nhất). Cách này áp dụng cho các ứng dụng mới hoặc ứng dụng hiện có triển khai cách xử lý thao tác bằng cử chỉ tuỳ chỉnh bằng OnBackPressedDispatcher, như mô tả trong phần Cung cấp tính năng điều hướng quay lại tuỳ chỉnh.

Nếu ứng dụng của bạn thuộc danh mục này, hãy làm theo các bước sau để thêm tính năng hỗ trợ cho cử chỉ vuốt ngược để dự đoán:

1. Để đảm bảo rằng các API vốn đang sử dụng OnBackPressedDispatcher API (chẳng hạn như Mảnh và Thành phần điều hướng) hoạt động liền mạch với tính năng xem trước thao tác quay lại, hãy nâng cấp lên 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. Chọn sử dụng tính năng xem trước thao tác quay lại, theo mô tả trên trang này.

Di chuyển ứng dụng AndroidX chứa API điều hướng quay lại không được hỗ trợ sang API AndroidX

Nếu ứng dụng của bạn dùng thư viện AndroidX nhưng triển khai hoặc tham chiếu đến các API điều hướng quay lại không được hỗ trợ, thì bạn cần chuyển sang sử dụng API AndroidX để hỗ trợ hành vi mới.

Lưu ý: Bạn nên sử dụng các thư viện AndroidX. AndroidX tự động bật cập nhật tính năng điều hướng Quay lại của hệ thống trong ứng dụng khi bạn bật tính năng này, đồng thời cung cấp nhiều tính năng hữu ích khác mà có thể tự động cập nhật API theo từng bản phát hành để giúp bạn tiết kiệm công sức và thời gian.

Cách di chuyển API không được hỗ trợ sang API AndroidX:

1. Di chuyển logic xử lý Quay lại của hệ thống sang OnBackPressedDispatcher của AndroidX bằng cách triển khai OnBackPressedCallback. Để biết hướng dẫn chi tiết, hãy xem bài viết Cung cấp tính năng điều hướng quay lại tuỳ chỉnh.

2. Tắt OnBackPressedCallback khi bạn đã sẵn sàng dừng chặn thao tác quay lại.

3. Dừng chặn các sự kiện quay lại qua OnBackPressed hoặc KeyEvent.KEYCODE_BACK.

4. Đảm bảo bạn đã nâng cấp lên 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. Khi bạn đã di chuyển thành công ứng dụng của mình, hãy chọn sử dụng tính năng xem trước thao tác quay lại (như mô tả trên trang này) để xem ảnh động quay lại trang chủ của hệ thống.

   Lưu ý: OnBackPressedCallback luôn được gọi bất kể giá trị của android:enableOnBackInvokedCallback là gì. Nói cách khác, việc tắt ảnh động hệ thống sẽ không ảnh hưởng đến logic xử lý thao tác quay lại của ứng dụng nếu ứng dụng sử dụng OnBackPressedCallback.

Di chuyển ứng dụng dùng API điều hướng quay lại không được hỗ trợ sang API nền tảng

Nếu ứng dụng của bạn không thể dùng các thư viện AndroidX và thay vào đó triển khai hoặc tham chiếu đến thành phần điều hướng Quay lại tuỳ chỉnh bằng các API không được hỗ trợ, thì bạn phải di chuyển sang API nền tảng OnBackInvokedCallback.

Lưu ý: Bạn nên sử dụng các thư viện AndroidX. AndroidX tự động bật cập nhật tính năng điều hướng Quay lại của hệ thống trong ứng dụng khi bạn bật tính năng này, đồng thời cung cấp nhiều tính năng hữu ích khác mà có thể tự động cập nhật API theo từng bản phát hành để giúp bạn tiết kiệm công sức và thời gian.

Hãy hoàn thành các bước sau để di chuyển API không được hỗ trợ sang API nền tảng:

1. Dùng API OnBackInvokedCallback mới trên các thiết bị chạy Android 13 trở lên, đồng thời dựa vào những API không được hỗ trợ trên các thiết bị chạy Android 12 trở xuống.

2. Đăng ký logic quay lại tuỳ chỉnh trong OnBackInvokedCallback bằng onBackInvokedDispatcher. Đây là cách để ngăn hoạt động hiện tại hoàn tất và lệnh gọi lại của bạn sẽ có cơ hội phản ứng với thao tác Quay lại sau khi người dùng hoàn tất thao tác Quay lại của hệ thống.

3. Huỷ đăng ký OnBackInvokedCallback khi đã sẵn sàng dừng chặn thao tác quay lại. Nếu không, người dùng có thể thấy hành vi không mong muốn khi sử dụng thao tác Quay lại của hệ thống – ví dụ: "bị nghẽn" giữa các khung hiển thị và buộc họ phải thoát ứng dụng của bạn.

   Sau đây là ví dụ về cách di chuyển logic ra khỏi 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. Dừng chặn các sự kiện quay lại qua OnBackPressed hoặc KeyEvent.KEYCODE_BACK đối với Android 13 trở lên.

5. Sau khi di chuyển thành công ứng dụng của mình, hãy chọn sử dụng tính năng xem trước thao tác quay lại (theo mô tả trên trang này) để OnBackInvokedCallback có hiệu lực.

Bạn có thể đăng ký OnBackInvokedCallback bằng PRIORITY_DEFAULT hoặc PRIORITY_OVERLAY (không có trong OnBackPressedCallback tương tự của AndroidX). Việc đăng ký một lệnh gọi lại bằng PRIORITY_OVERLAY sẽ hữu ích trong một số trường hợp. Một trường hợp có thể áp dụng phương án này là khi bạn di chuyển từ onKeyPreIme() và lệnh gọi lại của bạn cần nhận cử chỉ quay lại thay vì IME đang mở. Khi mở, các IME sẽ đăng ký lệnh gọi lại bằng PRIORITY_DEFAULT. Đăng ký lệnh gọi lại của bạn bằng PRIORITY_OVERLAY để đảm bảo rằng OnBackInvokedDispatcher gửi cử chỉ quay lại đến lệnh gọi lại thay vì IME đang mở.

Chọn sử dụng tính năng xem trước thao tác quay lại

Khi đã xác định được cách cập nhật ứng dụng dựa vào trường hợp của bạn, hãy chọn sử dụng nhằm hỗ trợ tính năng xem trước thao tác quay lại.

Để chọn sử dụng, trong AndroidManifest.xml, trong thẻ <application>, hãy thiết lập cờ android:enableOnBackInvokedCallback thành true.

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

Nếu bạn không cung cấp một giá trị, thì giá trị mặc định sẽ là false và thực hiện các hành động sau:

• Tắt ảnh động xem trước thao tác quay lại của hệ thống.
• Bỏ qua OnBackInvokedCallback, nhưng các lệnh gọi OnBackPressedCallback vẫn hoạt động.

Chọn sử dụng tính năng ở cấp độ hoạt động

Kể từ Android 14, cờ android:enableOnBackInvokedCallback cho phép bạn chọn sử dụng ảnh động xem trước của hệ thống ở cấp hoạt động. Hành vi này giúp bạn dễ dàng quản lý việc di chuyển các ứng dụng lớn có nhiều hoạt động sang sử dụng tính năng xem trước thao tác quay lại.

Đoạn mã sau đây là ví dụ về cách sử dụng enableOnBackInvokedCallback để bật ảnh động quay lại trang chủ của hệ thống từ MainActivity:

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

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

Trong ví dụ trước, việc thiết lập android:enableOnBackInvokedCallback=true cho ".SecondActivity" sẽ bật ảnh động hệ thống giữa nhiều hoạt động.

Khi sử dụng cờ android:enableOnBackInvokedCallback, hãy lưu ý những điểm cần cân nhắc sau đây:

• Việc thiết lập android:enableOnBackInvokedCallback=false sẽ tắt ảnh động xem trước thao tác quay lại ở cấp hoạt động hoặc cấp ứng dụng, tuỳ thuộc vào nơi bạn thiết lập thẻ và hướng dẫn hệ thống bỏ qua các lệnh gọi đến API nền tảng OnBackInvokedCallback. Tuy nhiên, các lệnh gọi đến OnBackPressedCallback sẽ tiếp tục chạy vì OnBackPressedCallback có khả năng tương thích ngược và sẽ gọi onBackPressed API (không hỗ trợ trước Android 13).
• Việc thiết lập cờ enableOnBackInvokedCallback ở cấp ứng dụng sẽ thiết lập giá trị mặc định cho tất cả hoạt động trong ứng dụng. Bạn có thể ghi đè giá trị mặc định đối với mỗi hoạt động bằng cách thiết lập cờ ở cấp hoạt động, như minh hoạ trong đoạn mã ví dụ trước.

Các phương pháp hay nhất về lệnh gọi lại

Dưới đây là các phương pháp hay nhất để dùng lệnh gọi lại hệ thống được hỗ trợ; BackHandler (dành cho Compose), OnBackPressedCallback hoặc OnBackInvokedCallback.

Xác định Trạng thái giao diện người dùng có thể bật và tắt mỗi lệnh gọi lại

Trạng thái giao diện người dùng (UI state) là thuộc tính mô tả giao diện người dùng. Bạn nên làm theo các bước tổng quan sau đây.

1. Xác định Trạng thái giao diện người dùng có thể bật và tắt mỗi lệnh gọi lại.

2. Xác định trạng thái đó bằng cách sử dụng loại phần tử giữ dữ liệu có thể ghi nhận được, chẳng hạn như StateFlow hoặc Trạng thái Compose, đồng thời bật hoặc tắt lệnh gọi lại khi trạng thái thay đổi.

Nếu ứng dụng của bạn từng liên kết logic quay lại với các câu lệnh có điều kiện, thì việc này có thể cho biết rằng bạn đang phản ứng với sự kiện quay lại sau khi sự kiện đã xảy ra. Đây là dạng thức bạn nên tránh bằng các lệnh gọi lại mới hơn. Nếu có thể, hãy di chuyển lệnh gọi lại ra bên ngoài câu lệnh có điều kiện và thay vào đó, liên kết lệnh gọi lại đó với một loại phần tử giữ dữ liệu có thể ghi nhận được.

Sử dụng lệnh gọi lại hệ thống cho Logic giao diện người dùng

Logic giao diện người dùng (UI logic) cho biết cách hiển thị giao diện người dùng. Sử dụng lệnh gọi lại hệ thống để chạy logic giao diện người dùng, chẳng hạn như hiển thị cửa sổ bật lên hoặc chạy ảnh động.

Nếu ứng dụng của bạn bật lệnh gọi lại hệ thống, thì ảnh động dự đoán sẽ không chạy và bạn phải xử lý sự kiện quay lại. Đừng tạo lệnh gọi lại chỉ để chạy logic không phải giao diện người dùng.

Ví dụ: nếu bạn chỉ chặn các sự kiện quay lại để ghi nhật ký, hãy chuyển sang ghi lại trong vòng đời của Hoạt động hoặc Mảnh.

• Đối với các trường hợp từ hoạt động đến hoạt động hoặc từ mảnh đến hoạt động, hãy ghi nhật ký nếu isFinishing trong onDestroy là true thuộc Vòng đời hoạt động.
• Đối với các trường hợp từ mảnh đến mảnh, hãy ghi lại nếu isRemoving trong onDestroy là đúng trong vòng đời khung hiển thị của Mảnh; hoặc ghi nhật ký bằng phương thức onBackStackChangeStarted hoặc onBackStackChangeCommitted trong FragmentManager.OnBackStackChangedListener.

Đối với trường hợp Compose, hãy ghi lại trong lệnh gọi lại onCleared() của ViewModel được liên kết với đích đến của Compose. Đây là tín hiệu tốt nhất để biết thời điểm một đích đến của Compose bị kéo ra khỏi ngăn xếp lui và bị huỷ.

Tạo lệnh gọi lại trách nhiệm duy nhất

Bạn làm được điều này vì bạn có thể thêm nhiều lệnh gọi lại vào trình điều phối. Các lệnh gọi lại được thêm vào ngăn xếp, trong đó lệnh gọi lại được bật và thêm gần đây nhất sẽ xử lý cử chỉ quay lại tiếp theo với một lệnh gọi lại cho mỗi thao tác quay lại.

Kiểm thử ảnh động xem trước thao tác quay lại

Thận trọng: Thành phần ảnh động này của tính năng cử chỉ vuốt ngược để dự đoán sẽ chưa được sử dụng cho đến khi có bản phát hành chính thức dành cho Android 13. Vui lòng xem Dòng thời gian, các mốc quan trọng và các cập nhật để biết thêm thông tin chi tiết.

Kể từ bản phát hành chính thức Android 13, bạn có thể bật tuỳ chọn dành cho nhà phát triển để kiểm thử ảnh động quay lại màn hình chính trong hình 1.

Để kiểm tra ảnh động này, hãy hoàn tất các bước sau:

1. Trên thiết bị của bạn, hãy chuyển đến phần Cài đặt > Hệ thống > Tuỳ chọn cho nhà phát triển (Settings > System > Developer options).

2. Chọn Ảnh động vuốt ngược dự đoán.

3. Chạy ứng dụng đã cập nhật và dùng cử chỉ vuốt ngược để xem ứng dụng hoạt động.