Box в Jetpack Compose: какво е, свойства на composable и как работи

Какво е Box в Jetpack Compose

Box — е composable функция, която поставя деца елементи в една област, наслоявайки ги един върху друг. Първият детски елемент се рисува отдолу, последният — отгоре. По подразбиране Box се напася към размера на най-големия детски елемент.

За разлика от Row и Column, Box не подрежда елементите последователно — всички деца елементи заемат една и съща област и могат да се припокриват. Това прави Box незаменим за композицията на интерфейсни слоеве.

Размерът на Box се определя по правилото: ако никой детски елемент няма фиксиран размер, Box се свива до минимален размер. Ако поне един детски елемент има Modifier.fillMaxSize, Box се разширява до максимален размер.

Според Android Developers Blog, 2024, Box е най-ефективният контейнер в Compose за случаи, когато елементите не изискват последователно подреждане. Box не извършва допълнителни измервания за позициониране, за разлика от Row и Column.

Основна сигнатура на Box

Box приема параметрите modifier, contentAlignment и propagateMinConstraints. Всички деца елементи се предават в content блок, където всеки може да има собствени модификатори.

@Composable
fun BoxExample() {
    Box(
        modifier = Modifier.size(200.dp),
        contentAlignment = Alignment.Center
    ) {
        Box(
            modifier = Modifier.fillMaxSize().background(Color.Blue)
        )
        Text(
            text = "Здравей",
            color = Color.White
        )
    }
}

ContentAlignment и Modifier.align в Box

contentAlignment — е параметър на Box, който задава подразбираното подравняване за всички деца елементи. Ако не е посочен, се използва Alignment.TopStart — елементите се поставят в горния ляв ъгъл на контейнера.

Modifier.align позволява промяна на подравняването за конкретен детски елемент независимо от contentAlignment. Например, Box с Alignment.Center може да съдържа елемент с Modifier.align(Alignment.BottomEnd), който ще бъде притиснат към долния прав ъгъл.

Според Material Design Guidelines, 2025, Modifier.align е полезен за позициониране на значки и иконки върху фонови изображения. Това позволява задаване на общо подравняване за цялото съдържание на Box и презаписването му за отделни елементи.

Таблица на стойностите на Alignment

Пример с Modifier.align

В този пример Box съдържа фоново изображение и значка в долния прав ъгъл. Modifier.align(BottomEnd) позиционира значка независимо от contentAlignment на цялия 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)
        )
    }
}

Управление на слоевете с zIndex

Modifier.zIndex управлява реда на рисуване на елементите внутрен на Box. По подразбиране елементите се рисуват в реда на декларация — първият елемент отдолу, последният отгоре. zIndex променя този ред.

Елемент с zIndex 2.0f се рисува върху елемент с zIndex 1.0f, независимо от реда им в кода. Отрицателните стойности на zIndex поставят елемента по-низко от останалите. Според Android Developers, 2024, zIndex засяга само реда на рисуване, а не обработката на събития на допиране.

zIndex е особено полезен в анимации и draggable компоненти, където елемент трябва временно да се повдигне над останалите. Например, при влачене на карта, нейният zIndex се увеличава, за да не бъде покрита от съседните елементи.

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

Практически примери за използване на Box

Box се използва широко за наслояване на текст върху изображение. Фоновото изображение се поставя първо, след което текст с Modifier.align за позициониране върху фона.

@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 = "Заглавие",
            color = Color.White,
            modifier = Modifier.align(Alignment.BottomStart)
                .padding(16.dp)
        )
    }
}

Вторият пример — Box за създаване на индикатор за зареждане. Box заема цялата област на екрана, а CircularProgressIndicator се центрира чрез contentAlignment.

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

Ограничения на размера на Box

Box по подразбиране се напася към размера на съдържанието. Ако децата елементи имат различни размери, Box приема размера на най-големия елемент. При липсва на деца елементи, Box се свива до минимален размер.

Modifier.clipToBounds ограничава рисуването на деца елементи до границите на Box. Без този модификатор, децата елементи могат да излязат извън Box. Според Material Design Guidelines, 2025, clipToBounds е задължителен при използване на Modifier.scale или Modifier.graphicsLayer внутрен на Box.

propagateMinConstraints — е параметър на Box, който предава минималните ограничения на размера на децата елементи. Ако е настроен на true, децата елементи не могат да са по-малки от минималния размер на Box. Това поведение е важно при създаване на поръчани контейнери с фиксирани минимални размери.

• Box — минимален контейнер, ако няма зададени размери и няма деца елементи с fillMaxSize
• Modifier.clipToBounds предотвратява излязането на съдържанието извън границите на Box
• propagateMinConstraints предава минималните ограничения на децата елементи