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

Abbildung 1. Mockup des Erscheinungsbildes der vorrausschauenden Geste zum Zurückgehen auf einem Smartphone

Mit der Funktion „Intelligente „Zurück“-Touch-Geste“ können Nutzer eine Vorschau der Seite aufrufen, zu der sie durch Wischen nach hinten 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 vorausschauende Rückwärtsanimationen nicht mehr verfügbar. Systemanimationen wie „Zurück zum Startbildschirm“, „Zwischen Aufgaben wechseln“ und „Zwischen Aktivitäten wechseln“ 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. Es bietet eine gängige Anwendungsfallimplementierung 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 mit benutzerdefinierter Rücknavigation aktualisieren

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

Ihre App verwendet AndroidX Wie Ihre App mit der Zurück-Navigation umgeht Empfohlener Migrationspfad (Link auf dieser Seite)
Ja AndroidX APIs Bestehende AndroidX-Back-Implementierung migrieren
Nicht unterstützte Plattform-APIs 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 App mit nicht unterstützten APIs für die Rückwärtsnavigation zu Plattform-APIs migrieren
Nicht unterstützte Plattform-APIs, aber keine Migration möglich Aktivieren Sie die Funktion erst, wenn sie erforderlich ist.

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 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 Zurück-Geste 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. Deaktivieren Sie die OnBackPressedCallback, wenn Sie die Zurück-Geste nicht mehr abfangen möchten.

  3. Unterbinden 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"

  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 Ihre App keine AndroidX-Bibliotheken verwenden kann und stattdessen eine benutzerdefinierte Zurück-Navigation mithilfe der nicht unterstützten APIs implementiert oder darauf verweist, müssen Sie zur OnBackInvokedCallback-Plattform-API 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 Ihr Callback kann auf die Schaltfläche „Zurück“ reagieren, sobald der Nutzer die systeminterne Navigation zurück abgeschlossen hat.

  3. Registrieren Sie die OnBackInvokedCallback nicht mehr, wenn Sie die Geste „Zurück“ 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 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. Unter Android 13 und höher werden Rückgabeereignisse über OnBackPressed oder KeyEvent.KEYCODE_BACK nicht mehr abgefangen.

  5. Nachdem Sie Ihre App migriert haben, aktivieren Sie die vorausschauende Wischgeste zum Zurück (wie auf dieser Seite beschrieben), damit OnBackInvokedCallback wirksam wird.

Sie können eine OnBackInvokedCallback mit PRIORITY_DEFAULT oder PRIORITY_OVERLAY registrieren, was in der ähnlichen AndroidX-OnBackPressedCallback nicht möglich 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. Registrieren Sie Ihren Callback bei PRIORITY_OVERLAY, damit OnBackInvokedDispatcher die Zurück-Geste an Ihren Callback statt an die geöffnete IME sendet.

Intelligente „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 vorweggenommenen 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. Dabei geschieht Folgendes:

  • Deaktiviert die Systemanimation für die intelligente „Zurück“-Touch-Geste.
  • 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. Durch dieses Verhalten ist es einfacher, große Apps mit mehreren Aktivitäten zu Apps mit vorausschauenden Rückwärts-Gesten zu migrieren. Unter Android 15 ist die Vorhersagefunktion für die Rückwärtsnavigation nicht mehr hinter der Entwickleroption versteckt. Apps können die vorausschauende Suche 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 systemweite Aktivitätsanimation aktiviert.

Beachten Sie bei der Verwendung des Flags android:enableOnBackInvokedCallback Folgendes:

  • 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 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 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. Definiere diesen Status mit einem beobachtbaren Datenhaltertyp wie StateFlow oder „Zustand zusammenstellen“ und aktiviere oder deaktiviere den Rückruf, 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 legt fest, 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 vorausschauenden Animationen nicht ausgeführt und Sie müssen das Zurück-Ereignis verarbeiten. Erstellen Sie keine Callbacks nur, um Logik auszuführen, die nicht zur Benutzeroberfläche gehört.

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.

Für den Fall „Compose“ (Erstellen) loggen Sie sich im onCleared()-Callback einer ViewModel ein, die mit dem Ziel „Compose“ verknüpft ist. Dies ist das beste Signal dafür, 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 aktivierten Status eines Rückrufs zu verwalten, wenn dieser Rückruf eine einzelne Aufgabe hat. Beispiel:

Die Reihenfolge der Callbacks in einem Stack.
Abbildung 2: Callback-Stack-Diagramm.

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 Callbacks darüber im Stack deaktiviert sind. In diesem Beispiel ist der Rückruf „Sind Sie sicher…?“ aktiviert, wenn der Nutzer Daten in ein Formular eingibt, andernfalls deaktiviert. Der Callback öffnet ein Bestätigungsdialogfeld, wenn der Nutzer zum Schließen des Formulars wischt.

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 dieser interne Rückruf 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 ebenfalls 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.

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“-Touch-Geste aus.

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