Ta strona została przetłumaczona przez Cloud Translation API.

Dodano obsługę gestu przewidywanego przejścia wstecz

**Rysunek 1.** Przykład wyglądu i sposobu działania gestu cofania się na telefonie

Android 14 (poziom interfejsu API 34) dodaje obsługę dodatkowych animacji systemowych i interfejsów API do tworzenia animacji niestandardowych. Więcej informacji znajdziesz w artykule o dodaniu obsługi wbudowanych i niestandardowych animacji wstecznych prognozowanych.

Użycie gestu cofania pozwala na przykład wyświetlić animowany podgląd ekranu głównego z tyłu aplikacji, tak jak na ilustracji 1. Począwszy od Androida 13 możesz przetestować tę animację powrotu na stronę główną, włączając opcję programisty (jak opisano na tej stronie).

Obsługa gestu przewidywania gestu cofania wymaga aktualizacji aplikacji przy użyciu zgodnego wstecznie OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) lub nowszego interfejsu API albo nowego interfejsu API platformy OnBackInvokedCallback. Większość aplikacji będzie używać zgodnego wstecznie interfejsu API AndroidX.

Ta aktualizacja zapewnia ścieżkę migracji umożliwiającą prawidłowe przechwytywanie nawigacji wstecznej, co obejmuje zastąpienie przechwytów wstecznych z KeyEvent.KEYCODE_BACK i wszystkich klas z metodami onBackPressed, takimi jak Activity i Dialog, nowym systemowym interfejsami API backendu.

Ćwiczenia z programowania i konferencje Google I/O

Oprócz skorzystania z dokumentacji dostępnej na tej stronie wypróbuj też nasze ćwiczenia z programowania. Udostępnia on typową implementację przypadku użycia komponentu WebView, który obsługuje przewidywalny gest cofania za pomocą interfejsów AndroidX Activity API.

Możesz też obejrzeć nasz film z Google I/O, w którym omawiamy dodatkowe przykłady implementacji interfejsów API AndroidaX i platformy.

Aktualizowanie aplikacji, która używa domyślnej nawigacji wstecz

Aktualizacja aplikacji pod kątem obsługi tej funkcji jest prosta, jeśli nie ma zaimplementowanego niestandardowego działania cofania (czyli to system pozostawia ją w rękach systemu). Włącz tę funkcję w sposób opisany w tym przewodniku.

Jeśli Twoja aplikacja używa fragmentów lub komponentu Nawigacja, uaktualnij ją do AndroidX Activity w wersji 1.6.0-alfa05 lub nowszej.

Aktualizowanie aplikacji, która używa niestandardowej nawigacji wstecz

Jeśli Twoja aplikacja korzysta z niestandardowego działania cofania, istnieją różne ścieżki migracji w zależności od tego, czy korzysta ona z AndroidaX i jak obsługuje nawigację wstecz.

Twoja aplikacja korzysta z AndroidaX	Jak aplikacja obsługuje nawigację wstecz	Zalecana ścieżka migracji (link na tej stronie)
Tak	Interfejsy API AndroidX	Migracja istniejącej implementacji AndroidaX
Tak	Interfejsy API nieobsługiwanej platformy	Migracja do interfejsów API AndroidaX aplikacji na Androida X, które zawierają nieobsługiwane interfejsy API nawigacji wstecz,
Nie	Interfejsy API platformy nieobsługiwanej platformy, możliwe do migracji	Przenoszenie aplikacji, która korzysta z nieobsługiwanych interfejsów API nawigacji wstecz, do interfejsów API platformy
Nie	Migracja nie jest możliwa w przypadku nieobsługiwanych interfejsów API platformy	Odłóż zgodę do czasu, aż ta funkcja stanie się wymagana

Migracja poprzedniej wersji nawigacji na AndroidzieX

Jest to najczęstszy (i najbardziej zalecany) przypadek użycia. Dotyczy on nowych i istniejących aplikacji, które implementują niestandardową nawigację przy użyciu gestów za pomocą OnBackPressedDispatcher, jak opisano w sekcji Udostępnianie niestandardowej nawigacji tylnej.

Jeśli Twoja aplikacja należy do tej kategorii, wykonaj te czynności, aby dodać obsługę przewidywanego gestu cofania:

Aby mieć pewność, że interfejsy API, które korzystają już z interfejsów API OnBackPressedDispatcher (takie jak fragmenty i komponent nawigacji), bezproblemowo współpracują z przewidywalnym gestem cofania, przejdź na Aktywność w Androidzie 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"
```
Włącz gest przewidywanego przejścia wstecz w sposób opisany na tej stronie.

Przenoszenie aplikacji na AndroidaX, które zawierają nieobsługiwane interfejsy API nawigacji wstecz, do interfejsów API AndroidaX

Jeśli Twoja aplikacja korzysta z bibliotek AndroidaX, ale implementuje nieobsługiwane interfejsy API nawigacji wstecz lub odwołuje się do nich, musisz przejść na interfejsy AndroidX API, aby zapewnić obsługę nowego sposobu.

Aby przenieść nieobsługiwane interfejsy API do interfejsów AndroidX:

Przenieś logikę cofania obsługi systemu do OnBackPressedDispatcher AndroidaX przy użyciu implementacji OnBackPressedCallback. Szczegółowe wskazówki znajdziesz w artykule o własnej nawigacji wstecz.
Gdy chcesz przestać przechwytywać ruch wsteczny, wyłącz OnBackPressedCallback.
Przestań przechwytywać zdarzenia wsteczne za pomocą funkcji OnBackPressed lub KeyEvent.KEYCODE_BACK.

Zaktualizuj AndroidX Activity w wersji 1.6.0-alfa05.

// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"

Po zakończeniu przenoszenia aplikacji włącz gest przewidywanego przejścia wstecz (jak opisano na tej stronie), aby zobaczyć animację systemową powrotu na ekran główny.

Uwaga: funkcja OnBackPressedCallback jest zawsze wywoływana niezależnie od wartości android:enableOnBackInvokedCallback. Inaczej mówiąc, wyłączenie animacji systemowej nie wpływa na logikę wsteczną aplikacji, jeśli korzysta ona z metody OnBackPressedCallback.

Przenoszenie aplikacji, która korzysta z nieobsługiwanych interfejsów API nawigacji wstecz, do interfejsów API platformy

Jeśli Twoja aplikacja nie może korzystać z bibliotek AndroidaX i zamiast tego implementuje niestandardową nawigację wstecz lub odwołuje się do niej przy użyciu nieobsługiwanych interfejsów API, musisz przejść na interfejs API platformy OnBackInvokedCallback.

Aby przenieść nieobsługiwane interfejsy API do interfejsu API platformy, wykonaj te czynności:

Używaj nowego interfejsu API OnBackInvokedCallback na urządzeniach z Androidem 13 lub nowszym oraz korzystaj z nieobsługiwanych interfejsów API na urządzeniach z Androidem 12 lub starszym.
Zarejestruj niestandardową logikę cofania w OnBackInvokedCallback w onBackInvokedDispatcher. Uniemożliwia to zakończenie bieżącej aktywności, a wywołanie zwrotne będzie mieć szansę zareagować na działanie Wstecz, gdy użytkownik zakończy w systemie nawigację wstecz.

Wyrejestruj OnBackInvokedCallback, gdy chcesz przestać przechwytywać gest cofania. W przeciwnym razie podczas korzystania z systemu nawigacji Wstecz w systemie użytkownicy mogą zauważyć niepożądane zachowanie – np. „utknąć” między widokami i wymuszać na nich zamknięcie aplikacji.

Oto przykład migracji logiki z 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)
           */
        }
    );
  }
}

Przestań przechwytywać zdarzenia wsteczne za pomocą funkcji OnBackPressed lub KeyEvent.KEYCODE_BACK na Androidzie 13 i nowszych.
Po zakończeniu migracji aplikacji włącz gest przewidywanego przejścia wstecz (jak opisano na tej stronie), aby funkcja OnBackInvokedCallback zaczęła działać.

Możesz zarejestrować OnBackInvokedCallback w usłudze PRIORITY_DEFAULT lub PRIORITY_OVERLAY, co nie jest dostępne na podobnych urządzeniach z AndroidemX OnBackPressedCallback. W niektórych przypadkach warto zarejestrować wywołanie zwrotne za pomocą funkcji PRIORITY_OVERLAY. Może się tak zdarzyć, gdy przeprowadzasz migrację z onKeyPreIme() i w wywołaniu zwrotnym musi zostać użyty gest cofania zamiast otwartego IME. edytory IME rejestrują wywołania zwrotne za pomocą funkcji PRIORITY_DEFAULT po otwarciu. Zarejestruj wywołanie zwrotne w PRIORITY_OVERLAY, aby mieć pewność, że OnBackInvokedDispatcher wysyła do wywołania zwrotnego gest cofania zamiast otwartego IME.

Wyraź zgodę na gest przewidywanego przejścia wstecz

Gdy już zdecydujesz, jak aktualizować aplikację w zależności od przypadku, włącz obsługę gestu przewidywania gestu cofania.

Aby włączyć tę funkcję, w panelu AndroidManifest.xml w tagu <application> ustaw flagę android:enableOnBackInvokedCallback na true.

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

Jeśli nie podasz wartości, zostanie użyta domyślna wartość false:

Wyłącza animację systemową gestów przewidywania.
Ignoruje metodę OnBackInvokedCallback, ale wywołania OnBackPressedCallback nadal działają.

Wyrażanie zgody na poziomie aktywności

Począwszy od Androida 14 flaga android:enableOnBackInvokedCallback umożliwia włączenie przewidywania animacji systemu na poziomie aktywności. Takie działanie ułatwia migrację dużych aplikacji o wieloma aktywnościami do funkcji przewidywania gestów cofania.

Ten kod pokazuje przykład użycia parametru enableOnBackInvokedCallback do włączenia animacji systemu powrotu na stronę główną z poziomu MainActivity:

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

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

W poprzednim przykładzie ustawienie android:enableOnBackInvokedCallback=true dla parametru ".SecondActivity" włącza animację systemu obejmującą wiele aktywności.

Podczas korzystania z flagi android:enableOnBackInvokedCallback pamiętaj o tych kwestiach:

Ustawienie android:enableOnBackInvokedCallback=false wyłącza animacje wsteczne na poziomie aktywności lub aplikacji (w zależności od miejsca ustawienia tagu) i informuje system, aby ignorował wywołania interfejsu API platformy OnBackInvokedCallback. Jednak wywołania OnBackPressedCallback są nadal wykonywane, ponieważ funkcja OnBackPressedCallback jest zgodna wstecznie i wywołuje interfejs API onBackPressed, który nie jest obsługiwany w wersjach starszych niż Android 13.
Ustawienie flagi enableOnBackInvokedCallback na poziomie aplikacji powoduje ustawienie wartości domyślnej dla wszystkich działań w aplikacji. Możesz zastąpić domyślną wartość dla poszczególnych działań, ustawiając flagę na poziomie aktywności, jak pokazano w poprzednim przykładzie kodu.

Sprawdzone metody dotyczące wywołań zwrotnych

Oto sprawdzone metody korzystania z obsługiwanych systemowych wywołań zwrotnych: BackHandler (do tworzenia wiadomości), OnBackPressedCallback i OnBackInvokedCallback.

Określ stan UI, który włącza i wyłącza każde wywołanie zwrotne

Stan UI to właściwość opisująca interfejs użytkownika. Zalecamy wykonanie tych ogólnych czynności.

Określ stan interfejsu, w którym każde wywołanie zwrotne zostanie włączone lub wyłączone.
Zdefiniuj ten stan za pomocą typu obserwowalnego właściciela danych, np. StateFlow lub stan tworzenia, i włącz lub wyłącz wywołanie zwrotne w miarę zmiany stanu.

Jeśli Twoja aplikacja kojarzyła wcześniej logikę wsteczną z instrukcją warunkową, może to oznaczać, że reagujesz na zdarzenie wstecz, gdy ono już wystąpiło – czyli wzorca, którego należy unikać w przypadku nowszych wywołań zwrotnych. W miarę możliwości przenieś wywołanie zwrotne poza instrukcję warunkową i powiąż je z obserwowalnym typem właściciela danych.

Używaj systemowych wywołań zwrotnych w UI Logic

Logika interfejsu określa, jak wyświetlić UI. Używaj systemowych wywołań zwrotnych do uruchamiania logiki interfejsu, np. wyświetlania wyskakującego okienka lub uruchamiania animacji.

Jeśli aplikacja zezwala na wywołanie zwrotne systemu, animacje prognozujące nie są uruchamiane i musisz obsługiwać zdarzenie wstecz. Nie twórz wywołań zwrotnych tylko do uruchamiania logiki niezwiązanej z interfejsem.

Jeśli np. przechwytujesz zdarzenia tylko w celu zarejestrowania, loguj w ramach cyklu życia aktywności lub fragmentów kodu.

W przypadkach związanych z aktywnością lub fragmentami do aktywności zapisz, jeśli isFinishing w onDestroy ma wartość true w trakcie cyklu życia aktywności.
W przypadku przypadków z fragmentami na fragment loguj, jeśli isRemoving w obrębie onDestroy ma wartość prawda w cyklu życia widoku fragmentu lub użyj metody onBackStackChangeStarted lub onBackStackChangeCommitted wewnątrz FragmentManager.OnBackStackChangedListener.

W przypadku polecenia Compose zaloguj się w wywołaniu zwrotnym onCleared() elementu ViewModel powiązanego z miejscem docelowym Compose. To najlepszy sygnał, że chcesz wiedzieć, kiedy miejsce docelowe tworzenia wiadomości zostało wyjęte z backendu i zniszczone.

Tworzenie pojedynczych wywołań zwrotnych

Jest to możliwe, ponieważ możesz dodać wiele wywołań zwrotnych do dyspozytora. Wywołania zwrotne są dodawane do stosu, w którym ostatnio dodane włączone wywołanie zwrotne obsługuje następny gest cofnięcia z jednym wywołaniem na każdy gest wstecz.

Przetestuj animację gestu przewidywania gestu wstecz

Począwszy od ostatniej wersji Androida 13 powinno być możliwe włączenie opcji dewelopera umożliwiającej testowanie animacji powrotu do strony głównej widoczną na ilustracji 1.

Aby przetestować tę animację, wykonaj te czynności:

Na urządzeniu otwórz Ustawienia > System > Opcje programisty.
Wybierz Animacje przewidywanego przejścia wstecz.
Uruchom zaktualizowaną aplikację i użyj gestu cofania, aby zobaczyć, jak działa ta wersja.