Assurer la compatibilité avec les encoches

Essayer Compose
Jetpack Compose est le kit d'outils d'interface utilisateur recommandé pour Android. Découvrez comment utiliser les encoches dans Compose.
<ph type="x-smartling-placeholder"></ph> Afficher les encoches dans Compose →

Une encoche est une zone située sur certains appareils qui s'étend sur toute la surface de l'écran. Elle offre une expérience bord à bord tout en laissant de l’espace pour les capteurs importants à l’avant de l’appareil.

Android est compatible avec les encoches sur les appareils équipés d'Android 9 (niveau d'API 28) et plus élevée. Toutefois, les fabricants d'appareils peuvent également prendre en charge les encoches sur appareils équipés d'Android 8.1 ou version antérieure.

Ce document explique comment prendre en charge les appareils avec encoches, y compris sur l'utilisation de la zone d'encoche, c'est-à-dire la bordure rectangle sur la surface de l'écran contenant l'encoche.

Image montrant un exemple d&#39;encoche en haut au centre
Image 1. 1 Écran encoche.

Choisissez comment votre application gère les zones d'encoche

Si vous ne souhaitez pas que votre contenu chevauche une encoche, pour que votre contenu ne chevauche pas la barre d'état et le barre de navigation. Si vous effectuez le rendu dans la zone d'encoche, utilisez WindowInsetsCompat.getDisplayCutout() pour récupérer un objet DisplayCutout qui contient les encarts sûrs et le cadre de délimitation pour chaque encoche. Ces API permettent vous pouvez vérifier si votre contenu chevauche l'encoche repositionnez-les si nécessaire.

Vous pouvez également déterminer si le contenu est disposé derrière l'encoche. La layoutInDisplayCutoutMode L'attribut de mise en page de la fenêtre contrôle la façon dont votre contenu est dessiné dans la zone d'encoche. Vous pouvez définir layoutInDisplayCutoutMode sur l'une des valeurs suivantes:

  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT: le contenu s'affiche dans l'encoche lorsque celle-ci est contenue la barre système. Sinon, la fenêtre ne chevauche pas l'encoche. pour Par exemple, le contenu peut être au format letterbox lorsqu'il est affiché en mode Paysage. Si votre application cible le SDK 35, ce qui est interprété comme ALWAYS pour les créations non flottantes. Windows.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS: contenu est toujours autorisé à s'étendre dans les zones d'encoche. Si votre application cible SDK 35 et qu'il s'exécute sur un appareil Android 15, c'est le seul mode autorisé pour pour garantir un affichage bord à bord.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: le contenu s'affiche dans la zone d'encoche en mode portrait et paysage. À ne pas faire utiliser pour les fenêtres flottantes. Si votre application cible le SDK 35, cela est interprété comme ALWAYS pour les fenêtres non flottantes.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: le contenu ne s'affiche jamais dans la zone d'encoche. Si votre application cible le SDK 35, interprétée comme ALWAYS pour les fenêtres non flottantes.

Vous pouvez définir le mode d'encoche soit par programmation, soit en définissant un style dans votre activité. Les éléments suivants : L'exemple définit un style pour appliquer LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES à l'activité.

<style name="ActivityTheme">
  <item name="android:windowLayoutInDisplayCutoutMode">
    shortEdges <!-- default, shortEdges, or never -->
  </item>
</style>

Les sections suivantes décrivent plus en détail les différents modes de découpe.

Comportement par défaut

Si votre application cible le SDK 35 et s'exécute sur un appareil Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS est le comportement par défaut. LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT est interprété comme LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS pour les fenêtres non flottantes.

Sinon, LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT est la valeur par défaut.

Afficher le contenu dans les encoches des bords courts

Si votre application cible le SDK 35 et s'exécute sur un appareil Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES est interprété comme LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS pour les fenêtres non flottantes.

Avec LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, le le contenu s'étend dans la zone d'encoche sur le bord court de l'écran en mode portrait et paysage, que les barres système soient masquées ou non visible. Lorsque vous utilisez ce mode, assurez-vous qu'aucun contenu important ne chevauche la zone de l'encoche.

L'image suivante est un exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES pour un appareil en mode portrait:

Image montrant le rendu du contenu dans la zone de l&#39;encoche en mode Portrait
Figure 2 : Rendu du contenu dans la zone d'encoche en mode Portrait.

L'image suivante est un exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES pour un appareil en mode paysage:

Image montrant le rendu du contenu dans la zone d&#39;encoche en mode Paysage
Figure 3 : Rendu du contenu dans la zone d'encoche en mode Paysage.

Dans ce mode, la fenêtre s'étend sous les encoches sur le bord court de l'écran en mode portrait et paysage, que la fenêtre masque ou non la barres système.

Une encoche dans un coin est considérée comme sur le bord court:

