Diese Seite wurde von der Cloud Translation API übersetzt.

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

**Abbildung 1.** Mockup des Erscheinungsbilds der vorausschauenden „Zurück“-Touch-Geste auf einem Smartphone

Android 14 (API-Level 34) unterstützt zusätzliche Systemanimationen und APIs, um benutzerdefinierte Animationen zu erstellen. Weitere Informationen findest du unter Unterstützung für integrierte und benutzerdefinierte „Zurück“-Animationen hinzufügen.

Wenn Sie beispielsweise eine „Zurück“-Touch-Geste verwenden, kann eine animierte Vorschau des Startbildschirms hinter Ihrer App angezeigt werden, wie im Mockup in Abbildung 1 dargestellt. Ab Android 13 kannst du diese Back-to-Home-Animation testen, indem du eine Entwickleroption aktivierst, wie auf dieser Seite beschrieben.

Wenn Sie die vorausschauende „Zurück“-Geste unterstützen möchten, müssen Sie Ihre App mit der abwärtskompatiblen OnBackPressedCallback AppCompat 1.6.0-alpha05 API (AndroidX) oder höher oder der neuen OnBackInvokedCallback-Plattform-API unterstützen. Die meisten Apps verwenden die abwärtskompatible AndroidX API.

Dieses Update bietet einen Migrationspfad, um die Zurücknavigation ordnungsgemäß abzufangen. Dabei werden umgekehrte Abfangen von KeyEvent.KEYCODE_BACK und allen Klassen durch onBackPressed-Methoden wie Activity und Dialog durch die neuen Back APIs des Systems ersetzt.

Video: Codelab und Google I/O

Zusätzlich zur Dokumentation auf dieser Seite können Sie unser Codelab ausprobieren. Es bietet eine gängige Implementierung einer WebView, die die vorausschauende Zurück-Geste mithilfe von AndroidX Activity APIs verarbeitet.

Sie können sich auch unser Google I/O-Video mit weiteren Beispielen für die Implementierung der AndroidX- und Plattform-APIs ansehen.

App aktualisieren, die die Standard-Zurück-Navigation verwendet

Die Aktualisierung Ihrer App zur Unterstützung dieser Funktion ist ganz einfach, wenn in Ihrer App kein benutzerdefiniertes Back-Verhalten implementiert ist. Aktivieren Sie diese Funktion wie in diesem Leitfaden beschrieben.

Wenn in deiner App Fragmente oder die Navigationskomponente verwendet wird, führe auch ein Upgrade auf AndroidX Activity 1.6.0-alpha05 oder höher durch.

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

Wenn in Ihrer Anwendung benutzerdefiniertes Verhalten beim Zurückgehen implementiert ist, gibt es unterschiedliche Migrationspfade, je nachdem, ob sie AndroidX verwendet und wie die Zurück-Navigation verarbeitet wird.

In deiner App wird Android X verwendet	So funktioniert die Rückwärtsnavigation in der App	Empfohlener Migrationspfad (Link auf dieser Seite)
Ja	AndroidX-APIs	Vorhandene AndroidX-Implementierung zurückmigrieren
Ja	Nicht unterstützte Plattform-APIs	AndroidX-App mit nicht unterstützten APIs zur Rückwärtsnavigation zu AndroidX APIs migrieren
Nein	Nicht unterstützte Plattform-APIs, Migration möglich	Apps, die nicht unterstützte Back-Navigations-APIs verwenden, zu Plattform-APIs migrieren
Nein	Nicht unterstützte Plattform-APIs, aber Migration nicht möglich	Aktivierung auf später verschieben, bis eine erforderliche Funktion erforderlich ist

Implementierung der Rückwärtsnavigation für AndroidX migrieren

Dieser Anwendungsfall ist der häufigste und wird auch am häufigsten empfohlen. Sie gilt für neue oder vorhandene Apps, in denen mit OnBackPressedDispatcher eine benutzerdefinierte Bedienung der Gestensteuerung implementiert ist (siehe Benutzerdefinierte Zurück-Navigation bereitstellen).

Wenn Ihre App zu dieser Kategorie gehört, führen Sie die folgenden Schritte aus, um die vorausschauende Zurück-Geste zu unterstützen:

