Jetpack Compose中的Box：什么是，composable属性和工作原理

Jetpack Compose 中的 Box 是什么

Box — 是一个 composable 函数，将子元素放置在一个区域内，将它们叠加在彼此之上。第一个子元素在底部绘制，最后一个在顶部。默认情况下，Box 会自适应最大子元素的尺寸。

与 Row 和 Column 不同，Box 不会顺序排列元素 — 所有子元素占据相同的区域，并可以相互覆盖。这使得 Box 在界面层次组合中不可或缺。

Box 的尺寸按规则确定：如果没有子元素具有固定尺寸，则 Box 收缩到最小尺寸。如果至少有一个子元素具有 Modifier.fillMaxSize，则 Box 扩张到最大尺寸。

据 Android Developers Blog, 2024所述，Box 是 Compose 中最高效的容器，适合元素不需要顺序排列的情况。与 Row 和 Column 不同，Box 不会为定位进行额外的测量。

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

Box 中的 ContentAlignment 和 Modifier.align

contentAlignment — 是 Box 的一个参数，用于设置所有子元素的默认对齐方式。如果未指定，则使用 Alignment.TopStart — 元素将放置在容器的左上角。

Modifier.align 可以独立于 contentAlignment 改变特定子元素的对齐方式。例如，使用 Alignment.Center 的 Box 可以包含一个使用 Modifier.align(Alignment.BottomEnd) 的元素，该元素将被粘贴在右下角。

据 Material Design Guidelines, 2025所述，Modifier.align 用于将徠章和图标定位在背景图像上。它可以设置 Box 整个内容的通用对齐方式，并为单个元素覆盖该设置。

Alignment 值表

使用 Modifier.align 的案例

在这个案例中，Box 包含一张背景图像和一个位于右下角的徠章。Modifier.align(BottomEnd) 独立于整个 Box 的 contentAlignment 对徠章进行定位。

@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 在动画和可拖拽组件中尤其有用，这些场景中元素需要暂时提升到其他元素之上。例如，拖拽卡片时，其 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所述，在 Box 内使用 Modifier.scale 或 Modifier.graphicsLayer 时，clipToBounds 是必须的。

propagateMinConstraints — 是 Box 的一个参数，将最小尺寸限制传递给子元素。如果设置为 true，则子元素不能小于 Box 的最小尺寸。这种行为在创建具有固定最小尺寸的自定义容器时很重要。

• Box — 如果未设置尺寸且没有带 fillMaxSize 的子元素，则为最小容器
• Modifier.clipToBounds 防止内容溢出 Box 边界
• propagateMinConstraints 将最小限制传递给子元素