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

**Abbildung 1.** Mockup der Vorhersage-Geste „Zurück“ auf einem Smartphone

Mit der intelligenten „Zurück“-Geste, einer Funktion für die Bedienung per Wischgesten, können Nutzer sehen, wohin sie durch das Wischen nach links gelangen.

Wenn Sie beispielsweise eine „Zurück“-Geste ausführen, kann eine animierte Vorschau des Startbildschirms hinter Ihrer App angezeigt werden, wie im Mockup in Abbildung 1 dargestellt.

Ab Android 15 ist die Entwickleroption für Vorhersage-Animationen für die Zurück-Geste nicht mehr verfügbar. Systemanimationen wie „Zurück zum Startbildschirm“, „Aufgabenübergreifend“ und „Aktivitätenübergreifend“ werden jetzt für Apps angezeigt, die das vorhersagende „Zurück“-Symbol entweder vollständig oder auf Aktivitätsebene aktiviert haben.

Sie können diese Animation zum Zurückkehren zum Startbildschirm testen, wie in einem späteren Abschnitt auf dieser Seite beschrieben.

Um die Vorhersage für die Zurück-Geste zu unterstützen, müssen Sie Ihre App aktualisieren und die abwärtskompatible OnBackPressedCallback AppCompat 1.6.0-alpha05-API (AndroidX) oder höher oder die neue OnBackInvokedCallback-Plattform-API verwenden. Die meisten Apps verwenden die abwärtskompatible AndroidX API.

Dieses Update bietet einen Migrationspfad, um die Rückwärtsnavigation richtig abzufangen. Dazu müssen die Rückwärtsnavigationen von KeyEvent.KEYCODE_BACK und alle Klassen mit onBackPressed-Methoden wie Activity und Dialog durch die neuen System-Back-APIs ersetzt werden.

Codelab und Google I/O-Video

Zusätzlich zu dieser Dokumentation können Sie auch unser Codelab ausprobieren. Sie bietet eine Implementierung eines gängigen Anwendungsfalls für eine WebView, die die vorhersagende Zurück-Geste mit AndroidX Activity APIs verarbeitet.

In unserem Google I/O-Video finden Sie weitere Beispiele für die Implementierung der AndroidX- und Plattform-APIs.

Benutzerdefinierte Zurück-Gesten in Compose verarbeiten

Compose bietet die PredictiveBackHandler-Composable-Funktion, um benutzerdefinierte Zurück-Gesten zu verarbeiten. Mit dieser API können Sie auf die Zurück-Geste reagieren. Sie stellt ein Flow von BackEventCompat-Objekten bereit, mit denen Sie benutzerdefinierte Animationen oder Übergänge implementieren können, während der Nutzer wischt.

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

Wenn Sie nur die Zurück-Geste abfangen möchten, ohne den Fortschritt zu verfolgen, verwenden Sie BackHandler.

Apps aktualisieren, die die Standard-Zurück-Navigation verwenden

Die Funktion „Vorhersagende Zurück-Geste“ ist standardmäßig aktiviert.

Wenn Ihre App Fragments oder die Navigation Component verwendet, aktualisieren Sie auch auf AndroidX Activity 1.6.0-alpha05 oder höher.

App aktualisieren, die benutzerdefinierte Zurück-Navigation verwendet

Wenn in Ihrer App ein benutzerdefiniertes Verhalten für die Zurück-Schaltfläche implementiert ist, gibt es je nachdem, ob sie AndroidX verwendet und wie sie die Zurück-Navigation verarbeitet, unterschiedliche Migrationspfade.

So geht Ihre App mit der Rückwärtsnavigation um	Empfohlener Migrationspfad (Link auf dieser Seite)
AndroidX-APIs	Bestehende AndroidX-Implementierung der „Zurück“-Geste migrieren
Nicht unterstützte Plattform-APIs	Eine AndroidX-App mit nicht unterstützten APIs für die Rückwärtsnavigation zu AndroidX-APIs migrieren

AndroidX-Implementierung der Rückwärtsnavigation migrieren

Dieser Anwendungsfall ist der häufigste (und der am meisten empfohlene). Sie gilt für neue oder vorhandene Apps, die die benutzerdefinierte Verarbeitung der Bedienung über Gesten mit OnBackPressedDispatcher implementieren, wie unter Benutzerdefinierte Zurück-Navigation bereitstellen beschrieben.

Damit APIs, die bereits OnBackPressedDispatcher verwenden (z. B. Fragmente und die Navigationskomponente), nahtlos mit der vorhersagenden Zurück-Geste funktionieren, müssen Sie auf AndroidX Activity 1.6.0-alpha05 aktualisieren.

```xml
// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```

Eine AndroidX-App mit nicht unterstützten APIs für die Zurück-Navigation zu AndroidX-APIs migrieren

