Découches dans Compose

Une encoche est une zone sur certains appareils qui s'étend dans la surface d'affichage. Il offre une expérience bord à bord tout en laissant de l'espace pour d'importants capteurs à l'avant de l'appareil.

Android est compatible avec les encoches sur les appareils équipés d'Android 9 (niveau d'API 28) ou version ultérieure. Toutefois, les fabricants d'appareils peuvent également accepter les encoches sur les appareils équipés d'Android 8.1 ou version antérieure.

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

Cas par défaut

Par défaut, les encoches sont incluses dans les informations sur les encarts de la fenêtre. De ce fait, votre application ne dessine pas dans les zones d'encoche lorsque vous suivez le guide pour la rendre 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 l'encoche et ne tracent pas l'emplacement de l'encoche 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 d'encoche.

Gérer manuellement les informations d'encoche

Vous pouvez gérer les découpes de différentes manières:

• Avec WindowInsets.displayCutout

• Paramètre 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 de découpe avec LocalView.current.rootWindowInsets.displayCutout

Pour Compose, nous vous recommandons de définir windowLayoutInDisplayCutoutMode sur default dans votre thème général, puis d'exploiter 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 si nécessaire ou de l'ignorer lorsqu'elle n'est pas requise.

Vous pouvez également appliquer les mêmes paramètres que ceux décrits dans la documentation sur Views Cutout 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 Encoche est ensuite appliqué à l'ensemble d'une activité et ne peut pas être contrôlé 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 aux informations d'encoche si nécessaire.

Bonnes pratiques

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

• Faites attention au placement des éléments critiques de l'interface utilisateur. Ne laissez pas la zone de découpe masquer le texte, les commandes ou d'autres informations importants.
• Ne placez pas et ne étendez pas d'éléments interactifs nécessitant une reconnaissance tactile dans la zone d'encoche. La sensibilité tactile peut être plus faible dans la zone de découpe.
• Lorsque vous suivez les conseils bord à bord, les informations d'encoche sont incluses dans les encarts safeDrawing / safeContent.
• Dans la mesure du 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 une coupure du contenu.

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

Veillez à tester tous les écrans et toutes les expériences de votre application. Faites des tests sur des appareils avec différents types d'encoches, si possible. Si vous n'avez pas d'appareil avec découpe, vous pouvez simuler des configurations d'encoche courantes sur n'importe quel appareil ou émulateur exécutant Android 9 ou une 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 la page jusqu'à la section Dessin et sélectionnez Simuler un écran avec une encoche.
3. Sélectionnez le type d'encoche.

   

Recommandations personnalisées

• Remarque : Le texte du lien s'affiche lorsque JavaScript est désactivé
• Encarts de fenêtre dans Compose
• Modificateurs graphiques
• Style de paragraphe