Dodano obsługę gestu przewidywanego przejścia wstecz

Rysunek 1. Podgląd wyglądu i działania gestu przewidywanego przejścia wstecz na telefonie

Przewidywane przejście wstecz, funkcja nawigacji przy użyciu gestów, umożliwia użytkownikom podgląd miejsca, do którego przeniesie ich przesunięcie palcem wstecz.

Na przykład użycie gestu wstecz może spowodować wyświetlenie animowanego podglądu ekranu głównego za aplikacją, jak pokazano na makiecie na rysunku 1.

Od Androida 15 opcja dla programistów dotycząca przewidywanych animacji przejścia wstecz nie jest już dostępna. Animacje systemowe, takie jak powrót do ekranu głównego, przechodzenie między zadaniami i przechodzenie między aktywnościami, pojawiają się teraz w aplikacjach, które wyraziły zgodę na gest przewidywanego przejścia wstecz w całej aplikacji lub na poziomie aktywności.

Możesz przetestować tę animację powrotu do ekranu głównego (zgodnie z opisem w następnej sekcji tej strony).

Aby obsługiwać gest przewidywanego przejścia wstecz, musisz zaktualizować aplikację, używając zgodnego wstecznie interfejsu API OnBackPressedCallback w AndroidX Activity 1.6.0 lub nowszym albo nowego interfejsu API platformy OnBackInvokedCallback. Większość aplikacji używa zgodnego wstecznie interfejsu AndroidX API.

Ta aktualizacja zapewnia ścieżkę migracji, która umożliwia prawidłowe przechwytywanie przechodzenia wstecz. Polega to na zastąpieniu przechwytywania przechodzenia wstecz z KeyEvent.KEYCODE_BACK i wszystkich klas z metodami onBackPressed, takimi jak Activity i Dialog, nowymi interfejsami API systemu do przechodzenia wstecz.

Ćwiczenie w Codelabs i film z Google I/O

Oprócz korzystania z dokumentacji na tej stronie wypróbuj nasze ćwiczenia z programowania. Przedstawia on implementację typowego przypadku użycia komponentu WebView obsługującego gest przewidywanego przejścia wstecz za pomocą interfejsów API aktywności AndroidX.

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

Obsługa niestandardowych gestów wstecz w Compose

Compose udostępnia funkcję kompozycyjną PredictiveBackHandler do obsługi niestandardowych gestów wstecz. Ten interfejs API umożliwia reagowanie na gest wstecz i udostępnia obiekt Flow obiektów BackEventCompat, których możesz używać do implementowania niestandardowych animacji lub przejść, gdy użytkownik przesuwa palcem.

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

// 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.
    }
}

Jeśli chcesz tylko przechwytywać gest cofnięcia bez śledzenia postępów, użyj BackHandler.

Aktualizowanie aplikacji, która używa domyślnego przechodzenia wstecz

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

Jeśli Twoja aplikacja używa fragmentów lub komponentu nawigacji, uaktualnij też AndroidX Activity do wersji 1.6.0 lub nowszej.

Aktualizowanie aplikacji, która korzysta z niestandardowego przechodzenia wstecz

Jeśli aplikacja implementuje niestandardowe zachowanie przy przechodzeniu wstecz, dostępne są różne ścieżki migracji w zależności od tego, czy używa ona AndroidX i jak obsługuje przechodzenie wstecz.

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

Migracja implementacji przechodzenia wstecz w AndroidX

Ten przypadek użycia jest najczęstszy (i najbardziej zalecany). Dotyczy to nowych lub istniejących 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 (takie jak fragmenty i komponent nawigacji), działają bezproblemowo 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 używa bibliotek AndroidX, ale implementuje nieobsługiwane interfejsy API do przechodzenia wstecz lub odwołuje się do nich, musisz przejść na interfejsy API AndroidX, aby obsługiwać nowe działanie.

Aby przenieść nieobsługiwane interfejsy API do interfejsów API AndroidX:

  1. Przenieś logikę obsługi systemowego przycisku Wstecz do OnBackPressedDispatcher AndroidX z implementacją OnBackPressedCallback. Szczegółowe instrukcje znajdziesz w artykule Niestandardowe przechodzenie wstecz.

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

  3. Przestań przechwytywać zdarzenia cofnięcia za pomocą OnBackPressed lub KeyEvent.KEYCODE_BACK.

  4. Upewnij się, że uaktualniasz do wersji 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 pliku AndroidManifest.xml w tagu <application> ustaw flagę android:enableOnBackInvokedCallback na false.

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

Jeśli ustawisz wartość Fałsz:

  • 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 pozwala zrezygnować z przewidywanych animacji systemowych na poziomie aktywności. Dzięki temu łatwiej jest przenieść duże aplikacje z wieloma aktywnościami na gesty przewidywanego przejścia wstecz.

Poniższy kod pokazuje przykład elementu enableOnBackInvokedCallback ustawionego tak, aby włączał systemową animację 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 API platformy OnBackInvokedCallback. Wywołania OnBackPressedCallback będą jednak nadal działać, ponieważ OnBackPressedCallback jest zgodny wstecznie i wywołuje interfejs API onBackPressed, który nie jest obsługiwany w wersjach starszych niż Android 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 powyższym przykładzie kodu.

Wytyczne dotyczące oddzwonienia

