إضافات WindowManager

تتيح مكتبة Jetpack WindowManager لمطوّري التطبيقات إمكانية توفير تطبيقات متوافقة مع أشكال الأجهزة الجديدة و بيئات النوافذ المتعدّدة.

إضافات WindowManager (الإضافات) هي وحدة للنظام الأساسي Android يمكن تفعيلها لتفعيل مجموعة متنوعة من ميزات Jetpack WindowManager. يتم تنفيذ الوحدة في AOSP في frameworks/base/libs/WindowManager/Jetpack وإرسالها على الأجهزة التي تتيح ميزات WindowManager.

توزيع وحدات الإضافات

يتم تجميع الإضافات في مكتبة .jar ويتم وضعها في قسم system_ext على الجهاز إذا كانت الإضافات مفعَّلة في ملف makefile للجهاز.

لتفعيل الإضافات على أحد الأجهزة، أضِف ما يلي إلى ملف التخزين التعريفي لجهاز المنتج:

$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)

يؤدي ذلك إلى تفعيل حزمتَي androidx.window.extensions وandroidx.window.sidecar على الجهاز وضبط السمة persist.wm.extensions.enabled. يؤدي تضمين هذه الحِزم في makefile أيضًا إلى وضع تعريفات في etc/permissions/، ما يجعلها متاحة لعمليات تقديم الطلبات. عادةً ما يتم تحميل الوحدات وتنفيذها كجزء من عملية التطبيق في وقت التشغيل، وذلك عندما تستخدمها مكتبة Jetpack WindowManager، ما يجعل عملها مشابهًا لرمز إطار العمل من جهة العميل، كما هو موضّح في الشكل التالي:

وحدة androidx.window.extensions هي وحدة "الإضافات" الحالية التي يتم تطويرها بنشاط. وحدة androidx.window.sidecar هي وحدة قديمة تم تضمينها للتوافق مع الإصدارات الأقدم من Jetpack WindowManager، ولكن لم تعُد تتم صيانة السيارة الجانبية بشكل نشط.

يوضّح الشكل التالي منطق تحديد استخدام androidx.window.extensions أو androidx.window.sidecar.

وحدات الإضافات

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

• تضمين الأنشطة
• معلومات حول تنسيق النافذة
• مساحة النافذة

يمكن أن تؤدي عمليات تنفيذ المصنّع الأصلي للجهاز للإضافات إلى توفير مكوّنات أو مكوّنات فارغة مع التنفيذ التلقائي أو الاستبدالي للطرق في واجهة WindowExtensions إذا لم يكن جهاز الجهاز يتيح الميزات ذات الصلة، ما لم تكن الميزة مطلوبة تحديدًا في مستند تعريف التوافق (CDD) 7.1.1.1.

الإضافات وواجهات برمجة تطبيقات Jetpack

توفر وحدة إضافات WindowManager واجهة برمجة تطبيقات خاصة بها بالإضافة إلى واجهات برمجة تطبيقات النظام الأساسي العامة. يتم تطوير وحدة "الإضافات" بشكل علني في مكتبة androidx.window.extensions Jetpack التي لا تستهدف المطوّرين، حتى تتمكّن مكتبة Jetpack WindowManager (androidx.window) من الربط بها في وقت الترجمة. وتوفّر واجهة برمجة التطبيقات الإضافات عادةً واجهات برمجة تطبيقات بمستوى أدنى.

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

من المفترض أن تتم إضافة واجهة برمجة التطبيقات Jetpack WindowManager (androidx.window) باعتبارها تابعة للتطبيق، وتوفّر واجهات برمجة التطبيقات العامة للمطوّرين، بما فيها تلك الخاصة بميزات إضافات WindowManager. تعمل مكتبة WindowManager تلقائيًا على تحميل الإضافات في عملية التطبيق ودمج واجهات برمجة تطبيقات الإضافات ذات المستوى الأدنى في واجهات تجريدية ذات مستوى أعلى وواجهات أكثر تركيزًا. تلتزم واجهات برمجة تطبيقات WindowManager في Jetpack بمعايير تطوير تطبيقات Android الحديثة، وهي مصمّمة لتوفير إمكانية تكامل مناسبة من خلال الدمج بشكل جيد مع قواعد البيانات التي تستخدم مكتبات AndroidX الأخرى.

