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 vorhersagende Rückwärtsanimationen 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 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 Zurück-Navigation 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.

Hinweis :KeyEvent.KEYCODE_BACK ist nicht veraltet, da es einige unterstützte Anwendungsfälle für KeyEvent.KEYCODE_BACK gibt. Das Abfangen von Back-Events von KeyEvent.KEYCODE_BACK wird jedoch nicht mehr unterstützt.

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.

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 AndroidX verwendet wird und wie die Zurück-Navigation gehandhabt wird, unterschiedliche Migrationspfade.

Ihre App verwendet AndroidX	So geht Ihre App mit der Rückwärtsnavigation um	Empfohlener Migrationspfad (Link auf dieser Seite)
Ja	AndroidX-APIs	Vorhandene AndroidX-Implementierung der Zurück-Funktion migrieren
	Nicht unterstützte Plattform-APIs	Eine AndroidX-App mit nicht unterstützten APIs für die Rückwärtsnavigation zu AndroidX-APIs migrieren
Nein	Nicht unterstützte Plattform-APIs, die migriert werden können	Eine App, die nicht unterstützte APIs für die Rückwärtsnavigation verwendet, zu Plattform-APIs migrieren
	Nicht unterstützte Plattform-APIs, aber keine Migration möglich	Sie können die Funktion vorübergehend deaktivieren, indem Sie das Attribut android:enableOnBackInvokedCallback im Tag <application> oder <activity> der AndroidManifest.xml-Datei Ihrer App auf false setzen.

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

AndroidX-Implementierung der Rückwärtsnavigation migrieren

Dieser Anwendungsfall ist der häufigste und wird am meisten empfohlen. Sie gilt für neue oder bestehende Apps, die die benutzerdefinierte Verarbeitung der 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 Navigation Component), 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 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-Zurück-Navigation in Ihrer App, wenn Sie die Funktion aktivieren. Außerdem bietet es 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 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 über OnBackPressed oder KeyEvent.KEYCODE_BACK wird beendet.

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. Das Deaktivieren der Systemanimation hat also keine Auswirkungen auf die Logik für die Rückwärtsnavigation Ihrer App, wenn sie OnBackPressedCallback verwendet.

Eine App, die nicht unterstützte APIs für die Zurück-Navigation verwendet, zu Plattform-APIs migrieren

Wenn Ihre App keine AndroidX-Bibliotheken verwenden kann und stattdessen eine benutzerdefinierte Zurück-Navigation mit den nicht unterstützten APIs implementiert oder darauf verweist, müssen Sie zur OnBackInvokedCallback-Plattform-API migrieren.

Hinweis: Wir empfehlen dringend, AndroidX-Bibliotheken zu verwenden. AndroidX aktiviert automatisch die aktualisierte System-Zurück-Navigation 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.

Führen Sie die folgenden Schritte aus, um nicht unterstützte APIs zur Plattform-API zu migrieren:

1. Verwenden Sie die neue OnBackInvokedCallback API auf Geräten mit Android 13 oder höher und die nicht unterstützten APIs auf Geräten mit Android 12 oder niedriger.

2. Registrieren Sie Ihre benutzerdefinierte Back-Logik in OnBackInvokedCallback mit onBackInvokedDispatcher. Dadurch wird verhindert, dass die aktuelle Aktivität beendet wird, und Ihr Callback hat die Möglichkeit, auf die Zurück-Aktion zu reagieren, sobald der Nutzer die Systemnavigation „Zurück“ abgeschlossen hat.

3. Heben Sie die Registrierung von OnBackInvokedCallback auf, wenn Sie das Abfangen der Zurück-Geste beenden möchten. Andernfalls kann es bei der Verwendung der System-Zurück-Navigation zu unerwünschtem Verhalten kommen, z. B. dass Nutzer zwischen Ansichten „hängen bleiben“ und Ihre App beenden müssen.

   Hier ein Beispiel für die Migration von Logik aus onBackPressed:

   Kotlin

   @Override
   fun onCreate() {
       if (BuildCompat.isAtLeastT()) {
           onBackInvokedDispatcher.registerOnBackInvokedCallback(
               OnBackInvokedDispatcher.PRIORITY_DEFAULT
           ) {
               /**
                * onBackPressed logic goes here. For instance:
                * Prevents closing the app to go home screen when in the
                * middle of entering data to a form
                * or from accidentally leaving a fragment with a WebView in it
                *
                * Unregistering the callback to stop intercepting the back gesture:
                * When the user transitions to the topmost screen (activity, fragment)
                * in the BackStack, unregister the callback by using
                * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
                * (https://developer.android.com/reference/kotlin/android/window/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
                */
           }
       }
   }

   Java

   @Override
   void onCreate() {
     if (BuildCompat.isAtLeastT()) {
       getOnBackInvokedDispatcher().registerOnBackInvokedCallback(
           OnBackInvokedDispatcher.PRIORITY_DEFAULT,
           () -> {
             /**
              * onBackPressed logic goes here - For instance:
              * Prevents closing the app to go home screen when in the
              * middle of entering data to a form
              * or from accidentally leaving a fragment with a WebView in it
              *
              * Unregistering the callback to stop intercepting the back gesture:
              * When the user transitions to the topmost screen (activity, fragment)
              * in the BackStack, unregister the callback by using
              * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
              * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
              */
           }
       );
     }
   }