Podczas korzystania z obsługiwanych wywołań zwrotnych systemu dotyczących cofania przestrzegaj tych wytycznych: PredictiveBackHandler lub BackHandler (w przypadku Compose), OnBackPressedCallback lub OnBackInvokedCallback.

Określanie stanu interfejsu, który włącza i wyłącza poszczególne wywołania zwrotne

Stan interfejsu to właściwość, która opisuje interfejs. Zalecamy wykonanie tych ogólnych 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 przechowującego dane dostępne do obserwacji, takiego jak StateFlow lub Compose State, i włączaj lub wyłączaj wywołanie zwrotne w zależności od zmiany stanu.

Jeśli Twoja aplikacja wcześniej powiązywała logikę przycisku Wstecz z instrukcjami warunkowymi, może to oznaczać, że reagujesz na zdarzenie cofnięcia 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 powiąż je z obserwowalnym typem obiektu przechowującego dane.

Używanie systemowych wywołań zwrotnych do obsługi logiki interfejsu

Logika interfejsu określa, jak wyświetlać interfejs. Używaj wywołań zwrotnych systemu, aby uruchamiać logikę interfejsu, np. wyświetlać okno lub uruchamiać animację.

Jeśli 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 aplikacja musi uruchamiać logikę biznesową lub rejestrować zdarzenia, gdy użytkownik przesuwa palcem wstecz, użyj tych metod:

  • W Compose: loguj w wywołaniu zwrotnym onCleared() elementu ViewModel powiązanego z miejscem docelowym Compose. To najlepszy sygnał, aby dowiedzieć się, kiedy miejsce docelowe Compose zostało usunięte ze stosu wstecznego i zniszczone.
  • Na Androidzie 16 lub nowszym: użyj OnBackInvokedCallback z PRIORITY_SYSTEM_NAVIGATION_OBSERVER. Spowoduje to utworzenie wywołania zwrotnego obserwatora, które nie wykorzystuje zdarzenia cofnięcia. Możesz na przykład zarejestrować to wywołanie zwrotne, gdy użytkownik przesunie palcem wstecz z aktywności głównej (opuszczając aplikację), aby zarejestrować zdarzenie cofnięcia lub uruchomić logikę biznesową, jednocześnie umożliwiając odtworzenie animacji powrotu do ekranu głównego.
  • W aplikacjach opartych na widokach: rejestruj zdarzenia w wywołaniach zwrotnych cyklu życia lub stosu wstecznego, zamiast wykorzystywać zdarzenia wstecz:
    • W przypadku przejść między aktywnościami sprawdź, czy isFinishing to true w ciągu Activity.onDestroy().
    • W przypadku przejść fragmentów sprawdź, czy isRemoving to true w cyklu życia widoku fragmentu onDestroy(), lub użyj FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted / onBackStackChangeCommitted).

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 ostatnio dodane włączone wywołanie zwrotne obsługuje następny gest wstecz, przy czym na każdy gest wstecz przypada jedno wywołanie zwrotne.

Stan włączenia wywołania zwrotnego jest łatwiejszy do zarządzania, jeśli wywołanie zwrotne ma jedno zadanie. Przykład:

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

Rysunek 2 pokazuje, jak można mieć na stosie wiele wywołań zwrotnych, z których każde odpowiada za jedną rzecz. W Compose wywołania zwrotne są oceniane od najbardziej wewnętrznego do najbardziej zewnętrznego elementu kompozycyjnego, a wywołanie zwrotne jest uruchamiane tylko wtedy, gdy wywołania zwrotne poprzedzające je na stosie są wyłączone:

  • Pojawi się okno z pytaniem „Czy na pewno…”. Przycisk PredictiveBackHandler jest włączony, gdy użytkownik wpisuje dane w formularzu, a w przeciwnym razie jest wyłączony. Gdy jest włączona, przechwytuje gest wstecz, aby wyświetlić okno potwierdzenia lub niestandardową animację w aplikacji.
  • Jeśli poprzednie wywołanie zwrotne jest wyłączone, uruchamiane jest wywołanie zwrotne BackHandler na poziomie ekranu. W tym przykładzie jest wyłączona.
  • Wywołanie zwrotne NavHost obsługuje przechodzenie wstecz, aby usunąć miejsca docelowe ze stosu wstecznego, jeśli poprzednie niestandardowe wywołania zwrotne są wyłączone.
  • Na koniec system obsługuje gest wstecz, jeśli wszystkie poprzednie wywołania zwrotne są wyłączone. Gdy stos wsteczny znajduje się w miejscu docelowym, system uruchamia animacje na poziomie systemu, takie jak powrót do ekranu głównego, przechodzenie między aktywnościami i przechodzenie między zadaniami.

To samo zachowanie stosu dotyczy aplikacji opartych na widokach: ostatnio dodany włączony element OnBackPressedCallback ma pierwszeństwo, a w razie potrzeby następuje powrót do FragmentManager i ostatecznie do obsługi cofania przez system.

Testowanie animacji gestu przewidywanego przejścia wstecz

Począwszy od Androida 15 animacje systemowe, takie jak powrót do ekranu głównego, przechodzenie między zadaniami i przechodzenie między aktywnościami, są domyślnie włączone w aplikacjach, które obsługują przewidywane przejście wstecz. Nie są już ukryte w opcjach programisty.

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

  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 wstecz, aby zobaczyć, jak działa.