À propos des encarts WindowInsets

La plate-forme Android est chargée de dessiner l'UI du système, comme la barre d'état et la barre de navigation. Cette UI système s'affiche, quelle que soit l'application utilisée par l'utilisateur.

WindowInsets fournit des informations sur l'UI du système pour s'assurer que votre application s'affiche dans la zone appropriée et que votre UI n'est pas masquée par l'UI du système.

Figure 1. Passer en mode bord à bord pour dessiner derrière les barres système

Sur Android 14 (niveau d'API 34) ou version antérieure, l'interface utilisateur de votre application ne s'affiche pas par défaut sous les barres système et les encoches.

Sur Android 15 (niveau d'API 35) ou version ultérieure, votre application s'affiche sous les barres système et les encoches une fois qu'elle cible le SDK 35. Cela permet d'offrir une expérience utilisateur plus fluide et de tirer pleinement parti de l'espace d'affichage disponible.

L'affichage du contenu derrière l'UI du système est appelé bord à bord. Sur cette page, vous allez découvrir les différents types d'encarts, comment passer en plein écran et comment utiliser les API d'encart pour animer votre interface utilisateur et vous assurer que le contenu de votre application n'est pas masqué par les éléments d'interface utilisateur du système.

Important : L'affichage de bord à bord est obligatoire sur Android 15 et versions ultérieures une fois que votre application cible le SDK 35. Si votre application n'est pas déjà de bord à bord, certaines parties de votre application peuvent être masquées et vous devez gérer les encarts. Selon l'application, ce travail peut être plus ou moins important. Le composant Material 3 Scaffold peut réduire le travail nécessaire pour être compatible avec l'application du mode sans bordure d'Android 15. Consultez Créer un composant Scaffold pour maintenir l'UI.

Principes de base des marges intérieures

Lorsqu'une application s'affiche de bord à bord, vous devez vous assurer que le contenu et les interactions importants ne sont pas masqués par l'UI du système. Par exemple, si un bouton est placé derrière la barre de navigation, l'utilisateur risque de ne pas pouvoir cliquer dessus.

La taille de l'UI du système et les informations sur son emplacement sont spécifiées à l'aide d'encarts.

Chaque partie de l'UI du système possède un type d'encart correspondant qui décrit sa taille et son emplacement. Par exemple, les encarts de la barre d'état fournissent la taille et la position de la barre d'état, tandis que les encarts de la barre de navigation fournissent la taille et la position de la barre de navigation. Chaque type d'encart se compose de quatre dimensions en pixels : haut, gauche, droite et bas. Ces dimensions indiquent la distance entre l'UI du système et les côtés correspondants de la fenêtre de l'application. Pour éviter tout chevauchement avec ce type d'UI système, l'UI de l'application doit donc être décalée de cette valeur.

Ces types d'encarts Android intégrés sont disponibles via WindowInsets :

WindowInsets.statusBars	Insets décrivant les barres d'état. Il s'agit des barres d'UI système supérieures contenant les icônes de notification et d'autres indicateurs.
WindowInsets.statusBarsIgnoringVisibility	Marges intérieures de la barre d'état lorsqu'elle est visible. Si les barres d'état sont masquées (en raison du passage en mode plein écran immersif), les encarts de la barre d'état principale seront vides, mais ces encarts ne seront pas vides.
WindowInsets.navigationBars	Insets décrivant les barres de navigation. Il s'agit des barres de l'UI du système situées à gauche, à droite ou en bas de l'appareil, qui décrivent la barre des tâches ou les icônes de navigation. Ces éléments peuvent changer au moment de l'exécution en fonction de la méthode de navigation préférée de l'utilisateur et de l'interaction avec la barre des tâches.
WindowInsets.navigationBarsIgnoringVisibility	Marges intérieures de la barre de navigation lorsqu'elles sont visibles. Si les barres de navigation sont masquées (en raison du passage en mode plein écran immersif), les encarts de la barre de navigation principale seront vides, mais pas ces encarts.
WindowInsets.captionBar	La marge intérieure décrivant la décoration de la fenêtre de l'UI du système si elle se trouve dans une fenêtre de forme libre, comme la barre de titre supérieure.
WindowInsets.captionBarIgnoringVisibility	Marges intérieures de la barre de légende lorsqu'elle est visible. Si les barres de sous-titres sont masquées, les encarts de la barre de sous-titres principale seront vides, mais ces encarts ne seront pas vides.
WindowInsets.systemBars	Union des encarts de la barre système, qui incluent les barres d'état, de navigation et de légende.
WindowInsets.systemBarsIgnoringVisibility	Insets de la barre système lorsqu'elle est visible. Si les barres système sont masquées (en raison du passage en mode plein écran immersif), les encarts de la barre système principale seront vides, mais ces encarts ne seront pas vides.
WindowInsets.ime	Insets décrivant l'espace occupé par le clavier virtuel en bas de l'écran.
WindowInsets.imeAnimationSource	Insets décrivant l'espace occupé par le clavier virtuel avant l'animation actuelle du clavier.
WindowInsets.imeAnimationTarget	Les encarts décrivant l'espace que le clavier virtuel occupera après l'animation actuelle du clavier.
WindowInsets.tappableElement	Type d'encarts décrivant plus en détail l'UI de navigation, indiquant l'espace où les "appuis" seront gérés par le système, et non par l'application. Pour les barres de navigation transparentes avec navigation par gestes, certains éléments de l'application peuvent être accessibles via l'UI de navigation du système.
WindowInsets.tappableElementIgnoringVisibility	Marges intérieures de l'élément cliquable lorsqu'il est visible. Si les éléments tactiles sont masqués (en raison du passage en mode plein écran immersif), les encarts des éléments tactiles principaux seront vides, mais ces encarts ne seront pas vides.
WindowInsets.systemGestures	Insets représentant la quantité d'insets où le système interceptera les gestes de navigation. Les applications peuvent spécifier manuellement la gestion d'un nombre limité de ces gestes à l'aide de Modifier.systemGestureExclusion.
WindowInsets.mandatorySystemGestures	Sous-ensemble des gestes système qui seront toujours gérés par le système et qui ne peuvent pas être désactivés à l'aide de Modifier.systemGestureExclusion.
WindowInsets.displayCutout	Marges intérieures représentant l'espacement nécessaire pour éviter tout chevauchement avec une découpe de l'écran (encoche ou trou).
WindowInsets.waterfall	Insets représentant les zones incurvées d'un écran Waterfall. Un écran incurvé comporte des zones incurvées le long des bords de l'écran, là où l'écran commence à s'enrouler sur les côtés de l'appareil.

Ces types sont résumés par trois types d'encarts "sûrs" qui garantissent que le contenu n'est pas masqué :

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

Ces types d'encarts "sécurisés" protègent le contenu de différentes manières, en fonction des encarts de la plate-forme sous-jacente :

• Utilisez WindowInsets.safeDrawing pour protéger le contenu qui ne doit pas être dessiné sous l'UI du système. Il s'agit de l'utilisation la plus courante des encarts : empêcher le dessin de contenu masqué par l'UI du système (partiellement ou complètement).
• Utilisez WindowInsets.safeGestures pour protéger le contenu avec des gestes. Cela évite que les gestes système n'entrent en conflit avec les gestes de l'application (comme ceux des bottom sheets, des carrousels ou des jeux).
• Utilisez WindowInsets.safeContent comme combinaison de WindowInsets.safeDrawing et WindowInsets.safeGestures pour vous assurer que le contenu ne présente aucun chevauchement visuel ni aucun chevauchement de gestes.