Wenn Ihre App AndroidX-Bibliotheken verwendet, aber die nicht unterstützten APIs für die Rückwärtsnavigation implementiert oder darauf verweist, müssen Sie zu AndroidX-APIs migrieren, um das neue Verhalten zu unterstützen.

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

Migrieren Sie die Logik für die Verarbeitung der Zurück-Schaltfläche zu OnBackPressedDispatcher von AndroidX mit einer Implementierung von OnBackPressedCallback. Eine ausführliche Anleitung finden Sie unter Benutzerdefinierte Zurück-Navigation bereitstellen.
Deaktivieren Sie OnBackPressedCallback, wenn Sie die Abfangung der Zurück-Geste beenden möchten.
Das Abfangen von Zurück-Ereignissen über OnBackPressed oder KeyEvent.KEYCODE_BACK wird beendet.
Führen Sie ein Upgrade auf AndroidX Activity 1.6.0-alpha05 durch.
```
// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```
Hinweis: OnBackPressedCallback wird immer aufgerufen, unabhängig vom Wert von android:enableOnBackInvokedCallback. Das Deaktivieren der Systemanimation hat also keine Auswirkungen auf die Logik für die Rückwärtsnavigation Ihrer App, wenn sie OnBackPressedCallback verwendet.

Intelligente „Zurück“-Geste deaktivieren

Wenn Sie die Funktion deaktivieren möchten, setzen Sie in AndroidManifest.xml im Tag <application> das Flag android:enableOnBackInvokedCallback auf false.

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

Wenn Sie diesen Wert auf „false“ setzen, passiert Folgendes:

Deaktiviert die Systemanimation für die intelligente „Zurück“-Touchgeste.
Ignoriert OnBackInvokedCallback, aber OnBackPressedCallback-Anrufe funktionieren weiterhin.

Anzeigenvorschläge auf Aktivitätsebene deaktivieren

Mit dem Flag android:enableOnBackInvokedCallback können Sie intelligente Systemanimationen auf Aktivitätsebene deaktivieren. So ist es einfacher, große Apps mit mehreren Aktivitäten zu migrieren, die die Vorhersage von Zurück-Gesten nutzen.

Der folgende Code zeigt ein Beispiel für enableOnBackInvokedCallback, das so festgelegt ist, dass die Systemanimation „Zurück zum Startbildschirm“ über MainActivity aktiviert wird:

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

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

Beachten Sie bei der Verwendung des Flags android:enableOnBackInvokedCallback Folgendes:

Wenn Sie android:enableOnBackInvokedCallback=false festlegen, werden die vorhersagenden Rückwärtsanimationen entweder auf Aktivitäts- oder auf App-Ebene deaktiviert, je nachdem, wo Sie das Tag festlegen. Das System wird dann angewiesen, Aufrufe der Plattform-API OnBackInvokedCallback zu ignorieren. Aufrufe von OnBackPressedCallback werden jedoch weiterhin ausgeführt, da OnBackPressedCallback abwärtskompatibel ist und die onBackPressed API aufruft, die vor Android 13 nicht 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

Hier finden Sie Best Practices für die Verwendung der unterstützten System-Back-Callbacks: PredictiveBackHandler oder BackHandler (für Compose), OnBackPressedCallback oder OnBackInvokedCallback.

UI-Status ermitteln, mit dem die einzelnen Rückrufe aktiviert und deaktiviert werden

Der UI-Status ist eine Property, die die Benutzeroberfläche beschreibt. Wir empfehlen, diese allgemeinen Schritte auszuführen.

Bestimmen Sie den UI-Status, der die einzelnen Callbacks aktiviert und deaktiviert.
Definieren Sie diesen Status mit einem beobachtbaren Daten-Holder-Typ wie StateFlow oder Compose State und aktivieren oder deaktivieren Sie den Callback, wenn sich der Status ändert.

Wenn in Ihrer App zuvor eine Back-Logik mit bedingten Anweisungen verknüpft war, reagieren Sie möglicherweise auf das Back-Ereignis, nachdem es bereits eingetreten ist. Bei neueren Callbacks sollten Sie dieses Muster vermeiden. Verschieben Sie den Callback nach Möglichkeit aus der bedingten Anweisung heraus und verknüpfen Sie ihn stattdessen mit einem beobachtbaren Datenhaltertyp.

System-Back-Callbacks für die UI-Logik verwenden

Die UI-Logik bestimmt, wie die Benutzeroberfläche angezeigt wird. Verwenden Sie System-Back-Callbacks, um UI-Logik auszuführen, z. B. um ein Dialogfeld anzuzeigen oder eine Animation auszuführen.

Wenn Ihre App ein OnBackPressedCallback oder ein OnBackInvokedCallback mit PRIORITY_DEFAULT oder PRIORITY_OVERLAY ermöglicht, werden die Vorhersage-Animationen für die Zurück-Geste nicht ausgeführt und Sie müssen das Zurück-Ereignis verarbeiten. Erstellen Sie diese Callbacks nicht, um Geschäftslogik auszuführen oder zu protokollieren.

