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

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

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

Sie können diese Animation „Zurück zum Startbildschirm“ testen, wie in einem der folgenden Abschnitte auf dieser Seite beschrieben.

Um die intelligente „Zurück“-Touchgeste zu unterstützen, müssen Sie Ihre App aktualisieren und die abwärtskompatible OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) oder eine höhere API oder die neue OnBackInvokedCallback Platform 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 Sie die „Zurück“-Abfangungen von KeyEvent.KEYCODE_BACK und alle Klassen mit onBackPressed Methoden wie Activity und Dialog durch die neuen System-APIs für die Rückwärtsnavigation ersetzen.

Codelab und Google I/O-Video

Zusätzlich zu dieser Dokumentation auf dieser Seite können Sie unser Codelab ausprobieren. Dort wird ein gängiger Anwendungsfall für die Implementierung eines WebView beschrieben, der die intelligente „Zurück“-Touchgeste mit AndroidX Activity APIs verarbeitet.

Sie können sich auch unser Google I/O-Video ansehen, in dem weitere Beispiele für die Implementierung der AndroidX- und Platform APIs behandelt werden.

Benutzerdefinierte „Zurück“-Touchgesten in Compose verarbeiten

Compose bietet die zusammensetzbare Funktion PredictiveBackHandler zum Verarbeiten benutzerdefinierter „Zurück“-Touchgesten. Mit dieser API können Sie auf die „Zurück“-Touchgeste reagieren und einen Flow von BackEventCompat-Objekten bereitstellen, 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 die „Zurück“-Touchgeste nur abfangen müssen, ohne den Fortschritt zu verfolgen, verwenden Sie BackHandler.

App aktualisieren, die die Standard-Rückwärtsnavigation verwendet

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

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

App aktualisieren, die eine benutzerdefinierte „Zurück“-Navigation verwendet

Wenn Ihre App ein benutzerdefiniertes „Zurück“-Verhalten implementiert, gibt es verschiedene Migrationspfade, je nachdem, ob sie AndroidX verwendet und wie sie die Rückwärtsnavigation verarbeitet.

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

Dieser Anwendungsfall ist der häufigste (und der am meisten empfohlene). Er gilt für neue oder vorhandene Apps, die die benutzerdefinierte Verarbeitung der Touchgesten mit OnBackPressedDispatcherimplementieren, wie unter Benutzerdefinierte „Zurück“-Navigation bereitstellenbeschrieben.

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

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

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

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 Ihre System-„Zurück“-Verarbeitungslogik zu AndroidX’s OnBackPressedDispatcher mit einer Implementierung von OnBackPressedCallback. Eine detaillierte Anleitung finden Sie unter Benutzerdefinierte „Zurück“-Navigation bereitstellen.

2. Deaktivieren Sie OnBackPressedCallback, wenn Sie die „Zurück“-Touchgeste nicht mehr abfangen möchten.

3. Beenden Sie das Abfangen von „Zurück“-Ereignissen über OnBackPressed oder KeyEvent.KEYCODE_BACK.

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

Intelligente „Zurück“-Touchgeste deaktivieren

Wenn Sie die intelligente „Zurück“-Touchgeste deaktivieren möchten, setzen Sie in AndroidManifest.xml im Tag <application> das android:enableOnBackInvokedCallback Flag auf false.

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

Wenn Sie diese Einstellung auf „false“ setzen, passiert Folgendes:

• Die Systemanimation für die intelligente „Zurück“-Touchgeste wird deaktiviert.
• OnBackInvokedCallback wird ignoriert, aber OnBackPressedCallback-Aufrufe funktionieren weiterhin.

Auf Aktivitätsebene deaktivieren

Mit dem Flag android:enableOnBackInvokedCallback können Sie Systemanimationen für die intelligente „Zurück“-Touchgeste auf Aktivitätsebene deaktivieren. So lassen sich große Apps mit mehreren Aktivitäten einfacher zu intelligenten „Zurück“-Touchgesten migrieren.

Der folgende Code zeigt ein Beispiel für enableOnBackInvokedCallback, das so festgelegt ist, dass die Systemanimation „Zurück zum Startbildschirm“ von 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 Animationen für die intelligente „Zurück“-Touchgeste entweder auf Aktivitätsebene oder auf App-Ebene deaktiviert, je nachdem, wo Sie das Tag festlegen. Das System wird angewiesen, Aufrufe der OnBackInvokedCallback Platform API 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 Callbacks

