Diese Seite wurde von der Cloud Translation API übersetzt.

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

**Abbildung 1.** Mockup der automatischen Vervollständigung für die Touch-Geste „Zurück“ auf einem Smartphone

Android 14 (API-Level 34) unterstützt zusätzliche Systemanimationen und APIs zum Erstellen benutzerdefinierter Animationen. Weitere Informationen findest du unter Unterstützung für integrierte und benutzerdefinierte Animationen mit Vorhersagen.

Mit einer Zurück-Geste kann beispielsweise eine animierte Vorschau des Startbildschirms hinter Ihrer App angezeigt werden, wie im Modell 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).

Um die Touch-Geste „Zurücksagen“ zu unterstützen, musst du deine App aktualisieren, die abwärtskompatible API OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) oder höher verwenden oder die neue OnBackInvokedCallback Platform API verwenden. Die meisten Apps verwenden die abwärtskompatible AndroidX API.

Dieses Update bietet einen Migrationspfad, um die Rücknavigation ordnungsgemäß abzufangen. Dazu gehört das Ersetzen von Back-Interceptions von KeyEvent.KEYCODE_BACK und allen Klassen durch onBackPressed-Methoden wie Activity und Dialog durch die neuen Back APIs des Systems.

Video zu Codelab und Google I/O

Sie können nicht nur die Dokumentation auf dieser Seite verwenden, sondern auch unser Codelab ausprobieren. Sie 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 ansehen, das weitere Beispiele zur Implementierung der AndroidX- und Plattform-APIs enthält.

App aktualisieren, die die standardmäßige „Zurück“-Navigation verwendet

Es ist ganz einfach, die App zur Unterstützung dieser Funktion zu aktualisieren, wenn sie kein benutzerdefiniertes Zurück-Verhalten implementiert, d. h., die Verarbeitung wird vom System übernommen. Aktivieren Sie diese Funktion wie in diesem Leitfaden beschrieben.

Wenn Ihre App Fragmente oder die Navigationskomponente verwendet, führen Sie außerdem ein Upgrade auf AndroidX Activity 1.6.0-alpha05 oder höher aus.

App aktualisieren, die benutzerdefinierte Rückwärtsnavigation verwendet

Wenn Ihre App ein benutzerdefiniertes Zurück-Verhalten implementiert, gibt es verschiedene Migrationspfade, je nachdem, ob AndroidX verwendet wird und wie die Zurück-Navigation verarbeitet wird.

Deine App verwendet AndroidX	So funktioniert die Rückwärtsnavigation in Ihrer App	Empfohlener Migrationspfad (Link auf dieser Seite)
Ja	AndroidX-APIs	Vorhandene AndroidX-Back-Implementierung migrieren
Ja	Nicht unterstützte Plattform-APIs	Eine AndroidX-App mit nicht unterstützten APIs zur Rücknavigation zu AndroidX APIs migrieren
Nein	Nicht unterstützte Plattform-APIs, Migration möglich	Eine App, die nicht unterstützte Zurücknavigations-APIs verwendet, zu Plattform-APIs migrieren
Nein	Nicht unterstützte Plattform-APIs können aber nicht migriert werden	Aktivierung verschieben, bis diese Funktion erforderlich wird

AndroidX-Implementierung für die Rückwärtsnavigation migrieren

Dies ist der häufigste (und der am häufigsten empfohlene) Anwendungsfall. Sie gilt für neue oder bestehende Apps, in denen die benutzerdefinierte Bedienung über Gesten mit OnBackPressedDispatcher implementiert wird, wie unter Benutzerdefinierte Zurück-Navigation anbieten beschrieben.

Wenn deine App in diese Kategorie fällt, kannst du so vorgehen, um Unterstützung für die voraussagende Zurück-Touch-Geste hinzuzufügen:

Führen Sie ein Upgrade auf AndroidX Activity 1.6.0-alpha05 durch, damit APIs, die bereits OnBackPressedDispatcher-APIs verwenden (z. B. Fragmente und die Navigationskomponente) reibungslos mit der voraussagenden Zurück-Touch-Geste funktionieren.
```
// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```
Aktiviere die automatische Vervollständigung für die Touch-Geste „Zurück“, wie auf dieser Seite beschrieben.

AndroidX-App mit nicht unterstützten APIs zur Rücknavigation zu AndroidX APIs migrieren

Wenn deine App AndroidX-Bibliotheken verwendet, aber die nicht unterstützten APIs zur Zurücknavigation 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:

Migriere die Back-Handling-Logik deines Systems mit einer Implementierung von OnBackPressedCallback zur OnBackPressedDispatcher von AndroidX. Eine ausführliche Anleitung finden Sie unter Benutzerdefinierte „Zurück“-Navigation.
Deaktiviere die OnBackPressedCallback, wenn du bereit bist, das Abfangen der Gegenbewegung zu beenden.
Beenden Sie das Abfangen von Ereignissen über OnBackPressed oder KeyEvent.KEYCODE_BACK.

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"

Wenn Sie Ihre App erfolgreich migriert haben, aktivieren Sie die Touch-Geste „Vorhersagbar“ (wie auf dieser Seite beschrieben), um die Systemanimation zur Rückwärtsbewegung 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 Handling-Logik Ihrer App aus, wenn sie OnBackPressedCallback verwendet.

App, die nicht unterstützte APIs zur Rücknavigation verwendet, 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:

Verwenden Sie die neue OnBackInvokedCallback API auf Geräten mit Android 13 oder höher und nutzen Sie die nicht unterstützten APIs auf Geräten mit Android 12 oder niedriger.
Registrieren Sie Ihre benutzerdefinierte Back-Logik in OnBackInvokedCallback mit onBackInvokedDispatcher. Dadurch wird verhindert, dass die aktuelle Aktivität abgeschlossen wird. Dein Callback hat die Möglichkeit, auf die „Zurück“-Aktion zu reagieren, sobald der Nutzer die „Zurück“-Navigation des Systems abgeschlossen hat.

Hebe die Registrierung von OnBackInvokedCallback auf, wenn du bereit bist, das Abfangen der „Zurück“-Geste zu beenden. Andernfalls bemerken Nutzer möglicherweise ein unerwünschtes Verhalten bei der Verwendung der Zurück-Navigation, z. B. wenn sie zwischen Ansichten hängen bleiben und ein Beenden der App erzwingen.

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)
           */
        }
    );
  }
}

Beenden Sie das Abfangen von Ereignissen über OnBackPressed oder KeyEvent.KEYCODE_BACK für Android 13 und höher.
Wenn Sie Ihre App erfolgreich migriert haben, aktivieren Sie die Touch-Geste für die automatische Vervollständigung (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. Die Registrierung eines Callbacks mit PRIORITY_OVERLAY ist in einigen Fällen hilfreich. Dies kann beispielsweise der Fall sein, wenn du von onKeyPreIme() migrierst und dein Callback die Zurück-Geste anstelle eines offenen IMEs erhalten muss. IMEs registrieren Callbacks beim Öffnen 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 du dich entschieden hast, wie du deine App auf Grundlage deines Falls aktualisieren sollst, aktiviere die Option zur automatischen Vervollständigung der Touch-Geste „Zurück“.

Legen Sie zum Aktivieren in AndroidManifest.xml im <application>-Tag das Flag android:enableOnBackInvokedCallback auf true fest.

<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, aber OnBackPressedCallback-Aufrufe funktionieren weiterhin.

Auf Aktivitätsebene aktivieren

Ab Android 14 können Sie mit dem Flag android:enableOnBackInvokedCallback prädiktive Systemanimationen auf Aktivitätsebene aktivieren. Dadurch ist es einfacher, große Anwendungen mit mehreren Aktivitäten zu vorausschauenden Touch-Gesten zu migrieren.

Der folgende Code zeigt ein Beispiel für die Verwendung von enableOnBackInvokedCallback, um die Back-to-Home-Systemanimation aus 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 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 du android:enableOnBackInvokedCallback=false festlegst, werden Animationen für die Rückwärtsbewegung entweder auf Aktivitätsebene oder auf App-Ebene deaktiviert, je nachdem, wo du das Tag festgelegt hast. 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 Compose), OnBackPressedCallback oder OnBackInvokedCallback.

Bestimmen Sie den UI-Status, der die einzelnen Callbacks aktiviert und deaktiviert

Der UI-Status ist eine Eigenschaft, die die UI beschreibt. Wir empfehlen, die folgenden übergeordneten Schritte zu befolgen.

Bestimmen Sie den UI-Status, mit dem die einzelnen Callbacks aktiviert und deaktiviert werden.
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 Ihre App zuvor eine Backlogik mit bedingten Anweisungen verknüpft hat, könnte dies bedeuten, dass Sie auf das „back“-Ereignis reagieren, nachdem es bereits aufgetreten ist. Dieses Muster sollten Sie bei neueren Callbacks vermeiden. Verschieben Sie den Callback nach Möglichkeit aus der bedingten Anweisung und ordnen Sie ihn stattdessen einem beobachtbaren Datenhaltertyp zu.

System-Back-Callbacks für UI Logic verwenden

Die UI-Logik legt fest, wie die UI angezeigt wird. Verwenden Sie System-Back-Callbacks, um UI-Logik auszuführen, z. B. das Anzeigen eines Pop-ups oder das Ausführen einer Animation.

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 nur für die Ausführung von Nicht-UI-Logik.

Wenn Sie beispielsweise Ereignisse nur zum Protokollieren abfangen, protokollieren Sie sie stattdessen innerhalb des Aktivitäts- oder Fragment-Lebenszyklus.

Bei Aktivitäten-zu-Aktivität-Fällen oder Fragment-zu-Aktivität-Fällen wird protokolliert, wenn isFinishing in onDestroy innerhalb des Aktivitätslebenszyklus true ist.
Logge bei Fragment-zu-Fragment-Fällen, ob isRemoving in onDestroy innerhalb des Ansichtslebenszyklus des Fragments wahr ist, oder protokolliere das Log mit der Methode onBackStackChangeStarted oder onBackStackChangeCommitted innerhalb von FragmentManager.OnBackStackChangedListener.

Protokollieren Sie für den „Compose“-Fall im onCleared()-Callback einer ViewModel, die dem Compose-Ziel zugeordnet ist. Dies ist das beste Signal, um zu wissen, wann ein Erstellungsziel vom Back-Stack getrennt und zerstört wurde.

Callbacks für einzelne Verantwortung erstellen

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

Animation mit Vorschlägen für „Zurück“-Touch-Geste testen

Ab der endgültigen Version von Android 13 solltest du eine Entwickleroption aktivieren können, mit der du die in Abbildung 1 gezeigte Animation von der Startseite testen kannst.

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 Hintergrundanimationen vorausschauend aus.
Starte die aktualisierte App und verwende die Touch-Geste „Zurück“, um sie in Aktion zu sehen.