Box sa Jetpack Compose: ano ito, mga katangian ng composable at paano ito gumagana

Ano ang Box sa Jetpack Compose

Box — ay isang composable function na naglalagay ng mga child element sa isang lugar, pinapatong ang mga ito sa isa't isa. Ang unang child element ay iginuhit sa ibaba, ang huli — sa itaas. Bilang default, ang Box ay umaangkop sa laki ng pinakamalaking child element.

Hindi tulad ng Row at Column, ang Box ay hindi nag-aayos ng mga elemento nang sunud-sunod — lahat ng child element ay sumasakop sa parehong lugar at maaaring magkapatong. Ginagawa nitong kailangan ang Box para sa komposisyon ng mga layer ng interface.

Ang laki ng Box ay natutukoy ayon sa panuntunan: kung walang child element ang may nakapirming laki, ang Box ay lumiliit sa pinakamababang laki. Kung hindi bababa sa isang child element ang may Modifier.fillMaxSize, ang Box ay lumalawak sa pinakamataas na laki.

Ayon sa Android Developers Blog, 2024, ang Box ay ang pinaka-epektibong container sa Compose para sa mga kaso kung saan ang mga elemento ay hindi nangangailangan ng sunud-sunod na pag-aayos. Ang Box ay hindi nagsasagawa ng mga karagdagang pagsukat para sa pagpoposisyon, hindi tulad ng Row at Column.

Pangunahing signature ng Box

Box ay tumatanggap ng mga parameter na modifier, contentAlignment at propagateMinConstraints. Lahat ng child element ay ipinapasa sa content block, kung saan ang bawat isa ay maaaring magkaroon ng sarili nitong mga modifier.

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

ContentAlignment at Modifier.align sa Box

contentAlignment — ay isang parameter ng Box na nagtatakda ng default na pagkakahanay para sa lahat ng child element. Kung hindi tinukoy, ginagamit ang Alignment.TopStart — ang mga elemento ay inilalagay sa kaliwang sulok sa itaas ng container.

Modifier.align ay nagpapahintulot na baguhin ang pagkakahanay para sa isang partikular na child element nang hiwalay sa contentAlignment. Halimbawa, ang Box na may Alignment.Center ay maaaring maglaman ng elemento na may Modifier.align(Alignment.BottomEnd) na ididikit sa kanang sulok sa ibaba.

Ayon sa Material Design Guidelines, 2025, ang Modifier.align ay kapaki-pakinabang para sa pagpoposisyon ng mga badge at icon sa ibabaw ng mga background na larawan. Ito ay nagpapahintulot na magtakda ng pangkalahatang pagkakahanay para sa buong nilalaman ng Box at baguhin ito para sa mga indibidwal na elemento.

Talaan ng mga halaga ng Alignment

Halimbawa gamit ang Modifier.align

Sa halimbawang ito ang Box ay naglalaman ng background na larawan at isang badge sa kanang sulok sa ibaba. Ang Modifier.align(BottomEnd) ay nagpoposisyon ng badge nang hiwalay sa contentAlignment ng buong 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)
        )
    }
}

Pamamahala ng mga layer gamit ang zIndex

Modifier.zIndex namamahala sa pagkakasunod-sunod ng pagguhit ng mga elemento sa loob ng Box. Bilang default, ang mga elemento ay iginuhit ayon sa pagkakasunod-sunod ng deklarasyon — ang unang elemento sa ibaba, ang huli sa itaas. Binabago ng zIndex ang pagkakasunod-sunod na ito.

Ang elemento na may zIndex 2.0f ay iginuhit sa ibabaw ng elemento na may zIndex 1.0f, anuman ang kanilang pagkakasunod-sunod sa code. Ang mga negatibong halaga ng zIndex ay naglalagay ng elemento sa ibaba ng iba. Ayon sa Android Developers, 2024, ang zIndex ay nakakaapekto lamang sa pagkakasunod-sunod ng pagguhit, hindi sa pagproseso ng mga touch event.

zIndex ay lalong kapaki-pakinabang sa mga animation at draggable component, kung saan ang isang elemento ay dapat pansamantalang tumaas sa ibabaw ng iba. Halimbawa, kapag nagda-drag ng card, ang zIndex nito ay tumataas upang hindi ito matakpan ng mga kalapit na elemento.

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

Mga praktikal na halimbawa ng paggamit ng Box

Box ay malawakang ginagamit para sa pagpapatong ng teksto sa larawan. Ang background na larawan ay inilalagay muna, pagkatapos ang teksto na may Modifier.align para sa pagpoposisyon sa ibabaw ng background.

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

Ang pangalawang halimbawa — Box para sa paggawa ng loading indicator. Sinasakop ng Box ang buong lugar ng screen, at ang CircularProgressIndicator ay naka-center sa pamamagitan ng contentAlignment.

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

Mga limitasyon sa laki ng Box

Box ay umaangkop sa laki ng nilalaman bilang default. Kung ang mga child element ay may iba't ibang laki, ang Box ay kumukuha ng laki ng pinakamalaking elemento. Kung walang child element, ang Box ay lumiliit sa pinakamababang laki.

Modifier.clipToBounds naglilimita sa pagguhit ng mga child element sa mga hangganan ng Box. Kung wala ang modifier na ito, ang mga child element ay maaaring lumabas sa Box. Ayon sa Material Design Guidelines, 2025, ang clipToBounds ay sapilitan kapag gumagamit ng Modifier.scale o Modifier.graphicsLayer sa loob ng Box.

propagateMinConstraints — ay isang parameter ng Box na nagpapasa ng mga minimum na limitasyon sa laki sa mga child element. Kung nakatakda sa true, ang mga child element ay hindi maaaring mas maliit sa minimum na laki ng Box. Ang pag-uugali na ito ay mahalaga kapag gumagawa ng mga custom container na may nakapirming minimum na laki.

• Box — pinakamababang container kung walang nakatakdang laki at walang child element na may fillMaxSize
• Modifier.clipToBounds pumipigil sa paglabas ng nilalaman mula sa mga hangganan ng Box
• propagateMinConstraints nagpapasa ng mga minimum na limitasyon sa mga child element