Hier sind Best Practices für die Verwendung der unterstützten System-„Zurück“-Callbacks: PredictiveBackHandler oder BackHandler (für Compose), OnBackPressedCallback oder OnBackInvokedCallback.

UI-Status bestimmen, der die einzelnen Callbacks aktiviert und deaktiviert

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

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

2. Definieren Sie diesen Status mit einem beobachtbaren Datenhalter typ wie StateFlow oder Compose State und aktivieren oder deaktivieren Sie den Callback, wenn sich der Status ändert.

Wenn Ihre App die „Zurück“-Logik zuvor mit bedingten Anweisungen verknüpft hat, bedeutet das möglicherweise, dass Sie auf das „Zurück“-Ereignis reagieren, nachdem es bereits aufgetreten ist. Vermeiden Sie dieses Muster mit neueren Callbacks. Verschieben Sie den Callback nach Möglichkeit außerhalb der bedingten Anweisung und verknüpfen Sie ihn stattdessen mit einem beobachtbaren Datenhaltertyp.

System-„Zurück“-Callbacks für die UI-Logik verwenden

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

Wenn Ihre App OnBackPressedCallback oder OnBackInvokedCallback mit PRIORITY_DEFAULT oder PRIORITY_OVERLAY aktiviert, werden die Animationen für die intelligente „Zurück“-Touchgeste 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 Ihre App Geschäftslogik ausführen oder protokollieren muss, wenn der Nutzer nach links wischt:

• Verwenden Sie OnBackInvokedCallback mit PRIORITY_SYSTEM_NAVIGATION_OBSERVER auf Geräten mit Android 16 und höher. Dadurch wird ein Observer-Callback erstellt, das das „Zurück“-Ereignis nicht verarbeitet. Sie können diesen Callback beispielsweise registrieren, wenn der Nutzer von der Stammaktivität nach links wischt, d. h. wenn der Nutzer Ihre App verlassen hat. 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.
• Protokollieren Sie in Fällen, in denen zwischen Aktivitäten oder zwischen Fragment und Aktivität gewechselt wird, ob isFinishing in onDestroy im Aktivitätslebenszyklus true ist.
• Protokollieren Sie in Fällen, in denen zwischen Fragmenten gewechselt wird, ob isRemoving in onDestroy im Lebenszyklus der Fragmentansicht „true“ ist. Alternativ können Sie die Methoden onBackStackChangeStarted oder onBackStackChangeCommitted in FragmentManager.OnBackStackChangedListener verwenden.
• Protokollieren Sie im Fall von Compose im onCleared()-Callback eines ViewModel, das mit dem Compose-Ziel verknüpft ist. Dies ist das beste Signal, um zu erkennen, wann ein Compose-Ziel aus dem Back-Stack entfernt und zerstört wird.

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“-Touchgeste verarbeitet. Für jede „Zurück“-Touchgeste wird ein Callback verwendet.

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

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 ist der Callback „Sind Sie sicher?“ aktiviert, wenn der Nutzer Daten in ein Formular eingibt, und andernfalls deaktiviert. Der Callback öffnet ein Bestätigungsdialogfeld, wenn der Nutzer nach links wischt, um das Formular zu verlassen.

Der andere Callback kann eine Material-Komponente enthalten, die die intelligente „Zurück“-Touchgeste unterstützt, einen AndroidX-Übergang mit den Progress APIs oder einen anderen benutzerdefinierten Callback.

Dasselbe Stack-Verhalten gilt in Compose: Der innerste PredictiveBackHandler oder BackHandler hat Vorrang.

Ebenso wird ein Callback von childFragmentManager's ausgeführt, wenn die oben genannten Callbacks deaktiviert sind und der Back-Stack für diesen 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 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 „Sind Sie sicher?“ deaktiviert wird.

Schließlich verarbeitet das System die „Zurück“-Touchgeste, wenn die oben genannten Callbacks deaktiviert sind. Um Systemanimationen wie „Zurück zum Startbildschirm“, „Zwischen Aktivitäten wechseln“ und „Zwischen Aufgaben wechseln“ auszulösen, muss der Back-Stack von supportFragmentManager leer sein, damit der interne Callback deaktiviert ist.

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

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

So testen Sie diese Animation:

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

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

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