Box w Jetpack Compose: co to jest, właściwości composable i jak działa

Czym jest Box w Jetpack Compose

Box — to funkcja composable, która umieszcza elementy potomne w jednym obszarze, nakładając je jeden na drugi. Pierwszy element potomny jest rysowany na dole, ostatni — na górze. Domyślnie Box dopasowuje się do rozmiaru największego elementu potomnego.

W przeciwieństwie do Row i Column, Box nie ustawia elementów sekwencyjnie — wszystkie elementy potomne zajmują ten sam obszar i mogą się nakładać. To czyni Box niezastąpionym do kompozycji warstw interfejsu.

Rozmiar Box jest określany według zasady: jeśli żaden element potomny nie ma stałego rozmiaru, Box zwija się do minimalnego rozmiaru. Jeśli co najmniej jeden element potomny ma Modifier.fillMaxSize, Box rozszerza się do maksymalnego.

Według Android Developers Blog, 2024, Box jest najbardziej wydajnym kontenerem w Compose w przypadkach, gdy elementy nie wymagają sekwencyjnego ułożenia. Box nie wykonuje dodatkowych pomiarów do pozycjonowania, w przeciwieństwie do Row i Column.

Podstawowa sygnatura Box

Box przyjmuje parametry modifier, contentAlignment i propagateMinConstraints. Wszystkie elementy potomne są przekazywane w bloku content, gdzie każdy może mieć własne modyfikatory.

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

ContentAlignment i Modifier.align w Box

contentAlignment — to parametr Box, który ustawia domyślne wyrównanie dla wszystkich elementów potomnych. Jeśli nie jest określony, używany jest Alignment.TopStart — elementy są umieszczane w lewym górnym rogu kontenera.

Modifier.align pozwala zmienić wyrównanie dla konkretnego elementu potomnego niezależnie od contentAlignment. Na przykład Box z Alignment.Center może zawierać element z Modifier.align(Alignment.BottomEnd), który będzie dociśnięty do prawego dolnego rogu.

Według Material Design Guidelines, 2025, Modifier.align jest przydatny do pozycjonowania znaczków i ikon na obrazach tła. Pozwala to ustawić ogólne wyrównanie dla całej zawartości Box i zmienić je dla poszczególnych elementów.

Tabela wartości Alignment

Przykład z Modifier.align

W tym przykładzie Box zawiera obraz tła i znaczek w prawym dolnym rogu. Modifier.align(BottomEnd) pozycjonuje znaczek niezależnie od contentAlignment całego 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)
        )
    }
}

Zarządzanie warstwami za pomocą zIndex

Modifier.zIndex zarządza kolejnością rysowania elementów wewnątrz Box. Domyślnie elementy są rysowane w kolejności deklaracji — pierwszy element na dole, ostatni na górze. zIndex zmienia tę kolejność.

Element z zIndex 2.0f jest rysowany nad elementem z zIndex 1.0f, niezależnie od ich kolejności w kodzie. Ujemne wartości zIndex przesuwają element poniżej pozostałych. Według Android Developers, 2024, zIndex wpływa tylko na kolejność rysowania, ale nie na obsługę zdarzeń dotykowych.

zIndex jest szczególnie przydatny w animacjach i komponentach typu draggable, gdzie element musi tymczasowo unieść się nad pozostałymi. Na przykład podczas przeciągania karty jej zIndex jest zwiększany, aby nie była zasłaniana przez sąsiednie elementy.

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

Praktyczne przykłady użycia Box

Box jest szeroko stosowany do nakładania tekstu na obraz. Obraz tła jest umieszczany pierwszy, następnie tekst z Modifier.align do pozycjonowania na tle.

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

Drugi przykład — Box do tworzenia wskaźnika ładowania. Box zajmuje cały obszar ekranu, a CircularProgressIndicator jest wyśrodkowany przez contentAlignment.

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

Ograniczenia rozmiarów Box

Box domyślnie dopasowuje się do rozmiaru zawartości. Jeśli elementy potomne mają różne rozmiary, Box przyjmuje rozmiar największego elementu. W przypadku braku elementów potomnych Box zwija się do minimalnego rozmiaru.

Modifier.clipToBounds ogranicza rysowanie elementów potomnych do granic Box. Bez tego modyfikatora elementy potomne mogą wychodzić poza Box. Według Material Design Guidelines, 2025, clipToBounds jest obowiązkowy przy użyciu Modifier.scale lub Modifier.graphicsLayer wewnątrz Box.

propagateMinConstraints — to parametr Box, który przekazuje minimalne ograniczenia rozmiarów elementom potomnym. Jeśli jest ustawiony na true, elementy potomne nie mogą być mniejsze niż minimalny rozmiar Box. To zachowanie jest ważne przy tworzeniu niestandardowych kontenerów ze stałymi minimalnymi rozmiarami.

• Box — minimalny kontener, jeśli nie określono rozmiarów i nie ma elementów potomnych z fillMaxSize
• Modifier.clipToBounds zapobiega wychodzeniu zawartości poza granice Box
• propagateMinConstraints przekazuje minimalne ograniczenia elementom potomnym