Dodano obsługę gestu przewidywanego przejścia wstecz

Rysunek 1. Wizualizacja przewidującego gestu wstecz na telefonie

Przejście wstecz na podstawie przewidywania to funkcja nawigacji za pomocą gestów, która pozwala użytkownikom wyświetlić podgląd miejsca, do którego doprowadzi ich gest przesunięcia wstecz.

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 dewelopera dotycząca animacji przewidywanego przejścia wstecz nie jest już dostępna. Animacje systemowe, takie jak animacja powrotu do ekranu głównego, animacja przełączania zadań i animacja przełączania aktywności, są teraz wyświetlane w aplikacjach, które korzystają z przewidywanego gestu wstecz, niezależnie od tego, czy korzystają z niego całkowicie, czy tylko na poziomie aktywności.

Możesz przetestować tę animację powrotu do strony głównej (jak opisano w następującej sekcji tej strony).

Obsługa przewidującego gestu wstecz wymaga zaktualizowania aplikacji przy użyciu zgodnego z poprzednimi wersjami interfejsu OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) lub nowszego albo nowego interfejsu OnBackInvokedCallback platformy. Większość aplikacji korzysta z interfejsu AndroidX API zgodnego ze starszymi wersjami.

Ta aktualizacja zapewnia ścieżkę migracji, która umożliwia prawidłowe przechwytywanie nawigacji wstecznej, co obejmuje zastąpienie przechwytów wstecznych od KeyEvent.KEYCODE_BACK i wszystkich klas metod onBackPressed, takich jak Activity i Dialog, nowym systemowym interfejsami API backendu.

Filmy z Codelab i Google I/O

Oprócz korzystania z tej dokumentacji na tej stronie wypróbuj nasze ćwiczenia z programowania. Udostępnia ona implementację WebView obsługującą przewidujący gest wstecz za pomocą interfejsów Activity w AndroidX.

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

Zaktualizuj aplikację, która używa domyślnej nawigacji wstecz

Zaktualizowanie aplikacji, aby obsługiwała tę funkcję, jest proste, jeśli aplikacja nie implementuje żadnego niestandardowego zachowania przy cofaniu (czyli pozostawia obsługę cofnięcia systemowi). Włącz tę funkcję w sposób opisany w tym przewodniku.

Jeśli Twoja aplikacja używa fragmentów lub komponentu nawigacji, zaktualizuj je do wersji AndroidX Activity 1.6.0-alpha05 lub nowszej.

Aktualizacja aplikacji, która korzysta z niestandardowej nawigacji wstecz

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

Twoja aplikacja używa AndroidX Jak aplikacja obsługuje przekierowanie wstecz Zalecane rozwiązanie do migracji (link na tej stronie)
Tak Interfejsy API AndroidX Migracja istniejącej implementacji AndroidaX
Nieobsługiwane interfejsy API platform Przejście z aplikacji AndroidX zawierającej nieobsługiwane interfejsy API nawigacji wstecz na interfejsy API AndroidX
Nie Interfejsy API nieobsługiwanych platform, które można przenieść Przejście z aplikacji korzystającej z nieobsługiwanych interfejsów API nawigacji wstecz na interfejsy API platformy
Nieobsługiwane interfejsy API platformy, ale nie można przeprowadzić migracji Odrocz akceptację do czasu, gdy ta funkcja stanie się wymagana.

Migracja implementacji przechodzenia wstecz w AndroidX

Ten przypadek użycia jest najczęstszy (i najbardziej zalecany). Dotyczy on nowych i istniejących aplikacji, które implementują niestandardową nawigację przy użyciu gestów za pomocą OnBackPressedDispatcher, jak opisano w sekcji Udostępnianie niestandardowej nawigacji tylnej.

Jeśli Twoja aplikacja należy do tej kategorii, wykonaj te czynności, aby dodać obsługę przewidywanego gestu cofania:

  1. Aby mieć pewność, że interfejsy API, które korzystają już z interfejsów API OnBackPressedDispatcher (takie jak fragmenty i komponent nawigacji), bezproblemowo współpracują z przewidywalnym gestem cofania, przejdź na Aktywność w Androidzie 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"

  2. Włącz gest przewidywanego przejścia wstecz w sposób opisany na tej stronie.

Przenoszenie aplikacji na AndroidaX, które zawierają nieobsługiwane interfejsy API nawigacji wstecz, do interfejsów API AndroidaX

