Découches dans Compose

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

Exemple de découpe en mode Portrait
Figure 1. Exemple de découpe en mode Portrait
Exemple de découpe en mode Paysage
Figure 2. Exemple de découpe en mode Paysage

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 prendre en charge les encoches sur les appareils équipés d'Android 8.1 ou version antérieure.

Cette page explique comment prendre en charge les appareils dotés d'une encoche dans Compose, y compris comment utiliser la zone d'encoche, c'est-à-dire le rectangle de bord à bord sur la surface d'affichage contenant l'encoche.

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 d'encoche lorsque vous suivez 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 dans les zones où une encoche est placée. WindowInsets.safeContent et WindowInsets.safeDrawing contiennent tous deux des informations sur l'encoche et ne dessinent pas là où se trouve cette encoche.

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 l'une des manières suivantes:

Pour Compose, nous vous recommandons de définir windowLayoutInDisplayCutoutMode sur default dans votre thème général, puis d'utiliser 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 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 de l'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écoupe est ensuite appliqué à l'ensemble de l'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.

pour réussir votre lancement

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 la zone d'encoche masquer un texte, des commandes ou d'autres informations importants.
  • Ne placez pas et n'étendez pas d'éléments interactifs nécessitant une reconnaissance tactile précise dans la zone d'encoche. La sensibilité tactile peut être inférieure dans la zone de l'encoche.
  • Lorsque vous suivez les instructions d'affichage bord à bord, les informations d'encoche 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 une coupure du contenu.

Tester le rendu de votre contenu avec les encoches

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

  1. Activez les Options pour les développeurs.
  2. Sur l'écran Developer options (Options pour les développeurs), faites défiler la page jusqu'à la section Drawing (Dessin), puis sélectionnez Simulate a display with a cutout (Simuler un écran avec une encoche).
  3. Sélectionnez le type d'encoche.
    simuler une encoche dans l'émulateur
    Figure 3. Utilisez les Options pour les développeurs pour tester l'affichage de votre contenu.