Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

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

**Abbildung 1.** Mockup der intelligenten „Zurück“-Touchgeste auf einem Smartphone

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

Wenn Sie beispielsweise die „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 Animationen für die intelligente „Zurück“-Geste nicht mehr verfügbar. Systemanimationen wie „Zurück zum Startbildschirm“, „Aufgabenübergreifend“ und „Aktivitätsübergreifend“ werden jetzt für Apps angezeigt, für die die intelligente „Zurück“-Geste entweder vollständig oder auf Aktivitätsebene aktiviert wurde.

Du kannst diese Animation zum Zurückkehren zum Startbildschirm testen (wie in einem folgenden Abschnitt dieser Seite beschrieben).

Wenn Sie die intelligente „Zurück“-Touchgeste 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 OnBackInvokedCallback-Plattform-API. Die meisten Apps verwenden die abwärtskompatible AndroidX API.

Dieses Update bietet einen Migrationspfad, um die Rückwärtsnavigation ordnungsgemäß abzufangen. Dazu müssen die Abfangvorgänge 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 gängige Anwendungsfallimplementierung einer WebView, die die intelligente „Zurück“-Touchgeste mithilfe von AndroidX Activity APIs verarbeitet.

Du kannst dir auch unser Google I/O-Video ansehen, in dem weitere Beispiele für die Implementierung der AndroidX- und Plattform-APIs gezeigt werden.

Benutzerdefinierte „Zurück“-Gesten in Compose verarbeiten

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

Wenn Sie PredictiveBackHandler verwenden möchten, muss Ihre App die Abhängigkeit androidx.activity:activity-compose (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 die „Zurück“-Geste nur abfangen müssen, ohne den Fortschritt zu verfolgen, verwenden Sie BackHandler.

Apps mit standardmäßiger Rückwärtsnavigation aktualisieren

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

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

Apps mit benutzerdefinierter Rückwärtsnavigation aktualisieren

Wenn in deiner App ein benutzerdefiniertes Verhalten für die Rückwärtsnavigation implementiert ist, gibt es verschiedene Migrationspfade, je nachdem, ob AndroidX verwendet wird und wie die Rückwärtsnavigation gehandhabt wird.

Wie Ihre App die Rückwärtsnavigation handhabt	Empfohlener Migrationspfad (Link auf dieser Seite)
AndroidX APIs	Vorhandene AndroidX-Implementierung für die „Zurück“-Geste migrieren
Nicht unterstützte Plattform-APIs	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 am meisten empfohlene). Sie gilt für neue oder vorhandene Apps, die eine benutzerdefinierte Bedienung über Gesten mit OnBackPressedDispatcher implementieren, wie unter Benutzerdefinierte Rückwärtsnavigation bereitstellen beschrieben.

Damit APIs, die bereits OnBackPressedDispatcher verwenden (z. B. Fragmente und die Navigationskomponente), nahtlos mit der intelligenten „Zurück“-Touchgeste funktionieren, führen Sie ein Upgrade auf AndroidX Activity 1.6.0 oder höher durch.

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

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:

Migriere die Logik für die Verarbeitung der Zurück-Geste deines Systems zu OnBackPressedDispatcher von AndroidX mit einer Implementierung von OnBackPressedCallback. Eine ausführliche Anleitung finden Sie unter Benutzerdefinierte Rückwärtsnavigation bereitstellen.
Deaktiviere die OnBackPressedCallback, wenn die „Zurück“-Geste nicht mehr abgefangen werden soll.
Beende das Abfangen von Zurück-Ereignissen mit OnBackPressed oder KeyEvent.KEYCODE_BACK.
Führe ein Upgrade auf AndroidX Activity 1.6.0 oder höher durch.
```
// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}
```
Hinweis: OnBackPressedCallback wird immer aufgerufen, unabhängig vom Wert von android:enableOnBackInvokedCallback. Mit anderen Worten: Das Deaktivieren der Systemanimation hat keine Auswirkungen auf die Logik für die „Zurück“-Geste 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 diese Option auf „false“ setzen, geschieht Folgendes:

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

Anzeigenvorschläge auf Aktivitätsebene deaktivieren

Mit dem Flag android:enableOnBackInvokedCallback können Sie vorausschauende Systemanimationen auf Aktivitätsebene deaktivieren. Dieses Verhalten erleichtert die Migration großer Apps mit mehreren Aktivitäten zu intelligenten „Zurück“-Touch-Gesten.

Der folgende Code zeigt ein Beispiel für enableOnBackInvokedCallback, das so festgelegt ist, dass die Systemanimation „Zurück zum Startbildschirm“ über die 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 Animationen für die intelligente „Zurück“-Geste entweder auf Aktivitäts- oder App-Ebene deaktiviert, je nachdem, wo Sie das Tag festlegen. Außerdem wird das System 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 Callbacks

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 bestimmen, der die einzelnen Callbacks aktiviert und deaktiviert

