Dodano obsługę gestu przewidywanego przejścia wstecz

Rysunek 1. Makieta przedstawiająca wygląd i działanie przewidywanego przejścia wstecz na telefonie

Przewidywane przejście wstecz to funkcja nawigacji przy użyciu gestów, która pozwala użytkownikom zobaczyć, dokąd przeniesie ich przesunięcie palcem w celu cofnięcia.

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 programisty dotycząca animacji przewidywanego przejścia wstecz nie jest już dostępna. Animacje systemowe, takie jak powrót do ekranu głównego, przejście między zadaniami i przejście między aktywnościami, są teraz wyświetlane w przypadku aplikacji, które włączyły przewidywane przejście wstecz w całości lub na poziomie aktywności.

Możesz przetestować animację powrotu do ekranu głównego (jak opisano w dalszej części tej strony).

Aby obsługiwać przewidywane przejście wstecz, musisz zaktualizować aplikację, użyć wstecznie zgodnego OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) lub nowszego interfejsu API albo nowego interfejsu OnBackInvokedCallback API platformy. Większość aplikacji korzysta ze wstecznie zgodnego interfejsu AndroidX API.

Ta aktualizacja zapewnia ścieżkę migracji, która umożliwia prawidłowe przechwytywanie nawigacji wstecz, co obejmuje zastąpienie przechwytywania przejścia wstecz z KeyEvent.KEYCODE_BACK i wszystkich klas z metodami onBackPressed, takich jak Activity i Dialog, nowymi interfejsami systemowymi Back API.

Ćwiczenie i film z Google I/O

Oprócz korzystania z dokumentacji na tej stronie wypróbuj nasze ćwiczenie. Zawiera ono implementację typowego przypadku użycia elementu WebView obsługującego przewidywane przejście wstecz za pomocą interfejsów AndroidX Activity API.

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

Obsługa niestandardowych gestów cofania w Compose

Compose udostępnia element kompozycyjny PredictiveBackHandler do obsługi niestandardowych gestów cofania. Ten interfejs API umożliwia reagowanie na gest cofania i udostępnia Flow obiektów BackEventCompat, których możesz użyć do implementowania niestandardowych animacji lub przejść podczas przesuwania palcem przez użytkownika.

PredictiveBackHandler(enabled = isBackHandlerEnabled) { progress: Flow<BackEventCompat> ->
    try {
        progress.collect { backEvent ->
            // Update your UI or animation based on backEvent.progress.
        }
        // Handle the final back action (e.g., navigate back).
    } catch (e: CancellationException) {
        // Back gesture was cancelled, reset your UI.
    }
}

Jeśli musisz tylko przechwycić gest cofania bez śledzenia postępu, użyj BackHandler.

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

Przewidywane przejście wstecz jest domyślnie włączone.

Jeśli Twoja aplikacja korzysta z fragmentów lub komponentu nawigacji, zaktualizuj ją też do AndroidX Activity 1.6.0-alpha05 lub nowszej.

Aktualizowanie aplikacji, która korzysta z niestandardowej nawigacji wstecz

Jeśli Twoja aplikacja implementuje niestandardowe zachowanie przejścia wstecz, dostępne są różne ścieżki migracji w zależności od tego, czy korzysta z AndroidX i jak obsługuje nawigację wstecz.

Jak Twoja aplikacja obsługuje nawigację wstecz Zalecana ścieżka migracji (link na tej stronie)
Interfejsy AndroidX API Migracja istniejącej implementacji przejścia wstecz w AndroidX
Nieobsługiwane interfejsy API platformy Migracja aplikacji AndroidX zawierającej nieobsługiwane interfejsy API nawigacji wstecz do interfejsów AndroidX API

Migracja implementacji przechodzenia wstecz w AndroidX

Ten przypadek użycia jest najczęstszy (i najbardziej zalecany). Dotyczy nowych i istniejących aplikacji, które implementują niestandardową obsługę nawigacji przy użyciu gestów za pomocą OnBackPressedDispatcher, jak opisano w Udostępnianie niestandardowego przechodzenia wstecz.

