Dodano obsługę gestu przewidywanego przejścia wstecz

Rysunek 1. Przykład wyglądu i działania gestu przewidywania cofania się na telefonie

Android 14 (poziom interfejsu API 34) dodaje obsługę dodatkowych animacji systemowych i interfejsów API umożliwiających tworzenie niestandardowych animacji. Więcej informacji znajdziesz w artykule o dodawaniu obsługi wbudowanych i niestandardowych animacji przewidywanego przejścia wstecz.

Na przykład za pomocą gestu cofania można wyświetlić animowany podgląd ekranu głównego aplikacji, tak jak na schemacie 1. Począwszy od Androida 13 możesz przetestować tę animację powrotu do strony głównej, włączając opcję dla programistów (zgodnie z opisem na tej stronie).

Obsługa gestu przewidywanego przejścia wstecz wymaga zaktualizowania aplikacji za pomocą zgodnego wstecznie interfejsu API OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) lub nowszego bądź nowego interfejsu API platformy OnBackInvokedCallback. Większość aplikacji będzie używać zgodnego wstecznie interfejsu API AndroidX.

Ta aktualizacja udostępnia ścieżkę migracji do prawidłowego przechwycenia nawigacji wstecznej, która obejmuje zastąpienie przechwyconych punktów z KeyEvent.KEYCODE_BACK oraz klas z metodami onBackPressed, takimi jak Activity i Dialog, nowymi systemowymi interfejsami API Back (Wstecz).

Ćwiczenia z programowania i film na Google I/O

Oprócz zapoznania się z dokumentacją przedstawioną na tej stronie skorzystaj z naszych ćwiczeń z programowania. Zawiera on typową implementację komponentu WebView do obsługi przewidywanego gestu wstecznego za pomocą interfejsów AndroidX Activity API.

Możesz też obejrzeć film o Google I/O, który zawiera dodatkowe przykłady implementacji interfejsów API AndroidX i platform.

Aktualizowanie aplikacji, która używa domyślnej nawigacji wstecz

Zaktualizowanie aplikacji w celu obsługi tej funkcji jest proste, jeśli nie jest w niej zaimplementowana żadne niestandardowe zachowanie wsteczne (czyli system nie odpowiada za jej obsługę). Włącz tę funkcję zgodnie z opisem w tym przewodniku.

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

Aktualizowanie aplikacji, która używa niestandardowego przechodzenia wstecz

Jeśli Twoja aplikacja ma niestandardowe zachowanie wsteczne, dostępne są różne ścieżki migracji w zależności od tego, czy używa ona AndroidaX i jak obsługuje nawigację wsteczną.

Aplikacja używa AndroidaX Jak aplikacja obsługuje nawigację wsteczną Zalecana ścieżka migracji (link na tej stronie)
Tak Interfejsy API AndroidX Migracja dotychczasowej implementacji AndroidX
Nieobsługiwane interfejsy API platformy Migracja aplikacji AndroidX zawierającej nieobsługiwane interfejsy API nawigacji wstecznej do interfejsów API AndroidX
Nie Nieobsługiwane interfejsy API platformy, możliwość migracji Migracja aplikacji, która używa nieobsługiwanych interfejsów API nawigacji wstecz do interfejsów API platformy
Nieobsługiwane interfejsy API platformy, ale nie można przeprowadzić migracji Odrocz zgodę, aż stanie się ona wymagana.

Migracja implementacji poprzedniej nawigacji na AndroidzieX

Ten przypadek użycia jest najczęstszy (i najbardziej zalecany). Dotyczy to nowych lub istniejących aplikacji, które implementują niestandardową nawigację przy użyciu gestów w OnBackPressedDispatcher, zgodnie z opisem w sekcji Zapewnianie niestandardowego przechodzenia wstecz.

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

  1. Aby interfejsy API, które korzystają już z interfejsów API OnBackPressedDispatcher (np. fragmenty lub komponent nawigacji), płynnie współdziałają z funkcją przewidywania powrotu, przejdź na 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"

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

Przeprowadź migrację aplikacji AndroidX zawierającej nieobsługiwane interfejsy API nawigacji wstecz do interfejsów API AndroidX

