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 برای مواردی است که عناصر نیاز به چینش متوالی ندارند. برخلاف Row و Column، Box اندازه‌گیری اضافی برای موقعیت‌یابی انجام نمی‌دهد.

امضای پایه Box

Box پارامترهای modifier، contentAlignment و propagateMinConstraints را می‌پذیرد. همه عناصر فرزند در بلوک content منتقل می‌شوند که هر کدام می‌توانند modifierهای خاص خود را داشته باشند.

@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 محدود می‌کند. بدون این modifier، عناصر فرزند می‌توانند از Box خارج شوند. به گفته Material Design Guidelines, 2025، clipToBounds هنگام استفاده از Modifier.scale یا Modifier.graphicsLayer در داخل Box الزامی است.

propagateMinConstraints — پارامتری از Box است که محدودیت‌های حداقل اندازه را به عناصر فرزند منتقل می‌کند. اگر روی true تنظیم شود، عناصر فرزند نمی‌توانند کوچک‌تر از حداقل اندازه Box باشند. این رفتار هنگام ایجاد کانتینرهای سفارشی با حداقل اندازه ثابت مهم است.

• Box — حداقل کانتینر در صورت عدم تعیین اندازه و نبود عناصر فرزند با fillMaxSize
• Modifier.clipToBounds از خروج محتوا از مرزهای Box جلوگیری می‌کند
• propagateMinConstraints محدودیت‌های حداقل را به عناصر فرزند منتقل می‌کند