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

„Predictive Back“ ist eine Navigationsfunktion über Gesten, mit der Nutzer in einer Vorschau sehen können, wohin sie durch „Zurückwischen“ gelangen.

So kann beispielsweise durch eine Rückwärtsgeste 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 mit Vorschlägen für den Rückwärtsgang nicht mehr verfügbar. Systemanimationen wie das Zurückgehen zum Startbildschirm, das Wechseln zwischen Aufgaben und das Wechseln zwischen Aktivitäten werden jetzt für Apps angezeigt, bei denen die intelligente „Zurück“-Geste entweder vollständig oder auf Aktivitätsebene aktiviert ist.

Sie können diese Animation zum Zurückkehren zur Startseite testen (wie im folgenden Abschnitt dieser Seite beschrieben).

Wenn Sie die vorausschauende Zurück-Geste unterstützen möchten, müssen Sie Ihre App aktualisieren. Verwenden Sie dazu die abwärtskompatible OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) oder eine höhere API 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 richtig abzufangen. Dazu müssen Rückwärts-Abfangungen 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 auf dieser Seite können Sie auch unser Codelab ausprobieren. Sie bietet eine gängige Implementierung einer WebView, die die vorausschauende Zurück-Geste mithilfe von AndroidX Activity APIs verarbeitet.

In unserem Google I/O-Video finden Sie weitere Beispiele für die Implementierung der AndroidX- und Plattform-APIs.

App aktualisieren, die die Standardnavigation zurück verwendet

Das Aktualisieren Ihrer App zur Unterstützung dieser Funktion ist ganz einfach, wenn Ihre App kein benutzerdefiniertes Zurück-Verhalten implementiert, d. h. die Rückgabe an das System überlässt. Aktivieren Sie diese Funktion, wie in diesem Leitfaden beschrieben.

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 benutzerdefinierte „Zurück“-Navigation verwendet

Wenn Ihre App ein benutzerdefiniertes Zurück-Verhalten implementiert, gibt es je nach Verwendung von AndroidX und der Art und Weise, wie die Zurück-Navigation verarbeitet wird, unterschiedliche Migrationspfade.

AndroidX-Implementierung der Rückwärtsnavigation migrieren

Dies ist der gängigste (und der am häufigsten empfohlene) Anwendungsfall. Sie gilt für neue oder vorhandene Apps, die eine benutzerdefinierte Navigation per Geste mit OnBackPressedDispatcher implementieren, wie unter Benutzerdefinierte Rückwärtsnavigation ermöglichen beschrieben.

Wenn Ihre App in diese Kategorie fällt, folgen Sie dieser Anleitung, um die Unterstützung für die vorausschauende Zurück-Geste hinzuzufügen:

1. Damit APIs, die bereits OnBackPressedDispatcher APIs verwenden (z. B. Fragmente und die Navigationskomponente), nahtlos mit der vorausschauenden Rückwärtsgeste funktionieren, aktualisieren Sie auf AndroidX Activity 1.6.0-alpha05.

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

2. Aktivieren Sie die intelligente „Zurück“-Touch-Geste, wie auf dieser Seite beschrieben.

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 Systemrückgabe zu OnBackPressedDispatcher von AndroidX mit einer Implementierung von OnBackPressedCallback. Eine ausführliche Anleitung finden Sie unter Benutzerdefinierte Rücknavigation bereitstellen.

2. Deaktiviere die OnBackPressedCallback, wenn du bereit bist, das Abfangen der Gegenbewegung zu beenden.

3. Beenden Sie das Abfangen von Ereignissen über OnBackPressed oder KeyEvent.KEYCODE_BACK.

4. Führen Sie ein Upgrade auf AndroidX Activity 1.6.0-alpha05 aus.

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

5. Nachdem Sie Ihre App erfolgreich migriert haben, aktivieren Sie die vorausschauende Geste zum Zurück (wie auf dieser Seite beschrieben), um die Systemanimation für die Rückkehr zum Startbildschirm zu sehen.

App mit nicht unterstützten APIs für die Rückwärtsnavigation zu Plattform-APIs migrieren