Jeśli Twoja aplikacja korzysta z bibliotek AndroidX, ale implementuje lub odwołuje się do nieobsługiwanych interfejsów API nawigacji wstecz, musisz przejść na korzystanie z interfejsów API AndroidX, aby obsługiwać nowe działanie.

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

  1. Przenieś wsteczną obsługę systemu do OnBackPressedDispatcher AndroidaX przy użyciu implementacji OnBackPressedCallback. Szczegółowe wskazówki znajdziesz w artykule o własnej nawigacji wstecz.

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

  3. Przestań przechwytywać zdarzenia „back” za pomocą funkcji OnBackPressed lub KeyEvent.KEYCODE_BACK.

  4. Zaktualizuj 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"

  5. Po zakończeniu przenoszenia aplikacji włącz gest przewidywanego przejścia wstecz (jak opisano na tej stronie), aby zobaczyć animację systemową powrotu na ekran główny.

Przenoszenie aplikacji, która korzysta z nieobsługiwanych interfejsów API nawigacji wstecz, do interfejsów API platformy

Jeśli Twoja aplikacja nie może używać bibliotek AndroidaX i zamiast tego implementuje niestandardową nawigację Wstecz lub odwołuje się do niej przy użyciu nieobsługiwanych interfejsów API, musisz przejść na interfejs API platformy OnBackInvokedCallback.

Aby przenieść nieobsługiwane interfejsy API do interfejsu API platformy, wykonaj te czynności:

  1. Używaj nowego interfejsu API OnBackInvokedCallback na urządzeniach z Androidem 13 lub nowszym oraz korzystaj z nieobsługiwanych interfejsów API na urządzeniach z Androidem 12 lub starszym.

  2. Zarejestruj niestandardową logikę cofania w OnBackInvokedCallback w onBackInvokedDispatcher. Uniemożliwia to zakończenie bieżącej aktywności, a wywołanie zwrotne będzie mieć szansę zareagować na działanie Wstecz, gdy użytkownik zakończy w systemie nawigację wstecz.

  3. Gdy chcesz przestać przechwytywać gest wstecz, zarejestruj OnBackInvokedCallback. W przeciwnym razie podczas korzystania z systemu nawigacji Wstecz w systemie użytkownicy mogą zauważyć niepożądane zachowanie – np. „utknąć” między widokami i wymusić na nich zamknięcie aplikacji.

    Oto przykład migracji logiki z poziomu onBackPressed:

    Kotlin

    @Override
fun onCreate() {
    if (BuildCompat.isAtLeastT()) {
        onBackInvokedDispatcher.registerOnBackInvokedCallback(
            OnBackInvokedDispatcher.PRIORITY_DEFAULT
        ) {
            /**
             * onBackPressed logic goes here. For instance:
             * Prevents closing the app to go home screen when in the
             * middle of entering data to a form
             * or from accidentally leaving a fragment with a WebView in it
             *
             * Unregistering the callback to stop intercepting the back gesture:
             * When the user transitions to the topmost screen (activity, fragment)
             * in the BackStack, unregister the callback by using
             * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
             * (https://developer.android.com/reference/kotlin/android/window/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
             */
        }
    }
}

    Java

    @Override
void onCreate() {
  if (BuildCompat.isAtLeastT()) {
    getOnBackInvokedDispatcher().registerOnBackInvokedCallback(
        OnBackInvokedDispatcher.PRIORITY_DEFAULT,
        () -> {
          /**
           * onBackPressed logic goes here - For instance:
           * Prevents closing the app to go home screen when in the
           * middle of entering data to a form
           * or from accidentally leaving a fragment with a WebView in it
           *
           * Unregistering the callback to stop intercepting the back gesture:
           * When the user transitions to the topmost screen (activity, fragment)
           * in the BackStack, unregister the callback by using
           * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
           * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
           */
        }
    );
  }
}

  4. Przestań przechwytywać zdarzenia wstecz za pomocą OnBackPressed lub KeyEvent.KEYCODE_BACK w Androidzie 13 i nowszych.

  5. Po migracji aplikacji zezwól na użycie przewidującego gestu wstecz (jak opisano na tej stronie), aby OnBackInvokedCallback zaczęło działać.