Der UI-Zustand ist eine Property, die die UI beschreibt. Wir empfehlen, die folgenden allgemeinen Schritte auszuführen.

Bestimmen Sie den UI-Zustand, der die einzelnen Callbacks aktiviert und deaktiviert.
Definiere diesen Status mit einem beobachtbaren Datenhaltertyp wie StateFlow oder Compose State und aktiviere oder deaktiviere den Callback, wenn sich der Status ändert.

Wenn in Ihrer App die Zurück-Logik bisher mit bedingten Anweisungen verknüpft war, kann dies bedeuten, dass Sie auf das Zurück-Ereignis reagieren, nachdem es bereits aufgetreten ist. Vermeiden Sie dieses Muster bei neueren Callbacks. Verschiebe den Callback nach Möglichkeit außerhalb der bedingten Anweisung und verknüpfe ihn stattdessen mit einem beobachtbaren Datenhaltertyp.

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

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

Wenn deine App einen OnBackPressedCallback oder einen OnBackInvokedCallback mit PRIORITY_DEFAULT oder PRIORITY_OVERLAY aktiviert, werden die Animationen für die intelligente „Zurück“-Geste nicht ausgeführt und du musst das „Zurück“-Ereignis verarbeiten. Erstellen Sie diese Callbacks nicht, um Geschäftslogik auszuführen oder zu protokollieren.

Verwende die folgenden Ansätze, wenn deine App Geschäftslogik ausführen oder protokollieren muss, wenn der Nutzer zurückwischt:

In Compose:Protokollieren Sie im onCleared()-Callback eines ViewModel, das mit dem Compose-Ziel verknüpft ist. Dies ist das beste Signal, um zu wissen, wann ein Compose-Ziel aus dem Back Stack entfernt und gelöscht wird.
Android 16 und höher:Verwenden Sie OnBackInvokedCallback mit PRIORITY_SYSTEM_NAVIGATION_OBSERVER. Dadurch wird ein Beobachter-Callback erstellt, der das Zurück-Ereignis nicht verarbeitet. Du kannst diesen Callback beispielsweise registrieren, wenn der Nutzer von der Stammaktivität zurückwischt (und deine App verlässt), um das Zurück-Ereignis zu protokollieren oder die Geschäftslogik auszuführen, während die Animation für die Rückkehr zum Startbildschirm abgespielt wird.
In ansichtsbasierten Apps:Protokollieren Sie in Lebenszyklus- oder Back-Stack-Callbacks, anstatt „Zurück“-Ereignisse zu verarbeiten:
- Prüfe bei Aktivitätsübergängen, ob isFinishing innerhalb von Activity.onDestroy() true ist.
- Prüfe bei Fragmentübergängen, ob isRemoving im Lebenszyklus der Fragmentansicht onDestroy() den Wert true hat, oder verwende FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted / onBackStackChangeCommitted).

Callbacks mit einer einzigen Aufgabe erstellen

Sie können dem Dispatcher mehrere Callbacks hinzufügen. Die Callbacks werden einem Stack hinzugefügt, in dem der zuletzt hinzugefügte aktivierte Callback die nächste „Zurück“-Geste verarbeitet, wobei ein Callback pro „Zurück“-Geste verwendet wird.

Der Aktivierungsstatus eines Callbacks lässt sich leichter verwalten, wenn dieser Callback nur eine einzige Aufgabe hat. Beispiel:

Reihenfolge von Callbacks in einem Stack in Compose. — **Abbildung 2**: Diagramm des Callback-Stacks in Compose.

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

Die Frage „Sind Sie sicher…“ PredictiveBackHandler ist aktiviert, wenn der Nutzer Daten in ein Formular eingibt, andernfalls deaktiviert. Wenn diese Option aktiviert ist, wird die Geste „Zurück“ 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 Callback NavHost verarbeitet die Rückwärtsnavigation, um Ziele aus dem Back Stack zu entfernen, wenn vorherige benutzerdefinierte Callbacks deaktiviert sind.
Schließlich verarbeitet das System die „Zurück“-Geste, wenn alle vorherigen Callbacks deaktiviert sind. Wenn sich der Back Stack am Stammziel befindet, löst das System Animationen auf Systemebene aus, z. B. „Zurück zum Startbildschirm“, „Aktivitätsübergreifend“ und „Aufgabenübergreifend“.

Dasselbe Stapelverhalten gilt für ansichtsbasierte Apps: Die zuletzt hinzugefügte aktivierte OnBackPressedCallback hat Vorrang, gefolgt von FragmentManager und schließlich der System-Zurück-Verarbeitung.

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

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

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

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