لمحة عن WindowInsetsRulers

WindowInsets هي واجهة برمجة التطبيقات العادية في Jetpack Compose للتعامل مع مساحات الشاشة التي يحجبها جزئيًا أو كليًا واجهة مستخدم النظام. تشمل هذه المساحات شريط الحالة وشريط التنقّل ولوحة المفاتيح على الشاشة. يمكنك بدلاً من ذلك تمرير WindowInsetsRulers محدّدة مسبقًا، مثل SafeDrawing إلى Modifier.fitInside أو Modifier.fitOutside لمحاذاة المحتوى مع أشرطة النظام وصورة مقطوعة للشاشة أو إنشاء WindowInsetsRulers مخصّصة.

مزايا WindowInsetsRulers

• تجنُّب تعقيد الاستهلاك: تعمل هذه الميزة خلال مرحلة تحديد الموضع في التنسيق. يعني ذلك أنّها تتجاوز تمامًا سلسلة استهلاك المساحات الداخلية ويمكنها دائمًا توفير المواضع المطلقة الصحيحة لأشرطة النظام وقطع الشاشة، بغض النظر عن الإجراءات التي اتّخذتها تنسيقات العناصر الرئيسية. يساعد استخدام طريقتَي Modifier.fitInside أو Modifier.fitOutside في حلّ المشاكل عندما تستهلك الدوال الإنشائية السلفية المساحات الداخلية بشكل غير صحيح.
• تجنُّب أشرطة النظام بسهولة: تساعد هذه الميزة محتوى تطبيقك في تجنُّب أشرطة النظام وصورة مقطوعة للشاشة، ويمكن أن تكون أكثر وضوحًا من استخدام WindowInsets مباشرةً.
• التخصيص بدرجة كبيرة: يمكن للمطوّرين محاذاة المحتوى مع المسطرة المخصّصة و التحكّم بدقة في تنسيقاتهم باستخدام التنسيقات المخصّصة.

عيوب WindowInsetsRulers

• لا يمكن استخدامها في القياس: بما أنّها تعمل خلال مرحلة تحديد الموضع ، فإنّ معلومات الموضع التي توفّرها غير متاحة خلال مرحلة القياس السابقة.

محاذاة المحتوى باستخدام طُرق المعدِّل

Modifier.fitInside تسمح للتطبيقات بمحاذاة المحتوى مع أشرطة النظام و قطع الشاشة. ويمكن استخدامها بدلاً من WindowInsets. Modifier.fitOutside عادةً ما تكون عكس Modifier.fitInside.

على سبيل المثال، للتحقّق من أنّ محتوى التطبيق يتجنّب أشرطة النظام وقطع الشاشة، يمكنك استخدام fitInside(WindowInsetsRulers.safeDrawing.current).

@Composable
fun FitInsideDemo(modifier: Modifier) {
    Box(
        modifier = modifier
            .fillMaxSize()
            // Or DisplayCutout, Ime, NavigationBars, StatusBar, etc...
            .fitInside(WindowInsetsRulers.SafeDrawing.current)
    )
}
InsetsSnippets.kt

يوضِّح الجدول التالي كيف سيبدو محتوى تطبيقك باستخدام المسطرة المحدّدة مسبقًا مع Modifier.fitInside أو Modifier.fitOutside.

نوع المسطرة المحدّدة مسبقًا	Modifier.fitInside	Modifier.fitOutside
DisplayCutout
Ime		لا ينطبق
NavigationBars
SafeDrawing		لا ينطبق (استخدِم StatusBar أو CaptionBar أو NavigationBar بدلاً من ذلك)
StatusBar

يتطلّب استخدام Modifier.fitInside وModifier.fitOutside أن تكون الدوال الإنشائية مقيّدة. يعني ذلك أنّه عليك تحديد المعدِّلات، مثل Modifier.size أو Modifier.fillMaxSize.

تعرض بعض المسطرة، مثل Modifier.fitOutside على SafeDrawing وSystemBars، مسطرة متعددة. في هذه الحالة، يضع Android الدالة الإنشائية باستخدام مسطرة واحدة من اليسار أو أعلى أو اليمين أو أسفل.

تجنُّب أداة IME باستخدام Modifier.fitInside

للتعامل مع العناصر السفلية باستخدام أداة IME مع Modifier.fitInside، مرِّر RectRuler تأخذ القيمة الداخلية لـ NavigationBar وIme.

@Composable
fun FitInsideWithImeDemo(modifier: Modifier) {
    Box(
        modifier = modifier
            .fillMaxSize()
            .fitInside(
                RectRulers.innermostOf(
                    WindowInsetsRulers.NavigationBars.current,
                    WindowInsetsRulers.Ime.current
                )
            )
    ) {
        TextField(
            value = "Demo IME Insets",
            onValueChange = {},
            modifier = modifier.align(Alignment.BottomStart).fillMaxWidth()
        )
    }
}
InsetsSnippets.kt

