Unterstützung für die vorausschauende „Zurück“-Touch-Geste hinzufügen

Android 14 (API-Level 34) unterstützt zusätzliche Systemanimationen und APIs benutzerdefinierte Animationen erstellen. Weitere Informationen finden Sie unter Unterstützung für integrierte und benutzerdefinierte zurückspulende Animationen

Mit einer „Zurück“-Touch-Geste können Sie z. B. eine animierte Vorschau Startbildschirm hinter Ihrer App, wie in dem Modell in Abbildung 1 dargestellt. Ab Android 13 können Sie Diese Back-to-Home-Animation testen, indem Sie eine Entwickleroption aktivieren wie auf dieser Seite beschrieben.

Um die Touch-Geste „Zurücksagen“ zu unterstützen, musst du deine App aktualisieren. Verwende dazu die abwärtskompatibel OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) oder höher oder die neue OnBackInvokedCallback-Version verwenden Plattform-API. Die meisten Apps verwenden die abwärtskompatible AndroidX API.

Dieses Update bietet einen Migrationspfad, um die Rückwärtsnavigation ordnungsgemäß abzufangen. das Ersatz von Back-Interceptions von KeyEvent.KEYCODE_BACK und alle Klassen mit onBackPressed-Methoden wie Activity und Dialog mit den neuen System Back APIs.

Video zu Codelab und Google I/O

Sie können nicht nur die Dokumentation auf dieser Seite verwenden, sondern auch unser Codelab ausprobieren. Es bietet eine gängige Implementierung einer WebView, die den „Zurück“-Touch-Geste mit AndroidX Activity APIs.

Sie können sich auch unser Google I/O-Video ansehen, in dem Sie weitere Beispiele Implementierung von AndroidX und Platform APIs.

App aktualisieren, die die Standardnavigation zurück verwendet

Es ist ganz einfach, die App zur Unterstützung dieser Funktion zu aktualisieren, wenn dies nicht der Fall ist. benutzerdefiniertes Backverhalten implementieren (d. h., die Back- an das System). Aktivieren Sie diese Funktion wie hier beschrieben. .

Wenn Ihre App Fragmente oder die Navigationskomponente verwendet, führen Sie auch ein Upgrade auf AndroidX Activity 1.6.0-alpha05 oder höher.

App aktualisieren, die benutzerdefinierte Rückwärtsnavigation verwendet

Wenn Ihre Anwendung ein benutzerdefiniertes Back-Verhalten implementiert, gibt es verschiedene Migrationspfade abhängig davon, ob AndroidX verwendet wird und wie die Rückwärtsnavigation gehandhabt wird.

AndroidX-Implementierung für die Rückwärtsnavigation migrieren

Dies ist der häufigste (und der am häufigsten empfohlene) Anwendungsfall. Sie gilt für neue oder vorhandene Apps, die eine benutzerdefinierte Navigation per Geste mit OnBackPressedDispatcher implementieren, wie unter Benutzerdefinierte Rückwärtsnavigation ermöglichen beschrieben.

Wenn deine App in diese Kategorie fällt, führe die folgenden Schritte aus, um Unterstützung für die automatische Touch-Geste „Zurück“:

1. Damit APIs, die bereits OnBackPressedDispatcher APIs verwenden (z. B. Fragmente und die Navigationskomponente), nahtlos mit der vorausschauenden Rückwärtsgeste funktionieren, aktualisieren Sie auf 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. Die automatische Vervollständigung für „Zurück“ aktivieren, wie unter auf dieser Seite.

AndroidX-App mit nicht unterstützten APIs für die Rückwärtsnavigation zu AndroidX-APIs migrieren

Wenn Ihre App AndroidX-Bibliotheken verwendet, aber die API implementiert oder auf sie verweist nicht unterstützte Back-Navigations-APIs verwenden, müssen Sie zu AndroidX-APIs migrieren. um das neue Verhalten zu unterstützen.

So migrieren Sie nicht unterstützte APIs zu AndroidX APIs:

1. Migrieren Sie die Back-Handling-Logik Ihres Systems zur OnBackPressedDispatcher mit einer Implementierung von OnBackPressedCallback Eine ausführliche Anleitung finden Sie unter Benutzerdefinierte Rückwärtsnavigation anbieten:

2. Deaktiviere die OnBackPressedCallback, wenn du bereit bist, das Abfangen des Back-Ends zu beenden Touch-Geste.

3. Stoppen Sie das Abfangen von Ereignissen über OnBackPressed oder KeyEvent.KEYCODE_BACK.

