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ć, gdzie przeniesie ich przesunięcie palcem w celu powrotu.

Na przykład użycie gestu powrotu może spowodować wyświetlenie animowanego podglądu 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 gest przewidywanego przejścia 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 interfejsu API albo nowego interfejsu API OnBackInvokedCallback 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 powrotu z KeyEvent.KEYCODE_BACK i wszystkich klas z metodami onBackPressed, takimi jak Activity i Dialog, nowymi interfejsami API systemu Back.

Uwaga: KeyEvent.KEYCODE_BACK nie jest wycofywany, ponieważ istnieją obsługiwane przypadki użycia KeyEvent.KEYCODE_BACK. Nie jest jednak już obsługiwane przechwytywanie zdarzeń powrotu z KeyEvent.KEYCODE_BACK.

Ć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 gest przewidywanego przejścia 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.

Obsługa niestandardowych gestów powrotu w Compose

Compose udostępnia element kompozycyjny PredictiveBackHandler do obsługi niestandardowych gestów powrotu. Ten interfejs API umożliwia reagowanie na gest powrotu 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 powrotu 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 powrotu, dostępne są różne ścieżki migracji w zależności od tego, czy korzysta z AndroidX i jak obsługuje przechodzenie wstecz.

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

Ważne: zdecydowanie zalecamy jak najszybsze wdrożenie przewidywanej nawigacji wstecz. W przeciwnym razie użytkownicy mogą napotkać nieoczekiwane zachowanie w przyszłej wersji Androida.

Migracja implementacji nawigacji wstecz 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 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.

Uwaga: zdecydowanie zalecamy korzystanie z bibliotek AndroidX. Gdy włączysz tę funkcję, AndroidX automatycznie włączy w Twojej aplikacji zaktualizowane przechodzenie wstecz systemu. Udostępnia też wiele innych przydatnych funkcji, które automatycznie aktualizują interfejsy API z każdą wersją, co pozwala zaoszczędzić czas i pracę.

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

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

2. Gdy będziesz gotowy(-a) do zatrzymania przechwytywania gestu powrotu, wyłącz OnBackPressedCallback.

3. Przestań przechwytywać zdarzenia powrotu 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"
   

   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 powrotu 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łączenie animacji systemowej 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 gestów 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>

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 platformy. Wywołania OnBackPressedCallback są jednak nadal wykonywane, ponieważ OnBackPressedCallback jest wstecznie zgodny i wywołuje interfejs onBackPressed API, który nie jest obsługiwany w Androidzie 13 ani starszych wersjach.
• 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 powrotu 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.

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 Compose State, 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 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 powrotu systemu do logiki interfejsu

Logika interfejsu określa sposób wyświetlania interfejsu. Używaj wywołań zwrotnych powrotu 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 powrotu. 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 powrotu, 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 powrotu. Możesz na przykład zarejestrować to wywołanie zwrotne, gdy użytkownik przesunie palcem w celu powrotu z głównej aktywności, czyli gdy opuści Twoją aplikację. W takim przypadku możesz zalogować zdarzenie powrotu lub uruchomić inną logikę biznesową, a animacja powrotu do ekranu głównego będzie nadal odtwarzana.
• W przypadku aktywności do aktywności lub fragmentu do aktywności zaloguj, czy isFinishing w onDestroy ma wartość true w cyklu życia działania.
• W przypadku 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 jest usuwane ze stosu wstecz i niszczone.

Tworzenie wywołań zwrotnych z pojedynczą 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 (po 1 wywołaniu zwrotnym na gest powrotu).

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

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 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 powrotu, 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 poprzednie wywołania zwrotne są wyłączone, a stos wstecz 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 powrotu, jeśli poprzednie wywołania zwrotne są wyłączone. 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

Uwaga: w Androidzie 15 animacje systemowe, takie jak powrót do ekranu głównego, przełączanie między zadaniami i przełączanie między aktywnościami, nie są już dostępne w opcjach programisty. 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.

Jeśli nadal używasz Androida 13 lub Androida 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 powrotu, aby zobaczyć, jak działa.