عرض المحتوى من الحافة إلى الحافة في تطبيقك والتعامل مع الأجزاء الداخلية من النوافذ في Compose

تتحمّل منصة Android مسؤولية رسم واجهة مستخدم النظام، مثل شريط الحالة وشريط التنقّل. يتم عرض واجهة مستخدم النظام هذه بغض النظر عن التطبيق الذي يستخدمه المستخدم.

WindowInsets يوفّر معلومات عن واجهة مستخدم النظام لضمان أن يرسم تطبيقك في المنطقة الصحيحة وألا تحجب واجهة مستخدم النظام واجهة المستخدم الخاصة بك.

في الإصدار 14 من نظام التشغيل Android (المستوى 34 من واجهة برمجة التطبيقات) والإصدارات الأقدم، لا يتم رسم واجهة مستخدم تطبيقك أسفل أشرطة النظام وفتحات الشاشة تلقائيًا.

في الإصدار 15 من نظام التشغيل Android (المستوى 35 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يرسم تطبيقك تحت شريط عمود التطبيقات في النظام وفتحات العرض بعد أن يستهدف الإصدار 35 من حزمة تطوير البرامج (SDK). ويؤدي ذلك إلى توفير تجربة مستخدم أكثر سلاسة والسماح لتطبيقك بالاستفادة الكاملة من مساحة النافذة المتاحة له.

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

الاطّلاع على الأساسيات المُدرجة

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

يتم تحديد حجم واجهة مستخدم النظام والمعلومات حول مكان وضعها عبر المجموعات.

يحتوي كل جزء من واجهة مستخدم النظام على نوع مقابِل من المكوّنات المضمّنة يصف حجمها ومكان وضعها. على سبيل المثال، توفر الأجزاء الداخلية لشريط الحالة حجم شريط الحالة وموضعه، بينما توفر المساحة الداخلية لشريط التنقل حجم شريط التنقل وموضعه. يتكون كل نوع من الداخليات من أربعة أبعاد بكسل: أعلى، ويسار، ويمين، وأسفل. تحدد هذه الأبعاد مدى امتداد واجهة مستخدم النظام عن الجوانب المقابلة لنافذة التطبيق. لتجنُّب التداخل مع هذا النوع من واجهة مستخدم النظام، يجب وضع واجهة مستخدم التطبيق داخل الشاشة بقدرٍ مماثل.

تتوفّر أنواع الشرائح المضمّنة هذه في Android من خلال WindowInsets:

ويتم تلخيص هذه الأنواع من خلال ثلاثة أنواع داخلية "آمنة" تضمن عدم حجب المحتوى:

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

تعمل أنواع الأجزاء الداخلية "الآمنة" هذه على حماية المحتوى بطرق مختلفة، استنادًا إلى الأجزاء الأساسية من النظام الأساسي:

• استخدِم WindowInsets.safeDrawing لحماية المحتوى الذي لا يجب رسمه أسفل أي واجهة مستخدم للنظام. هذا هو الاستخدام الأكثر شيوعًا للعناصر المضمّنة: لمنع رسم المحتوى الذي يحجبه واجهة مستخدِم النظام (إما جزئيًا أو تمامًا).
• استخدِم WindowInsets.safeGestures لحماية المحتوى باستخدام الإيماءات. يجنّب ذلك تضارب إيماءات النظام مع إيماءات التطبيق (مثل إيماءات الأوراق السفلية أو لوحات العرض الدوّارة أو الألعاب).
• استخدِم WindowInsets.safeContent كمجموعة من WindowInsets.safeDrawing وWindowInsets.safeGestures لضمان عدم تداخل المحتوى بصريًا وعدم تداخل الإيماءات.

إعداد المُدرَجات

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

1. استهدِف الإصدار 35 من حزمة تطوير البرامج (SDK) أو إصدارًا أحدث من أجل فرض العرض على كامل الشاشة على نظام التشغيل Android 15 والإصدارات الأحدث. يظهر تطبيقك خلف واجهة مستخدم النظام. يمكنك تعديل واجهة مستخدم تطبيقك من خلال التعامل مع العناصر المضمّنة.
2. يمكنك، إذا أردت، طلب enableEdgeToEdge() في Activity.onCreate()، ما يسمح لتطبيقك بالظهور بشكل تام في إصدارات Android السابقة.

3. اضبط android:windowSoftInputMode="adjustResize" في إدخال AndroidManifest.xml في "نشاطك". يسمح هذا الإعداد لتطبيقك بتلقّي حجم محرِّر الكتابة الآلي للبرامج كإدراج، والذي يمكنك استخدامه لملء المحتوى وتنسيقه بشكل مناسب عند ظهور محرِّر الكتابة الآلي واختفائه في تطبيقك.

   <!-- in your AndroidManifest.xml file: -->
   <activity
     android:name=".ui.MainActivity"
     android:label="@string/app_name"
     android:windowSoftInputMode="adjustResize"
     android:theme="@style/Theme.MyApplication"
     android:exported="true">
   

واجهات برمجة التطبيقات لإنشاء المحتوى

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

على سبيل المثال، في ما يلي الطريقة الأساسية لتطبيق المكوّنات المضمّنة على محتوى تطبيقك بالكامل:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    enableEdgeToEdge()

    setContent {
        Box(Modifier.safeDrawingPadding()) {
            // the rest of the app
        }
    }
}
InsetsSnippets.kt

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