4. Führen Sie ein Upgrade auf 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. Wenn Sie Ihre Anwendung erfolgreich migriert haben, der automatischen Vervollständigung der Touch-Geste „Zurück“ aktivieren (siehe Beschreibung auf auf dieser Seite), um die Back-to-Home-Systemanimation zu sehen.

App, die nicht unterstützte APIs zur Rücknavigation verwendet, zu Plattform-APIs migrieren

Wenn Ihre App keine AndroidX-Bibliotheken verwenden kann und stattdessen Verweis auf die benutzerdefinierte Zurück-Navigation mit den nicht unterstützten APIs, müssen Sie mit der OnBackInvokedCallback-Plattform-API.

Führen Sie die folgenden Schritte aus, um nicht unterstützte APIs zur Plattform-API zu migrieren:

1. Die neue OnBackInvokedCallback API auf Geräten mit Android 13 oder und die nicht unterstützten APIs auf Geräten mit Android 12 oder darunter.

2. Registrieren Sie Ihre benutzerdefinierte Back-Logik in OnBackInvokedCallback mit onBackInvokedDispatcher. Dadurch wird verhindert, dass die aktuelle Aktivität und Ihr Callback kann einmal auf die Aktion „Zurück“ reagieren. Die Nutzenden schließen die Zurück-Navigation des Systems ab.

3. Registrierung von OnBackInvokedCallback aufheben, wenn Sie bereit sind, das Abfangen des „Zurück“-Touch-Geste. Andernfalls bemerken Nutzer möglicherweise ein unerwünschtes Verhalten, wenn sie eine System „Zurück“-Navigation, z. B. „nicht weiterkommen“ zwischen Aufrufen und z. B. das Beenden der App zu erzwingen.

   Hier ein Beispiel für die Migration der Logik aus 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. Abfangen von Ereignissen über OnBackPressed oder KeyEvent.KEYCODE_BACK beenden für Android 13 und höher.

5. Nachdem Sie Ihre App migriert haben, aktivieren Sie die vorausschauende Wischgeste zum Zurück (wie auf dieser Seite beschrieben), damit OnBackInvokedCallback wirksam wird.

Du kannst eine OnBackInvokedCallback bei PRIORITY_DEFAULT registrieren oder PRIORITY_OVERLAY, das in der ähnlichen Version von AndroidX nicht verfügbar ist OnBackPressedCallback. Die Registrierung eines Callbacks bei PRIORITY_OVERLAY ist in manchen Fällen hilfreich. Dies kann beispielsweise der Fall sein, wenn Sie von onKeyPreIme() migrieren und Ihr Rückruf die Zurück-Geste statt einer geöffneten IME erhalten soll. IMEs registrieren Callbacks beim Öffnen mit PRIORITY_DEFAULT. Registrieren Sie Ihren Callback bei PRIORITY_OVERLAY, um sicherzustellen, OnBackInvokedDispatcher leitet stattdessen die „Zurück“-Geste an deinen Callback weiter des geöffneten IMEs.

„Zurück“-Touch-Geste aktivieren

Sobald Sie sich für ein Update entschieden haben, die die voraussagende „Zurück“-Touch-Geste unterstützen.

Für die Aktivierung legen Sie in AndroidManifest.xml im <application>-Tag den Wert android:enableOnBackInvokedCallback in true.

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

Wenn Sie keinen Wert angeben, wird standardmäßig false verwendet. Dabei geschieht Folgendes:

• Deaktiviert die Systemanimation für die intelligente „Zurück“-Touch-Geste.
• OnBackInvokedCallback wird ignoriert, aber OnBackPressedCallback Aufrufe weiterzuarbeiten.

Auf Aktivitätsebene aktivieren

Ab Android 14 können Sie mit dem Flag android:enableOnBackInvokedCallback vorausschauende Systemanimationen auf Aktivitätsebene aktivieren. Dieses Verhalten macht es einfacher, große Apps mit mehreren Aktivitäten zu „Zurück“-Touch-Gesten.

Der folgende Code zeigt ein Beispiel für die Verwendung von enableOnBackInvokedCallback zum Aktivieren Sie die Back-to-Home-Systemanimation von MainActivity:

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

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

Im vorherigen Beispiel wird android:enableOnBackInvokedCallback=true für ".SecondActivity" aktiviert die aktivitätsübergreifende Systemanimation.

Beachten Sie bei der Verwendung des android:enableOnBackInvokedCallback-Flag:

