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 für die Bedienung über Gesten, können Nutzerinnen und Nutzer sehen, wohin sie durch das Zurückwischen gelangen.

Wenn sie beispielsweise die „Zurück“-Touchgeste verwenden, kann eine animierte Vorschau des Startbildschirms hinter der 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 höher-API 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 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 „Zurück“ ersetzen.

Hinweis: KeyEvent.KEYCODE_BACK ist nicht veraltet, da es einige unterstützte Anwendungs fälle für KeyEvent.KEYCODE_BACK gibt. Das Abfangen von „Zurück“-Ereignissen von KeyEvent.KEYCODE_BACK wird jedoch nicht mehr unterstützt.

Codelab und Google I/O-Video

Zusätzlich zu dieser Dokumentation auf dieser Seite können Sie unser Codelab ausprobieren. Dort wird eine gängige Anwendungsfallimplementierung eines WebView beschrieben, bei der die intelligente „Zurück“-Touchgeste mit AndroidX Activity APIs verarbeitet wird.

Sie können sich auch unser Google I/O-Video ansehen, in dem weitere Beispiele für die Implementierung der AndroidX- und Plattform-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.

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

Wichtig: Wir empfehlen dringend, die intelligente „Zurück“-Navigation so schnell wie möglich zu implementieren. Andernfalls kann es in einer zukünftigen Version von Android zu unerwartetem Verhalten kommen.

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 Bedienung über Gesten mit OnBackPressedDispatcherimplementieren, wie unter Benutzerdefinierte Rückwärtsnavigation 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.

Hinweis: Wir empfehlen dringend, AndroidX-Bibliotheken zu verwenden. AndroidX aktiviert automatisch die aktualisierte System-Rückwärtsnavigation in Ihrer App, wenn Sie die Funktion aktivieren. Außerdem bietet AndroidX viele weitere nützliche Funktionen, die APIs mit jeder Version automatisch aktualisieren, um Ihnen Arbeit und Zeit zu sparen.

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 mit 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"
   

   Hinweis: OnBackPressedCallback wird immer aufgerufen, unabhängig vom Wert von android:enableOnBackInvokedCallback. Mit anderen Worten: Das Deaktivieren der Systemanimation hat keine Auswirkungen auf die „Zurück“-Verarbeitungslogik Ihrer App, wenn sie OnBackPressedCallback verwendet.

Intelligente „Zurück“-Touchgeste deaktivieren

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

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

Wenn Sie diese Option 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 leichter 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äts- oder App-Ebene deaktiviert, je nachdem, wo Sie das Tag festlegen. Das System wird angewiesen, Aufrufe der OnBackInvokedCallback Plattform-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 bei 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 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, das das „Zurück“-Ereignis nicht verarbeitet. Sie können diesen Callback beispielsweise registrieren, wenn der Nutzer von der Stammaktivität zurückwischt, 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 von Aktivität zu Aktivität oder Fragment zu Aktivität, ob isFinishing in onDestroy innerhalb des Aktivitätslebenszyklus true ist.
• Protokollieren Sie in Fällen von Fragment zu Fragment, ob isRemoving in onDestroy innerhalb des Lebenszyklus der Fragmentansicht „true“ ist. Oder protokollieren Sie mit den Methoden onBackStackChangeStarted oder onBackStackChangeCommitted in FragmentManager.OnBackStackChangedListener.
• Protokollieren Sie im Fall von Compose innerhalb des onCleared()-Callbacks 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 Verantwortung 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, wobei für jede „Zurück“-Touchgeste ein Callback verwendet wird.

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

Abbildung 2. Diagramm des Callback-Stacks

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, die ihm im Stack vorangehen, 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 zurückwischt, 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 der Callback eines childFragmentManager' ausgeführt, wenn die vorherigen 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 vorherigen 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 vorherigen 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

Hinweis: Ab Android 15 sind Systemanimationen wie „Zurück zum Startbildschirm“, „Zwischen Aufgaben wechseln“ und „Zwischen Aktivitäten wechseln“ nicht mehr hinter der Entwickleroption verborgen. Sie werden jetzt für Apps angezeigt, die die intelligente „Zurück“-Touchgeste entweder vollständig oder auf Aktivitätsebene aktiviert haben.

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.