Dodano obsługę gestu przewidywanego przejścia wstecz

Rysunek 1. Makieta wyglądu i działania gestu przewidywanego powrotu na telefonie

Przewidywane przejście wstecz to funkcja nawigacji gestami, która umożliwia użytkownikom sprawdzenie, dokąd przeniesie ich gest przesunięcia wstecz.

Na przykład użycie gestu przejścia wstecz może wyświetlić animowany podgląd ekranu głównego za aplikacją, jak pokazano na makiecie na ilustracji 1.

Od Androida 15 opcja programisty dotycząca animacji przewidywania powrotu nie jest już dostępna. Animacje systemowe, takie jak powrót do ekranu głównego, przełączanie między zadaniami i przełączanie między aktywnościami, są teraz wyświetlane w przypadku aplikacji, które włączyły gest przewidywanego przejścia wstecz w całości lub na poziomie aktywności.

Możesz przetestować animację powrotu do domu (zgodnie z opisem w dalszej części tej strony).

Obsługa gestu przewidywania powrotu wymaga zaktualizowania aplikacji, użycia wstecznie zgodnego interfejsu API OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) lub nowszego albo użycia nowego interfejsu API platformy OnBackInvokedCallback. Większość aplikacji korzysta z interfejsu AndroidX API, który jest zgodny wstecznie.

Ta aktualizacja zapewnia ścieżkę migracji, która umożliwia prawidłowe przechwytywanie nawigacji wstecznej. Wymaga to zastąpienia przechwytywań wstecznych z KeyEvent.KEYCODE_BACK i wszystkich klas z metodami onBackPressed, takimi jak Activity i Dialog, nowymi systemowymi interfejsami API nawigacji wstecznej.

Ćwiczenia z programowania i film z Google I/O

Oprócz korzystania z dokumentacji na tej stronie wypróbuj nasze ćwiczenia z programowania. Zawiera ona implementację typowego przypadku użycia elementu WebView, który obsługuje gest przewidywanego przejścia wstecz za pomocą interfejsów API AndroidX Activity.

Możesz też obejrzeć nasz film z Google I/O, w którym znajdziesz dodatkowe przykłady wdrażania interfejsów API AndroidX i platformy.

Aktualizowanie aplikacji, która korzysta z domyślnej nawigacji wstecz

Domyślnie włączone jest przewidywanie powrotu.

Jeśli Twoja aplikacja korzysta z fragmentów lub komponentu Navigation, uaktualnij ją do wersji AndroidX Activity 1.6.0-alpha05 lub nowszej.

Aktualizowanie aplikacji, która korzysta z niestandardowej nawigacji wstecz

Jeśli Twoja aplikacja implementuje niestandardowe zachowanie przycisku Wstecz, istnieją różne ścieżki migracji, w zależności od tego, czy korzysta z Androida X i jak obsługuje nawigację wstecz.

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 funkcji „Wstecz” w Androidzie X
Interfejsy API nieobsługiwanych platform Migracja aplikacji AndroidX zawierającej nieobsługiwane interfejsy API nawigacji wstecznej do interfejsów API AndroidX
Nie Interfejsy API nieobsługiwanej platformy, które można przenieść Przenoszenie aplikacji, która korzysta z nieobsługiwanych interfejsów API nawigacji wstecznej, na interfejsy API platformy
Interfejsy API nieobsługiwanej platformy, ale nie można przeprowadzić migracji Możesz tymczasowo zrezygnować z udostępniania danych, ustawiając atrybut android:enableOnBackInvokedCallback na wartość false w tagu <application> lub <activity> w pliku AndroidManifest.xml aplikacji.

Przenoszenie implementacji przechodzenia wstecz w AndroidzieX

Ten przypadek użycia jest najczęstszy (i najbardziej zalecany). Dotyczy to nowych i dotychczasowych aplikacji, które implementują niestandardową obsługę nawigacji przy użyciu gestów za pomocą OnBackPressedDispatcher, zgodnie z opisem w artykule Zapewnianie niestandardowej nawigacji wstecz.

