برنامه های افزودنی WindowManager

کتابخانه 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 استفاده می‌شوند، اجرا می‌شوند، که عملکرد آن را شبیه به کد چارچوب سمت کلاینت می‌کند، همانطور که در شکل زیر نشان داده شده است:

شکل 1. برنامه های افزودنی WindowManager که مشابه کد پلت فرم در فرآیند برنامه بارگذاری شده اند.

ماژول androidx.window.extensions ماژول 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 درخواست شده باشد. .

برنامه های افزودنی و API های Jetpack

ماژول 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
اندروید 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 مراجعه کنید. تست‌های 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. نتایج را تجزیه و تحلیل کنید.

برای اجرای تست ها از اندروید استودیو مراحل زیر را انجام دهید:

  1. اندروید استودیو را باز کنید.
  2. دستگاهی را وصل کنید که گزینه های توسعه دهنده و اشکال زدایی USB را فعال کرده است.
  3. به رایانه اجازه دهید دستگاه را اشکال زدایی کند.
  4. به یک آزمایش در کتابخانه پنجره ماژول پنجره بروید.
  5. یک کلاس آزمایشی را باز کنید و با استفاده از فلش های سبز رنگ در سمت راست ویرایشگر اجرا کنید.

همچنین، می‌توانید در Android Studio پیکربندی برای اجرای یک روش تست، یک کلاس آزمایشی یا تمام تست‌های یک ماژول ایجاد کنید.

نتایج را می توان با نگاه کردن به خروجی پوسته به صورت دستی تجزیه و تحلیل کرد. اگر دستگاه با مفروضات خاصی مطابقت نداشته باشد، برخی از آزمایش‌ها نادیده گرفته می‌شوند. نتایج در یک مکان استاندارد ذخیره می شوند و تحلیلگران می توانند یک اسکریپت برای تجزیه و تحلیل خودکار نتایج بنویسند.