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

Mit der intelligenten „Zurück“-Geste, einer Bedienung über Gesten, können Nutzerinnen und Nutzer sehen, wohin sie durch das Zurückwischen gelangen.

Wenn Sie beispielsweise eine „Zurück“-Geste verwenden, 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 intelligente „Zurück“-Geste-Animationen nicht mehr verfügbar. Systemanimationen wie „Zurück zum Startbildschirm“, „Aufgabenübergreifend“ und „Aktivitätenübergreifend“ werden jetzt für Apps angezeigt, die die intelligente „Zurück“-Geste 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).

Wenn Sie die Vorhersage für die Zurück-Geste unterstützen möchten, müssen Sie Ihre App aktualisieren. Verwenden Sie dazu die abwärtskompatible OnBackPressedCallback in AndroidX Activity 1.6.0 oder höher oder die neue Plattform-API OnBackInvokedCallback. 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 Zurück-Abfangungen aus 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 zum Verarbeiten benutzerdefinierter Zurück-Gesten. Mit dieser API können Sie auf die Zurück-Geste reagieren und erhalten ein Flow von BackEventCompat-Objekten, mit denen Sie benutzerdefinierte Animationen oder Übergänge implementieren können, während der Nutzer wischt.

Damit Sie PredictiveBackHandler verwenden können, muss Ihre App die androidx.activity:activity-compose-Abhängigkeit (Version 1.8.0 oder höher) enthalten:

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

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

Apps aktualisieren, die die Standard-Rückwärtsnavigation verwenden

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

Wenn Ihre App Fragments oder die Navigation Component verwendet, führen Sie auch ein Upgrade auf AndroidX Activity 1.6.0 oder höher durch.

App aktualisieren, die benutzerdefinierte Rückwärtsnavigation verwendet

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

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. Fragments und die Navigation Component), nahtlos mit der vorhersagenden Zurück-Geste funktionieren, müssen Sie ein Upgrade auf AndroidX Activity 1.6.0 oder höher durchführen.

// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

Eine 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 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:

1. 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.

2. Deaktivieren Sie die OnBackPressedCallback, wenn Sie die Abfangung der Zurück-Geste beenden möchten.

3. Das Abfangen von Zurück-Ereignissen mit OnBackPressed oder KeyEvent.KEYCODE_BACK sollte nicht mehr erfolgen.

4. Aktualisieren Sie auf AndroidX Activity 1.6.0 oder höher.

   // In your build.gradle file:
   dependencies {
       // Add this in addition to your other dependencies
       implementation "androidx.activity:activity:1.6.0"
   }
   

Intelligente „Zurück“-Geste deaktivieren

Wenn Sie die Speicherung 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“-Geste.
• Ignoriert OnBackInvokedCallback, aber OnBackPressedCallback-Anrufe funktionieren weiterhin.

Deaktivierung auf Aktivitätsebene

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 intelligenten Touch-Gesten zu migrieren.

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

Richtlinien für Rückrufe

Beachten Sie die folgenden Richtlinien, wenn Sie die unterstützten System-Back-Callbacks verwenden: PredictiveBackHandler oder BackHandler (für Compose), OnBackPressedCallback oder OnBackInvokedCallback.

UI-Status ermitteln, mit dem die einzelnen Callbacks aktiviert und deaktiviert werden

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

1. Bestimmen Sie den UI-Status, der die einzelnen Callbacks aktiviert und deaktiviert.

2. Definieren Sie diesen Status mit einem Observable Data 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. Vermeiden Sie dieses Muster bei neueren Callbacks. 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 intelligenten „Zurück“-Geste-Animationen 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:

• In Compose:Loggen Sie innerhalb des onCleared()-Rückrufs eines ViewModel, der mit dem Compose-Ziel verknüpft ist. Dies ist das beste Signal, um zu wissen, wann ein Compose-Ziel aus dem Backstack entfernt und zerstört wird.
• Android 16 und höher:Verwenden Sie OnBackInvokedCallback mit PRIORITY_SYSTEM_NAVIGATION_OBSERVER. Dadurch wird ein Observer-Callback erstellt, der das Back-Ereignis nicht verarbeitet. Sie können diesen Callback beispielsweise registrieren, wenn der Nutzer von der Stammaktivität zurückwischt (und Ihre App verlässt), um das Zurück-Ereignis zu protokollieren oder Geschäftslogik auszuführen, während die Animation „Zurück zum Startbildschirm“ weiterhin abgespielt wird.
• In View-basierten Apps:Protokollieren Sie innerhalb von Lebenszyklus- oder Backstack-Callbacks, anstatt Back-Ereignisse zu verarbeiten:
  • Prüfen Sie für Aktivitätsübergänge, ob isFinishing innerhalb von Activity.onDestroy() true ist.
  • Prüfen Sie bei Fragmentübergängen, ob isRemoving innerhalb des View-Lebenszyklus des Fragments true ist onDestroy(), oder verwenden Sie FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted / onBackStackChangeCommitted).

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 für eine Aufgabe zuständig ist. Beispiel:

Abbildung 2 zeigt, wie Sie mehrere Callbacks im Stack haben können, die jeweils für eine Aufgabe zuständig sind. In Compose werden Callbacks vom innersten zum äußersten Composable ausgewertet. Ein Callback wird nur ausgeführt, wenn die Callbacks, die ihm im Stapel vorangehen, deaktiviert sind:

• Die Frage „Möchten Sie wirklich…?“ PredictiveBackHandler ist aktiviert, wenn der Nutzer Daten in ein Formular eingibt, und andernfalls deaktiviert. Wenn diese Option aktiviert ist, wird die Zurück-Geste abgefangen, um ein Bestätigungsdialogfeld oder eine benutzerdefinierte In-App-Animation anzuzeigen.
• Der BackHandler auf Bildschirmebene wird ausgeführt, wenn der vorherige Callback deaktiviert ist. In diesem Beispiel ist sie deaktiviert.
• Der NavHost-Callback verarbeitet die Rückwärtsnavigation, um Ziele aus dem Backstack zu entfernen, wenn vorherige benutzerdefinierte Callbacks deaktiviert sind.
• Schließlich verarbeitet das System die Zurück-Geste, wenn alle vorherigen Rückrufe deaktiviert sind. Wenn sich der Backstack am Stammziel befindet, löst das System Animationen auf Systemebene aus, z. B. „Zurück zum Startbildschirm“, „Aktivitätenübergreifend“ und „Aufgabenübergreifend“.

Das gleiche Stapelverhalten gilt für View-basierte Apps: Die zuletzt hinzugefügte aktivierte OnBackPressedCallback hat Vorrang. Wenn sie nicht vorhanden ist, wird auf FragmentManager zurückgegriffen und schließlich auf die Systemrücktaste.

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

Ab Android 15 sind Systemanimationen wie „Zurück zum Startbildschirm“, „Aufgabenübergreifend“ und „Aktivitätenübergreifend“ standardmäßig für Apps aktiviert, die die intelligente „Zurück“-Touchgeste unterstützen. Sie sind nicht mehr hinter einer Entwickleroption verborgen.

Auf Geräten mit Android 13 oder Android 14 können Sie die Entwickleroption aktivieren, um die in Abbildung 1 gezeigte Animation für die Rückkehr zum Startbildschirm zu testen:

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

2. Wählen Sie Animationen für intelligente „Zurück“-Gesten aus.

3. Starten Sie die aktualisierte App und verwenden Sie die Zurück-Geste, um sie in Aktion zu sehen.