![](https://developer.android.com/static/images/about/versions/13/predictive-back-nav-home.gif?authuser=5&hl=fr)
Android 14 (niveau d'API 34) est compatible avec des animations système supplémentaires et avec des API permettant de créer des animations personnalisées. Pour en savoir plus, consultez Ajout de la prise en charge des animations intégrées et personnalisées pour la prévisualisation du 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 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 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.
Mettre à jour une application qui utilise le retour arrière par défaut
La mise à jour de votre application pour prendre en charge cette fonctionnalité est simple si votre application ne personnalise pas le comportement de retour (en d'autres termes, si elle laisse le système gérer les retours). Activez cette fonctionnalité comme décrit dans ce guide.
Si votre application utilise des fragments ou le composant Navigation, passez également à AndroidX Activity 1.6.0-alpha05 ou une version ultérieure.
Mettre à jour une application qui personnalise le retour arrière
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.
Votre application utilise AndroidX | Comment votre application gère le retour arrière | Processus de migration recommandé (lien sur cette page) |
Oui | API AndroidX | Migrer une implémentation existante de retour arrière AndroidX |
API de plate-forme non compatibles | Migrer une application AndroidX contenant des API de retour 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 retour 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 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é.
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 :
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"
Activez la prévisualisation du geste Retour, comme décrit sur cette page.
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 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 :
Migrez la logique de traitement des retours système vers
OnBackPressedDispatcher
d'AndroidX avec l'implémentation deOnBackPressedCallback
. Pour en savoir plus, consultez la page Fournir un retour arrière personnalisé.Désactivez
OnBackPressedCallback
lorsque vous êtes prêt à arrêter l'interception du geste de retour.Arrêtez toute interception d'événements de retour via
OnBackPressed
ouKeyEvent.KEYCODE_BACK
.Veillez à passer à 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"
Une fois la migration de votre application effectuée, activez la prévisualisation du geste Retour (comme décrit sur cette page) pour voir l'animation système de retour à la page d'accueil.
Migrer une application qui utilise des API de retour arrière non compatibles vers des API de plate-forme
Si votre application ne peut pas utiliser les bibliothèques AndroidX, et qu'elle implémente ou fait référence au retour arrière personnalisé à l'aide des API non compatibles, vous devez migrer vers l'API de plate-forme OnBackInvokedCallback
.
Effectuez les étapes suivantes pour migrer des API non compatibles vers l'API de plate-forme :
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.Enregistrez votre logique personnalisée des retours dans
OnBackInvokedCallback
aveconBackInvokedDispatcher
. 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é le retour arrière système.Annulez l'enregistrement de
OnBackInvokedCallback
lorsque vous êtes prêt à arrêter d'intercepter le geste de retour. Sinon, les utilisateurs risquent de constater un comportement indésirable lors de l'utilisation d'un retour arrière 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) */ } ); } }
Arrêtez toute interception d'événements de retour via
OnBackPressed
ouKeyEvent.KEYCODE_BACK
pour Android 13 et versions ultérieures.Une fois la migration de votre application effectuée, activez la prévisualisation du geste Retour (comme décrit sur cette page) pour qu'
OnBackInvokedCallback
prenne effet.
Vous pouvez enregistrer un OnBackInvokedCallback
avec PRIORITY_DEFAULT
ou PRIORITY_OVERLAY
, qui n'est pas disponible dans l'OnBackPressedCallback
AndroidX similaire. Il peut être utile d'enregistrer un rappel avec PRIORITY_OVERLAY
dans certains cas. Cela peut s'appliquer, par exemple, lorsque vous migrez depuis onKeyPreIme()
et que votre rappel doit recevoir le geste Retour au lieu d'un IME ouvert. Les IME enregistrent des rappels avec PRIORITY_DEFAULT
lorsqu'ils sont ouverts.
Enregistrez votre rappel avec PRIORITY_OVERLAY
pour vous assurer qu'OnBackInvokedDispatcher
envoie le geste Retour à votre rappel au lieu de l'IME ouvert.
Activer la prévisualisation du geste Retour
Une fois que vous avez déterminé comment mettre à jour votre application en fonction de votre situation, activez la prise en charge de 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, la valeur par défaut est false
, et les actions suivantes se déclenchent :
- L'animation système de la prévisualisation du geste Retour est désactivée.
OnBackInvokedCallback
est ignoré, mais les appelsOnBackPressedCallback
continuent de fonctionner.
Activer au niveau de l'activité
À partir d'Android 14, l'indicateur android:enableOnBackInvokedCallback
vous permet d'activer 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 d'utilisation de enableOnBackInvokedCallback
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>
Dans l'exemple précédent, la définition de android:enableOnBackInvokedCallback=true
pour ".SecondActivity"
active l'animation système multi-activités.
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-formeOnBackInvokedCallback
. Toutefois, les appels àOnBackPressedCallback
continuent de s'exécuter, carOnBackPressedCallback
est rétrocompatible et appelle l'APIonBackPressed
, 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.
Bonnes pratiques concernant les rappels
Voici les bonnes pratiques à suivre pour utiliser les rappels système compatibles : 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.
Déterminez l'état d'interface utilisateur qui activera et désactivera chaque rappel.
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, ce que vous devez éviter avec les rappels plus récents. 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 un pop-up ou exécuter une animation.
Si votre application active un rappel de retour système, les animations prédictives ne s'exécutent pas, et vous devez gérer l'événement "Retour". Ne créez pas de rappels uniquement pour exécuter une logique autre que celle de l'UI.
Par exemple, si vous n'interceptez les événements "Retour" que pour les consigner, consignez-les dans le cycle de vie de l'activité ou du fragment.
- Pour les cas d'activité à activité ou de fragment à activité, consignez-les si
isFinishing
dansonDestroy
esttrue
dans le cycle de vie de l'activité. - Pour les cas de fragment à fragment, consignez-les si
isRemoving
dansonDestroy
est true dans le cycle de vie de la vue du fragment, ou consignez-les à l'aide des méthodesonBackStackChangeStarted
ouonBackStackChangeCommitted
dansFragmentManager.OnBackStackChangedListener
.
Pour le cas Compose, connectez-vous au 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.
Créer des rappels à responsabilité unique
Cela est possible, car vous pouvez ajouter plusieurs rappels au dispatcher. 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.
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 :
Sur votre appareil, accédez à Paramètres > Système > Options pour les développeurs.
Sélectionnez Animations pour la prévisualisation du Retour.
Lancez votre application mise à jour et utilisez le geste Retour pour le voir en action.