Możesz zarejestrować OnBackInvokedCallback w usłudze PRIORITY_DEFAULT lub PRIORITY_OVERLAY, co nie jest dostępne na podobnych urządzeniach z AndroidemX OnBackPressedCallback. W niektórych przypadkach przydatne może być zarejestrowanie wywołania zwrotnego za pomocą funkcji PRIORITY_OVERLAY.

Dotyczy to sytuacji, gdy migrujesz z onKeyPreIme() i Twoje wywołanie zwrotne musi otrzymać gest wstecz zamiast otwartego IME. Gdy IME zostanie otwarte, rejestruje wywołania zwrotne z PRIORITY_DEFAULT. Zarejestruj wywołanie zwrotne w komponencie PRIORITY_OVERLAY, aby mieć pewność, że OnBackInvokedDispatcher przekaże gest wstecz do wywołania zwrotnego zamiast do otwartego IME.

Wyraź zgodę na gest przewidywanego przejścia wstecz

Gdy określisz, jak zaktualizować aplikację na podstawie swojego przypadku, włącz obsługę przewidującego gestu wstecz.

Aby to zrobić, w tagu AndroidManifest.xml ustaw flagę android:enableOnBackInvokedCallback na true.<application>

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

Jeśli nie podasz wartości, zostanie użyta domyślna wartość false, a w ramach tej wartości:

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

Akceptacja na poziomie aktywności

Od Androida 14 flaga android:enableOnBackInvokedCallback umożliwia włączenie animacji systemowych przewidujących na poziomie aktywności. Takie działanie ułatwia migrację dużych aplikacji o wieloma aktywnościami do funkcji przewidywania gestów cofania. W Androidzie 15 przewidywane cofnięcie nie jest już opcją dla deweloperów. Aplikacje mogą korzystać z przewidywania wstecznego w pełni lub na poziomie aktywności.

Ten kod pokazuje przykład użycia zmiennej enableOnBackInvokedCallback do włączenia animacji systemu powrotu na stronę główną z obiektu MainActivity:

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

        <activity
            android:name=".MainActivity"
            android:enableOnBackInvokedCallback="true"
            ...
        </activity>
        <activity
            android:name=".SecondActivity"
            android:enableOnBackInvokedCallback="false"
            ...
        </activity>
    </application>
</manifest>

W poprzednim przykładzie ustawienie android:enableOnBackInvokedCallback=true dla ".SecondActivity" powoduje włączenie animacji systemowej obejmującej wiele aktywności.

Podczas korzystania z flagi android:enableOnBackInvokedCallback należy wziąć pod uwagę te kwestie:

  • Ustawienie android:enableOnBackInvokedCallback=false wyłącza przewidywane animacje wsteczne na poziomie aktywności lub aplikacji (w zależności od tego, gdzie ustawisz tag), a także zleci systemowi zignorowanie wywołań interfejsu API platformy OnBackInvokedCallback. Wywołania interfejsu OnBackPressedCallback są jednak nadal wykonywane, ponieważ interfejs OnBackPressedCallback jest zgodny ze starszymi wersjami i wywołuje interfejs API onBackPressed, który nie jest obsługiwany w wersjach Androida starszych niż 13.
  • Ustawienie flagi enableOnBackInvokedCallback na poziomie aplikacji powoduje ustawienie domyślnej wartości dla wszystkich działań w aplikacji. Możesz zmienić domyślną wartość dla poszczególnych działań, 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 systemu: BackHandler (dla funkcji tworzenia wiadomości), OnBackPressedCallback lub OnBackInvokedCallback.

Określ stan UI, który włącza i wyłącza każde wywołanie zwrotne

Stan interfejsu użytkownika to właściwość opisująca interfejs użytkownika. Zalecamy wykonanie tych ogólnych czynności.

  1. Określ stan interfejsu, w którym każde wywołanie zwrotne zostanie włączone lub wyłączone.

  2. Zdefiniuj ten stan, używając typu obserwowalnego właściciela danych, np. StateFlow lub stan tworzenia, i włącz lub wyłącz wywołanie zwrotne w miarę zmiany stanu.

Jeśli Twoja aplikacja wcześniej powiązała logikę cofnięcia z oświadczeniami warunkowymi, może to oznaczać, że reagujesz na zdarzenie cofnięcia po tym, jak już ono nastąpiło. Unikaj tego w przypadku nowych wywołań zwrotnych. Jeśli to możliwe, przenieś funkcję z poziomu instrukcji warunkowej na zewnątrz i zamiast tego powiązać ją z obserwowalnym typem uchwytu danych.