Damit APIs, die bereits OnBackPressedDispatcher APIs verwenden (z. B. Fragments und die Navigationskomponente), reibungslos mit der vorausschauenden Zurück-Geste zusammenarbeiten, 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"
```
Aktiviere die vorausschauende „Zurück“-Touch-Geste, wie auf dieser Seite beschrieben.

AndroidX-App mit nicht unterstützten Back-Navigation APIs zu AndroidX APIs migrieren

Wenn deine App AndroidX-Bibliotheken verwendet, aber die nicht unterstützten Back-Navigation APIs implementiert oder darauf verweist, musst du zu AndroidX APIs migrieren, um das neue Verhalten zu unterstützen.

So migrieren Sie nicht unterstützte APIs zu AndroidX APIs:

Migrieren Sie die Verarbeitungslogik des Systems zurück zu OnBackPressedDispatcher von AndroidX, indem Sie OnBackPressedCallback implementieren. Eine ausführliche Anleitung finden Sie unter Benutzerdefinierte Zurücknavigation bereitstellen.
Deaktivieren Sie OnBackPressedCallback, wenn Sie bereit sind, das Abfangen der Back-Touch-Geste zu beenden.
Beenden Sie das Abfangen von Ereignissen über OnBackPressed oder KeyEvent.KEYCODE_BACK.

Führe 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"

Nachdem Sie Ihre App migriert haben, aktivieren Sie die vorausschauende „Zurück“-Touch-Geste (wie auf dieser Seite beschrieben), um die Animation für die Zurück-zu-Startseite-Systemanimation zu sehen.

Hinweis: OnBackPressedCallback wird unabhängig vom Wert von android:enableOnBackInvokedCallback immer aufgerufen. Mit anderen Worten: Das Deaktivieren der Systemanimation wirkt sich nicht auf die Back-Handler-Logik Ihrer Anwendung aus, wenn sie OnBackPressedCallback verwendet.

Anwendungen, die nicht unterstützte Back-Navigation APIs verwenden, zu Plattform-APIs migrieren

Wenn deine App keine AndroidX-Bibliotheken verwenden kann und stattdessen eine benutzerdefinierte Rücknavigation mit nicht unterstützten APIs implementiert oder darauf verweist, musst du zur OnBackInvokedCallback-Plattform-API migrieren.

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

Verwenden Sie die neue OnBackInvokedCallback API auf Geräten mit Android 13 oder höher. Nutzen Sie die nicht unterstützten APIs auf Geräten mit Android 12 oder niedriger.
Registrieren Sie Ihre benutzerdefinierte Backlogik mit onBackInvokedDispatcher in OnBackInvokedCallback. Dadurch wird verhindert, dass die aktuelle Aktivität beendet wird, und Ihr Callback kann auf die Back-Aktion reagieren, sobald der Nutzer die System-Zurück-Navigation abgeschlossen hat.

Heben Sie die Registrierung von OnBackInvokedCallback auf, wenn das Abfangen der Zurück-Touch-Geste nicht mehr möglich ist. Andernfalls kann es bei Nutzern zu unerwünschtem Verhalten kommen, wenn sie eine Systemrücknavigation verwenden, z. B. wenn sie zwischen Ansichten hängen bleiben und ein Beenden der App erzwingen 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)
           */
        }
    );
  }
}

Unter Android 13 und höher werden keine Ereignisse mehr über OnBackPressed oder KeyEvent.KEYCODE_BACK abgefangen.
Nachdem Sie Ihre App migriert haben, aktivieren Sie die vorausschauende „Zurück“-Touch-Geste (wie auf dieser Seite beschrieben), damit OnBackInvokedCallback wirksam wird.

Du kannst ein OnBackInvokedCallback mit PRIORITY_DEFAULT oder PRIORITY_OVERLAY registrieren, das in ähnlichen AndroidX-OnBackPressedCallback nicht verfügbar ist. In einigen Fällen ist die Registrierung eines Callbacks mit PRIORITY_OVERLAY hilfreich. Das kann beispielsweise der Fall sein, wenn Sie von onKeyPreIme() migrieren und Ihr Callback die „Zurück“-Geste statt eines offenen IME erhalten muss. IMEs registrieren Callbacks mit PRIORITY_DEFAULT, wenn sie geöffnet werden. Registrieren Sie den Callback bei PRIORITY_OVERLAY, damit OnBackInvokedDispatcher die „Zurück“-Geste an Ihren Callback sendet und nicht an den offenen IME.

Vorhersehbare „Zurück“-Touch-Geste aktivieren

Nachdem Sie festgelegt haben, wie Sie Ihre App basierend auf Ihrem Fall aktualisieren, aktivieren Sie die Unterstützung der vorausschauenden „Zurück“-Touch-Geste.

Zum Aktivieren 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 der Standardwert false verwendet und folgende Aktionen werden ausgeführt:

Deaktiviert die Systemanimation mit den vorausschauenden „Zurück“-Touch-Gesten.
OnBackInvokedCallback wird ignoriert, aber OnBackPressedCallback-Aufrufe funktionieren weiterhin.

Aktivierung auf Aktivitätsebene

Ab Android 14 können Sie mit dem Flag android:enableOnBackInvokedCallback Vorhersagesystemanimationen auf Aktivitätsebene aktivieren. Dadurch lässt sich die Migration großer Apps mit mehreren Aktivitäten zu vorausschauenden Zurück-Gesten einfacher gestalten.

Der folgende Code zeigt ein Beispiel für die Verwendung von enableOnBackInvokedCallback, um die Back-to-Home-Systemanimation aus der MainActivity zu aktivieren:

<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 das 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 Hinweise:

Wenn Sie android:enableOnBackInvokedCallback=false festlegen, werden vorausschauende Rückanimationen entweder auf Aktivitäts- oder auf App-Ebene deaktiviert, je nachdem, wo Sie das Tag festgelegt haben. 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 mehr unterstützt wird.
Wenn Sie das Flag enableOnBackInvokedCallback auf Anwendungsebene festlegen, wird der Standardwert für alle Aktivitäten in der App festgelegt. Sie können den Standardwert für jede 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 Systemrückrufe: BackHandler (für das Schreiben), OnBackPressedCallback oder OnBackInvokedCallback.

Bestimmen des UI-Status, mit dem die einzelnen Callbacks aktiviert und deaktiviert werden

Der UI-Status ist eine Eigenschaft, mit der die UI beschrieben wird. Wir empfehlen die folgenden übergeordneten Schritte.

Bestimmen Sie den UI-Status, mit dem die einzelnen Callbacks aktiviert und deaktiviert werden.
Definieren Sie diesen Status mit einem beobachtbaren Dateninhabertyp wie StateFlow oder dem Erstellungsstatus und aktivieren oder deaktivieren Sie den Callback, wenn sich der Status ändert.

Wenn Ihre Anwendung zuvor eine Back-Logik mit bedingten Anweisungen verknüpft hat, könnte dies bedeuten, dass Sie auf das Back-Ereignis reagieren, nachdem es bereits eingetreten ist. Ein Muster, das Sie bei neueren Callbacks vermeiden sollten. Verschieben Sie den Callback nach Möglichkeit aus der bedingten Anweisung und verknüpfen Sie ihn stattdessen mit einem beobachtbaren Datenspeichertyp.

Systemrückrufe für UI Logic verwenden

Die UI-Logik bestimmt, wie die UI angezeigt wird. Verwenden Sie Systemrückrufe, um UI-Logik auszuführen, z. B. das Anzeigen von Pop-ups oder das Ausführen einer Animation.

Wenn Ihre App einen Systemrückruf ermöglicht, werden die Vorhersageanimationen nicht ausgeführt und Sie müssen das Back-Ereignis verarbeiten. Erstellen Sie keine Callbacks, die nur zur Ausführung von Logiken außerhalb der Benutzeroberfläche dienen.

Wenn Sie beispielsweise Ereignisse nur zum Protokollieren abfangen, protokollieren Sie sie stattdessen im Aktivitäts- oder Fragmentlebenszyklus.

Für Fälle, bei denen eine Aktivität zu einer Aktivität oder ein Fall von einem Teil einer Aktivität erfolgt, muss Folgendes protokolliert werden: isFinishing innerhalb von onDestroy innerhalb des Aktivitätslebenszyklus true.
Bei Fragment-zu-Fragment-Fällen muss protokolliert werden, wenn isRemoving in onDestroy innerhalb des Ansichtslebenszyklus des Fragments wahr ist. Oder protokolliere mit der Methode onBackStackChangeStarted oder onBackStackChangeCommitted innerhalb von FragmentManager.OnBackStackChangedListener.

Protokolliere für den Compose-Fall im onCleared()-Callback einer ViewModel, die 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 gelöscht wurde.

Callbacks für einzelne Verantwortung erstellen

Dies ist möglich, da Sie mehrere Rückrufe an den Disponenten hinzufügen können. Die Callbacks werden einem Stack hinzugefügt, in dem der zuletzt hinzugefügte aktivierte Callback die nächste „Zurück“-Geste mit einem Callback pro „Zurück“-Touch-Geste verarbeitet.

Animation der vorausschauenden „Zurück“-Touch-Geste testen

Ab dem endgültigen Release von Android 13 sollten Sie eine Entwickleroption aktivieren können, um die in Abbildung 1 gezeigte Back-to-Home-Animation zu testen.

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

Rufen Sie auf Ihrem Gerät Einstellungen > System > Entwickleroptionen auf.
Wählen Sie Vorhersehbare Rückwärtsanimationen aus.
Starten Sie die aktualisierte App und verwenden Sie die „Zurück“-Geste, um sie in Aktion zu sehen.