توفير صور اقتصاصية للعرض

تجربة طريقة Compose

‫Jetpack Compose هي مجموعة أدوات واجهة المستخدِم المقترَحة لنظام Android. تعرَّف على كيفية استخدام الصور المقطوعة للشاشة في Compose.

الصور المقطوعة للشاشة في Compose ←

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

يتيح Android استخدام الصور المقطوعة للشاشة على الأجهزة التي تعمل بالإصدار 9 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) والإصدارات الأحدث. ومع ذلك، يمكن لمصنّعي الأجهزة أيضًا إتاحة استخدام الصور المقطوعة للشاشة على الأجهزة التي تعمل بالإصدار 8.1 من نظام التشغيل Android أو الإصدارات الأقدم.

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

اختيار كيفية تعامل تطبيقك مع مناطق الصور المقطوعة للشاشة

إذا كنت لا تريد أن يتراكب المحتوى مع منطقة الصورة المقطوعة للشاشة، يكفي بشكل عام التأكّد من عدم تراكب المحتوى مع شريط الحالة وشريط التنقّل. إذا كنت تعرض المحتوى في منطقة الصورة المقطوعة للشاشة، استخدِم WindowInsetsCompat.getDisplayCutout() لاسترداد عنصر DisplayCutout يتضمّن المساحات الداخلية الآمنة والمربّع المحيط بكل صورة مقطوعة للشاشة. تتيح لك واجهات برمجة التطبيقات هذه التحقّق مما إذا كان المحتوى يتراكب مع الصورة المقطوعة للشاشة، ما يتيح لك تغيير موضعه إذا لزم الأمر.

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

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT: يتم عرض المحتوى في منطقة الصورة المقطوعة للشاشة عندما تكون الصورة المقطوعة للشاشة مضمّنة في شريط نظام. وفي ما عدا ذلك، لا تتراكب النافذة مع الصورة المقطوعة للشاشة، على سبيل المثال، قد يتم عرض المحتوى في مربّع أسود عند عرضه في الوضع الأفقي. إذا كان تطبيقك يستهدف الإصدار 35 من حزمة تطوير البرامج (SDK)، يتم تفسير هذه القيمة على أنّها ALWAYS للنوافذ غير العائمة.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS: يُسمح دائمًا للمحتوى بالامتداد إلى مناطق الصور المقطوعة للشاشة. إذا كان تطبيقك يستهدف الإصدار 35 من حزمة تطوير البرامج (SDK) ويعمل على جهاز Android 15، هذا هو الوضع الوحيد المسموح به للنوافذ غير العائمة لضمان عرض المحتوى حتى حافة الشاشة.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: يتم عرض المحتوى في منطقة الصورة المقطوعة للشاشة في الوضعين الرأسي والأفقي. لا تستخدِم هذا الوضع للنوافذ العائمة. إذا كان تطبيقك يستهدف الإصدار 35 من حزمة تطوير البرامج (SDK)، يتم تفسير هذه القيمة على أنّها ALWAYS للنوافذ غير العائمة.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: لا يتم عرض المحتوى مطلقًا في منطقة الصورة المقطوعة للشاشة. إذا كان تطبيقك يستهدف الإصدار 35 من حزمة تطوير البرامج (SDK)، يتم تفسير هذه القيمة على أنّها ALWAYS للنوافذ غير العائمة.

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

<style name="ActivityTheme">
  <item name="android:windowLayoutInDisplayCutoutMode">
    shortEdges <!-- default, shortEdges, or never -->
  </item>
</style>

توضِّح الأقسام التالية أوضاع الصور المقطوعة للشاشة المختلفة بمزيد من التفصيل.

الإعداد التلقائي

إذا كان تطبيقك يستهدف الإصدار 35 من حزمة تطوير البرامج (SDK) ويعمل على جهاز Android 15، يكون LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS هو الإعداد التلقائي، ويتم تفسير LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT على أنّه LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS للنوافذ غير العائمة.

وفي ما عدا ذلك، يكون LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT هو الإعداد التلقائي.

عرض المحتوى في مناطق الصور المقطوعة للشاشة على الحواف القصيرة

إذا كان تطبيقك يستهدف الإصدار 35 من حزمة تطوير البرامج (SDK) ويعمل على جهاز Android 15، يتم تفسير LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES على أنّه LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS للنوافذ غير العائمة.

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

الصورة التالية هي مثال على LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES لجهاز في الوضع الرأسي:

الصورة التالية هي مثال على LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES لجهاز في الوضع الأفقي:

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

تُعد الصورة المقطوعة للشاشة في الزاوية على الحافة القصيرة:

عدم عرض المحتوى مطلقًا في منطقة الصورة المقطوعة للشاشة

إذا كان تطبيقك يستهدف الإصدار 35 من حزمة تطوير البرامج (SDK) ويعمل على جهاز Android 15، يتم تفسير LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER على أنّه LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS للنوافذ غير العائمة.

باستخدام LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER، لا يُسمح مطلقًا للنافذة بالتراكب مع منطقة الصورة المقطوعة للشاشة.

في ما يلي مثال على LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER في الوضع الرأسي:

في ما يلي مثال على LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER في الوضع الأفقي:

أفضل الممارسات لإتاحة استخدام الصور المقطوعة للشاشة

عند استخدام الصور المقطوعة للشاشة، يُرجى مراعاة ما يلي:

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

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

  

• استخدِم View.getLocationInWindow() لتحديد مقدار مساحة النافذة التي يستخدمها تطبيقك. لا تفترض أنّ التطبيق يستخدم النافذة بأكملها، ولا تستخدِم View.getLocationOnScreen().

• استخدِم أوضاع الصور المقطوعة للشاشة always أو shortEdges أو never إذا كان تطبيقك بحاجة إلى الانتقال إلى وضع ملء الشاشة والخروج منه. يمكن أن يؤدي السلوك التلقائي للصورة المقطوعة للشاشة إلى عرض المحتوى في تطبيقك في منطقة الصورة المقطوعة للشاشة أثناء ظهور أشرطة النظام، ولكن ليس أثناء وضع ملء الشاشة. يؤدي ذلك إلى تحرّك المحتوى للأعلى والأسفل أثناء عمليات الانتقال، كما هو موضّح في المثال التالي.

  

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

  

• عند التعامل مع MotionEvent، استخدِم MotionEvent.getX() و MotionEvent.getY() لتجنُّب مشاكل الإحداثيات المماثلة. لا تستخدِم MotionEvent.getRawX() أو MotionEvent.getRawY().

اختبار كيفية عرض المحتوى

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

1. فعِّل خيارات المطوّرين.
2. في شاشة خيارات المطوّرين ، انتقِل للأسفل إلى قسم الرسم وانقر على محاكاة شاشة تتضمّن صورة مقطوعة للشاشة.

3. اختَر نوع الصورة المقطوعة للشاشة.

   

مراجع إضافية

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT