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

La prévisualisation du Retour est une fonctionnalité de navigation par gestes qui permet aux utilisateurs de prévisualiser la page vers laquelle ils seront redirigés s'ils effectuent le geste Retour.

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 la figure 1.

À partir d'Android 15, l'option pour les développeurs concernant les animations pour la prévisualisation du Retour n'est plus disponible. Les animations système telles que le retour à l'écran d'accueil, le multitâche et le passage d'une activité à une autre s'affichent désormais pour les applications qui ont activé la prévisualisation du geste Retour, soit entièrement, soit au niveau d'une activité.

Vous pouvez tester cette animation de retour à l'écran d'accueil (comme décrit dans une section suivante de 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 rétrocompatible dans AndroidX Activity 1.6.0 ou une API supérieure, ou l'utilisation de la nouvelle API de plate-forme OnBackInvokedCallback. La plupart des applications utilisent l'API AndroidX rétrocompatible.

Cette mise à jour fournit un chemin de migration pour intercepter correctement le retour arrière au cours de la navigation, ce qui implique de remplacer les interceptions de KeyEvent.KEYCODE_BACK et toutes les classes avec des méthodes onBackPressed, telles que Activity et Dialog, par les nouvelles API système Back.

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 de plate-forme.

Gérer les gestes de retour personnalisés dans Compose

Compose fournit le composable PredictiveBackHandler pour gérer les gestes de retour personnalisés. Cette API vous permet de répondre au geste Retour et fournit un Flow d'objets BackEventCompat que vous pouvez utiliser pour implémenter des animations ou des transitions personnalisées lorsque l'utilisateur balaie l'écran.

Pour utiliser PredictiveBackHandler, assurez-vous que votre application inclut la dépendance androidx.activity:activity-compose (version 1.8.0 ou ultérieure) :

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}

PredictiveBackHandler(enabled = isBackHandlerEnabled) { progress: Flow<BackEventCompat> ->
    try {
        progress.collect { backEvent ->
            // Update your UI or animation based on backEvent.progress.
        }
        // Handle the final back action (e.g., navigate back).
    } catch (e: CancellationException) {
        // Back gesture was cancelled, reset your UI.
    }
}
PredictiveBackSnippets.kt

Si vous n'avez besoin que d'intercepter le geste Retour sans suivre la progression, utilisez BackHandler.

Mettre à jour une application qui utilise le retour arrière par défaut

La prévisualisation du retour en arrière est activée par défaut.

Si votre application utilise des fragments ou le composant Navigation, passez également à AndroidX Activity 1.6.0 ou version ultérieure.

Mettre à jour une application qui utilise le retour arrière personnalisé

Si votre application personnalise le comportement de retour, il existe différents chemins de migration selon qu'elle utilise AndroidX ou non, et selon la manière dont elle gère le retour arrière.

Migrer une implémentation AndroidX pour le retour 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 un retour arrière personnalisé.

Pour vous assurer que les API qui utilisent déjà 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 ou version ultérieure.

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

Migrer une application AndroidX contenant des API de retour arrière non compatibles vers les API AndroidX

Si votre application utilise des bibliothèques AndroidX, mais implémente ou fait référence à des API de retour en 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 un retour arrière personnalisé.

2. Désactivez OnBackPressedCallback lorsque vous êtes prêt à arrêter d'intercepter le geste de retour.

3. Arrêtez toute interception d'événements de retour à l'aide de OnBackPressed ou KeyEvent.KEYCODE_BACK.

4. Veillez à passer à AndroidX Activity 1.6.0 ou version ultérieure.

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

Désactiver la prévisualisation du geste Retour

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

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

Si vous définissez cette valeur sur "false", les actions suivantes sont effectuées :

• L'animation système de la prévisualisation du geste Retour est désactivée.
• OnBackInvokedCallback est ignoré, mais les appels OnBackPressedCallback continuent de fonctionner.

Désactiver au niveau de l'activité

L'indicateur android:enableOnBackInvokedCallback vous permet de désactiver les animations système prédictives au niveau de l'activité. Ce comportement facilite la migration des applications multi-activités volumineuses vers la prévisualisation des gestes Retour.

Le code suivant montre un exemple de enableOnBackInvokedCallback défini pour activer l'animation système de retour à l'écran d'accueil à partir de MainActivity :

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

        <activity
            android:name=".MainActivity"
            android:enableOnBackInvokedCallback="true"
            ...
        </activity>
        <activity
            android:name=".SecondActivity"
            android:enableOnBackInvokedCallback="false"
            ...
        </activity>
    </application>
</manifest>

Tenez compte des points suivants lorsque vous utilisez l'indicateur android:enableOnBackInvokedCallback :

• Définir android:enableOnBackInvokedCallback=false désactive les animations de prévisualisation du Retour soit au niveau de l'activité, soit au niveau de l'application, selon l'endroit où vous définissez la balise, et demande au système d'ignorer les appels à l'API de plate-forme OnBackInvokedCallback. Toutefois, les appels à OnBackPressedCallback continuent de s'exécuter, car OnBackPressedCallback est rétrocompatible et appelle l'API onBackPressed, qui n'est pas prise en charge avant Android 13.
• Définir l'indicateur enableOnBackInvokedCallback au niveau de l'application établit la valeur par défaut pour toutes les activités dans l'application. Vous pouvez ignorer la valeur par défaut par activité en définissant l'indicateur au niveau de l'activité, comme indiqué dans l'exemple de code précédent.