تجنُّب شريط الحالة وشريط العنوان باستخدام Modifier.fitInside

وبالمثل، للتحقّق من أنّ العناصر العلوية تتجنّب شريط الحالة وشريط العنوان معًا باستخدام Modifier.fitInside، مرِّر RectRuler تأخذ القيمة الداخلية لـ StatusBars وCaptionBar.

@Composable
fun FitInsideWithStatusAndCaptionBarDemo(modifier: Modifier) {
    Box(
        modifier = modifier
            .fillMaxSize()
            .fitInside(
                RectRulers.innermostOf(
                    WindowInsetsRulers.StatusBars.current,
                    WindowInsetsRulers.CaptionBar.current
                )
            )
    )
}
InsetsSnippets.kt

إنشاء WindowInsetsRulers مخصّصة

يمكنك محاذاة المحتوى مع المسطرة المخصّصة. على سبيل المثال، لنفترض حالة استخدام تتعامل فيها دالة إنشائية رئيسية مع المساحات الداخلية بشكل غير صحيح، ما يؤدي إلى حدوث مشاكل في المساحة المتروكة في عنصر ثانوي لاحق. على الرغم من أنّه يمكن حلّ هذه المشكلة بطرق أخرى، بما في ذلك باستخدام Modifier.fitInside، يمكنك أيضًا إنشاء مسطرة مخصّصة لمحاذاة الدالة الإنشائية الثانوية بدقة بدون الحاجة إلى حلّ المشكلة في الدالة الإنشائية الرئيسية السابقة، كما هو موضّح في المثال والفيديو التاليَين:

@Composable
fun WindowInsetsRulersDemo(modifier: Modifier) {
    Box(
        contentAlignment = BottomCenter,
        modifier = modifier
            .fillMaxSize()
            // The mistake that causes issues downstream, as .padding doesn't consume insets.
            // While it's correct to instead use .windowInsetsPadding(WindowInsets.navigationBars),
            // assume it's difficult to identify this issue to see how WindowInsetsRulers can help.
            .padding(WindowInsets.navigationBars.asPaddingValues())
    ) {
        TextField(
            value = "Demo IME Insets",
            onValueChange = {},
            modifier = modifier
                // Use alignToSafeDrawing() instead of .imePadding() to precisely place this child
                // Composable without having to fix the parent upstream.
                .alignToSafeDrawing()

            // .imePadding()
            // .fillMaxWidth()
        )
    }
}

fun Modifier.alignToSafeDrawing(): Modifier {
    return layout { measurable, constraints ->
        if (constraints.hasBoundedWidth && constraints.hasBoundedHeight) {
            val placeable = measurable.measure(constraints)
            val width = placeable.width
            val height = placeable.height
            layout(width, height) {
                val bottom = WindowInsetsRulers.SafeDrawing.current.bottom
                    .current(0f).roundToInt() - height
                val right = WindowInsetsRulers.SafeDrawing.current.right
                    .current(0f).roundToInt()
                val left = WindowInsetsRulers.SafeDrawing.current.left
                    .current(0f).roundToInt()
                measurable.measure(Constraints.fixed(right - left, height))
                    .place(left, bottom)
            }
        } else {
            val placeable = measurable.measure(constraints)
            layout(placeable.width, placeable.height) {
                placeable.place(0, 0)
            }
        }
    }
}
InsetsSnippets.kt

يعرض الفيديو التالي مثالاً على استهلاك المساحات الداخلية للوحة المفاتيح على الشاشة بشكل غير صحيح بسبب دالة إنشائية رئيسية سابقة في الصورة على اليمين، واستخدام المسطرة المخصّصة لحلّ المشكلة على اليسار. تظهر مساحة متروكة إضافية أسفل الدالة الإنشائية TextField لأنّ الدالة الإنشائية الرئيسية لم تستهلك المساحة المتروكة لشريط التنقّل. يتم وضع العنصر الثانوي في الموضع الصحيح في الصورة على اليسار باستخدام مسطرة مخصّصة كما هو موضّح في عينة التعليمات البرمجية السابقة.

التأكّد من أنّ العناصر الرئيسية مُقيَّدة

لاستخدام WindowInsetsRulers بأمان، تأكَّد من أنّ الدالة الإنشائية الرئيسية توفّر قيودًا صالحة. يجب أن يكون للدوال الإنشائية الرئيسية حجم محدّد ولا يمكن أن تعتمد على حجم عنصر ثانوي يستخدم WindowInsetsRulers. استخدِم fillMaxSize أو معدِّلات الحجم الأخرى في الدوال الإنشائية الرئيسية.

وبالمثل، يمكن أن يؤدي وضع دالة إنشائية تستخدم WindowInsetsRulers داخل حاوية قابلة للتمرير، مثل verticalScroll، إلى حدوث سلوك غير متوقّع لأنّ الحاوية القابلة للتمرير توفّر قيودًا غير محدودة للارتفاع، ما يتعارض مع منطق المسطرة.