Aby mieć pewność, że interfejsy API, które już korzystają z OnBackPressedDispatcher (takie jak fragmenty i komponent nawigacji), będą bezproblemowo współpracować z przewidywanym przejściem wstecz, zaktualizuj je 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"
}

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

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

Aby przeprowadzić migrację nieobsługiwanych interfejsów API do interfejsów AndroidX API:

  1. Przenieś logikę obsługi przejścia wstecz w systemie do AndroidX's OnBackPressedDispatcher z implementacją OnBackPressedCallback. Szczegółowe wskazówki znajdziesz w sekcji Udostępnianie niestandardowego przechodzenia wstecz.

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

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

  4. Pamiętaj, aby zaktualizować aplikację 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"
}

Rezygnacja z przewidywanego przejścia wstecz

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

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

Ustawienie tej wartości na false powoduje:

  • Wyłącza animację systemową gestu przewidywanego przejścia wstecz.
  • ignorowanie OnBackInvokedCallback, ale wywołania OnBackPressedCallback nadal działają.

Rezygnacja na poziomie aktywności

Flaga android:enableOnBackInvokedCallback umożliwia rezygnację z przewidywanych animacji systemowych na poziomie aktywności. Dzięki temu łatwiej jest przeprowadzić migrację dużych aplikacji z wieloma aktywnościami do przewidywanych gestów cofania.

Poniższy kod pokazuje przykład ustawienia enableOnBackInvokedCallback na włączenie animacji systemowej 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 przewidywanego przejścia wstecz na poziomie aktywności lub aplikacji (w zależności od tego, gdzie ustawisz tag) i nakazuje systemowi ignorowanie wywołań interfejsu OnBackInvokedCallback API platformy. Jednak wywołania OnBackPressedCallback nadal działają, ponieważ OnBackPressedCallback jest wstecznie zgodny i wywołuje interfejs onBackPressed API, 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 każdej aktywności, ustawiając flagę na poziomie aktywności, jak pokazano w poprzednim przykładzie kodu.

Wskazówki dotyczące wywołań zwrotnych

Korzystając z obsługiwanych wywołań zwrotnych przejścia wstecz w systemie, postępuj zgodnie z tymi wskazówkami: PredictiveBackHandler lub BackHandler (w przypadku Compose), OnBackPressedCallback lub OnBackInvokedCallback.

Określanie stanu interfejsu, który włącza i wyłącza każde wywołanie 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 każde wywołanie zwrotne.

  2. Zdefiniuj ten stan za pomocą typu kontenera danych dostępnych do obserwacji, takiego jak StateFlow lub stan Compose, i włączaj lub wyłączaj wywołanie zwrotne w miarę zmiany stanu.

Jeśli Twoja aplikacja wcześniej łączyła logikę przejścia wstecz z instrukcjami warunkowymi, może to oznaczać, że reagujesz na zdarzenie przejścia wstecz po jego wystąpieniu. Unikaj tego wzorca w przypadku nowszych wywołań zwrotnych. Jeśli to możliwe, przenieś wywołanie zwrotne poza instrukcję warunkową i zamiast tego powiąż je z obserwowalnym typem kontenera danych.

Używanie wywołań zwrotnych przejścia wstecz w systemie do logiki interfejsu

Logika interfejsu określa sposób wyświetlania interfejsu. Używaj wywołań zwrotnych przejścia wstecz w systemie do uruchamiania logiki interfejsu, np. wyświetlania okna lub uruchamiania animacji.

Jeśli Twoja aplikacja włącza OnBackPressedCallback lub OnBackInvokedCallback z PRIORITY_DEFAULT lub PRIORITY_OVERLAY, animacje przewidywanego przejścia wstecz nie są uruchamiane i musisz obsłużyć zdarzenie przejścia wstecz. Nie twórz tych wywołań zwrotnych do uruchamiania logiki biznesowej ani do logowania.

