إضافات WindowManager

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

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

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

يتم تجميع الإضافات في مكتبة .jar ووضعها في system_ext. على الجهاز في حال تفعيل الإضافات في ملف Makefile الخاص بالجهاز.

لتفعيل الإضافات على جهاز، عليك إضافة ما يلي إلى جهاز المنتج. 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، مما يجعل عملية مشابهة لرمز إطار العمل من جانب العميل، كما هو موضح في ما يلي الشكل:

الشكل 1. تم تحميل إضافات WindowManager في التطبيق. مماثلة للتعليمة البرمجية للنظام الأساسي.

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

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

الشكل 2. شجرة القرار للوصول 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) كتطبيق وتوفير واجهات برمجة التطبيقات (API) العامة التي يواجهها المطوّرون، بما في ذلك تلك لميزات إضافات WindowManager. مكتبة WindowManager تلقائيًا يتم تحميل الإضافات في عملية التطبيق وتلخيص المستوى الأدنى واجهات برمجة تطبيقات الإضافات في رسومات تجريدية ذات مستوى أعلى وأكثر تركيزًا من الواجهات. تتّبع واجهات برمجة التطبيقات WindowManager Jetpack المعايير المتّبعة وهي تطوير تطبيقات Android وتهدف إلى توفير إمكانية التشغيل التفاعلي من خلال الدمج جيدًا مع قواعد الرموز التي تستخدم إصدارات أخرى من نظام التشغيل AndroidX المكتبات.

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

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

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

إصدار نظام Android الأساسي مستوى واجهة برمجة تطبيقات إضافات WindowManager API إصدار واجهة برمجة التطبيقات androidx.window.extensions
الإصدار 15 من نظام التشغيل Android 6 1.5.0 (قريبًا)
الإصدار 14 من نظام التشغيل Android QPR3 5 1.4.0 (قريبًا)
الإصدار 14 من نظام التشغيل Android QPR1 4 1.3.0
Android 14 3 1.2.0
الإصدار 13 من نظام التشغيل Android QPR3 2 1.1.0
Android 13 1 1.0.0
Android 12L 1 1.0.0

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

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

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

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

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

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

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

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

الأداء

يتم تخزين وحدة "الإضافات" مؤقتًا في برامج تحميل فئات النظام بخلاف "مسار التمهيد" (bootclasspath)، بدءًا من 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: داخل Android 14، وهو قيمة يمكن استخدامها لمحاكاتها التي يتم فيها استنتاج حالة المفصّلة باستخدام حالة القاعدة، على النحو المحدّد في 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" لإجراء اختبار. أو طريقة اختبار معينة أو كل الاختبارات في الوحدة النمطية.

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