Dodano obsługę gestu przewidywanego przejścia wstecz

**Rysunek 1.** Makieta przedstawiająca wygląd i działanie gestu 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 użycie gestu 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, przełączanie między zadaniami i przełączanie 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ć gest przewidywanego przejścia wstecz, musisz zaktualizować aplikację, używając wstecznie zgodnego OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) lub nowszego albo nowego 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 polega na zastąpieniu przechwytywania przejścia wstecz z KeyEvent.KEYCODE_BACK i wszystkich klas z metodami onBackPressed, takich jak Activity i Dialog, nowymi interfejsami systemowymi Back API.

Ćwiczenia w Codelabs i film z Google I/O

Oprócz korzystania z dokumentacji na tej stronie wypróbuj nasze ćwiczenia w Codelabs. Zawierają one typową implementację obsługi gestu przewidywanego przejścia wstecz w komponencie WebView 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żywać 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ślnego przechodzenia 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 przechodzenia 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 dotychczasowych 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 gestem przewidywanego przejścia wstecz, zaktualizuj aplikację 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 przechodzenia 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:

Przenieś logikę obsługi przejścia wstecz systemu do AndroidX’s OnBackPressedDispatcher z implementacją OnBackPressedCallback. Szczegółowe wskazówki znajdziesz w sekcji Udostępnianie niestandardowego przechodzenia wstecz.
Gdy zechcesz przestać przechwytywać gest cofania, wyłącz OnBackPressedCallback.
Przestań przechwytywać zdarzenia przejścia wstecz za pomocą OnBackPressed lub KeyEvent.KEYCODE_BACK.
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"
```
Uwaga: OnBackPressedCallback jest zawsze wywoływany niezależnie od wartości android:enableOnBackInvokedCallback. Innymi słowy, wyłączenie animacji systemowej nie wpływa na logikę obsługi przejścia wstecz w aplikacji, jeśli korzysta ona z OnBackPressedCallback.

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 migrować duże aplikacje z wieloma aktywnościami do przewidywanego przejścia wstecz.

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>

Jeśli używasz 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. Wywołania OnBackPressedCallback nadal działają, ponieważ OnBackPressedCallback jest zgodny wstecznie i wywołuje interfejs onBackPressed API, który nie jest obsługiwany w wersjach Androida wcześniejszych 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.

Sprawdzone metody dotyczące wywołań zwrotnych

Oto sprawdzone metody korzystania z obsługiwanych wywołań zwrotnych przejścia wstecz systemu: 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 ogólnych czynności.

Określ stan interfejsu, który włącza i wyłącza każde wywołanie zwrotne.
Zdefiniuj ten stan za pomocą obserwowalnego typu kontenera danych, takiego jak StateFlow lub Compose State, 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 systemu w logice interfejsu

Logika interfejsu określa, jak wyświetlać interfejs. Używaj wywołań zwrotnych przejścia wstecz systemu 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 przesunie 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 z aktywności do aktywności lub z fragmentu do aktywności zaloguj, czy isFinishing w onDestroy ma wartość true w cyklu życia działania.
W przypadku przejścia z fragmentu do fragmentu 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ść. Na przykład:

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

Rysunek 2 pokazuje, jak można mieć w stosie wiele wywołań zwrotnych, z których każde odpowiada za jedną rzecz. Wywołanie zwrotne jest uruchamiane tylko wtedy, gdy wywołania zwrotne znajdujące się nad nim 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 zawierać komponent Material, 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's jest uruchamiane, jeśli powyższe 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 powyższe 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, jeśli powyższe wywołania zwrotne są wyłączone, system obsługuje gest cofania. Aby uruchomić animacje systemowe, takie jak powrót do ekranu głównego, przełączanie między aktywnościami i przełączanie 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ę:

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.