Jetpack ComposeのBox：概要、composableプロパティ、動作方法

Jetpack ComposeのBoxとは？

Boxは子要素を同じ領域に配置し、互いに重ね合わせるcomposable関数です。最初の子要素は一番下に描画され、最後の要素は一番上に描画されます。デフォルトでは、Boxは最も大きな子要素のサイズに合わせて調整されます。

RowやColumnとは異なり、Boxは要素を順番に配置しません。すべての子要素は同じ領域を占有し、互いに重なり合うことができます。これにより、Boxはインターフェースレイヤーの構成に不可欠な存在となっています。

Boxのサイズは次のルールで決定されます。子要素に固定サイズがない場合、Boxは最小サイズに縮小します。少なくとも1つの子要素に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
        )
    }
}

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

2つ目の例は、ローディングインジケータを作成するための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に設定すると、子要素はModifier.sizeやModifier.constrainを介してBoxに設定された最小サイズより小さくできません。この動作は、固定の最小サイズを持つカスタムコンテナを作成する際に重要です。

• Box — サイズが設定されておらず、fillMaxSizeを持つ子要素がない場合の最小コンテナ
• Modifier.clipToBoundsコンテンツがBoxの境界外にはみ出すのを防ぐ
• propagateMinConstraints最小制約を子要素に伝播する