Używaj systemowych wywołań zwrotnych w UI Logic

Logika interfejsu określa, jak wyświetlić UI. Używaj wywołań zwrotnych systemu do wykonywania logiki interfejsu, np. wyświetlania wyskakującego okienka lub animacji.

Jeśli Twoja aplikacja umożliwia wywołanie systemu wstecz, animacje przewidujące nie są uruchamiane i musisz obsłużyć zdarzenie wstecz. Nie twórz wywołań zwrotnych tylko do uruchamiania logiki niezwiązanej z interfejsem.

Jeśli na przykład przechwytujesz zdarzenia back tylko po to, aby je rejestrować, zamiast tego rejestruj je w cyklu życia Activity lub Fragment.

  • W przypadku przypadków aktywności do aktywności lub fragmentu do aktywności odnotuj, czy isFinishing w onDestroy jest true w cyklu życia aktywności.
  • W przypadku fragmentacji jako fragmentu loguj, jeśli isRemoving w obrębie onDestroy ma wartość prawda w cyklu życia widoku fragmentu. Możesz też zalogować się w usłudze FragmentManager.OnBackStackChangedListener za pomocą metod onBackStackChangeStarted lub onBackStackChangeCommitted.

W przypadku polecenia Compose zaloguj się w wywołaniu zwrotnym onCleared() elementu ViewModel powiązanego z miejscem docelowym Compose. To najlepszy sygnał o tym, że miejsce docelowe w komponowaniu zostało usunięte ze stosu i zniszczone.

Tworzenie wywołań o jednym zadaniu

Możesz dodać wiele wywołań zwrotnych do dyspozytora. Wywołania zwrotne są dodawane do stosu, w którym ostatnio dodane włączone wywołanie zwrotne obsługuje następny gest cofania z jednym wywołaniem dla każdego gestu.

Łatwiej jest zarządzać stanem włączenia wywołania zwrotnego, jeśli ma ono tylko jedną odpowiedzialność. Na przykład:

kolejność wywołań zwrotnych w stosie.
Rysunek 2. Diagram stosu wywołania zwrotnego.

Na rysunku 2 widać, jak można mieć w grupie wiele wywołań zwrotnych, z których każde odpowiada za coś innego. Funkcja wywołania zwrotnego jest wykonywana tylko wtedy, gdy funkcje wywołania zwrotnego znajdujące się nad nią w zbiorze są wyłączone. W tym przykładzie wywołanie zwrotne „Czy na pewno...” jest włączone, gdy użytkownik wpisuje dane w formularzu. W przeciwnym razie jest wyłączone. Wywołanie zwrotne otwiera okno potwierdzenia, gdy użytkownik przesunie palcem wstecz, aby zamknąć formularz.

Inny wywołanie zwrotne może zawierać komponent Material, który obsługuje przewidywanie powrotów, przejście AndroidX za pomocą interfejsów API Progress lub inne niestandardowe wywołanie zwrotne.

childFragmentManager wywoływana jest, jeśli powyższe wywołania są wyłączone, a stół zagnieżdżony tego FragmentManager nie jest pusty. childFragmentManager jest dołączony do Fragmentu. W tym przykładzie wywołanie zwrotne wewnętrzne jest wyłączone.

Podobnie wywołanie wewnętrzne supportFragmentManager jest wykonywane, jeśli powyższe wywołania są wyłączone, a stos nie jest pusty. Takie zachowanie występuje, gdy do nawigacji używasz FragmentManager lub NavigationComponent, ponieważ NavigationComponent opiera się na FragmentManager. W tym przykładzie ta funkcja wywołania zwrotnego jest wykonywana, jeśli użytkownik nie wpisał tekstu w formularzu, co spowodowało wyłączenie funkcji wywołania zwrotnego „Czy na pewno…?”.

Na koniec super.onBackPressed() to wywołanie na poziomie systemu, które jest ponownie wykonywane, jeśli powyższe wywołania są wyłączone. Aby aktywować animacje systemowe, takie jak powrót do strony głównej, aktywność międzynarodowa i przedział zadań, stos wsteczny supportFragmentManager musi być pusty, więc wewnętrzne wywołanie zwrotne jest wyłączone.

Testowanie animacji przewidywanego przejścia wstecz

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

Aby przetestować tę animację, wykonaj te czynności:

  1. Na urządzeniu wybierz 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.