Wenn deine App keine AndroidX-Bibliotheken verwenden kann und stattdessen die benutzerdefinierte Zurück-Navigation mithilfe der nicht unterstützten APIs implementiert oder darauf verweist, musst du zur API der OnBackInvokedCallback-Plattform migrieren.

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 Rückgabelogik in OnBackInvokedCallback mit onBackInvokedDispatcher. Dadurch wird verhindert, dass die aktuelle Aktivität abgeschlossen wird, und dein Callback hat die Möglichkeit, auf die „Zurück“-Aktion zu reagieren, sobald der Nutzer die „Zurück“-Navigation des Systems abgeschlossen hat.

3. Registrieren Sie die OnBackInvokedCallback nicht mehr, wenn Sie die Zurück-Geste nicht mehr abfangen möchten. Andernfalls kann es bei der Verwendung der systeminternen Rückwärtsnavigation zu unerwünschten Verhaltensweisen kommen, z. B. zu einer „Sperrung“ zwischen Ansichten, die Nutzer dazu zwingt, Ihre App zu beenden.

   Hier ein Beispiel für die Migration der 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. Unter Android 13 und höher werden Rückgabeereignisse über OnBackPressed oder KeyEvent.KEYCODE_BACK nicht mehr abgefangen.

5. Wenn Sie Ihre App erfolgreich migriert haben, aktivieren Sie die Touch-Geste „Vorhersagbar“ (wie auf dieser Seite beschrieben), damit OnBackInvokedCallback wirksam wird.

Du kannst eine OnBackInvokedCallback bei PRIORITY_DEFAULT oder PRIORITY_OVERLAY registrieren, was im ähnlichen AndroidX-OnBackPressedCallback nicht verfügbar ist. In einigen Fällen ist es hilfreich, einen Callback bei PRIORITY_OVERLAY zu registrieren.

Dies gilt, wenn Sie von onKeyPreIme() migrieren und Ihr Callback die Zurück-Geste anstelle einer geöffneten IME erhalten muss. IMEs registrieren beim Öffnen Callbacks mit PRIORITY_DEFAULT. Registriere deinen Callback bei PRIORITY_OVERLAY, damit OnBackInvokedDispatcher die Zurück-Geste an deinen Callback sendet und nicht an den offenen IME.

„Zurück“-Touch-Geste aktivieren

Nachdem Sie entschieden haben, wie Sie Ihre App aufgrund Ihres Falls aktualisieren möchten, aktivieren Sie die Unterstützung der vorausschauenden Zurück-Geste.

Wenn Sie die Funktion aktivieren möchten, setzen Sie in AndroidManifest.xml im <application>-Tag das Flag android:enableOnBackInvokedCallback auf true.

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

Wenn Sie keinen Wert angeben, wird standardmäßig false verwendet und Folgendes gilt:

• Dadurch wird die Systemanimation zur automatischen Vervollständigung des Touch-Gestens „Zurück“ deaktiviert.
• OnBackInvokedCallback wird ignoriert, OnBackPressedCallback-Aufrufe funktionieren aber weiterhin.

Aktivitätsebene aktivieren

Ab Android 14 können Sie mit dem Flag android:enableOnBackInvokedCallback vorausschauende Systemanimationen auf Aktivitätsebene aktivieren. Dadurch ist es einfacher, große Anwendungen mit mehreren Aktivitäten zu vorausschauenden Touch-Gesten zu migrieren. Unter Android 15 ist die Vorhersagefunktion für die Schaltfläche „Zurück“ nicht mehr hinter der Entwickleroption verborgen. Apps können die Vervollständigung vollständig oder auf Aktivitätsebene aktivieren.

Im folgenden Codebeispiel wird gezeigt, wie mit enableOnBackInvokedCallback die Systemanimation für die Rückkehr 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>

Im vorherigen Beispiel wird durch Festlegen von android:enableOnBackInvokedCallback=true für ".SecondActivity" die aktivitätsübergreifende Systemanimation aktiviert.

Beachten Sie bei der Verwendung des Flags android:enableOnBackInvokedCallback die folgenden Überlegungen:

• Wenn Sie android:enableOnBackInvokedCallback=false festlegen, werden vorausschauende Rückwärtsanimationen entweder auf Aktivitäts- oder auf App-Ebene deaktiviert, je nachdem, wo Sie das Tag einfügen. Außerdem wird das System 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 Anwendungsebene festlegen, wird der Standardwert für alle Aktivitäten in der Anwendung 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 Rückrufe