يتم عرض جميع أنواع العناصر المضمّنة هذه تلقائيًا باستخدام الرسوم المتحركة لنظام IME الذي تم نقله إلى واجهة برمجة التطبيقات 21. بالإضافة إلى ذلك، يتم أيضًا تلقائيًا استخدام الرسوم المتحركة في جميع التنسيقات التي تستخدم هذه الأجزاء المُدمَجة عند تغيير قيم الأجزاء المُدمَجة.

هناك طريقتان أساسيتان لاستخدام أنواع الحشو هذه لتعديل تنسيقات العناصر القابلة للتركيب: عناصر تعديل الحشو وعناصر تعديل حجم الحشو.

مُعدِّلات المساحة المتروكة

يطبّق Modifier.windowInsetsPadding(windowInsets: WindowInsets) العناصر المضمّنة في النافذة المحدّدة كحشو، تمامًا كما يفعل Modifier.padding. على سبيل المثال، يطبّق Modifier.windowInsetsPadding(WindowInsets.safeDrawing) إدراج الرسم الآمن كوسادة على جميع الجوانب الأربعة.

تتوفّر أيضًا عدة طرق مدمجة لأدوات الاستخدام الأكثر شيوعًا لأنواع الحشو الأكثر شيوعًا. Modifier.safeDrawingPadding() هي إحدى هذه الطرق، وهي مكافئة لمحاولة Modifier.windowInsetsPadding(WindowInsets.safeDrawing). هناك عوامل تعديل مشابهة لأنواع العناصر المضمّنة الأخرى.

مُعدِّلات حجم الملحقات

تُطبِّق المُعدِّلات التالية مقدارًا من المكوّنات المضمّنة في النافذة من خلال ضبط حجم المكوّن ليكون حجم المكوّنات المضمّنة:

تكون هذه المُعدِّلات مفيدة بشكل خاص لتحديد حجم Spacer الذي يشغل مساحة المُدرَجات:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

الاستهلاك داخل الرسم البياني

إنّ مفاتيح تعديل المساحة المتروكة (windowInsetsPadding والمساعدات مثل safeDrawingPadding) تستهلك تلقائيًا جزءًا من المساحات الداخلية التي يتم تطبيقها كمساحة متروكة. عند الانتقال إلى مستوى أعمق في شجرة التركيب، يُدرك مُعدِّلات الحشو المُدمجة للعناصر المُدمجة ومُعدِّلات حجم العناصر المُدمجة أنّه سبق أن تم استخدام جزء من العناصر المُدمجة من قِبل مُعدِّلات الحشو الخارجي للعناصر المُدمجة، لذا يتجنّبون استخدام الجزء نفسه من العناصر المُدمجة أكثر من مرّة، ما قد يؤدي إلى زيادة المساحة بشكلٍ مفرط.

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

نتيجةً لذلك، تغيّر مُعدِّلات الحشو المُدمجة تلقائيًا مقدار الحشو المُطبَّق على كلّ عنصر قابل للتجميع.

