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 مفيد بشكل خاص في الرسوم المتحركة والمكونات القابلة للسحب، حيث يحتاج العنصر إلى الارتفاع مؤقتًا فوق الباقي. على سبيل المثال، عند سحب بطاقة، يزيد 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 عبر Modifier.size أو Modifier.constrain.

• Box — حاوية أدنى إذا لم يتم تعيين أحجام ولا توجد عناصر فرعية مع fillMaxSize
• Modifier.clipToBounds يمنع تسرب المحتوى خارج حدود Box
• propagateMinConstraints ينقل القيود الدنيا إلى العناصر الفرعية