
Przewidujące wstecz, funkcja nawigacji przy użyciu gestów, która pozwala użytkownikom sprawdzić, do którego momentu użytkownik cofnął się po przesunięciu palcem do tyłu.
Na przykład gest cofania może wyświetlić animowany podgląd ekranu głównego za aplikacją, jak pokazano na makiecie na rysunku 1.
Od Androida 15 opcja dewelopera dotycząca animacji przewidywanego przejścia wstecz nie jest już dostępna. Animacje systemowe, takie jak animacja powrotu do ekranu głównego, animacja przełączania zadań i animacja przełączania aktywności, są teraz wyświetlane w aplikacjach, które korzystają z przewidywanego gestu wstecz, niezależnie od tego, czy korzystają z niego całkowicie, czy tylko na poziomie aktywności.
Możesz przetestować tę animację powrotu do strony głównej (jak opisano w następującej sekcji tej strony).
Obsługa przewidującego gestu wstecz wymaga zaktualizowania aplikacji przy użyciu zgodnego z poprzednimi wersjami interfejsu OnBackPressedCallback
AppCompat 1.6.0-alpha05 (AndroidX) lub nowszego albo nowego interfejsu OnBackInvokedCallback
platformy. Większość aplikacji korzysta z interfejsu AndroidX API zgodnego ze starszymi wersjami.
Ta aktualizacja zapewnia ścieżkę migracji, która umożliwia prawidłowe przechwytywanie nawigacji wstecznej, co obejmuje zastąpienie przechwytów wstecznych od KeyEvent.KEYCODE_BACK
i wszystkich klas metod onBackPressed
, takich jak Activity
i Dialog
, nowym systemowym interfejsami API backendu.
Filmy z Codelab i Google I/O
Oprócz korzystania z tej dokumentacji na tej stronie wypróbuj nasze ćwiczenia z programowania. Udostępnia ona implementację WebView obsługującą przewidujący gest wstecz za pomocą interfejsów Activity w AndroidX.
Możesz też obejrzeć nasz film z Google I/O, w którym omawiamy dodatkowe przykłady implementacji interfejsów API AndroidaX i platformy.
Zaktualizuj aplikację, która używa domyślnej nawigacji wstecz
Zaktualizowanie aplikacji, aby obsługiwała tę funkcję, jest proste, jeśli aplikacja nie implementuje żadnego niestandardowego zachowania przy cofaniu (czyli pozostawia obsługę cofnięcia systemowi). Zaakceptuj tę funkcję zgodnie z instrukcjami podanymi 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.
Aktualizacja aplikacji, która korzysta z niestandardowej nawigacji wstecz
Jeśli aplikacja implementuje niestandardowe zachowanie przy wstecznym przechodzeniu, dostępne są różne ścieżki migracji w zależności od tego, czy korzysta ona z AndroidX i jak obsługuje nawigację wsteczną.
Twoja aplikacja używa AndroidX | Jak aplikacja obsługuje przekierowanie wstecz | Zalecane rozwiązanie do migracji (link na tej stronie) |
Tak | Interfejsy API AndroidaX | Migracja istniejącej implementacji AndroidX back |
Nieobsługiwane interfejsy API platform | Migracja do interfejsów API AndroidaX aplikacji na Androida X, które zawierają nieobsługiwane interfejsy API nawigacji wstecz, | |
Nie | Interfejsy API nieobsługiwanych platform, które można przenieść | Przejście z aplikacji korzystającej z nieobsługiwanych interfejsów API nawigacji wstecz na interfejsy API platformy |
Nieobsługiwane interfejsy API platformy, ale nie można przeprowadzić migracji | Odrocz akceptację do czasu, gdy ta funkcja stanie się wymagana. |
Migracja poprzedniej wersji nawigacji w Androidzie
Ten przypadek użycia jest najczęstszy (i najbardziej zalecany). Dotyczy to nowych lub istniejących aplikacji, które implementują niestandardowe gesty nawigacyjne za pomocą OnBackPressedDispatcher
, zgodnie z opisem w artykule Niestandardowa nawigacja wstecz.
Jeśli Twoja aplikacja należy do tej kategorii, wykonaj te czynności, aby dodać obsługę przewidywanego gestu cofania:
Aby zapewnić płynne działanie interfejsów API, które już korzystają z interfejsów API
OnBackPressedDispatcher
(takich jak fragmenty i komponent nawigacji), z użyciem przewidującego gestu wstecz, zaktualizuj do 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"
Włącz gest przewidywanego przejścia wstecz w sposób opisany na tej stronie.
Migracja aplikacji AndroidX zawierającej nieobsługiwane interfejsy API nawigacji wstecz na interfejsy AndroidX
Jeśli Twoja aplikacja korzysta z bibliotek AndroidX, 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 API AndroidX:
Przenieś wsteczną obsługę systemu do
OnBackPressedDispatcher
AndroidaX przy użyciu implementacjiOnBackPressedCallback
. Szczegółowe wskazówki znajdziesz w artykule Dodawanie niestandardowej opcji Wstecz.Gdy chcesz przestać przechwytywać gest Wstecz, wyłącz
OnBackPressedCallback
.Przestań przechwytywać zdarzenia „back” za pomocą funkcji
OnBackPressed
lubKeyEvent.KEYCODE_BACK
.Zaktualizuj do 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"
Po zakończeniu migracji aplikacji zezwól na użycie przewidującego gestu wstecz (jak opisano na tej stronie), aby wyświetlić animację powrotu do ekranu głównego.
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 używać 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
wonBackInvokedDispatcher
. Dzięki temu bieżąca aktywność nie zostanie zakończona, a Twoja funkcja wywołania zwrotnego będzie mogła zareagować na działanie Wstecz, gdy użytkownik użyje tej opcji w systemie.Gdy chcesz przestać przechwytywać gest wstecz, zarejestruj
OnBackInvokedCallback
. W przeciwnym razie użytkownicy mogą zauważyć niepożądane działanie podczas korzystania z systemu Wstecz – np. „zawieszanie się” między widokami, co zmusza ich do przymusowego zamknięcia aplikacji.Oto przykład migracji logiki z poziomu
onBackPressed
:@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) */ } } }
@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 wstecz za pomocą
OnBackPressed
lubKeyEvent.KEYCODE_BACK
w Androidzie 13 i nowszych.Po migracji aplikacji zezwól na użycie przewidującego gestu wstecz (jak opisano na tej stronie), aby
OnBackInvokedCallback
zaczęło działać.
Możesz zarejestrować OnBackInvokedCallback
za pomocą PRIORITY_DEFAULT
lub PRIORITY_OVERLAY
, co nie jest możliwe w przypadku podobnego pakietu AndroidX OnBackPressedCallback
. W niektórych przypadkach przydatne może być zarejestrowanie wywołania zwrotnego za pomocą funkcji PRIORITY_OVERLAY
.
Dotyczy to sytuacji, gdy migrujesz z onKeyPreIme()
i Twoje wywołanie zwrotne musi otrzymać gest wstecz zamiast otwartego IME. edytory IME rejestrują wywołania zwrotne za pomocą funkcji PRIORITY_DEFAULT
po otwarciu.
Zarejestruj wywołanie zwrotne w komponencie PRIORITY_OVERLAY
, aby mieć pewność, że OnBackInvokedDispatcher
przekaże gest wstecz do wywołania zwrotnego zamiast do otwartego IME.
Włączanie gestu przewidywanego przejścia wstecz
Gdy określisz, jak zaktualizować aplikację na podstawie swojego przypadku, włącz obsługę przewidującego gestu wstecz.
Aby to zrobić, w tagu AndroidManifest.xml
ustaw flagę android:enableOnBackInvokedCallback
na true
.<application>
<application
...
android:enableOnBackInvokedCallback="true"
... >
...
</application>
Jeśli nie podasz wartości, zostanie użyta domyślna wartość false
, a w ramach tej wartości:
- Wyłącza animację systemową przewidywanego przejścia wstecz.
- Ignoruje
OnBackInvokedCallback
, aleOnBackPressedCallback
nadal działa.
Akceptacja na poziomie aktywności
Począwszy od Androida 14 flaga android:enableOnBackInvokedCallback
umożliwia włączenie przewidywania animacji systemu na poziomie aktywności. Dzięki temu przenoszenie dużych aplikacji wielozadaniowych na przewidujące gesty wstecz jest łatwiejsze. W Androidzie 15 przewidywane cofnięcie nie jest już opcją dla deweloperów. Aplikacje mogą korzystać z przewidywania wstecznego w pełni lub na poziomie aktywności.
Poniższy kod pokazuje przykład użycia funkcji enableOnBackInvokedCallback
do włączenia animacji systemu powrotu do domu 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 ".SecondActivity"
powoduje włączenie animacji systemowej obejmującej wiele aktywności.
Podczas korzystania z flagi android:enableOnBackInvokedCallback
należy wziąć pod uwagę te kwestie:
- 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 platformyOnBackInvokedCallback
. Jednak wywołaniaOnBackPressedCallback
są nadal wykonywane, ponieważ funkcjaOnBackPressedCallback
jest zgodna wstecznie i wywołuje interfejs APIonBackPressed
, który nie jest obsługiwany w wersjach starszych niż Android 13. - Ustawienie flagi
enableOnBackInvokedCallback
na poziomie aplikacji ustala wartość domyślną dla wszystkich aktywności w aplikacji. Możesz ją zastąpić dla danej aktywności, ustawiając flagę na poziomie aktywności, jak pokazano w poprzednim przykładzie kodu.
Sprawdzone metody dotyczące wywołania zwrotnego
Oto sprawdzone metody korzystania z obsługiwanych wywołań zwrotnych systemu: BackHandler
(dla funkcji tworzenia wiadomości), OnBackPressedCallback
lub 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 użytkownika, który włącza i wyłącza poszczególne połączenia zwrotne.
Określ ten stan za pomocą obserwowalnego typu danych, takiego jak
StateFlow
lub Stan tworzenia, i włącz lub wyłącz wywołanie zależnie od stanu.
Jeśli Twoja aplikacja wcześniej powiązała logikę cofnięcia z oświadczeniami warunkowymi, może to oznaczać, że reagujesz na zdarzenie cofnięcia po tym, jak już ono nastąpiło. Unikaj tego w przypadku nowych wywołań zwrotnych. Jeśli to możliwe, przenieś funkcję z poziomu instrukcji warunkowej na zewnątrz i zamiast tego powiązać ją z obserwowalnym typem uchwytu danych.
Używaj systemowych wywołań zwrotnych w UI Logic
Logika interfejsu określa sposób wyświetlania interfejsu. Używaj wywołań zwrotnych systemu do wykonywania logiki interfejsu, np. wyświetlania wyskakującego okienka lub animacji.
Jeśli Twoja aplikacja umożliwia wywołanie systemu wstecz, animacje przewidujące nie są uruchamiane i musisz obsłużyć zdarzenie wstecz. Nie twórz wywołań zwrotnych tylko do uruchamiania logiki niezwiązanej z interfejsem.
Jeśli na przykład przechwytujesz zdarzenia back tylko po to, aby je rejestrować, zamiast tego rejestruj je w cyklu życia Activity lub Fragment.
- W przypadku przypadków aktywności do aktywności lub fragmentu do aktywności odnotuj, czy
isFinishing
wonDestroy
jesttrue
w cyklu życia aktywności. - W przypadku fragmentów względem siebie rejestruj, czy
isRemoving
wonDestroy
jest prawdziwe w cyklu życia widoku fragmentu. Możesz też zalogować się w usłudzeFragmentManager.OnBackStackChangedListener
za pomocą metodonBackStackChangeStarted
lubonBackStackChangeCommitted
.
W przypadku Compose loguj w wywołaniu zwrotnym onCleared()
funkcji ViewModel
powiązanej z miejscem docelowym Compose. To najlepszy sygnał o tym, że miejsce docelowe w komponowaniu zostało usunięte ze stosu i zniszczone.
Tworzenie pojedynczych wywołań zwrotnych
Możesz dodać wiele wywołań zwrotnych do dyspozytora. Zwróć uwagę, że wywołania są dodawane do stosu, w którym ostatnie dodane włączone wywołanie obsługuje następny gest wstecz. Każdy gest wstecz jest obsługiwany przez jedno wywołanie.
Łatwiej jest zarządzać stanem włączenia wywołania zwrotnego, jeśli ma ono tylko jedną odpowiedzialność. Na przykład:

Rysunek 2 pokazuje, jak można mieć w stosie wiele wywołań zwrotnych, z których każde odpowiada za jedną rzecz. Funkcja wywołania zwrotnego jest wykonywana tylko wtedy, gdy funkcje wywołania zwrotnego znajdujące się nad nią w zbiorze są wyłączone. W tym przykładzie wywołanie „Czy na pewno…” jest włączone, gdy użytkownik wpisuje dane w formularzu, i wyłączone w innych przypadkach. Wywołanie zwrotne otwiera okno potwierdzenia, gdy użytkownik przesunie palcem wstecz, aby zamknąć formularz.
Inny wywołanie zwrotne może zawierać komponent Material, który obsługuje przewidywanie powrotów, przejście AndroidX za pomocą interfejsów API Progress lub inne niestandardowe wywołanie zwrotne.
childFragmentManager
wywoływana jest, jeśli powyższe wywołania są wyłączone, a stół zagnieżdżony tego FragmentManager
nie jest pusty. childFragmentManager
jest dołączony do Fragmentu. W tym przykładzie to wewnętrzne wywołanie zwrotne jest wyłączone.
Podobnie wywołanie wewnętrzne supportFragmentManager
jest wykonywane, jeśli powyższe wywołania są wyłączone, a stos nie jest pusty. Takie zachowanie jest spójne przy korzystaniu z narzędzia FragmentManager
lub NavigationComponent
do nawigacji, ponieważ NavigationComponent
używa funkcji FragmentManager
. W tym przykładzie ta funkcja wywołania zwrotnego jest wykonywana, jeśli użytkownik nie wpisał tekstu w formularzu, co spowodowało wyłączenie funkcji wywołania zwrotnego „Czy na pewno…?”.
super.onBackPressed()
to wywołanie zwrotne na poziomie systemu, które jest ponownie uruchamiane, jeśli powyższe wywołania zwrotne będą wyłączone. Aby wywołać animacje systemowe, takie jak powrót do domu, przełączanie między aktywnościami i zadaniami, backstack supportFragmentManager
musi być pusty, aby jego wewnętrzny callback był wyłączony.
Przetestuj animację gestu przewidywania gestu wstecz
Jeśli nadal używasz Androida 13 lub Androida 14, możesz przetestować animację powrotu do ekranu głównego, którą przedstawia rysunek 1.
Aby przetestować tę animację, wykonaj te czynności:
Na urządzeniu wybierz 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.