بالنظر إلى مثال LazyColumn نفسه كما في السابق، يتم تغيير حجم LazyColumn باستخدام المُعدِّل imePadding. داخل LazyColumn، يتم تحديد حجم العنصر الأخير ليكون ارتفاع أسفل أشرطة النظام:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

عندما يكون IME مغلقًا، لا يطبّق المُعدِّل imePadding() أيّ مساحة تملأ الفراغ، لأنّه لا يملك IME أيّ ارتفاع. بما أنّ مُعدِّل imePadding() لا يستخدم مساحة متروكة، لن يتم استهلاك أي مساحات داخلية، وسيكون ارتفاع Spacer مطابقًا لحجم الجانب السفلي من أشرطة النظام.

عند فتح أداة تحرير أسلوب الإدخال (IME)، يتم تطبيق رسم متحرك يُطابق حجم أداة IME ، ويبدأ مفتاح التعديل imePadding() في تطبيق المساحة المتروكة السفلية لتغيير حجم LazyColumn عند فتح أداة IME. عندما يبدأ المُعدِّل imePadding() بتطبيق المَعلمة bottom padding، يبدأ أيضًا في استخدام هذه الكمية من المَعلمات المُدمَجة. لذلك، يبدأ ارتفاع الرمز Spacer في الانخفاض، لأنّه سبق أن تم تطبيق جزء من المسافة بين عمودَي النظام بواسطة المُعدِّل imePadding(). بعد أن يطبّق المُعدِّل imePadding() مقدارًا من الحشو السفلي أكبر من أشرطة النظام، يصبح ارتفاع Spacer صفرًا.

عند إغلاق IME، تحدث التغييرات بالترتيب العكسي: يبدأ Spacer في التوسّع من ارتفاع صفري بعد أن يصبح imePadding() أصغر من الجانب السفلي من أشرطة النظام، إلى أن يتطابق Spacer أخيرًا مع ارتفاع الجانب السفلي من أشرطة النظام بعد أن يتم إخفاء IME بالكامل من خلال صورة متحركة.

ويحدث ذلك من خلال التواصل بين جميع معدِّلات windowInsetsPadding، ويمكن أن يتأثر بطريقتين أخريَين.

يستهلك Modifier.consumeWindowInsets(insets: WindowInsets) أيضًا المكوّنات المضمّنة بالطريقة نفسها التي يستهلك بها Modifier.windowInsetsPadding، ولكنّه لا يطبّق المكوّنات المضمّنة المستهلكة كحشو. يكون ذلك مفيدًا مع عوامل تعديل حجم المقتطف، للإشارة إلى العناصر الشقيقة بأنّه سبق أن تم استخدام كمية معيّنة من المقتطفات:

Column(Modifier.verticalScroll(rememberScrollState())) {
    Spacer(Modifier.windowInsetsTopHeight(WindowInsets.systemBars))

    Column(
        Modifier.consumeWindowInsets(
            WindowInsets.systemBars.only(WindowInsetsSides.Vertical)
        )
    ) {
        // content
        Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
    }

    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.systemBars))
}
InsetsSnippets.kt

يتصرّف Modifier.consumeWindowInsets(paddingValues: PaddingValues) بطريقة مشابهة جدًاWindowInsets للإصدار الذي يتضمّن مَعلمة، ولكنّه يأخذPaddingValues عشوائيًا للاستهلاك. يكون ذلك مفيدًا لإعلام الأطفال عندما يتم توفير المسافة أو الحشو من خلال آلية أخرى غير عوامل تعديل الحشو المضمّنة، مثل Modifier.padding العادي أو الفواصل التي يكون ارتفاعها ثابتًا:

Column(Modifier.padding(16.dp).consumeWindowInsets(PaddingValues(16.dp))) {
    // content
    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
}
InsetsSnippets.kt

في الحالات التي تكون فيها إدراجات النوافذ الأوّلية مطلوبة بدون الاستهلاك، استخدِم قيم WindowInsets مباشرةً، أو استخدِم WindowInsets.asPaddingValues() لمحاولة عرض PaddingValues للإدراجات التي لا تتأثر بالاستهلاك. ومع ذلك، بسبب التحذيرات الواردة أدناه، يُفضّل استخدام مُعدِّلات الحشو للنافذة المُدمَجة ومُعدِّلات حجم النافذة المُدمَجة كلما أمكن ذلك.