Jeśli Twoja aplikacja musi uruchamiać logikę biznesową lub logować, gdy użytkownik przesuwa palcem w celu cofnięcia, użyj tych metod:

  • Użyj 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 przejścia wstecz. Możesz na przykład zarejestrować to wywołanie zwrotne, gdy użytkownik przesunie palcem w celu cofnięcia z głównej aktywności, czyli gdy opuści Twoją aplikację. W takim przypadku możesz zalogować zdarzenie przejścia wstecz lub uruchomić inną logikę biznesową, a animacja powrotu do ekranu głównego będzie nadal odtwarzana.
  • W przypadku przejścia między Activity lub między fragmentem a Activity zaloguj, czy isFinishing w onDestroy ma wartość true w cyklu życia działania.
  • W przypadku przejścia między fragmentami zaloguj, czy isRemoving w onDestroy ma wartość true w cyklu życia widoku fragmentu. Możesz też logować za pomocą metod onBackStackChangeStarted lub onBackStackChangeCommitted w FragmentManager.OnBackStackChangedListener.
  • W przypadku Compose zaloguj w wywołaniu zwrotnym onCleared() elementu ViewModel powiązanego z miejscem docelowym Compose. Jest to najlepszy sygnał informujący o tym, kiedy miejsce docelowe Compose zostanie usunięte ze stosu wstecz i zniszczone.

Tworzenie wywołań zwrotnych o pojedynczej 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 cofania (po 1 wywołaniu zwrotnym na gest cofania).

Łatwiej jest zarządzać stanem włączonym wywołania zwrotnego, jeśli ma ono pojedynczą odpowiedzialność. Przykład:

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

Rysunek 2 pokazuje, jak można mieć wiele wywołań zwrotnych w stosie, z których każde odpowiada za jedną rzecz. Wywołanie zwrotne jest uruchamiane tylko wtedy, gdy wywołania zwrotne poprzedzające je w stosie są wyłączone. W tym przykładzie wywołanie zwrotne „Czy na pewno chcesz wyjść?” jest włączone, gdy użytkownik wprowadza dane do formularza, a w przeciwnym razie jest wyłączone. Wywołanie zwrotne otwiera okno potwierdzenia, gdy użytkownik przesunie palcem w celu cofnięcia, aby wyjść z formularza.

Inne wywołanie zwrotne może obejmować komponent Material Design, który obsługuje przewidywane przejście wstecz, przejście AndroidX korzystające z interfejsów Progress API lub inne niestandardowe wywołanie zwrotne.

To samo zachowanie stosu obowiązuje w Compose: pierwszeństwo ma najbardziej wewnętrzny element PredictiveBackHandler lub BackHandler.

Podobnie wywołanie zwrotne childFragmentManager jest uruchamiane, jeśli poprzednie wywołania zwrotne są wyłączone, a stos wstecz dla tego FragmentManager nie jest pusty. W tym przykładzie to wewnętrzne wywołanie zwrotne jest wyłączone.

Podobnie wewnętrzne wywołanie zwrotne supportFragmentManager jest uruchamiane, jeśli poprzednie wywołania zwrotne są wyłączone, a jego stos nie jest pusty. W tym przykładzie to wywołanie zwrotne jest uruchamiane, jeśli użytkownik nie wprowadził tekstu do formularza, co spowodowało wyłączenie wywołania zwrotnego „Czy na pewno chcesz wyjść?”.

Na koniec system obsługuje gest cofania, jeśli poprzednie wywołania zwrotne są wyłączone. Aby uruchomić animacje systemowe, takie jak powrót do ekranu głównego, przejście między aktywnościami i przejście między zadaniami, stos wstecz supportFragmentManager musi być pusty, aby jego wewnętrzne wywołanie zwrotne było wyłączone.

Testowanie animacji gestu przewidywanego przejścia wstecz

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

Aby przetestować tę animację:

  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.