Verwenden Sie die folgenden Ansätze, wenn in Ihrer App Geschäftslogik ausgeführt oder protokolliert werden muss, wenn der Nutzer zurückwischt:

Verwenden Sie OnBackInvokedCallback mit PRIORITY_SYSTEM_NAVIGATION_OBSERVER auf Geräten mit Android 16 und höher. Dadurch wird ein Observer-Callback erstellt, der das Zurück-Ereignis nicht verarbeitet. Sie können diesen Callback beispielsweise registrieren, wenn der Nutzer von der Stammaktivität zurückwischt, also wenn er Ihre App verlässt. In diesem Fall können Sie das Zurück-Ereignis protokollieren oder andere Geschäftslogik ausführen. Die Animation „Zurück zum Startbildschirm“ wird trotzdem abgespielt.
Bei Fällen vom Typ „Aktivität zu Aktivität“ oder „Fragment zu Aktivität“ protokollieren Sie, ob isFinishing innerhalb von onDestroy true innerhalb des Aktivitätslebenszyklus ist.
Bei Fragment-zu-Fragment-Fällen protokollieren Sie, ob isRemoving innerhalb von onDestroy im Ansichtslebenszyklus des Fragments „true“ ist. Oder Sie protokollieren mit den Methoden onBackStackChangeStarted oder onBackStackChangeCommitted innerhalb von FragmentManager.OnBackStackChangedListener.
Bei Compose-Vorgängen sollten Sie innerhalb des onCleared()-Callbacks eines ViewModel protokollieren, das mit dem Compose-Ziel verknüpft ist. Dies ist das beste Signal dafür, wann ein Compose-Ziel aus dem Backstack entfernt und zerstört wird.

Callbacks mit nur einer Aufgabe erstellen

Sie können dem Dispatcher mehrere Callbacks hinzufügen. Die Callbacks werden einem Stapel hinzugefügt. Der zuletzt hinzugefügte aktivierte Callback verarbeitet die nächste Zurück-Geste mit einem Callback pro Zurück-Geste.

Es ist einfacher, den aktivierten Status eines Callbacks zu verwalten, wenn dieser Callback nur eine Aufgabe hat. Beispiel:

Reihenfolge der Callbacks in einem Stack. — **Abbildung 2.** Stapeldiagramm für Rückrufe.

Abbildung 2 zeigt, wie Sie mehrere Callbacks im Stack haben können, die jeweils für eine Aufgabe zuständig sind. Ein Callback wird nur ausgeführt, wenn die Callbacks darüber im Stack deaktiviert sind. In diesem Beispiel wird der Callback „Are you sure…“ aktiviert, wenn der Nutzer Daten in ein Formular eingibt, und deaktiviert, wenn dies nicht der Fall ist. Der Callback öffnet ein Bestätigungsdialogfeld, wenn der Nutzer zurückwischt, um das Formular zu verlassen.

Der andere Callback kann eine Material-Komponente enthalten, die Predictive Back unterstützt, einen AndroidX-Übergang mit den Progress APIs oder einen anderen benutzerdefinierten Callback.

Dasselbe Stapelverhalten gilt in Compose: Das innerste PredictiveBackHandler oder BackHandler hat Vorrang.

Der Callback von childFragmentManager wird ausgeführt, wenn die oben genannten Callbacks deaktiviert sind und der Backstack für dieses FragmentManager nicht leer ist. In diesem Beispiel ist dieser interne Callback deaktiviert.

Ebenso wird der interne Callback von supportFragmentManager ausgeführt, wenn die oben genannten Callbacks deaktiviert sind und der zugehörige Stack nicht leer ist. In diesem Beispiel wird dieser Callback ausgeführt, wenn der Nutzer keinen Text in das Formular eingegeben hat, wodurch der Callback „Are you sure…“ deaktiviert wird.

Schließlich verarbeitet das System die Zurück-Geste, wenn die oben genannten Rückrufe deaktiviert sind. Damit Systemanimationen wie „Zurück zum Startbildschirm“, „Aktivitätenübergreifend“ und „Aufgabenübergreifend“ ausgelöst werden, muss der Backstack von supportFragmentManager leer sein, damit der interne Callback deaktiviert ist.

Animation für intelligente „Zurück“-Touchgeste testen

Wenn Sie Android 13 oder Android 14 verwenden, können Sie die in Abbildung 1 gezeigte Animation „Zurück zum Startbildschirm“ testen.

Führen Sie die folgenden Schritte aus, um diese Animation zu testen:

Rufen Sie auf Ihrem Gerät die Einstellungen > System > Entwickleroptionen auf.
Wählen Sie Animationen für intelligente „Zurück“-Touchgeste aus.
Starten Sie die aktualisierte App und verwenden Sie die Zurück-Geste, um sie in Aktion zu sehen.