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 передає мінімальні обмеження дочірнім елементам