إصدارات الإضافات وتحديثاتها

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

يعرض الجدول التالي إصدارات واجهة برمجة التطبيقات androidx.window.extensions الخاصة بإصدارات مختلفة من Android.

يزداد مستوى واجهة برمجة التطبيقات للإضافات (العمود الأوسط) في كل مرة تتم فيها إضافة إلى مساحة واجهة برمجة التطبيقات الثابتة الحالية (العمود الأيسر).

التوافق مع الأمام والخلف

يتعامل Jetpack WindowManager مع تعقيدات التعامل مع التحديثات المتكررة على مستوى واجهة برمجة التطبيقات، والتطوّر السريع لواجهة برمجة التطبيقات، والتوافق مع الأنظمة القديمة. عند تنفيذ رمز المكتبة في عملية تطبيق التطبيق، تتحقّق المكتبة من مستوى واجهة برمجة التطبيقات Extensions API المُعلَن عنه وتوفّر إمكانية الوصول إلى الميزات وفقًا للمستوى المُعلَن عنه.

لحماية التطبيق من الأعطال في وقت التشغيل، يُجري WindowManager أيضًا فحصًا لعكس Java في وقت التشغيل لواجهات برمجة التطبيقات المتاحة لإضافة ميزات وفقًا لمستوى واجهة برمجة التطبيقات لإضافة ميزات المُعلَن عنه. وفي حال عدم التطابق، يمكن لـ WindowManager إيقاف استخدام الإضافات (جزئيًا أو كليًا) والإبلاغ عن الميزات ذات الصلة باعتبارها غير متوفرة للتطبيق.

يتم تنفيذ إضافات WindowManager كوحدة system_ext تستخدم واجهات برمجة تطبيقات النظام الأساسي الخاص لاستدعاء واجهة WindowManager الأساسية وDeviceStateManager وخدمات النظام الأخرى أثناء تنفيذ ميزات الإضافات.

قد لا يتم الحفاظ على التوافق مع الإصدارات التجريبية للإضافات قبل إصدار نظام Android الأساسي الربع سنوي أو السنوي ذي الصلة والذي يتم إنهاء الإصدارات به. يمكن العثور على السجلّ الكامل لواجهات برمجة تطبيقات الإضافات في فرع الإصدارات الملفات النصية لواجهات برمجة التطبيقات window:extensions:extensions.

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

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

الأداء

يتم تخزين وحدة "الإضافات" مؤقتًا في أداة تحميل فئات النظام غير المضمّنة في مسار تحميل التشغيل تلقائيًا اعتبارًا من Android 14 (المستوى 34 من واجهة برمجة التطبيقات)، لذا لا يتأثر الأداء بسبب تحميل الوحدة إلى الذاكرة عند بدء تشغيل التطبيق. قد يكون لاستخدام ميزات الوحدة الفردية تأثير بسيط في خصائص أداء التطبيقات عند تنفيذ طلبات IPC إضافية بين العميل والخادم.

الوحدات

تضمين الأنشطة

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

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

إعداد الجهاز

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

معلومات عن تنسيق النافذة

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

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

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

بالنسبة إلى الميزات القابلة للطي، يجب الإبلاغ عن تحديثات الحالة عندما يتغيّر موضع المفصّلة بين الحالات الثابتة. في حالة العرض المسطّح، يجب أن تُبلغ واجهة برمجة التطبيقات تلقائيًا عن FoldingFeature.State.FLAT. إذا كان من الممكن ترك جهاز الجهاز في وضع نصف مطوي في حالة ثابتة، يجب أن تُبلغ واجهة برمجة التطبيقات عن FoldingFeature.State.HALF_OPENED. لا تتوفّر حالة مغلقة في واجهة برمجة التطبيقات، لأنّ نافذة التطبيق لن تكون مرئية في هذه الحالة أو لن تتجاوز حدود المفصل.

إعداد الجهاز

لإتاحة تطبيق ميزة "الطيّ"، على المصنّعين الأصليين للأجهزة تنفيذ ما يلي:

• يجب ضبط حالات الجهاز في "device_state_configuration.xml" ليتم استخدامها في "DeviceStateManagerService". يُرجى الاطّلاع على DeviceStateProviderImpl.java للرجوع إليها.

  إذا لم تكن عمليات التنفيذ التلقائية DeviceStateProvider أو DeviceStatePolicy مناسبة للجهاز، يمكن استخدام عملية تنفيذ مخصّصة.

• فعِّل وحدة "الإضافات" كما هو موضَّح في قسم توزيع وحدة "الإضافات".

• حدِّد موقع ميزات العرض في مورد سلسلة com.android.internal.R.string.config_display_features (عادةً ما يكون في frameworks/base/core/res/res/values/config.xml في الظهور على سطح الجهاز).

  التنسيق المتوقّع للسلسلة هو:

  <type>-[<left>,<top>,<right>,<bottom>]

  ويمكن أن تكون قيمة السمة type إما fold أو hinge. تمثل قيم left وtop وright وbottom إحداثيات عدد صحيح في مساحة إحداثيات العرض في اتجاه العرض الطبيعي. يمكن أن تحتوي سلسلة الضبط على العديد من ميزات العرض مفصولة بفواصل منقوطة.

  مثلاً:

  <!-- Jetpack WindowManager display features -->
  <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
  

• حدِّد التعيين بين معرّفات حالة الجهاز الداخلية المستخدَمة في DeviceStateManager والثوابت العامة للحالة المُرسَلة إلى المطوّرين في com.android.internal.R.array.config_device_state_postures.

  التنسيق المتوقّع لكل إدخال هو:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  معرّفات الولايات المتوافقة هي:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: لا تتضمّن الولاية ميزات قابلة للطي للإبلاغ عنها. على سبيل المثال، قد يكون ذلك الوضع هو الوضع المغلق للجهاز القابل للطيّ والشاشة الرئيسية على الجزء الداخلي.
  • COMMON_STATE_HALF_OPENED = 2: ميزة "الطيّ" مفتوحة نصفها.
  • COMMON_STATE_FLAT = 3: ميزة الطي مسطّحة. على سبيل المثال، يمكن أن يكون هذا الوضع هو الجهاز العادي القابل للطيّ بينما تظهر الشاشة الرئيسية على الجزء الداخلي.
  • COMMON_STATE_USE_BASE_STATE = 1000: في الإصدار 14 من نظام التشغيل Android، قيمة يمكن استخدامها في حالات الأداء المُحاكي التي يتم فيها اشتقاق حالة المفصل باستخدام الحالة الأساسية، كما هو محدّد في CommonFoldingFeature.java

  يُرجى الاطّلاع على DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int) للحصول على مزيد من المعلومات.

  مثلاً:

  <!-- Map of System DeviceState supplied by DeviceStateManager to WindowManager posture.-->
  <string-array name="config_device_state_postures" translatable="false">
      <item>0:1</item>    <!-- CLOSED       : COMMON_STATE_NO_FOLDING_FEATURES -->
      <item>1:2</item>    <!-- HALF_OPENED  : COMMON_STATE_HALF_OPENED -->
      <item>2:3</item>    <!-- OPENED       : COMMON_STATE_FLAT -->
      <item>3:1</item>    <!-- REAR_DISPLAY : COMMON_STATE_NO_FOLDING_FEATURES -->
      <item>4:1000</item> <!-- CONCURRENT   : COMMON_STATE_USE_BASE_STATE -->
  </string-array>
  

مساحة النافذة

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

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

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

إعداد الجهاز

لإتاحة تطبيق ميزة "الطيّ"، على المصنّعين الأصليين للأجهزة تنفيذ ما يلي:

• اضبط حالات الجهاز في device_state_configuration.xml لاستخدامها من قِبل DeviceStateManagerService. يمكنك الاطّلاع على DeviceStateProviderImpl.java للحصول على مزيد من المعلومات.

  إذا لم يكن التنفيذ التلقائي لسمة DeviceStateProvider أو DeviceStatePolicy مناسبًا للجهاز، يمكن استخدام تنفيذ مخصّص.

• بالنسبة إلى الأجهزة القابلة للطيّ التي تتيح الوضع "فتح" أو "مسطّح"، يجب تحديد معرّفات الحالة المناسبة في com.android.internal.R.array.config_openDeviceStates.

