Box dans Jetpack Compose : qu'est-ce que c'est, propriétés composables et fonctionnement

Qu'est-ce que Box dans Jetpack Compose ?

Box est une fonction composable qui place les éléments enfants dans la même zone, les empilant les uns sur les autres. Le premier élément enfant est dessiné en bas, le dernier en haut. Par défaut, Box s'ajuste à la taille du plus grand élément enfant.

Contrairement à Row et Column, Box n'organise pas les éléments séquentiellement — tous les éléments enfants occupent la même zone et peuvent se chevaucher. Cela rend Box indispensable pour composer des couches d'interface.

La taille de Box est déterminée par la règle : si aucun élément enfant n'a de taille fixe, Box se réduit à la taille minimale. Si au moins un élément enfant a Modifier.fillMaxSize, Box s'étend au maximum.

Selon Android Developers Blog, 2024, Box est le conteneur le plus efficace dans Compose pour les cas où les éléments ne nécessitent pas de disposition séquentielle. Box n'effectue pas de mesures supplémentaires pour le positionnement, contrairement à Row et Column.

Signature de base de Box

Box accepte les paramètres modifier, contentAlignment et propagateMinConstraints. Tous les éléments enfants sont passés dans le bloc content, où chacun peut avoir ses propres modificateurs.

@Composable
fun BoxExample() {
    Box(
        modifier = Modifier.size(200.dp),
        contentAlignment = Alignment.Center
    ) {
        Box(
            modifier = Modifier.fillMaxSize().background(Color.Blue)
        )
        Text(
            text = "Bonjour",
            color = Color.White
        )
    }
}

ContentAlignment et Modifier.align dans Box

contentAlignment est un paramètre de Box qui définit l'alignement par défaut pour tous les éléments enfants. S'il n'est pas spécifié, Alignment.TopStart est utilisé — les éléments sont placés dans le coin supérieur gauche du conteneur.

Modifier.align permet de remplacer l'alignement d'un élément enfant spécifique indépendamment de contentAlignment. Par exemple, un Box avec Alignment.Center peut contenir un élément avec Modifier.align(Alignment.BottomEnd) qui sera fixé dans le coin inférieur droit.

Selon les Material Design Guidelines, 2025, Modifier.align est utile pour positionner des badges et des icônes sur des images d'arrière-plan. Cela permet de définir un alignement général pour tout le contenu de Box et de le remplacer pour des éléments individuels.

Tableau des valeurs d'Alignment

Exemple avec Modifier.align

Dans cet exemple, Box contient une image d'arrière-plan et un badge dans le coin inférieur droit. Modifier.align(BottomEnd) positionne le badge indépendamment du contentAlignment de Box.

@Composable
fun BadgeExample() {
    Box(
        modifier = Modifier.size(120.dp),
        contentAlignment = Alignment.Center
    ) {
        Box(
            modifier = Modifier.size(100.dp).background(Color.Gray)
        )
        Box(
            modifier = Modifier
                .size(30.dp)
                .align(Alignment.BottomEnd)
                .background(Color.Red, CircleShape)
        )
    }
}

Gestion des couches avec zIndex

Modifier.zIndex contrôle l'ordre de dessin des éléments à l'intérieur de Box. Par défaut, les éléments sont dessinés dans l'ordre de déclaration — le premier élément en bas, le dernier en haut. zIndex remplace cet ordre.

Un élément avec zIndex 2.0f est dessiné au-dessus d'un élément avec zIndex 1.0f, indépendamment de leur ordre dans le code. Les valeurs négatives de zIndex placent un élément en dessous des autres. Selon Android Developers, 2024, zIndex affecte uniquement l'ordre de dessin, pas le traitement des événements tactiles.

zIndex est particulièrement utile dans les animations et les composants glissables, où un élément doit temporairement s'élever au-dessus des autres. Par exemple, lors du glissement d'une carte, son zIndex augmente pour ne pas être masquée par les éléments voisins.

@Composable
fun ZIndexExample() {
    Box(modifier = Modifier.size(150.dp)) {
        Box(modifier = Modifier.size(80.dp)
            .align(Alignment.TopStart)
            .zIndex(2.0f)
            .background(Color.Green))
        Box(modifier = Modifier.size(100.dp)
            .align(Alignment.Center)
            .zIndex(1.0f)
            .background(Color.Blue))
    }
}

Exemples pratiques d'utilisation de Box

Box est largement utilisé pour superposer du texte sur des images. L'image d'arrière-plan est placée en premier, puis le texte avec Modifier.align pour le positionner sur le fond.

@Composable
fun ImageWithOverlay() {
    Box(modifier = Modifier.fillMaxWidth().height(200.dp)) {
        Image(
            painter = painterResource(R.drawable.photo),
            contentDescription = "Photo",
            modifier = Modifier.fillMaxSize(),
            contentScale = ContentScale.Crop
        )
        Box(
            modifier = Modifier.fillMaxSize()
                .background(Color.Black.copy(alpha = 0.4f))
        )
        Text(
            text = "Titre",
            color = Color.White,
            modifier = Modifier.align(Alignment.BottomStart)
                .padding(16.dp)
        )
    }
}

Le deuxième exemple est Box pour créer un indicateur de chargement. Box occupe toute la zone de l'écran et CircularProgressIndicator est centré via contentAlignment.

@Composable
fun LoadingOverlay() {
    Box(
        modifier = Modifier.fillMaxSize(),
        contentAlignment = Alignment.Center
    ) {
        CircularProgressIndicator(
            modifier = Modifier.size(48.dp)
        )
    }
}

Contraintes de taille de Box

Box s'ajuste par défaut à la taille de son contenu. Si les éléments enfants ont des tailles différentes, Box prend la taille du plus grand élément. En l'absence d'éléments enfants, Box se réduit à la taille minimale.

Modifier.clipToBounds restreint le rendu des éléments enfants aux limites de Box. Sans ce modificateur, les éléments enfants peuvent s'étendre au-delà de Box. Selon les Material Design Guidelines, 2025, clipToBounds est obligatoire lors de l'utilisation de Modifier.scale ou Modifier.graphicsLayer à l'intérieur de Box.

propagateMinConstraints est un paramètre de Box qui transmet les contraintes de taille minimale aux éléments enfants. S'il est défini sur true, les éléments enfants ne peuvent pas être plus petits que la taille minimale définie pour Box via Modifier.size ou Modifier.constrain.

• Box — conteneur minimal si aucune taille n'est définie et qu'aucun élément enfant n'a fillMaxSize
• Modifier.clipToBounds empêche le contenu de déborder des limites de Box
• propagateMinConstraints transmet les contraintes minimales aux éléments enfants