Découches dans Compose

Une encoche est une zone de certains appareils qui s'étend dans l'écran sur la surface de l'écran. Elle offre une expérience bord à bord tout en offrant de l'espace pour 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.

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 sont incluses dans les informations sur les encarts de la fenêtre. Pour cette raison, votre application ne dessine pas dans les zones de l'encoche lorsque vous suivez le guide pour afficher une application 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 encoche 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 d'encoche

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

• Avec WindowInsets.displayCutout

• Définition dans le fichier manifeste du thème avec android:windowLayoutInDisplayCutoutMode

• Définir l'option par programmation sur un Window avec window.attributes.layoutInDisplayCutoutMode

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

Pour Compose, nous vous recommandons de définir windowLayoutInDisplayCutoutMode sur default dans votre thème général, puis exploiter WindowInsets.displayCutout pour gérer les encarts de 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 ceux de la vue Views Cutout de la documentation décrit en paramétrant soit le thème de l'activité android:windowLayoutInDisplayCutoutMode, 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'encoche est ensuite appliqué à l'ensemble d'une activité et ne peuvent pas être contrôlés par composable individuel.

Pour respecter l'encoche dans certains composables, mais pas dans d'autres, utilisez WindowInset.displayCutout Cette API vous permet d'accéder à l'encoche des informations supplémentaires si nécessaire.

Bonnes pratiques

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 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 inférieure dans le dans la zone d'encoche.
• Lorsque vous suivez les conseils d'affichage bord à bord, les informations de découpe sont incluses dans les encarts safeDrawing/safeContent.
• Si possible, utilisez Modifier.windowInsetsPadding(WindowInsets.safeDrawing). pour déterminer 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 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 d'encoche.