Dodano obsługę gestu przewidywanego przejścia wstecz

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

Na przykład gest 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 dla programistów 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 predykcyjnego powrotu w całości lub na poziomie aktywności.

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

Obsługa gestu przewidywanego przejścia wstecz wymaga zaktualizowania aplikacji, użycia wstecznie zgodnego interfejsu OnBackPressedCallback w AndroidX Activity 1.6.0 lub nowszego albo użycia nowego interfejsu 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 przechodzenia wstecz. 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 w Codelabs i film z Google I/O

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

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

Obsługa niestandardowych gestów wstecz w Compose

Biblioteka Compose udostępnia funkcję kompozycyjną PredictiveBackHandler do obsługi niestandardowych gestów powrotu. Ten interfejs API umożliwia reagowanie na gest cofania i udostępnia listę obiektów FlowBackEventCompat, których możesz użyć do wdrożenia niestandardowych animacji lub przejść podczas przesuwania palcem przez użytkownika.

Aby używać PredictiveBackHandler, upewnij się, że Twoja aplikacja zawiera zależność androidx.activity:activity-compose (wersja 1.8.0 lub nowsza):

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}

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.
    }
}
PredictiveBackSnippets.kt

Jeśli chcesz tylko przechwycić gest cofnięcia bez śledzenia postępu, użyj BackHandler.

Aktualizowanie aplikacji, która korzysta z domyślnego przechodzenia wstecz

Domyślnie włączone jest przewidywane przejście wstecz.

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

Aktualizowanie aplikacji, która korzysta z niestandardowego przechodzenia 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 przechodzenie wstecz.

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 niestandardowego przechodzenia 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 przewidywanego przejścia wstecz, przejdź na AndroidX Activity 1.6.0 lub nowszą wersję.

// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

Migracja aplikacji AndroidX zawierającej nieobsługiwane interfejsy API przechodzenia wstecz 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 przechodzenia 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 systemu do biblioteki AndroidX OnBackPressedDispatcher z implementacją OnBackPressedCallback. Szczegółowe wskazówki znajdziesz w artykule Zapewnianie niestandardowego przechodzenia wstecz.

2. Gdy chcesz przestać przechwytywać gest cofania, wyłącz OnBackPressedCallback.

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

4. Uaktualnij do AndroidX Activity 1.6.0 lub nowszej.

   // In your build.gradle file:
   dependencies {
       // Add this in addition to your other dependencies
       implementation "androidx.activity:activity:1.6.0"
   }
   

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>

Jeśli ustawisz tę opcję na wartość „fałsz”, wykonane zostaną te czynności:

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

Rezygnowanie 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 przewidywanych gestów wstecz.

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 powrotu z przewidywaniem 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 będą jednak nadal działać, 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 działań w aplikacji. Możesz zastąpić wartość domyślną dla poszczególnych działań, ustawiając flagę na poziomie działania, jak pokazano w poprzednim przykładzie kodu.

Wytyczne dotyczące oddzwonienia

Podczas korzystania z obsługiwanych wywołań zwrotnych systemu PredictiveBackHandler lub BackHandler (w przypadku Compose), OnBackPressedCallback lub OnBackInvokedCallback postępuj zgodnie z tymi wskazówkami.

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 do uruchamiania logiki interfejsu, np. wyświetlania okna dialogowego lub uruchamiania animacji.

Jeśli Twoja aplikacja umożliwia 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, aby uruchamiać logikę biznesową ani rejestrować zdarzenia.

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

• W przypadku funkcji Compose: rejestruj w wywołaniu zwrotnym onCleared() funkcji ViewModel powiązanej z miejscem docelowym Compose. To najlepszy sygnał informujący o tym, kiedy miejsce docelowe Compose jest usuwane ze stosu wstecznego i niszczone.
• Na Androidzie 16 i nowszych wersjach: użyj OnBackInvokedCallback z PRIORITY_SYSTEM_NAVIGATION_OBSERVER. 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 (opuszczając aplikację), aby zarejestrować zdarzenie powrotu lub uruchomić logikę biznesową, jednocześnie umożliwiając odtworzenie animacji powrotu do ekranu głównego.
• W aplikacjach opartych na widokach: rejestruj zdarzenia w ramach wywołań zwrotnych cyklu życia lub stosu wstecznego, a nie w ramach zdarzeń wstecznych:
  • W przypadku przejść aktywności sprawdź, czy isFinishing to true w ramach Activity.onDestroy().
  • W przypadku przejść między fragmentami sprawdź, czy isRemoving ma wartość true w ramach cyklu życia widoku fragmentu onDestroy(), lub użyj FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted / onBackStackChangeCommitted).

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 jest zarządzać stanem włączonym wywołania zwrotnego, jeśli ma ono jedno zadanie. Przykład:

Ilustracja 2 pokazuje, jak w stosie może być wiele wywołań zwrotnych, z których każde odpowiada za jedną czynność. W Compose wywołania zwrotne są oceniane od najbardziej wewnętrznego do najbardziej zewnętrznego komponentu, a wywołanie zwrotne jest uruchamiane tylko wtedy, gdy wywołania zwrotne poprzedzające je w stosie są wyłączone:

• Komunikat „Czy na pewno...” PredictiveBackHandler jest włączony, gdy użytkownik wprowadza dane do formularza, a w innych przypadkach jest wyłączony. Gdy ta opcja jest włączona, przechwytuje gest cofania, aby wyświetlić okno potwierdzenia lub niestandardową animację w aplikacji.
• BackHandler na poziomie ekranu jest uruchamiana, jeśli poprzednie wywołanie zwrotne jest wyłączone. W tym przykładzie jest ona wyłączona.
• Wywołanie zwrotne NavHost obsługuje przechodzenie wstecz, aby wysuwać miejsca docelowe ze stosu wstecznego, jeśli poprzednie niestandardowe wywołania zwrotne są wyłączone.
• Na koniec system obsługuje gest powrotu, jeśli wszystkie poprzednie wywołania zwrotne są wyłączone. Gdy stos wsteczny znajduje się w miejscu docelowym, system wywołuje animacje na poziomie systemu, takie jak powrót do ekranu głównego, przejście między aktywnościami i przejście między zadaniami.

To samo zachowanie stosu obowiązuje w aplikacjach opartych na widokach: ostatni dodany element z włączoną obsługą OnBackPressedCallback ma pierwszeństwo, a w razie potrzeby następuje powrót do FragmentManager i ostatecznie do obsługi przycisku Wstecz przez system.

Sprawdź animację gestu przewidywanego przejścia wstecz

Od Androida 15 animacje systemowe, takie jak powrót do ekranu głównego, przełączanie między zadaniami i przełączanie między aktywnościami, są domyślnie włączone w przypadku aplikacji, które obsługują przewidywane przejście wstecz. Nie są już dostępne w opcjach dla programistów.

Na urządzeniach z Androidem 13 lub 14 możesz włączyć opcje programisty, aby przetestować animację powrotu do ekranu głównego pokazaną na ilustracji 1:

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

2. Wybierz Animacje przewidywanego przejścia wstecz.

3. Uruchom zaktualizowaną aplikację i wykonaj gest cofania, aby zobaczyć, jak działa.