کتابخانه Jetpack WindowManager توسعه دهندگان برنامه را قادر می سازد تا از عوامل شکل دستگاه جدید و محیط های چند پنجره ای پشتیبانی کنند.
افزونههای WindowManager (افزونهها) یک ماژول پلتفرم اندرویدی است که قابلیتهای مختلف Jetpack WindowManager را فعال میکند. این ماژول در AOSP در frameworks/base/libs/WindowManager/Jetpack
پیاده سازی شده و بر روی دستگاه هایی ارسال می شود که از ویژگی های WindowManager پشتیبانی می کنند.
برنامههای افزودنی در یک کتابخانه .jar
کامپایل میشوند و در پارتیشن system_ext
در دستگاه قرار میگیرند، اگر افزونهها در فایل ساخت دستگاه فعال باشند.
برای فعال کردن برنامههای افزودنی در دستگاه، موارد زیر را به فایل ساخت دستگاه محصول اضافه کنید:
$(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
ماژول Extensions فعلی است که در حال توسعه فعال است. ماژول androidx.window.sidecar
یک ماژول قدیمی است که برای سازگاری با نسخه های اولیه Jetpack WindowManager گنجانده شده است، اما سایدکار دیگر به طور فعال نگهداری نمی شود.
شکل زیر منطق تعیین استفاده از androidx.window.extensions
یا androidx.window.sidecar
را نشان می دهد.
androidx.window.extensions
یا androidx.window.sidecar
.برنامههای افزودنی ویژگیهای پنجرهسازی را برای دستگاههای صفحهنمایش بزرگ تاشو و دستگاههایی که از پنجرهسازی در نمایشگرهای خارجی پشتیبانی میکنند، ارائه میکنند. مناطق ویژگی عبارتند از:
اگر سختافزار دستگاه از ویژگیهای مربوطه پشتیبانی نمیکند، اگر سختافزار دستگاه از ویژگیهای مربوطه پشتیبانی نمیکند، میتوانند مؤلفهها یا مؤلفههای تهی را با اجرای پیشفرض یا خرد روشها در رابط WindowExtensions
ارائه کنند، مگر اینکه این ویژگی بهطور خاص در سند تعریف سازگاری (CDD) 7.1.1.1 درخواست شده باشد. .
ماژول WindowManager Extensions سطح API خود را علاوه بر APIهای پلتفرم عمومی ارائه می دهد. ماژول Extensions به صورت عمومی در یک کتابخانه Jetpack androidx.window.extensions
غیر توسعهدهنده توسعه داده شده است، به طوری که Jetpack WindowManager ( androidx.window
) میتواند در زمان کامپایل با آن پیوند برقرار کند. سطح Extensions API معمولاً APIهای سطح پایینتری ارائه میکند.
API هایی که برنامه های افزودنی ارائه می دهند فقط برای استفاده از کتابخانه Jetpack WindowManager در نظر گرفته شده است. برنامههای کاربردی برنامههای افزودنی قرار نیست مستقیماً توسط توسعهدهندگان برنامه فراخوانی شوند. کتابخانه Extensions نباید به عنوان وابستگی برای یک برنامه در فایل ساخت Gradle اضافه شود تا از عملکرد صحیح اطمینان حاصل شود. از پیش کامپایل کردن کتابخانه افزونه ها در یک برنامه به طور مستقیم خودداری کنید. در عوض، برای جلوگیری از بارگیری ترکیبی از کلاس های Extensions از پیش کامپایل شده و ارائه شده در زمان اجرا، به بارگذاری زمان اجرا تکیه کنید.
Jetpack WindowManager ( androidx.window
) قرار است بهعنوان یک وابستگی برنامه اضافه شود و APIهای رو به رو توسعهدهنده عمومی، از جمله ویژگیهای برنامههای افزودنی WindowManager را ارائه میدهد. کتابخانه WindowManager به طور خودکار برنامههای افزودنی را در فرآیند برنامه بارگیری میکند و APIهای برنامههای افزودنی سطح پایینتر را در انتزاعهای سطح بالاتر و رابطهای متمرکزتر میپیچد. APIهای WindowManager Jetpack از استانداردهای توسعه برنامههای کاربردی اندروید مدرن پیروی میکنند و قرار است با ادغام با پایگاههای کدی که از دیگر کتابخانههای AndroidX استفاده میکنند، قابلیت همکاری راحت را فراهم کنند.
ماژول Extensions را میتوان همراه با بهروزرسانیهای سالانه یا فصلی پلتفرم اندروید بهروزرسانی کرد. بهروزرسانیهای سهماهه سطح Extensions API را بین بهروزرسانیهای API پلتفرم Android افزایش میدهد، امکان تکرار سریعتر را فراهم میکند و فرصتی را برای OEMها فراهم میکند تا دسترسی رسمی API را به ویژگیهای جدید نزدیک به راهاندازی سختافزار اضافه کنند.
جدول زیر نسخههای androidx.window.extensions
API را برای نسخههای مختلف اندروید فهرست میکند.
نسخه پلتفرم اندروید | سطح API برنامه های افزودنی WindowManager | androidx.window.extensions نسخه API |
---|---|---|
اندروید 15 | 6 | 1.5.0 (به زودی) |
اندروید 14 QPR3 | 5 | 1.4.0 (به زودی) |
اندروید 14 QPR1 | 4 | 1.3.0 |
اندروید 14 | 3 | 1.2.0 |
اندروید 13 QPR3 | 2 | 1.1.0 |
اندروید 13 | 1 | 1.0.0 |
اندروید 12L | 1 | 1.0.0 |
سطح Extensions API (ستون مرکزی) هر بار که به سطح API پایدار موجود اضافه می شود (ستون سمت راست) افزایش می یابد.
Jetpack WindowManager پیچیدگی برخورد با بهروزرسانیهای مکرر سطح API، تکامل سریع API و سازگاری رو به عقب را مدیریت میکند. هنگامی که کد کتابخانه در فرآیند برنامه اجرا می شود، کتابخانه سطح Extensions API اعلام شده را بررسی می کند و دسترسی به ویژگی ها را مطابق با سطح اعلام شده فراهم می کند.
برای محافظت از برنامه در برابر خرابی در زمان اجرا، WindowManager همچنین بررسی بازتاب جاوا در زمان اجرا را از APIهای افزونه های موجود مطابق با سطح API برنامه های افزودنی اعلام شده انجام می دهد. در صورت عدم تطابق، WindowManager میتواند استفاده از برنامههای افزودنی را (به طور جزئی یا کامل) غیرفعال کند و ویژگیهای مربوطه را به عنوان در دسترس نبودن برنامه گزارش دهد.
افزونههای WindowManager بهعنوان یک ماژول system_ext
پیادهسازی میشوند که از APIهای پلتفرم خصوصی برای فراخوانی هسته WindowManager، DeviceStateManager
و سایر سرویسهای سیستم در اجرای ویژگیهای Extensions استفاده میکند.
ممکن است سازگاری با نسخه های پیش از انتشار افزونه ها قبل از انتشار سه ماهه یا سالانه مربوط به پلت فرم Android که نسخه ها با آن نهایی شده اند حفظ شود. تاریخچه کامل برنامههای کاربردی برنامههای افزودنی را میتوانید در window:extensions:extensions
فایلهای متنی API .
نسخههای جدیدتر افزونهها باید به کار با نسخههای قدیمیتر WindowManager که در برنامهها کامپایل شدهاند، ادامه دهند تا سازگاری رو به جلو حفظ شود. برای اطمینان از این موضوع، هر نسخه جدید Extensions API فقط API های جدید اضافه می کند و قدیمی ترها را حذف نمی کند. در نتیجه، برنامههای دارای نسخههای قدیمیتر WindowManager میتوانند به استفاده از APIهای افزونههای قدیمیتر که برنامهها بر روی آنها کامپایل شدهاند، ادامه دهند.
راستیآزمایی CTS تضمین میکند که برای هر نسخه اعلامشده برنامههای کاربردی برنامههای افزودنی در دستگاه، همه APIهای آن و نسخههای قبلی موجود و کاربردی هستند.
ماژول Extensions به طور پیشفرض با شروع Android 14 (سطح API 34) در بارکنندههای کلاس سیستم غیر bootclasspath در حافظه پنهان ذخیره میشود، بنابراین به دلیل بارگیری ماژول در حافظه هنگام راهاندازی برنامه، تأثیری بر عملکرد ندارد. هنگامی که تماسهای IPC اضافی بین کلاینت و سرور انجام میشود، استفاده از ویژگیهای ماژول مجزا ممکن است تأثیر کمی بر ویژگیهای عملکرد برنامهها داشته باشد.
جزء Activity embedding مجموعه ای از ویژگی ها را فراهم می کند که برنامه ها را قادر می سازد تا نمایش پنجره فعالیت را در محدوده برنامه والد سازماندهی کنند. این شامل نشان دادن دو فعالیت به طور همزمان در کنار هم در یک طرح چند صفحه ای است که بهینه سازی صفحه نمایش بزرگ را برای برنامه های قدیمی تسهیل می کند.
مؤلفه جاسازی فعالیت باید در همه دستگاههایی که دارای صفحه نمایش داخلی با اندازه یا بزرگتر از sw600 dp
هستند در دسترس باشد. جاسازی فعالیت باید در دستگاههایی که از اتصالات نمایشگر خارجی پشتیبانی میکنند نیز فعال شود، زیرا ممکن است وقتی نمایشگرهای خارجی در زمان اجرا متصل هستند، برنامه در اندازه بزرگتر نشان داده شود.
هیچ پیکربندی دستگاه خاصی لازم نیست به جز فعال کردن ماژول Extensions همانطور که در بخش توزیع ماژول Extensions توضیح داده شده است. فعال کردن برنامههای افزودنی در همه دستگاههایی که از حالت چند پنجرهای پشتیبانی میکنند منطقی است. نسخههای اندروید آینده احتمالاً برنامههای افزودنی را در پیکربندی دستگاههای معمولی دستی و صفحهنمایش بزرگ مورد نیاز خواهند بود.
مؤلفه اطلاعات طرحبندی پنجره، موقعیت و وضعیت لولا را در دستگاه تاشو زمانی که لولا از پنجره برنامه عبور میکند، شناسایی میکند. اطلاعات طرحبندی پنجره، برنامهها را قادر میسازد تا به طرحبندیهای بهینهشده در حالت رومیزی روی صفحههای تاشو پاسخ دهند و نشان دهند. برای جزئیات استفاده ، به پوشه برنامه خود آگاه شوید .
دستگاههای Android تاشو که شامل یک لولا است که نواحی پانل نمایشگر جداگانه یا پیوسته را به هم متصل میکند، باید اطلاعات مربوط به لولا را از طریق WindowLayoutComponent
در دسترس برنامهها قرار دهند.
موقعیت لولا و مرزها باید نسبت به پنجره برنامه شناسایی شده توسط یک Context
ارسال شده به API گزارش شود. اگر کران پنجره برنامه با مرزهای لولا تلاقی نداشته باشد، DisplayFeature
لولا نباید گزارش شود. همچنین زمانی که موقعیت آنها ممکن است به طور قابل اعتماد گزارش نشود، گزارش نکردن ویژگیهای نمایش قابل قبول است، مانند زمانی که کاربر میتواند آزادانه پنجره برنامه را در حالت چند پنجرهای یا حالت جعبه نامه سازگار جابجا کند.
برای ویژگیهای تاشو ، زمانی که موقعیت لولا بین حالتهای پایدار تغییر میکند، بهروزرسانیهای وضعیت باید گزارش شوند. به طور پیش فرض در حالت نمایش تخت، API باید FoldingFeature.State.FLAT
را گزارش کند. اگر بتوان سختافزار دستگاه را در حالت نیمه تا شده در حالت پایدار رها کرد، API باید FoldingFeature.State.HALF_OPENED
را گزارش کند. هیچ حالت بسته ای در API وجود ندارد، زیرا در چنین حالتی پنجره برنامه یا قابل مشاهده نخواهد بود یا از مرزهای لولا عبور نمی کند.
برای پشتیبانی از اجرای ویژگی تاشو، OEM ها باید موارد زیر را انجام دهند:
حالت های دستگاه را در
device_state_configuration.xml
پیکربندی کنید تا توسطDeviceStateManagerService
استفاده شود. برای مرجع بهDeviceStateProviderImpl.java
مراجعه کنید.اگر اجرای پیشفرض
DeviceStateProvider
یاDeviceStatePolicy
برای دستگاه مناسب نباشد، میتوان از یک پیادهسازی سفارشی استفاده کرد.ماژول Extensions را همانطور که در بخش توزیع ماژول Extensions توضیح داده شد، فعال کنید.
محل ویژگی های نمایشگر را در منبع رشته
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 هستند (همانطور که CDD Android از نظر ویژگیهایی مانند اندازه، تراکم، و امکانات ناوبری موجود تعریف میکند) صفحه نمایشی را پوشش میدهند که با دوربینهای دستگاه عقب همسو میشود، باید به حالت نمایش عقب دسترسی داشته باشند.
در اندروید 14، حالت نمایش دوگانه به برنامههایی که روی صفحهنمایش داخلی دستگاه تاشو اجرا میشوند، این امکان را میدهد تا محتوای اضافی را روی صفحهنمایش رو به روی دیگر کاربران نشان دهند. به عنوان مثال، صفحه نمایش جلد می تواند پیش نمایش دوربین را به فردی که از او عکس گرفته یا ضبط می شود نشان دهد.
برای پشتیبانی از اجرای ویژگی تاشو، OEM ها باید موارد زیر را انجام دهند:
حالت های دستگاه را در
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
برای استفاده توسط Extensions مشخص کنید. - شناسه حالت را در
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
مشخص کنید تا اگر قرار است شناسه برای برنامهها در دسترس باشد، توسط Extensions استفاده شود. - شناسه حالت را در
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests
اضافه کنید تا در دسترس برنامه ها قرار گیرد.
-
OEM ها باید اجرای خود را تأیید کنند تا از رفتار مورد انتظار در سناریوهای رایج اطمینان حاصل کنند. تستها و تستهای CTS با استفاده از Jetpack WindowManager در دسترس OEMها برای آزمایش پیادهسازی هستند.
برای اجرای تستهای CTS، به اجرای تستهای CTS مراجعه کنید. تستهای CTS مربوط به Jetpack WindowManager تحت cts/tests/framework/base/windowmanager/jetpack/
قرار دارند. نام ماژول تست CtsWindowManagerJetpackTestCases
است.
برای دانلود تستهای Jetpack WindowManager، دستورالعملهای Android Jetpack را دنبال کنید. تستها در کتابخانه پنجره زیر ماژول window:window
window: window/window/src/androidTest/
قرار دارند.
برای اجرای تست های دستگاه برای ماژول window:window
از خط فرمان، موارد زیر را انجام دهید:
- دستگاهی را وصل کنید که گزینه های توسعه دهنده و اشکال زدایی USB را فعال کرده است.
- به رایانه اجازه دهید دستگاه را اشکال زدایی کند.
- یک پوسته در پوشه ریشه مخزن androidx باز کنید.
- دایرکتوری را به
framework/support
تغییر دهید. - دستور زیر را اجرا کنید:
./gradlew window:window:connectedAndroidTest
. - نتایج را تجزیه و تحلیل کنید.
برای اجرای تست ها از اندروید استودیو مراحل زیر را انجام دهید:
- اندروید استودیو را باز کنید.
- دستگاهی را وصل کنید که گزینه های توسعه دهنده و اشکال زدایی USB را فعال کرده است.
- به رایانه اجازه دهید دستگاه را اشکال زدایی کند.
- به یک آزمایش در کتابخانه پنجره ماژول پنجره بروید.
- یک کلاس آزمایشی را باز کنید و با استفاده از فلش های سبز رنگ در سمت راست ویرایشگر اجرا کنید.
همچنین، میتوانید در Android Studio پیکربندی برای اجرای یک روش تست، یک کلاس آزمایشی یا تمام تستهای یک ماژول ایجاد کنید.
نتایج را می توان با نگاه کردن به خروجی پوسته به صورت دستی تجزیه و تحلیل کرد. اگر دستگاه با مفروضات خاصی مطابقت نداشته باشد، برخی از آزمایشها نادیده گرفته میشوند. نتایج در یک مکان استاندارد ذخیره می شوند و تحلیلگران می توانند یک اسکریپت برای تجزیه و تحلیل خودکار نتایج بنویسند.