• Wenn Sie android:enableOnBackInvokedCallback=false festlegen, werden vorausschauende Rückwärtsanimationen entweder auf Aktivitäts- oder auf App-Ebene deaktiviert, je nachdem, wo Sie das Tag einfügen. Außerdem wird das System angewiesen, Aufrufe der OnBackInvokedCallback-Plattform-API zu ignorieren. OnBackPressedCallback-Aufrufe werden jedoch weiterhin ausgeführt, OnBackPressedCallback ist abwärtskompatibel und ruft onBackPressed auf API, die vor Android 13 nicht mehr unterstützt wird.
• Wenn Sie das Flag enableOnBackInvokedCallback auf App-Ebene festlegen, wird der Standardwert für alle Aktivitäten in der App festgelegt. Sie können den Standardwert pro Aktivität überschreiben, indem Sie das Flag auf Aktivitätsebene festlegen, wie im vorherigen Codebeispiel gezeigt.

Best Practices für Rückrufe

Im Folgenden finden Sie Best Practices für die Verwendung der unterstützten System-Rückrufe: BackHandler (zum Schreiben), OnBackPressedCallback oder OnBackInvokedCallback

Bestimmen Sie den UI-Status, der jeden Callback aktiviert und deaktiviert

Status der Benutzeroberfläche ist eine Eigenschaft, die die Benutzeroberfläche beschreibt. Wir empfehlen, diese allgemeinen Schritte.

1. Bestimmen Sie den UI-Status, mit dem die einzelnen Callbacks aktiviert und deaktiviert werden.

2. Definieren Sie diesen Status mithilfe eines Inhabers von beobachtbaren Daten Typ wie StateFlow oder Zusammensetzung des Status und Aktivieren oder Deaktivieren des Callbacks, wenn sich der Status ändert.

Wenn Ihre App zuvor Rücklogik mit bedingten Anweisungen verknüpft hat, Das könnte bedeuten, dass Sie auf das Ereignis vom Typ „Zurück“ reagieren, bereits aufgetreten – ein Muster, das Sie bei neueren Callbacks vermeiden sollten. Verschieben Sie den Rückruf nach Möglichkeit außerhalb der bedingten Anweisung und ordnen Sie ihn stattdessen einem beobachtbaren Dateninhabertyp zu.

System-Back-Callbacks für UI Logic verwenden

UI-Logik schreibt, wie die Benutzeroberfläche angezeigt wird. Verwenden Sie System-Back-Callbacks, um UI-Logik auszuführen, z. B. Pop-up einblenden oder eine Animation ausführen.

Wenn deine App einen System-Back-Callback aktiviert, werden die Vorhersageanimationen nicht ausgeführt und Sie müssen das Back-Ereignis verarbeiten. Keine Callbacks erstellen, die nur auf der Benutzeroberfläche basieren Logik.

Wenn Sie beispielsweise Ereignisse nur zur Protokollierung abfangen, protokollieren Sie sie im Stattdessen gibt es die Aktivität oder den Fragmentlebenszyklus.

• Bei Aktivitäts-zu-Aktivitäts- oder Fragment-zu-Aktivitäts-Fällen protokollieren Sie, ob isFinishing in onDestroy true im Aktivitätslebenszyklus ist.
• Bei Fällen von Fragmenten zu Fragmenten wird protokolliert, wenn isRemoving in onDestroy gleich true innerhalb des Ansichtslebenszyklus des Fragments; oder Protokoll mit onBackStackChangeStarted- oder onBackStackChangeCommitted-Methoden innerhalb FragmentManager.OnBackStackChangedListener

Für den Fall „Compose“ (Erstellen) loggen Sie sich im onCleared()-Callback einer ViewModel ein, die mit dem Ziel „Compose“ verknüpft ist. Dies ist das beste Signal, um zu wissen, Ein Erstellungsziel wird vom Back-Stack getrennt und zerstört.

Callbacks für einzelne Verantwortung erstellen

Dies ist möglich, weil Sie dem Disponenten mehrere Rückrufe hinzufügen können. Die Callbacks werden einem Stapel hinzugefügt, in dem der zuletzt hinzugefügte aktivierte Callback enthalten ist. verarbeitet die nächste Zurück-Geste mit einem Callback pro Zurück-Touch-Geste.

Animation für die intelligente „Zurück“-Touch-Geste testen

Ab der endgültigen Version von Android 13 sollten Sie in der Lage sein, eine Entwickleroption zum Testen der in Abbildung 1 gezeigten Back-to-Home-Animation.

So testen Sie diese Animation:

1. Rufen Sie auf Ihrem Gerät Einstellungen > System > Entwickleroptionen.

2. Wählen Sie Hintergrundanimationen vorausschauend aus.

3. Starte die aktualisierte App und verwende die Touch-Geste „Zurück“, um sie in Aktion zu sehen.