Im Folgenden finden Sie Best Practices für die Verwendung der unterstützten System-Back-Callbacks BackHandler (für „Schreiben“), 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, die folgenden allgemeinen Schritte auszuführen.

1. Bestimme den UI-Status, der die einzelnen Rückrufe aktiviert und deaktiviert.

2. Definieren Sie diesen Status mithilfe eines beobachtbaren Dateninhabertyps wie StateFlow oder Erstellungsstatus und aktivieren oder deaktivieren Sie den Callback, wenn sich der Status ändert.

Wenn Sie in Ihrer App zuvor Rückgabelogik mit bedingten Anweisungen verknüpft haben, bedeutet das möglicherweise, dass Sie auf das Zurück-Ereignis reagieren, nachdem es bereits aufgetreten ist. Vermeiden Sie dieses Muster bei neueren Rückrufen. Verschieben Sie den Rückruf nach Möglichkeit außerhalb der bedingten Anweisung und ordnen Sie ihn stattdessen einem beobachtbaren Dateninhabertyp zu.

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. ein Pop-up anzuzeigen oder eine Animation auszuführen.

Wenn Ihre App einen System-Back-Callback aktiviert, werden die Vorhersageanimationen nicht ausgeführt und Sie müssen das Back-Ereignis verarbeiten. Erstellen Sie keine Callbacks, die nicht zur UI-Logik gehören.

Wenn Sie beispielsweise Back-Ereignisse nur zum Logging abfangen, sollten Sie sie stattdessen im Lebenszyklus der Aktivität oder des Fragments erfassen.

• Bei Aktivitäts-zu-Aktivitäts- oder Fragment-zu-Aktivitäts-Fällen protokollieren Sie, ob isFinishing in onDestroy true im Aktivitätslebenszyklus ist.
• Bei Fragment-zu-Fragment-Fällen protokollieren Sie, ob isRemoving innerhalb von onDestroy während des Lebenszyklus der Ansicht des Fragments wahr ist. Sie können auch die Methoden onBackStackChangeStarted oder onBackStackChangeCommitted in FragmentManager.OnBackStackChangedListener verwenden.

Protokollieren Sie für den „Compose“-Fall im onCleared()-Callback einer ViewModel, die dem Compose-Ziel zugeordnet ist. So können Sie am besten erkennen, wann ein Ziel für die Zusammenstellung aus dem Backstack entfernt und zerstört wird.

Rückrufe mit einer einzigen Aufgabe erstellen

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

Es ist einfacher, den Aktivierungsstatus eines Callbacks zu verwalten, wenn dieser eine einzige Zuständigkeit hat. Beispiel:

Abbildung 2 zeigt, wie Sie mehrere Callbacks im Stack haben können, die jeweils für eine Sache verantwortlich sind. Ein Callback wird nur ausgeführt, wenn die darüber im Stack angeordneten Callbacks deaktiviert sind. In diesem Beispiel ist der Callback „Are you sure...“ aktiviert, wenn der Nutzer Daten in ein Formular eingibt. Andernfalls ist er deaktiviert. Der Callback öffnet ein Bestätigungsdialogfeld, wenn der Nutzer wischt, um das Formular zu verlassen.

Der andere Callback kann eine Materialkomponente enthalten, die die Vorschaufunktion unterstützt, einen AndroidX-Übergang mit den Progress APIs oder einen anderen benutzerdefinierten Callback.

Der Rückruf von childFragmentManager wird ausgeführt, wenn die oben genannten Rückrufe deaktiviert sind und der Rückstapel für diese FragmentManager nicht leer ist. childFragmentManager ist in einem Fragment angehängt. In diesem Beispiel ist der interne Callback deaktiviert.

Ebenso wird der interne Rückruf von supportFragmentManager ausgeführt, wenn die oben genannten Rückrufe deaktiviert sind und der Stack nicht leer ist. Dieses Verhalten ist konsistent, wenn Sie entweder 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 „Sind Sie sicher…?“ deaktiviert wird.

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

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

Wenn Sie noch Android 13 oder Android 14 verwenden, können Sie die in Abbildung 1 gezeigte Animation für die Rückkehr zum Startbildschirm testen.

Führen Sie die folgenden Schritte aus, um diese Animation zu testen:

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

2. Wählen Sie Hintergrundanimationen vorausschauend aus.

3. Starten Sie die aktualisierte App und testen Sie die Touch-Geste für „Zurück“.