Aby mieć pewność, że interfejsy API, które już korzystają z OnBackPressedDispatcher(np. fragmenty i komponent nawigacji), będą bezproblemowo działać z gestem powrotu predykcyjnego, zaktualizuj je do AndroidX Activity 1.6.0-alpha05.

```xml
// In your build.gradle file:
dependencies {

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

Migracja aplikacji AndroidX zawierającej nieobsługiwane interfejsy API nawigacji wstecznej do interfejsów API AndroidX

Jeśli Twoja aplikacja korzysta z bibliotek AndroidX, ale implementuje lub odwołuje się do nieobsługiwanych interfejsów API nawigacji wstecz, musisz przejść na interfejsy API AndroidX, aby obsługiwać nowe zachowanie.

Aby przenieść nieobsługiwane interfejsy API na interfejsy AndroidX API:

  1. Przenieś logikę obsługi przycisku Wstecz do biblioteki AndroidX OnBackPressedDispatcher, implementując interfejs OnBackPressedCallback. Szczegółowe wskazówki znajdziesz w artykule Zapewnianie niestandardowej nawigacji wstecz.

  2. Wyłącz OnBackPressedCallback, gdy chcesz przestać przechwytywać gest cofania.

  3. Przestań przechwytywać zdarzenia wstecz za pomocą OnBackPressed lub KeyEvent.KEYCODE_BACK.

  4. Pamiętaj, aby przejść na 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"

Migracja aplikacji, która korzysta z nieobsługiwanych interfejsów API nawigacji wstecznej, na interfejsy API platformy

Jeśli aplikacja nie może korzystać z bibliotek AndroidX i zamiast tego implementuje lub odwołuje się do niestandardowej nawigacji wstecznej przy użyciu nieobsługiwanych interfejsów API, musisz przejść na OnBackInvokedCallbackinterfejs API platformy.

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

  1. Używaj nowego interfejsu OnBackInvokedCallback API na urządzeniach z Androidem 13 lub nowszym, a na urządzeniach z Androidem 12 lub starszym korzystaj z nieobsługiwanych interfejsów API.

  2. Zarejestruj niestandardową logikę powrotu w OnBackInvokedCallback za pomocą onBackInvokedDispatcher. Zapobiega to zakończeniu bieżącej aktywności, a wywołanie zwrotne może zareagować na działanie Wstecz, gdy użytkownik zakończy nawigację systemową Wstecz.

  3. Wyrejestruj OnBackInvokedCallback, gdy chcesz przestać przechwytywać gest powrotu. W przeciwnym razie użytkownicy mogą zaobserwować niepożądane zachowanie podczas korzystania z nawigacji wstecznej systemu – na przykład „utknięcie” między widokami i konieczność wymuszenia zamknięcia aplikacji.

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

  4. Przestań przechwytywać zdarzenia wstecz za pomocą OnBackPressed lub KeyEvent.KEYCODE_BACK w przypadku Androida 13 i nowszych wersji.

Możesz zarejestrować OnBackInvokedCallback za pomocą PRIORITY_DEFAULT lub PRIORITY_OVERLAY, co nie jest dostępne w podobnym pakiecie AndroidX OnBackPressedCallback. Zarejestrowanie wywołania zwrotnego za pomocą PRIORITY_OVERLAY jest w niektórych przypadkach przydatne.

Ma to zastosowanie, gdy przenosisz dane z onKeyPreIme(), a funkcja wywołania zwrotnego musi odbierać gest powrotu zamiast otwartego edytora IME. Po otwarciu edytory IME rejestrują wywołania zwrotne w PRIORITY_DEFAULT. Zarejestruj wywołanie zwrotne w PRIORITY_OVERLAY, aby mieć pewność, że OnBackInvokedDispatcher przekaże gest powrotu do wywołania zwrotnego zamiast do otwartego edytora IME.

Rezygnacja z przewidywanego przejścia wstecz

Aby zrezygnować, w AndroidManifest.xml w tagu <application> ustaw flagę android:enableOnBackInvokedCallback na false.

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

Ustawienie tej opcji na „false” powoduje:

  • Wyłącza animację systemową gestu przewidywanego przejścia wstecz.
  • Ignoruje OnBackInvokedCallback, ale połączenia OnBackPressedCallback nadal działają.

Rezygnowanie na poziomie aktywności

Od Androida 16 flaga android:enableOnBackInvokedCallback umożliwia rezygnację z animacji systemowych opartych na prognozach na poziomie aktywności. Dzięki temu łatwiej jest migrować duże aplikacje z wieloma aktywnościami na gesty wstecz predykcyjne.

Poniższy kod pokazuje przykład ustawienia wartości enableOnBackInvokedCallback, aby włączyć animację systemową powrotu do ekranu głównego z MainActivity:

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

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

Korzystając z flagi android:enableOnBackInvokedCallback, pamiętaj o tych kwestiach:

  • Ustawienie android:enableOnBackInvokedCallback=false wyłącza animacje predykcyjnego powrotu na poziomie aktywności lub aplikacji (w zależności od tego, gdzie ustawisz tag) i nakazuje systemowi ignorowanie wywołań interfejsu API platformy OnBackInvokedCallback. Wywołania funkcji OnBackPressedCallback są jednak nadal wykonywane, ponieważ OnBackPressedCallback jest zgodna wstecznie i wywołuje interfejs API onBackPressed, który nie jest obsługiwany w wersjach Androida starszych niż 13.
  • Ustawienie flagi enableOnBackInvokedCallback na poziomie aplikacji określa wartość domyślną dla wszystkich aktywności w aplikacji. Możesz zastąpić wartość domyślną dla poszczególnych aktywności, ustawiając flagę na poziomie aktywności, jak pokazano w poprzednim przykładzie kodu.

Sprawdzone metody dotyczące oddzwaniania

Oto sprawdzone metody korzystania z obsługiwanych wywołań zwrotnych systemowego przycisku Wstecz:BackHandler (w przypadku Compose), OnBackPressedCallback lub OnBackInvokedCallback.

Określ stan interfejsu, który włącza i wyłącza poszczególne wywołania zwrotne.

Stan interfejsu to właściwość opisująca interfejs. Zalecamy wykonanie tych czynności.

  1. Określ stan interfejsu, który włącza i wyłącza poszczególne wywołania zwrotne.

  2. Zdefiniuj ten stan za pomocą typu obiektu danych obserwowanych, np. StateFlow lub stanu Compose, i włączaj lub wyłączaj wywołanie zwrotne w miarę zmiany stanu.

Jeśli Twoja aplikacja wcześniej łączyła logikę powrotu z instrukcjami warunkowymi, może to oznaczać, że reagujesz na zdarzenie powrotu po jego wystąpieniu. Unikaj tego wzorca dzięki nowszym wywołaniom zwrotnym. Jeśli to możliwe, przenieś wywołanie zwrotne poza instrukcję warunkową i zamiast tego powiąż je z obserwowalnym typem pojemnika danych.

Używanie wywołań zwrotnych systemowego przycisku Wstecz w logice interfejsu

Logika interfejsu określa sposób wyświetlania interfejsu. Używaj wywołań zwrotnych systemowego przejścia wstecz, aby uruchamiać logikę interfejsu, np. wyświetlać okno dialogowe lub uruchamiać animację.

Jeśli Twoja aplikacja umożliwia OnBackPressedCallback lub OnBackInvokedCallback z PRIORITY_DEFAULT lub PRIORITY_OVERLAY, animacje przewidywania powrotu nie działają i musisz obsłużyć zdarzenie powrotu. Nie twórz tych wywołań zwrotnych, aby uruchamiać logikę biznesową lub rejestrować zdarzenia.

Jeśli aplikacja musi uruchamiać logikę biznesową lub rejestrować zdarzenia, gdy użytkownik przesuwa palcem w tył, zastosuj te metody:

  • Używaj OnBackInvokedCallback z PRIORITY_SYSTEM_NAVIGATION_OBSERVER na urządzeniach z Androidem 16 lub nowszym. Spowoduje to utworzenie wywołania zwrotnego obserwatora, które nie zużywa zdarzenia wstecz. Możesz na przykład zarejestrować to wywołanie zwrotne, gdy użytkownik przesunie palcem z powrotem z aktywności głównej, czyli gdy opuści aplikację. W takim przypadku możesz zarejestrować zdarzenie powrotu lub uruchomić inną logikę biznesową, a animacja powrotu do ekranu głównego nadal będzie odtwarzana.
  • W przypadku przejść między aktywnościami lub fragmentami a aktywnościami rejestruj, czy isFinishing w onDestroy występuje w true w cyklu życia aktywności.
  • W przypadku fragmentów loguj, czy isRemoving w onDestroy ma wartość true w cyklu życia widoku fragmentu. Możesz też zalogować się za pomocą metod onBackStackChangeStarted lub onBackStackChangeCommitted w ramach FragmentManager.OnBackStackChangedListener.
  • W przypadku funkcji Compose rejestruj zdarzenia w wywołaniu zwrotnym onCleared() elementu ViewModel powiązanego z miejscem docelowym Compose. To najlepszy sygnał informujący o tym, kiedy miejsce docelowe kompozycji jest usuwane ze stosu wstecznego i niszczone.

Tworzenie wywołań zwrotnych o jednej odpowiedzialności

Do dyspozytora możesz dodać wiele wywołań zwrotnych. Wywołania zwrotne są dodawane do stosu, w którym ostatnie dodane włączone wywołanie zwrotne obsługuje następny gest powrotu, przy czym na każdy gest powrotu przypada jedno wywołanie zwrotne.

Łatwiej zarządzać stanem włączonym wywołania zwrotnego, jeśli ma ono jedno zadanie. Na przykład:

Kolejność wywołań zwrotnych w stosie.
Rysunek 2. Diagram stosu wywołań zwrotnych.

Ilustracja 2 pokazuje, jak w stosie może być wiele wywołań zwrotnych, z których każde odpowiada za jedną czynność. Funkcja zwrotna jest wykonywana tylko wtedy, gdy funkcje zwrotne znajdujące się nad nią w stosie są wyłączone. W tym przykładzie wywołanie zwrotne „Are you sure…” jest włączone, gdy użytkownik wprowadza dane do formularza, a w innych przypadkach jest wyłączone. Wywołanie zwrotne otwiera okno potwierdzenia, gdy użytkownik przesunie palcem w tył, aby zamknąć formularz.

Inne wywołanie zwrotne może obejmować komponent materiału, który obsługuje predykcyjne cofanie, przejście AndroidX z użyciem interfejsów API Progress lub inne niestandardowe wywołanie zwrotne.

Wywołanie zwrotne childFragmentManager jest wykonywane, jeśli powyższe wywołania zwrotne są wyłączone, a stos wsteczny tego elementu FragmentManager nie jest pusty. Element childFragmentManager jest dołączony w ramach fragmentu. W tym przykładzie to wewnętrzne wywołanie zwrotne jest wyłączone.

Podobnie wewnętrzne wywołanie zwrotne supportFragmentManager jest wykonywane, jeśli powyższe wywołania zwrotne są wyłączone, a jego stos nie jest pusty. Ten sposób działania jest spójny, gdy do nawigacji używasz FragmentManager lub NavigationComponent, ponieważ NavigationComponent zależy od FragmentManager. W tym przykładzie wywołanie zwrotne zostanie uruchomione, jeśli użytkownik nie wpisze tekstu w formularzu, co spowoduje wyłączenie wywołania zwrotnego „Czy na pewno...”.

Ostatnim typem jest wywołanie zwrotne na poziomie systemu super.onBackPressed(), które jest wykonywane, jeśli powyższe wywołania zwrotne są wyłączone. Aby wywołać animacje systemowe, takie jak powrót do ekranu głównego, przejście między aktywnościami i przejście między zadaniami, stos wsteczny supportFragmentManager musi być pusty, aby jego wewnętrzne wywołanie zwrotne było wyłączone.

Sprawdź animację gestu przewidywanego przejścia wstecz

Jeśli nadal używasz Androida 13 lub Androida 14, możesz przetestować animację powrotu do ekranu głównego pokazaną na ilustracji 1.

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

  1. Na urządzeniu otwórz Ustawienia > System > Opcje programisty.

  2. Wybierz Animacje przewidywanego przejścia wstecz.

  3. Uruchom zaktualizowaną aplikację i użyj gestu cofania, aby zobaczyć, jak działa.