مراحل Jetpack Compose وعناصر الحشو

يستخدم Compose واجهات برمجة التطبيقات الأساسية في AndroidX لتعديل الأجزاء المُدمجة وإضافة مؤثرات متحركة إليها، والتي تستخدِم واجهات برمجة التطبيقات الأساسية للنظام الأساسي التي تُدير الأجزاء المُدمجة. بسبب سلوك الاطّلاع على المنصة، ترتبط الأجزاء المُدمَجة بعلاقة خاصة مع مراحل Jetpack Compose.

يتم تعديل قيمة العناصر المضمّنة بعد مرحلة التركيب، ولكن قبل مرحلة التنسيق. وهذا يعني أنّ قراءة قيمة المكوّنات المضمّنة في التركيب تستخدِم بشكل عام قيمة المكوّنات المضمّنة بعد لقطة واحدة. تم تصميم المُعدِّلات المضمّنة الموضّحة في هذه الصفحة لتأخير استخدام قيم العناصر المضمّنة إلى أن تصل إلى مرحلة التنسيق، ما يضمن استخدام قيم العناصر المضمّنة في الإطار نفسه عند تعديلها.

صور متحركة لأداة IME في لوحة المفاتيح مع WindowInsets

يمكنك تطبيق Modifier.imeNestedScroll() على حاوية قابلة للانتقال لفتح ميزة IME وإغلاقها تلقائيًا عند الانتقال إلى أسفل الحاوية.

class WindowInsetsExampleActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        WindowCompat.setDecorFitsSystemWindows(window, false)

        setContent {
            MaterialTheme {
                MyScreen()
            }
        }
    }
}

@OptIn(ExperimentalLayoutApi::class)
@Composable
fun MyScreen() {
    Box {
        LazyColumn(
            modifier = Modifier
                .fillMaxSize() // fill the entire window
                .imePadding() // padding for the bottom for the IME
                .imeNestedScroll(), // scroll IME at the bottom
            content = { }
        )
        FloatingActionButton(
            modifier = Modifier
                .align(Alignment.BottomEnd)
                .padding(16.dp) // normal 16dp of padding for FABs
                .navigationBarsPadding() // padding for navigation bar
                .imePadding(), // padding for when IME appears
            onClick = { }
        ) {
            Icon(imageVector = Icons.Filled.Add, contentDescription = "Add")
        }
    }
}
MigrationOtherConsiderationsSnippets.kt

دعم داخلي لمكونات Material 3

لتسهيل الاستخدام، تتعامل العديد من العناصر القابلة للتجميع المضمّنة في Material 3 (androidx.compose.material3) مع الأجزاء المضمّنة بنفسها، استنادًا إلى كيفية وضع العناصر القابلة للتجميع في تطبيقك وفقًا لمواصفات Material.

عناصر قابلة للتركيب في مساحة داخلية

في ما يلي قائمة بمكونات Material التي تدخّل تلقائيًا في عمليات الحشو.

أشرطة التطبيقات

• TopAppBar / SmallTopAppBar / CenterAlignedTopAppBar / MediumTopAppBar / LargeTopAppBar: يطبّق الجانبَين الأعلى والأفقي من أشرطة النظام كوسادة لأنّه يتم استخدامه في أعلى النافذة.
• BottomAppBar: يطبِّق الجانبَين الأسفل والأفقي من أشرطة النظام كمساحة متروكة.

حاويات المحتوى

• ModalDrawerSheet / DismissibleDrawerSheet / PermanentDrawerSheet (محتوى متوفّر داخل لائحة التنقّل المشروطة): يتم تطبيق مواضع الإعلانات الرأسية والبدء على المحتوى.
• ModalBottomSheet: يُطبِّق العناصر المُدمَجة في أسفل الصفحة.
• ‫NavigationBar : لتطبيق العناصر المضمّنة في أسفل وأفقيًا
• NavigationRail: يطبِّق هذا المقياس على شكل الإعلان الداخلي الفئة والبدء.

سقالة

بشكلٍ تلقائي، يقدّم Scaffold العناصر المضمّنة كمَعلمة paddingValues لاستخدامها. لا تطبّق Scaffold العناصر المضمّنة على المحتوى، بل تقع هذه المسؤولية على عاتقك. على سبيل المثال، لاستخدام هذه المكوّنات المضمّنة مع LazyColumn داخل Scaffold:

Scaffold { innerPadding ->
    // innerPadding contains inset information for you to use and apply
    LazyColumn(
        // consume insets as scaffold doesn't do it by default
        modifier = Modifier.consumeWindowInsets(innerPadding),
        contentPadding = innerPadding
    ) {
        items(count = 100) {
            Box(
                Modifier
                    .fillMaxWidth()
                    .height(50.dp)
                    .background(colors[it % colors.size])
            )
        }
    }
}
InsetsSnippets.kt

إلغاء القيم التلقائية للعناصر المضمّنة

يمكنك تغيير المَعلمة windowInsets التي يتم تمريرها إلى العنصر القابل للتجميع لمحاولة ضبط سلوك العنصر القابل للتجميع. يمكن أن تكون هذه المَعلمة نوعًا مختلفًا من نافذة مضمّنة لتطبيقها بدلاً من ذلك، أو يمكن إيقافها من خلال تمرير مثيل فارغ: WindowInsets(0, 0, 0, 0).

على سبيل المثال، لإيقاف معالجة الإدخال على LargeTopAppBar، اضبط مَعلمة windowInsets على مثيل فارغ:

LargeTopAppBar(
    windowInsets = WindowInsets(0, 0, 0, 0),
    title = {
        Text("Hi")
    }
)
InsetsSnippets.kt

إمكانية التشغيل التفاعلي مع مربّعات عرض النظام

قد تحتاج إلى إلغاء الأجزاء المضمّنة التلقائية عندما تحتوي شاشتك على كلٍّ من "طرق العرض" و "رمز الإنشاء" في التسلسل الهرمي نفسه. في هذه الحالة، عليك تحديد بوضوح العنصر الذي يجب أن يستخدِم المكوّنات المضمّنة والعنصر الذي يجب أن يتجاهلها.

على سبيل المثال، إذا كان التنسيق الخارجي هو تنسيق Android View، يجب أن تستهلك العناصر الداخلية في نظام العرض وتتجاهلها في Compose. بدلاً من ذلك، إذا كان التنسيق الخارجي قابلاً للإنشاء، يجب استخدام المجموعات في Compose وإدراج عناصر AndroidView القابلة للإنشاء وفقًا لذلك.

يستهلك كل ComposeView تلقائيًا جميع المكوّنات المضمّنة على مستوى الاستهلاك WindowInsetsCompat. لتغيير هذا السلوك التلقائي، اضبط السمة ComposeView.consumeWindowInsets على false.

حماية شريط النظام

بعد أن يستهدف تطبيقك الإصدار 35 من حزمة تطوير البرامج (SDK) أو إصدار أحدث، يتم فرض قيود على التشفير التام بين الأطراف. يكون شريط حالة النظام وشريطي التنقل بالإيماءات شفافين، لكن شريط التنقل المكون من ثلاثة أزرار شفاف.

لإزالة الحماية التلقائية الشفافة لخلفية التنقّل باستخدام الأزرار الثلاثة، اضبط Window.setNavigationBarContrastEnforced على false.

المراجع

• الآن في Android: تطبيق Android مُفعّل بالكامل تم إنشاؤه بالكامل باستخدام Kotlin وJetpack Compose
• معالجة عمليات فرض العرض على الشاشة بالكامل في Android 15: درس تطبيقي يشرح عملية فرض العرض على الشاشة بالكامل في Android 15
• نصائح حول التعامل مع المَعلمات المخصّصة للعرض على الشاشة بالكامل في نظام التشغيل Android 15
• معاينة واجهة مستخدم تطبيقك الشاملة واختبارها
• 3 طُرق لتحسين تجربة استخدام تطبيق Android: من الحافة إلى الحافة، وميزة "الظهر القائمة على التوقّعات"، و"نظرة سريعة": فيديو على YouTube يتحدث عن إجراءات التنفيذ الشاملة لإصدار Android 15.
• الرسم من الحافة إلى الحافة والعناصر المضمّنة | نصائح حول إنشاء المحتوى: فيديو على YouTube يعرض كيفية التعامل مع العناصر المضمّنة للرسم من الحافة إلى الحافة