4. Das Abfangen von Zurück-Ereignissen mit OnBackPressed oder KeyEvent.KEYCODE_BACK für Android 13 und höher beenden.

Sie können ein OnBackInvokedCallback mit PRIORITY_DEFAULT oder PRIORITY_OVERLAY registrieren, was in der ähnlichen AndroidX-Bibliothek OnBackPressedCallback nicht möglich ist. Die Registrierung eines Callbacks mit PRIORITY_OVERLAY ist in einigen Fällen hilfreich.

Das gilt, wenn Sie von onKeyPreIme() migrieren und Ihr Callback die Zurück-Geste anstelle einer geöffneten IME empfangen muss. IMEs registrieren Callbacks bei PRIORITY_DEFAULT, wenn sie geöffnet werden. Registrieren Sie Ihren Callback mit PRIORITY_OVERLAY, damit OnBackInvokedDispatcher die Zurück-Geste an Ihren Callback anstelle der geöffneten IME sendet.

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.

Anzeigenvorschläge auf Aktivitätsebene deaktivieren

Ab Android 16 können Sie mit dem Flag android:enableOnBackInvokedCallback predictive Systemanimationen auf Aktivitätsebene deaktivieren. Dieses Verhalten erleichtert die Migration großer Apps mit mehreren Aktivitäten zu vorhersagbaren Rückwärtsgesten.

Im folgenden Codebeispiel wird enableOnBackInvokedCallback so festgelegt, 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:

• Durch Festlegen von android:enableOnBackInvokedCallback=false werden Vorhersage-Rückwärtsanimationen entweder auf Aktivitätsebene 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.

Best Practices für Callbacks

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

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

UI-Status ist eine Property, 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 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 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. zum Anzeigen eines Dialogfelds oder zum Ausführen einer Animation.

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 Rückrufe nicht, um Geschäftslogik auszuführen oder zu protokollieren.

Wenn Ihre App Geschäftslogik ausführen oder protokollieren muss, wenn der Nutzer zurückwischt, können Sie die folgenden Ansätze verwenden:

• 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 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 während des Ansichtslebenszyklus des Fragments „true“ ist. Oder Sie protokollieren mit den Methoden onBackStackChangeStarted oder onBackStackChangeCommitted innerhalb von FragmentManager.OnBackStackChangedListener.
• Im Compose-Fall 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 Backstack entfernt und zerstört wird.

Callbacks mit nur einer Aufgabe erstellen

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

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

Abbildung 2. Stapeldiagramm für Rückrufe.

Abbildung 2 zeigt, wie Sie mehrere Callbacks im Stack haben können, die jeweils für eine bestimmte 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.

Der Callback von childFragmentManager wird ausgeführt, wenn die oben genannten Callbacks deaktiviert sind und der Backstack für dieses FragmentManager nicht leer ist. Dabei wird childFragmentManager in einem Fragment angehängt. 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. Dieses Verhalten ist konsistent, unabhängig davon, ob Sie FragmentManager oder NavigationComponent für die Navigation verwenden, da NavigationComponent auf FragmentManager basiert. 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.

super.onBackPressed()ist der Callback auf Systemebene, der wieder ausgeführt wird, wenn die oben genannten Callbacks deaktiviert sind. Damit Systemanimationen wie „Zurück zum Startbildschirm“, „Aktivitätenübergreifend“ und „Aufgabenübergreifend“ ausgelöst werden können, muss der Backstack von supportFragmentManager leer sein, damit der interne Callback deaktiviert ist.

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

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

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

So testen Sie diese Animation:

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

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

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