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، مما يجعل
عملية مشابهة لرمز إطار العمل من جانب العميل، كما هو موضح في ما يلي
الشكل:
الوحدة androidx.window.extensions
هي وحدة "الإضافات" الحالية ضمن.
والتطوير النشط. الوحدة androidx.window.sidecar
هي وحدة قديمة.
للتوافق مع الإصدارات الأقدم من Jetpack WindowManager،
ولكن لم تعد السيارة الجانبية تتم صيانتها بشكل نشط.
يوضح الشكل التالي منطق تحديد استخدام
androidx.window.extensions
أو androidx.window.sidecar
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
من سطر الأوامر، اتّبِع الخطوات التالية:
ما يلي:
- وصِّل جهازًا تم تفعيل ميزة "خيارات المطوّرين" و"تصحيح أخطاء الجهاز عبر USB" فيه.
- اسمح للكمبيوتر بتصحيح أخطاء الجهاز.
- افتح واجهة أوامر في الدليل الجذر لمستودع androidx.
- تغيير الدليل إلى
framework/support
- نفِّذ الطلب التالي:
./gradlew window:window:connectedAndroidTest
. - حلل النتائج.
لإجراء الاختبارات من "استوديو Android"، اتّبِع الخطوات التالية:
- افتح "استوديو Android".
- وصِّل جهازًا تم تفعيل ميزة "خيارات المطوّرين" و"تصحيح أخطاء الجهاز عبر USB" فيه.
- اسمح للكمبيوتر بتصحيح أخطاء الجهاز.
- انتقِل إلى اختبار داخل مكتبة النوافذ في وحدة النافذة.
- افتح صف اختبار وجري باستخدام الأسهم الخضراء على الجانب الأيمن من المحرِّر.
بدلاً من ذلك، يمكنك إنشاء إعدادات في "استوديو Android" لإجراء اختبار. أو طريقة اختبار معينة أو كل الاختبارات في الوحدة النمطية.
يمكن تحليل النتائج يدويًا من خلال الاطّلاع على نتائج واجهة الأوامر. بعض الإشعارات يتم تخطي الاختبار إذا لم يفي الجهاز بافتراضات معينة. النتائج هي ويتم حفظه في موقع قياسي، ويمكن للمحللين كتابة نص برمجي لأتمتة تحليل النتائج.