• بالنسبة إلى الأجهزة القابلة للطيّ التي تتيح استخدام الحالات المطوية، يمكنك إدراج معرّفات الحالة المقابلة في com.android.internal.R.array.config_foldedDeviceStates.

• بالنسبة إلى الأجهزة القابلة للطي التي تتيح وضعية نصف مطوي (المفصلة مفتوحة نصفها مثل الكمبيوتر المحمول)، يجب إدراج الحالات المقابلة في com.android.internal.R.array.config_halfFoldedDeviceStates.

• على الأجهزة التي تتيح وضع الشاشة الخلفية:

  • أدرِج الولايات المقابلة في com.android.internal.R.array.config_rearDisplayDeviceStates لـ DeviceStateManager.
  • حدِّد عنوان الشاشة الفعلي للشاشة الخلفية في com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • حدِّد معرّف الولاية في com.android.internal.R.integer.config_deviceStateRearDisplay لتستخدمه الإضافات.
  • أضِف معرّف الحالة في com.android.internal.R.array.config_deviceStatesAvailableForAppRequests لإتاحته للتطبيقات.

• على نظام التشغيل Android 14، بالنسبة إلى الأجهزة التي تتيح وضع العرض المزدوج (المتزامن):

  • اضبط السمة com.android.internal.R.bool.config_supportsConcurrentInternalDisplays على true.
  • حدِّد عنوان العرض الفعلي للشاشة الخلفية في com.android.internal.R.config_deviceStateConcurrentRearDisplay.
  • حدِّد معرّف الحالة في com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay لاستخدامه في الإضافات إذا كان من المفترض أن يكون المعرّف متاحًا للتطبيقات.
  • أضِف معرّف الحالة في com.android.internal.R.array.config_deviceStatesAvailableForAppRequests لإتاحته للتطبيقات.

التحقق

يجب على المصنّعين الأصليين للأجهزة التحقق من عمليات التنفيذ لضمان السلوك المتوقع في السيناريوهات المشتركة. تتوفّر اختبارات CTS والاختبارات التي تستخدم Jetpack WindowManager لمصنّعي المعدّات الأصلية لاختبار عمليات التنفيذ.

اختبارات CTS

لإجراء اختبارات CTS، يُرجى الاطّلاع على إجراء اختبارات CTS. تندرج اختبارات CTS المرتبطة بـ Jetpack WindowManager ضمن cts/tests/framework/base/windowmanager/jetpack/. اسم وحدة الاختبار هو CtsWindowManagerJetpackTestCases.

اختبارات WindowManager

لتنزيل اختبارات Jetpack WindowManager، اتّبِع تعليمات Android Jetpack. يمكن العثور على الاختبارات في مكتبة النوافذ ضمن وحدة window:window: window/window/src/androidTest/.

لتشغيل اختبارات الجهاز لمكوّن window:window من سطر الأوامر، اتّبِع الخطوات التالية:

1. وصِّل جهازًا تم تفعيل خيارات المطوّرين وميزة "تصحيح أخطاء USB" عليه.
2. اسمح للكمبيوتر بتصحيح أخطاء الجهاز.
3. افتح واجهة أوامر في الدليل الجذر لمستودع androidx.
4. غيِّر الدليل إلى framework/support.
5. شغِّل الأمر التالي: ./gradlew window:window:connectedAndroidTest.
6. تحليل النتائج

لإجراء الاختبارات من "استوديو Android"، اتّبِع الخطوات التالية:

1. افتح "استوديو Android".
2. وصِّل جهازًا تم تفعيل خيارات المطوّرين وميزة "تصحيح أخطاء USB" عليه.
3. اسمح للكمبيوتر بتصحيح أخطاء الجهاز.
4. انتقِل إلى اختبار ضمن مكتبة النوافذ في وحدة النوافذ.
5. افتح فئة اختبارية وشغِّلها باستخدام الأسهم الخضراء على يسار المحرِّر.

بدلاً من ذلك، يمكنك إنشاء إعداد في "استوديو Android" لاستخدام طريقة اختبار أو فئة اختبار أو كل الاختبارات في وحدة معيّنة.

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