Ajouter la prise en charge de la prévisualisation du geste Retour

Stay organized with collections Save and categorize content based on your preferences.
Figure 1 : Mockup de l'apparence de la prévisualisation du geste Retour sur un téléphone

Android 13 (niveau d'API 33) introduit la prévisualisation du geste Retour pour les appareils Android tels que les téléphones, les grands écrans et les pliables. Cette fonctionnalité fait partie d'une version pluriannuelle. Lorsqu'elle est entièrement mise en œuvre, elle permet aux utilisateurs de prévisualiser la destination ou un autre résultat d'un geste Retour avant de l'exécuter complètement. Ils peuvent ainsi décider de continuer ou de rester dans l'affichage actuel.

Par exemple, vous pouvez utiliser le geste Retour pour afficher un aperçu animé de l'écran d'accueil derrière votre application, comme illustré dans le mockup de la figure 1. À partir d'Android 13, vous pouvez tester cette animation de retour à l'écran d'accueil en activant une option pour les développeurs (comme décrit sur cette page).

La prise en charge de la prévisualisation du geste Retour nécessite la mise à jour de votre application, l'utilisation de OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) ou d'une API supérieure, ou de la nouvelle API de la plate-forme OnBackInvokedCallback.

Cette mise à jour fournit un chemin de migration pour les API de navigation vers l'arrière qui ne sont plus prises en charge, et qui sont KeyEvent.KEYCODE_BACK, ainsi que pour toutes les classes avec des méthodes onBackPressed telles que Activity et Dialog.

Atelier de programmation et vidéo Google I/O

En plus d'utiliser cette documentation, essayez notre atelier de programmation. Vous y découvrirez un exemple d'implémentation courante de WebView avec gestion de la prévisualisation du geste Retour via les API AndroidX Activity.

Vous pouvez également regarder notre vidéo Google I/O, qui montre d'autres exemples d'implémentation des API AndroidX et Platform.

Mettre à jour une application qui utilise la navigation vers l'arrière par défaut

La mise à jour de votre application pour prendre en charge cette fonctionnalité est simple si votre application n'implémente aucun comportement de retour personnalisé (en d'autres termes, si elle laisse le système gérer les retours). Il vous suffit d'activer cette fonctionnalité comme décrit sur cette page.

Mettre à jour une application qui utilise la navigation vers l'arrière personnalisée

Si votre application implémente un comportement de retour personnalisé, il existe différents chemins de migration selon qu'elle utilise AndroidX ou non, et selon la manière dont elle gère la navigation vers l'arrière.

Votre application utilise AndroidX Comment votre application gère la navigation vers l'arrière Processus de migration recommandé (lien sur cette page)
Oui API AndroidX Migrer une implémentation existante de navigation vers l'arrière AndroidX
API de plate-forme non compatibles Migrer une application AndroidX contenant des API de navigation vers l'arrière non compatibles vers les API AndroidX
Non API de plate-forme non compatibles, possibilité de migration Migrer une application qui utilise des API de navigation vers l'arrière non compatibles vers des API de plate-forme
API de plate-forme non compatibles, mais migration impossible Différer l'activation jusqu'à ce que cette fonctionnalité devienne obligatoire

Migrer une implémentation AndroidX pour la navigation vers l'arrière

Ce cas d'utilisation est le plus courant (et le plus recommandé). Il s'applique aux applications nouvelles ou existantes qui implémentent la gestion de la navigation par gestes personnalisée avec OnBackPressedDispatcher, comme décrit dans la section Fournir une navigation vers l'arrière personnalisée.

Si votre application appartient à cette catégorie, suivez les étapes ci-dessous pour ajouter la prise en charge de la prévisualisation du geste Retour :

  1. Pour vous assurer que les API qui utilisent déjà des API OnBackPressedDispatcher (comme les fragments et le composant Navigation) fonctionnent de manière fluide avec la prévisualisation du geste Retour, passez à 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. Activez la prévisualisation du geste Retour, comme décrit sur cette page.

Migrer une application AndroidX contenant des API de navigation vers l'arrière non compatibles vers les API AndroidX

Si votre application utilise des bibliothèques AndroidX, mais met en œuvre ou fait référence à des API de navigation vers l'arrière non compatibles, vous devrez migrer vers les API AndroidX pour prendre en charge le nouveau comportement.

Pour migrer des API non compatibles vers les API AndroidX :

  1. Migrez la logique de traitement des retours système vers OnBackPressedDispatcher d'AndroidX avec l'implémentation de OnBackPressedCallback. Pour en savoir plus, consultez la page Fournir une navigation vers l'arrière personnalisée.

  2. Pour arrêter d'intercepter la navigation vers l'arrière du système, désactivez les instances de OnBackPressedCallback déjà activées ou n'activez aucun rappel.

  3. Veillez à mettre à niveau vers 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"
    
  4. Une fois la migration de votre application terminée, activez la prévisualisation du geste Retour comme décrit sur cette page.

Migrer une application qui utilise des API de navigation vers l'arrière non compatibles vers des API de plate-forme

Si votre application ne peut pas utiliser les bibliothèques AndroidX, et qu'elle met en œuvre ou fait référence à la navigation vers l'arrière personnalisée à l'aide des API non compatibles, vous devez migrer vers l'API de la plate-forme OnBackInvokedCallback.

Effectuez les étapes suivantes pour migrer des API non compatibles vers l'API de la plate-forme :

  1. Utilisez la nouvelle API OnBackInvokedCallback sur les appareils équipés d'Android 13 ou version ultérieure, et utilisez les API non compatibles sur les appareils équipés d'Android 12 ou version antérieure.

  2. Enregistrez votre logique personnalisée des retours dans OnBackInvokedCallback, et intégrez la logique dans la méthode onBackInvoked. Cela empêche la fin de l'activité actuelle, et votre rappel peut réagir à l'action Retour une fois que l'utilisateur a terminé la navigation vers l'arrière du système.

  3. Pour garantir la bonne prise en charge des futures améliorations de la navigation vers l'arrière, votre application DOIT se désinscrire de OnBackInvokedCallback. Sinon, les utilisateurs risquent de constater un comportement indésirable lors de l'utilisation de la navigation vers l'arrière du système (comme rester bloqués entre les affichages et être forcés de quitter l'application).

    Voici un exemple de migration de logique hors de 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. Une fois la migration de votre application effectuée, activez la prévisualisation du geste Retour comme décrit dans la section suivante.

Activer la prévisualisation du geste Retour

Une fois que vous avez déterminé comment mettre à jour votre application en fonction de votre situation, vous pouvez facilement prendre en charge la prévisualisation du geste Retour.

Pour activer cette option, dans AndroidManifest.xml, dans la balise <application>, définissez l'option android:enableOnBackInvokedCallback sur true.

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

Si vous ne fournissez pas de valeur, elle est définie par défaut sur false et désactive la prévisualisation du geste Retour.

Tester l'animation de la prévisualisation du geste Retour

À partir de la version finale d'Android 13, vous devriez pouvoir activer une option de développeur afin de tester l'animation de retour à la page d'accueil, illustrée à la figure 1.

Pour tester cette animation, procédez comme suit :

  1. Sur votre appareil, accédez à Paramètres > Système > Options pour les développeurs.

  2. Sélectionnez Animations pour la prévisualisation du Retour.

  3. Lancez votre application mise à jour et utilisez le geste Retour pour le voir en action.