Découches dans Compose

Une encoche d'écran est une zone sur certains appareils qui s'étend sur la surface de l'écran. Il 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 d'écran sur les appareils équipés d'Android 9 (niveau d'API 28) ou version ultérieure. Toutefois, les fabricants d'appareils peuvent également prendre en charge les encoches d'affichage sur les appareils équipés d'Android 8.1 ou version antérieure.

Cette page explique comment prendre en charge les appareils avec des encoches dans Compose, y compris comment utiliser la zone de découpe, c'est-à-dire le rectangle de bord à bord sur la surface de l'écran qui contient la découpe.

Cas par défaut

Par défaut, les encoches d'affichage sont incluses dans les informations sur les encarts de fenêtre. Par conséquent, votre application ne s'affichera pas dans les zones de découpe de l'écran lorsque vous suivrez le guide pour l'afficher de bord à bord.

Par exemple, lorsque vous utilisez Modifier.windowInsetsPadding(WindowInsets.safeContent) ou Modifier.windowInsetsPadding(WindowInsets.safeDrawing), votre application ne dessine pas automatiquement les zones où une découpe est placée. WindowInsets.safeContent et WindowInsets.safeDrawing contiennent tous deux des informations sur la découpe de l'écran et ne dessinent pas l'emplacement d'une découpe de l'appareil.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    WindowCompat.setDecorFitsSystemWindows(window, false)

    setContent {
        Box(Modifier.windowInsetsPadding(WindowInsets.safeContent)) {
            // Any composable inside here will avoid drawing behind cutouts
        }
    }
}
CutoutSnippets.kt

Pour personnaliser davantage ce comportement, vous devez gérer vous-même les informations de découpe.

Gérer manuellement les informations de découpe

Vous pouvez gérer les découpes de l'une des manières suivantes:

• Utiliser WindowInsets.displayCutout

• Paramètre dans le fichier manifeste du thème avec android:windowLayoutInDisplayCutoutMode

• Définir de manière automatisée l'option sur un Window avec window.attributes.layoutInDisplayCutoutMode

• Accéder à l'objet Path de découpe avec LocalView.current.rootWindowInsets.displayCutout

Pour Compose, il est recommandé de définir windowLayoutInDisplayCutoutMode sur default dans votre thème global, puis d'utiliser WindowInsets.displayCutout pour gérer les encarts dans vos composables:

Canvas(modifier = Modifier.fillMaxSize().windowInsetsPadding(WindowInsets.displayCutout)) {
    drawRect(Color.Red, style = Stroke(2.dp.toPx()))
}
CutoutSnippets.kt

Cette approche vous permet de respecter la marge intérieure displayCutout lorsque cela est nécessaire, ou de l'ignorer lorsque ce n'est pas le cas.

Vous pouvez également appliquer les mêmes paramètres que la documentation sur les vues découpées en définissant le thème d'activité android:windowLayoutInDisplayCutoutMode sur une autre option ou en définissant l'attribut de fenêtre à l'aide de window.attributes.layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT. Toutefois, le mode découpé est ensuite appliqué à l'ensemble d'une activité et ne peut pas être contrôlé par composable individuel.

Pour respecter la découpe de l'écran dans certains composables, mais pas dans d'autres, utilisez WindowInset.displayCutout. Cette API vous permet d'accéder aux informations de découpe si nécessaire.

Bonnes pratiques

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

• Tenez compte du placement des éléments essentiels de l'interface utilisateur. Ne laissez pas la zone découpée masquer du texte, des commandes ou d'autres informations importants.
• Ne placez ni n'étendez aucun élément interactif nécessitant une reconnaissance tactile précise dans la zone découpée. La sensibilité tactile peut être plus faible dans la zone découpée.
• Lorsque vous suivez les conseils d'affichage bord à bord, les informations de découpe sont incluses dans les encarts safeDrawing / safeContent.
• Dans la mesure du possible, utilisez Modifier.windowInsetsPadding(WindowInsets.safeDrawing) pour déterminer la marge appropriée à appliquer à votre contenu. Évitez de coder en dur la hauteur de la barre d'état, car cela peut entraîner un chevauchement ou un contenu coupé.

Tester l'affichage de votre contenu avec des découpages

Veillez à tester tous les écrans et toutes les expériences de votre application. Si possible, effectuez des tests sur des appareils avec différents types de découpes. Si vous ne possédez pas d'appareil avec une encoche, vous pouvez simuler des configurations d'encoche courantes sur n'importe quel appareil ou émulateur exécutant Android 9 ou version ultérieure en procédant comme suit:

1. Activez les options pour les développeurs.
2. Sur l'écran Options pour les développeurs, faites défiler l'écran jusqu'à la section Drawing (Dessin) et sélectionnez Simulate a display with a cutout (Simuler un écran avec une encoche).
3. Sélectionnez le type de découpe.