Image montrant un appareil avec une découpe dans un angle
Figure 4 : Un appareil avec une découpe dans un coin.

Ne jamais afficher de contenu dans l'encoche

Si votre application cible le SDK 35 et s'exécute sur un appareil Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER est interprété comme LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS pour les fenêtres non flottantes.

Avec LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER, la fenêtre n'est jamais autorisée à avec la zone de l'encoche.

Voici un exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER dans portrait:

Image montrant l&#39;option LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER pour le mode Portrait
Figure 5 : Exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER pour le mode Portrait.

Voici un exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER dans Mode Paysage:

Image montrant l&#39;option LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER pour le mode paysage
Figure 6 : Exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en mode Paysage.

Bonnes pratiques concernant la compatibilité avec l'encoche

Lorsque vous utilisez des encoches, tenez compte des points suivants:

  • Faites attention au placement des éléments essentiels de l'interface utilisateur. Ne laissez pas le pour masquer le texte, les commandes ou toute autre information important.
  • Ne placez pas et n'étendez pas d'éléments interactifs qui nécessitent une dans la zone d'encoche. La sensibilité tactile peut être inférieure dans le dans la zone d'encoche.

  • Si possible, utilisez WindowInsetsCompat jusqu'à Récupérez la hauteur de la barre d'état et déterminez la marge intérieure appropriée à appliquer à votre contenu. Évitez de coder en dur la hauteur de la barre d'état, car cela peut entraîner les contenus qui se chevauchent ou sont tronqués.

    <ph type="x-smartling-placeholder">
    </ph> Image montrant du contenu découpé en haut pour une configuration incorrecte des encarts <ph type="x-smartling-placeholder">
    </ph> Figure 7. Utilisez WindowInsetsCompat pour évitez de chevaucher ou de couper le contenu.

  • Utiliser View.getLocationInWindow() pour déterminer l'espace de fenêtre utilisé par votre application. Ne partez pas du principe que l'application en utilisant la fenêtre entière et n'utilisez pas View.getLocationOnScreen()

  • Utilisez les modes de découpe always, shortEdges ou never si votre application doit avant et après le mode immersif. Le comportement par défaut de l'encoche contenu de votre application pour qu'il s'affiche dans la zone d'encoche lorsque les barres système mais pas en mode immersif. Cela entraîne le déplacement du contenu vers le haut pendant les transitions, comme illustré dans l'exemple suivant.

    <ph type="x-smartling-placeholder">
    </ph> Image montrant du contenu se déplaçant vers le haut et vers le bas lors des transitions <ph type="x-smartling-placeholder">
    </ph> Figure 8 : Exemple de contenu se déplaçant vers le haut et vers le bas pendant les transitions.

  • En mode immersif, vous devez choisir entre les coordonnées de fenêtre et d'écran, car votre application n'utilise pas tout l'écran au format letterbox. Grâce au letterbox, les coordonnées indiquées à partir de l'origine de l'écran ne sont pas identiques aux coordonnées depuis l'origine de la fenêtre. Vous pouvez transformer les coordonnées de l'écran en coordonnées selon vos besoins à l'aide de getLocationOnScreen(). L'image suivante affiche les différences de coordonnées lorsque le contenu est au format letterbox:

    <ph type="x-smartling-placeholder">
    </ph> Image montrant les coordonnées de fenêtre par rapport aux coordonnées de l&#39;écran lorsque le contenu est au format letterbox <ph type="x-smartling-placeholder">
    </ph> Figure 9 : Coordonnées de la fenêtre ou de l'écran au format letterbox.

  • Lors de la gestion de MotionEvent, utilisez MotionEvent.getX() et MotionEvent.getY() pour éviter des problèmes de coordonnée similaires. Ne pas utiliser MotionEvent.getRawX() ou MotionEvent.getRawY()

Tester le rendu de votre contenu

Testez tous les écrans et expériences de votre application. Effectuez des tests sur des appareils avec des types d'encoches, si possible. Si votre appareil n'est pas doté d'une encoche, vous pouvez simuler des configurations d'encoche courantes sur n'importe quel appareil ou émulateur exécutant Android ; version 9 ou ultérieure. Pour ce faire, procédez comme suit:

  1. Activez les Options pour les développeurs.
  2. Faites défiler l'écran Developer options (Options pour les développeurs) vers le bas jusqu'à la section Drawing (Dessin). puis sélectionnez Simuler un écran avec une encoche.

  3. Sélectionnez le type d'encoche.

    <ph type="x-smartling-placeholder">
    </ph> Image montrant comment simuler une encoche dans l&#39;émulateur <ph type="x-smartling-placeholder">
    </ph> Figure 10. Ces options vous permettent de tester l'efficacité le rendu du contenu.

Ressources supplémentaires