Box in Jetpack Compose: Was es ist, composable Eigenschaften und wie es funktioniert

Was ist Box in Jetpack Compose?

Box ist eine composable-Funktion, die Kind-Elemente im selben Bereich platziert und übereinander stapelt. Das erste Kind-Element wird unten gezeichnet, das letzte oben. Standardmäßig passt sich Box an die Größe des größten Kind-Elements an.

Im Gegensatz zu Row und Column ordnet Box Elemente nicht sequenziell an — alle Kind-Elemente belegen denselben Bereich und können sich überlappen. Dies macht Box unverzichtbar für die Zusammensetzung von Oberflächenschichten.

Die Größe von Box wird durch die Regel bestimmt: Wenn kein Kind-Element eine feste Größe hat, wird Box auf die Mindestgröße verkleinert. Wenn mindestens ein Kind-Element Modifier.fillMaxSize hat, wird Box auf das Maximum vergrößert.

Laut Android Developers Blog, 2024 ist Box der effizienteste Container in Compose für Fälle, in denen Elemente keine sequenzielle Anordnung benötigen. Box führt im Gegensatz zu Row und Column keine zusätzlichen Messungen für die Positionierung durch.

Grundlegende Signatur von Box

Box akzeptiert die Parameter modifier, contentAlignment und propagateMinConstraints. Alle Kind-Elemente werden im content-Block übergeben, wobei jedes seine eigenen Modifikatoren haben kann.

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

ContentAlignment und Modifier.align in Box

contentAlignment ist ein Box-Parameter, der die Standardausrichtung für alle Kind-Elemente festlegt. Wenn nicht angegeben, wird Alignment.TopStart verwendet — Elemente werden in der oberen linken Ecke des Containers platziert.

Modifier.align ermöglicht es, die Ausrichtung für ein bestimmtes Kind-Element unabhängig von contentAlignment zu überschreiben. Beispielsweise kann eine Box mit Alignment.Center ein Element mit Modifier.align(Alignment.BottomEnd) enthalten, das in der unteren rechten Ecke fixiert wird.

Laut Material Design Guidelines, 2025 ist Modifier.align nützlich zum Positionieren von Badges und Symbolen über Hintergrundbildern. Dies ermöglicht es, eine allgemeine Ausrichtung für alle Box-Inhalte festzulegen und für einzelne Elemente zu überschreiben.

Tabelle der Alignment-Werte

Beispiel mit Modifier.align

In diesem Beispiel enthält Box ein Hintergrundbild und ein Badge in der unteren rechten Ecke. Modifier.align(BottomEnd) positioniert das Badge unabhängig vom contentAlignment der 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)
        )
    }
}

Layer-Verwaltung mit zIndex

Modifier.zIndex steuert die Zeichenreihenfolge von Elementen innerhalb der Box. Standardmäßig werden Elemente in der Deklarationsreihenfolge gezeichnet — das erste Element unten, das letzte oben. zIndex überschreibt diese Reihenfolge.

Ein Element mit zIndex 2.0f wird über einem Element mit zIndex 1.0f gezeichnet, unabhängig von ihrer Reihenfolge im Code. Negative zIndex-Werte platzieren ein Element unter anderen. Laut Android Developers, 2024 beeinflusst zIndex nur die Zeichenreihenfolge, nicht die Behandlung von Berührungsereignissen.

zIndex ist besonders nützlich in Animationen und ziehbaren Komponenten, bei denen ein Element vorübergehend über andere gehoben werden muss. Beim Ziehen einer Karte wird beispielsweise ihr zIndex erhöht, damit sie nicht von benachbarten Elementen überdeckt wird.

@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))
    }
}

Praktische Beispiele zur Verwendung von Box

Box wird häufig zum Überlagern von Text auf Bildern verwendet. Das Hintergrundbild wird zuerst platziert, dann der Text mit Modifier.align zur Positionierung über dem Hintergrund.

@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 = "Titel",
            color = Color.White,
            modifier = Modifier.align(Alignment.BottomStart)
                .padding(16.dp)
        )
    }
}

Das zweite Beispiel ist Box zum Erstellen eines Ladeindikators. Box belegt den gesamten Bildschirmbereich, und CircularProgressIndicator wird über contentAlignment zentriert.

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

Größenbeschränkungen von Box

Box passt sich standardmäßig an die Größe ihres Inhalts an. Wenn Kind-Elemente unterschiedliche Größen haben, nimmt Box die Größe des größten Elements an. Wenn keine Kind-Elemente vorhanden sind, wird Box auf die Mindestgröße verkleinert.

Modifier.clipToBounds schränkt das Rendern von Kind-Elementen auf die Box-Grenzen ein. Ohne diesen Modifikator können Kind-Elemente über die Box hinausragen. Laut Material Design Guidelines, 2025 ist clipToBounds bei Verwendung von Modifier.scale oder Modifier.graphicsLayer innerhalb von Box obligatorisch.

propagateMinConstraints ist ein Box-Parameter, der Mindestgrößenbeschränkungen an Kind-Elemente weitergibt. Wenn auf true gesetzt, können Kind-Elemente nicht kleiner sein als die für Box über Modifier.size oder Modifier.constrain festgelegte Mindestgröße.

• Box — minimaler Container, wenn keine Größen festgelegt sind und kein Kind-Element fillMaxSize hat
• Modifier.clipToBounds verhindert, dass Inhalt über die Box-Grenzen austritt
• propagateMinConstraints gibt Mindestbeschränkungen an Kind-Elemente weiter