Jeśli Twoja aplikacja korzysta z bibliotek AndroidX, ale implementuje nieobsługiwane interfejsy API nawigacji wstecznej lub wspomina do nich, musisz przejść na interfejsy AndroidX API, aby obsługiwać nowe zachowanie.

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

  1. Przenieś logikę obsługi wstecznej systemu do OnBackPressedDispatcher systemu AndroidX, implementując OnBackPressedCallback. Szczegółowe wskazówki znajdziesz w artykule o dostosowywaniu niestandardowej nawigacji wstecz.

  2. Wyłącz OnBackPressedCallback, gdy chcesz przestać przechwytywać gesty wstecz.

  3. Zatrzymaj przechwytywanie zdarzeń wstecz przez OnBackPressed lub KeyEvent.KEYCODE_BACK.

  4. Pamiętaj, aby zaktualizować 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 przeniesieniu aplikacji wyraź zgodę na gest przewidywanego przejścia wstecz (jak opisano na tej stronie), aby zobaczyć animację systemu powrotu do ekranu głównego.

Przeprowadź migrację aplikacji, która używa nieobsługiwanych interfejsów API nawigacji wstecz do interfejsów API platformy

Jeśli Twoja aplikacja nie może używać bibliotek AndroidX i implementuje niestandardową nawigację wsteczną lub się do niej odnosi za pomocą nieobsługiwanych interfejsów API, musisz przejść na interfejs API platformy OnBackInvokedCallback.

Aby przenieść nieobsługiwane interfejsy API do interfejsu API platformy:

  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ę wsteczną w OnBackInvokedCallback w onBackInvokedDispatcher. Zapobiega to zakończeniu bieżącej aktywności, a wywołanie zwrotne umożliwia zareagowanie na działanie wsteczne, gdy użytkownik zakończy w systemie nawigację wstecz.

  3. Wyrejestruj OnBackInvokedCallback, gdy chcesz przestać przechwytywać gest wstecz. W przeciwnym razie użytkownicy korzystający z systemowego nawigacji wstecz mogą czuć niepożądane zachowanie, np. „utknięcie” między widokami i wymuszanie zamknięcia aplikacji.

    Oto przykład przenoszenia logiki z 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. Zatrzymaj przechwytywanie zdarzeń wstecz przez OnBackPressed lub KeyEvent.KEYCODE_BACK na Androidzie 13 i nowszych.

  5. Po przeniesieniu aplikacji wyraź zgodę na gest przewidywanego przejścia wstecz (jak opisano na tej stronie), aby funkcja OnBackInvokedCallback zaczęła działać.

Możesz zarejestrować urządzenie OnBackInvokedCallback w usłudze PRIORITY_DEFAULT lub PRIORITY_OVERLAY, które nie są dostępne w podobnym AndroidzieX OnBackPressedCallback. W niektórych przypadkach przydatne może być zarejestrowanie wywołania zwrotnego w usłudze PRIORITY_OVERLAY. Może się tak zdarzyć w przypadku migracji z onKeyPreIme(), a wywołanie zwrotne musi otrzymać gest wstecz, a nie otwarty edytor IME. Po otwarciu narzędzia IME rejestrują wywołania zwrotne w usłudze PRIORITY_DEFAULT. Zarejestruj wywołanie zwrotne w usłudze PRIORITY_OVERLAY, aby mieć pewność, że OnBackInvokedDispatcher wyśle gest cofania do Twojego wywołania zwrotnego, a nie do otwartego IME.

Wyrażaj zgodę na gest przewidywanego przejścia wstecz

Gdy już zdecydujesz, jak zaktualizować aplikację na podstawie swojego przypadku, włącz obsługę gestu przewidywania wstecznego.

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

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

Jeśli nie podasz wartości, zostanie użyta domyślna wartość false i w ten sposób:

  • Wyłącza animację systemową przewidywania gestów wstecznych.
  • Ignoruje polecenie OnBackInvokedCallback, ale połączenia typu OnBackPressedCallback nadal działają.

Zgłaszanie się na poziomie aktywności

