إعداد مساحات النافذة

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

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

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

   <!-- 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

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

على سبيل المثال، هذه هي الطريقة الأساسية لتطبيق الهوامش الداخلية على محتوى تطبيقك بالكامل:

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

    enableEdgeToEdge()

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

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

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

هناك طريقتان أساسيتان لاستخدام أنواع الحواف الداخلية هذه من أجل تعديل تنسيقات Composable، وهما: أدوات تعديل المساحة المتروكة وأدوات تعديل حجم الحواف الداخلية.

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

تطبِّق 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

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

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

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

يتم تحقيق هذا السلوك من خلال التواصل بين جميع معدِّلات 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.

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