Consignes concernant les rappels

Suivez ces consignes lorsque vous utilisez les rappels système compatibles : PredictiveBackHandler ou BackHandler (pour Compose), OnBackPressedCallback ou OnBackInvokedCallback.

Déterminer l'état d'interface utilisateur qui activera et désactivera chaque rappel

L'état de l'UI est la propriété qui décrit l'UI. Nous vous recommandons de suivre ces étapes générales.

1. Déterminez l'état d'interface utilisateur qui activera et désactivera chaque rappel.

2. Définissez cet état à l'aide d'un type de conteneur de données observable, tel que StateFlow ou Compose State, puis activez ou désactivez le rappel lorsque l'état change.

Si votre application associait déjà une logique de retour à des instructions conditionnelles, cela peut signifier que vous réagissez à l'événement "Retour" une fois qu'il s'est déjà produit. Évitez ce schéma avec les nouveaux rappels. Si possible, déplacez le rappel en dehors de l'instruction conditionnelle et associez-le à un type de conteneur de données observables.

Utiliser des rappels système pour la logique d'UI

La logique d'UI détermine comment afficher l'interface utilisateur. Utilisez des rappels système pour exécuter une logique d'UI, par exemple pour afficher une boîte de dialogue ou exécuter une animation.

Si votre application active un OnBackPressedCallback ou un OnBackInvokedCallback avec PRIORITY_DEFAULT ou PRIORITY_OVERLAY, les animations pour la prévisualisation du Retour ne s'exécutent pas, et vous devez gérer l'événement "Retour". Ne créez pas ces rappels pour exécuter la logique métier ni pour consigner des informations.

Utilisez les approches suivantes si votre application doit exécuter une logique métier ou enregistrer des informations lorsque l'utilisateur effectue un balayage vers l'arrière :

• Dans Compose : enregistrez-vous dans le rappel onCleared() d'un ViewModel associé à la destination Compose. Il s'agit du meilleur signal pour savoir quand une destination Compose a été retirée de la pile "Retour" et détruite.
• Sur Android 16 ou version ultérieure : utilisez OnBackInvokedCallback avec PRIORITY_SYSTEM_NAVIGATION_OBSERVER. Cela crée un rappel d'observateur qui ne consomme pas l'événement "Retour". Par exemple, vous pouvez enregistrer ce rappel lorsque l'utilisateur balaie l'écran vers l'arrière depuis l'activité racine (en quittant votre application) pour enregistrer l'événement de retour ou exécuter une logique métier tout en permettant à l'animation de retour à l'écran d'accueil de se lancer.
• Dans les applications basées sur les vues : enregistrez les rappels de cycle de vie ou de pile de retour au lieu de consommer les événements de retour :
  • Pour les transitions d'activité, vérifiez si isFinishing est true dans Activity.onDestroy().
  • Pour les transitions de fragment, vérifiez si isRemoving est true dans le cycle de vie de la vue du fragment onDestroy(), ou utilisez FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted/onBackStackChangeCommitted).

Créer des rappels à responsabilité unique

Vous pouvez ajouter plusieurs rappels au répartiteur. Les rappels sont ajoutés à une pile dans laquelle le dernier rappel activé gère le geste Retour suivant, avec un rappel par geste Retour.

Il est plus facile de gérer l'état activé d'un rappel si ce rappel a une seule responsabilité. Exemple :

La figure 2 montre comment vous pouvez avoir plusieurs rappels dans la pile, chacun étant responsable d'une chose. Dans Compose, les rappels sont évalués du composable le plus intérieur au plus extérieur, et un rappel ne s'exécute que si les rappels qui le précèdent dans la pile sont désactivés :

• Le message "Voulez-vous vraiment…" PredictiveBackHandler est activé lorsque l'utilisateur saisit des données dans un formulaire, et désactivé dans le cas contraire. Lorsqu'il est activé, il intercepte le geste Retour pour afficher une boîte de dialogue de confirmation ou une animation personnalisée dans l'application.
• Le BackHandler au niveau de l'écran s'exécute si le rappel précédent est désactivé. Dans cet exemple, il est désactivé.
• Le rappel NavHost gère le retour en arrière pour supprimer les destinations de la pile "Retour" si les rappels personnalisés précédents sont désactivés.
• Enfin, le système gère le geste Retour si tous les rappels précédents sont désactivés. Lorsque la pile "Retour" est à sa destination racine, le système déclenche des animations au niveau du système, telles que le retour à l'écran d'accueil, le passage d'une activité à l'autre et le passage d'une tâche à l'autre.

Le même comportement de pile s'applique dans les applications basées sur des vues : le dernier OnBackPressedCallback activé ajouté est prioritaire, puis FragmentManager et enfin la gestion du Retour système.

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

À partir d'Android 15, les animations système telles que le retour à l'écran d'accueil, le passage d'une tâche à une autre et le passage d'une activité à une autre sont activées par défaut pour les applications qui prennent en charge la prévisualisation du Retour. Elles ne sont plus associées à une option pour les développeurs.

Sur les appareils équipés d'Android 13 ou d'Android 14, vous pouvez activer l'option pour les développeurs afin de tester l'animation de retour à l'écran d'accueil illustrée à la figure 1 :

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.