Od Androida 14 flaga android:enableOnBackInvokedCallback umożliwia włączanie prognozowanych animacji systemowych na poziomie aktywności. Ułatwia to migrację dużych aplikacji wieloaktywności na gesty przewidywania.

Poniższy kod pokazuje przykład użycia metody enableOnBackInvokedCallback w celu włączenia animacji powrotu do domu z poziomu interfejsu 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 elementu ".SecondActivity" włącza animację systemową obejmującą różne działania.

Gdy używasz flagi android:enableOnBackInvokedCallback, pamiętaj o tych kwestiach:

  • Ustawienie android:enableOnBackInvokedCallback=false wyłącza animacje prognozowane wstecz na poziomie aktywności lub aplikacji, w zależności od tego, gdzie został ustawiony tag, oraz instruuje system, aby ignorował wywołania interfejsu API platformy OnBackInvokedCallback. Wywołania OnBackPressedCallback będą jednak nadal wykonywane, ponieważ interfejs OnBackPressedCallback jest zgodny wstecznie i wywołuje interfejs API onBackPressed, który nie jest obsługiwany w wersji Androida 13.
  • Ustawienie flagi enableOnBackInvokedCallback na poziomie aplikacji określa domyślną wartość dla wszystkich działań w aplikacji. Możesz zastąpić wartość domyślną dla każdego działania, 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 systemowych wywołań zwrotnych: BackHandler (do tworzenia wiadomości), OnBackPressedCallback lub OnBackInvokedCallback.

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

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 użytkownika, w którym każde wywołanie zwrotne jest włączone lub wyłączone.

  2. Określ ten stan za pomocą obserwowalnego typu posiadacza danych, np. StateFlow lub stan tworzenia, a potem włącz lub wyłącz wywołanie zwrotne w miarę zmiany stanu.

Jeśli aplikacja kojarzyła wcześniej logikę wsteczną z wyrażeniami warunkowymi, może to oznaczać, że reagujesz na zdarzenie wsteczne już po jego wystąpieniu. Tego wzorca należy unikać przy nowszych wywołaniach zwrotnych. Jeśli to możliwe, przenieś wywołanie zwrotne poza instrukcję warunkową i zamiast tego powiąż wywołanie zwrotne z obserwowalnym typem właściciela danych.

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

Logika interfejsu określa, jak będzie się on wyświetlać. Używaj systemowych wywołań zwrotnych do uruchamiania logiki interfejsu, np. do wyświetlania wyskakującego okienka lub uruchamiania animacji.

Jeśli Twoja aplikacja umożliwia systemowe wywołanie zwrotne, animacje prognozujące nie są uruchamiane i musisz obsługiwać zdarzenie wsteczne. Nie twórz wywołań zwrotnych tylko w celu uruchomienia logiki poza interfejsem.

Jeśli na przykład przechwytujesz zdarzenia wsteczne tylko do logowania, loguj się w ramach cyklu życia aktywności lub fragmentu kodu.

  • W przypadku przypadków stosunek aktywności do aktywności lub fragmentów względem aktywności loguj, jeśli w cyklu życia aktywności isFinishing w onDestroy ma wartość true.
  • W przypadku przypadków z fragmentami na fragmenty loguj, jeśli isRemoving w onDestroy ma wartość prawda w cyklu życia widoku fragmentu lub loguj za pomocą metod onBackStackChangeStarted lub onBackStackChangeCommitted w FragmentManager.OnBackStackChangedListener.

W przypadku tworzenia zgłoszenia zaloguj się w ramach wywołania zwrotnego onCleared() ViewModel powiązanego z miejscem docelowym tworzenia. To najlepszy sygnał, że miejsce docelowe tworzenia zostało usunięte ze stosu i zniszczone.

Tworzenie wywołań zwrotnych jednej odpowiedzi

Jest to możliwe, ponieważ możesz dodać do danego dyspozytora kilka 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 wsteczny z jednym wywołaniem zwrotnym na gest zwrotny.

Testowanie animacji gestu przewidywanego przejścia wstecz

Począwszy od ostatecznej wersji Androida 13 należy włączyć opcję programisty, aby przetestować animację powrotu do ekranu głównego widoczną na ilustracji 1.

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

  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.