תוספי windowManager

הספרייה Jetpack WindowManager מאפשרת למפתחי אפליקציות לתמוך בגורמי צורה חדשים של מכשירים ובסביבות מרובות חלונות.

‫WindowManager Extensions (תוספים) הוא מודול פלטפורמת 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, אבל כבר לא מתבצעת תחזוקה פעילה של ה-sidecar.

באיור הבא מוצגת הלוגיקה לקביעת השימוש ב-androidx.window.extensions או ב-androidx.window.sidecar.

מודולים של תוספים

תוספים מספקים תכונות של חלונות למכשירים מתקפלים עם מסך גדול ולמכשירים שתומכים בחלונות במסכים חיצוניים. תחומי התכונות כוללים:

• הטמעת פעילות
• מידע על פריסת החלון
• אזור החלון

הטמעות של Extensions על ידי יצרני ציוד מקורי (OEM) יכולות לספק רכיבים מסוג null או רכיבים עם הטמעות ברירת מחדל או stub של השיטות בממשק WindowExtensions אם החומרה של המכשיר לא תומכת בתכונות המתאימות, אלא אם התכונה נדרשת באופן ספציפי במסמך הגדרת התאימות (CDD) 7.1.1.1.

תוספים וממשקי API של Jetpack

מודול WindowManager Extensions מספק משטח API משלו בנוסף לממשקי ה-API הציבוריים של הפלטפורמה. מודול התוספים מפותח באופן ציבורי בספריית Jetpack androidx.window.extensions שלא מיועדת למפתחים, כדי ש-Jetpack WindowManager ‏(androidx.window) יוכל לקשר אליו בזמן ההידור. בדרך כלל, ממשקי ה-API ברמת Extensions מספקים ממשקי API ברמה נמוכה יותר.

ממשקי ה-API שמוצעים על ידי התוספים מיועדים לשימוש רק בספריית Jetpack WindowManager. ממשקי ה-API של התוספים לא מיועדים להפעלה ישירה על ידי מפתחי אפליקציות. כדי להבטיח שהפונקציונליות תפעל בצורה תקינה, אסור להוסיף את ספריית התוספים כתלות בקובץ ה-build של Gradle. לא כדאי לבצע קומפילציה מראש של ספריית התוספים ישירות באפליקציה. במקום זאת, כדאי להסתמך על טעינה בזמן ריצה כדי למנוע טעינה של שילוב של מחלקות תוספים שעברו קומפילציה מראש ושל מחלקות תוספים שסופקו בזמן ריצה.

ספריית Jetpack WindowManager‏ (androidx.window) מיועדת להוספה כתלות של אפליקציה, והיא מספקת את ממשקי ה-API הציבוריים שפונים למפתחים, כולל אלה של תכונות ההרחבות של WindowManager. ספריית WindowManager טוענת באופן אוטומטי תוספים לתהליך האפליקציה, ועוטפת את ממשקי ה-API של התוספים ברמה הנמוכה בהפשטות ברמה גבוהה יותר ובממשקים ממוקדים יותר. ממשקי ה-API של WindowManager Jetpack עומדים בתקנים של פיתוח אפליקציות מודרניות ל-Android, והם נועדו לספק יכולת פעולה הדדית נוחה על ידי שילוב טוב עם בסיסי קוד שמשתמשים בספריות אחרות של AndroidX.

גרסאות ועדכונים של תוספים

אפשר לעדכן את מודול התוספים יחד עם עדכונים שנתיים או רבעוניים של פלטפורמת Android. עדכונים רבעוניים מאפשרים להעלות את רמת Extensions API בין עדכוני פלטפורמת Android API, וכך לקצר את מחזור הפיתוח ולספק ל-OEM (יצרני ציוד מקורי) הזדמנות להוסיף גישה רשמית ל-API לתכונות חדשות בסמוך להשקות של חומרה.

בטבלה הבאה מפורטות גרסאות ה-API של androidx.window.extensions לגרסאות שונות של Android.

רמת ה-API של התוספים (העמודה האמצעית) עולה בכל פעם שנוסף משהו לממשק ה-API היציב הקיים (העמודה השמאלית).

תאימות לאחור וקדימה

‫Jetpack WindowManager מטפל במורכבות של עדכוני רמת API תכופים, התפתחות מהירה של API ותאימות לדורות קודמים. כשקוד הספרייה מופעל בתהליך האפליקציה, הספרייה בודקת את רמת ה-API של התוספים שהוגדרה ומספקת גישה לתכונות בהתאם לרמה שהוגדרה.

כדי להגן על אפליקציה מפני קריסה בזמן הריצה, WindowManager מבצע גם בדיקת השתקפות של Java בזמן הריצה של ממשקי ה-API הזמינים של Extensions בהתאם לרמת ה-API של Extensions שהוגדרה. אם יש אי התאמה, WindowManager יכול להשבית את השימוש בתוספים (באופן חלקי או מלא) ולדווח על התכונות הרלוונטיות כלא זמינות לאפליקציה.

תוספי WindowManager מיושמים כמודול system_ext שמשתמש בממשקי API פרטיים של הפלטפורמה כדי לבצע קריאה לליבת WindowManager‏, DeviceStateManager, ולשירותי מערכת אחרים בהטמעה של תכונות התוספים.

יכול להיות שלא תהיה תאימות לגרסאות של Extensions לפני ההשקה, לפני הגרסה הרבעונית או השנתית התואמת של פלטפורמת Android שבה הגרסאות מסתיימות. היסטוריה מלאה של Extensions APIs זמינה בענף הגרסה window:extensions:extensions API text files.

גרסאות חדשות יותר של Extensions צריכות להמשיך לפעול עם גרסאות ישנות יותר של WindowManager שקומפלו לאפליקציות, כדי לשמור על תאימות קדימה. כדי להבטיח זאת, כל גרסה חדשה של Extensions API מוסיפה רק ממשקי API חדשים ולא מסירה ממשקי API ישנים יותר. כתוצאה מכך, אפליקציות עם גרסאות ישנות יותר של WindowManager יכולות להמשיך להשתמש בממשקי Extensions API הישנים יותר שהאפליקציות קומפלו איתם.

אימות CTS מוודא שלכל גרסה מוצהרת של ממשקי Extensions API במכשיר, כל ממשקי ה-API של הגרסה הזו ושל גרסאות קודמות קיימים ופועלים.

ביצועים

מודול התוספים נשמר במטמון בטועני מחלקות מערכת שאינם bootclasspath כברירת מחדל החל מ-Android 14 (רמת API‏ 34), כך שאין השפעה על הביצועים בגלל טעינת המודול לזיכרון בהפעלת האפליקציה. לשימוש בתכונות של מודולים נפרדים עשויה להיות השפעה קלה על מאפייני הביצועים של אפליקציות כשמתבצעות קריאות נוספות ל-IPC בין הלקוח לשרת.

מודולים

הטמעת פעילות

רכיב הטמעת הפעילות מאפשר לאפליקציות לבצע אופטימיזציה של ממשק המשתמש שלהן למכשירים עם מסך גדול ולצגים חיצוניים. הטמעת פעילות מאפשרת הצגה של שתי פעילויות זו לצד זו בפריסה מרובת חלוניות, וכך מקלה על פיתוח אפליקציות מותאמות לאפליקציות מדור קודם.

רכיב הטמעת הפעילות צריך להיות זמין בכל המכשירים עם מסך מובנה בגודל של sw600dp או יותר. צריך להפעיל גם את הטמעת הפעילות במכשירים שתומכים בחיבורים למסכים חיצוניים, כי יכול להיות שהאפליקציה תוצג בגודל גדול יותר כשמסכים חיצוניים מחוברים בזמן הריצה.

תצורת מכשיר

לא נדרשת הגדרה ספציפית של המכשיר, מלבד הפעלת מודול התוספים כמו שמתואר בקטע הפצת מודול התוספים. מומלץ להפעיל את התוספים בכל המכשירים שתומכים במצב מרובה חלונות. בגרסאות עתידיות של Android, סביר להניח שיהיה צורך בתוספים בהגדרות נפוצות של מכשירים ניידים ומכשירים עם מסך גדול.

מידע על פריסת החלון

רכיב המידע על פריסת החלונות מזהה את המיקום והמצב של הציר במכשיר מתקפל כשהציר חוצה חלון של אפליקציה. מידע על פריסת החלונות מאפשר לאפליקציות להגיב ולהציג פריסות אופטימליות במצב שולחן במכשירים מתקפלים. פרטים נוספים על השימוש מופיעים במאמר בנושא התאמת האפליקציה למכשירים מתקפלים.

במכשירי 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 לא מתאימות למכשיר, אפשר להשתמש בהטמעה מותאמת אישית.

• מפעילים את מודול התוספים כמו שמתואר בקטע הפצת מודול התוספים.

• מציינים את המיקום של תכונות התצוגה במשאב המחרוזת 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, מצב התצוגה הכפולה מאפשר לאפליקציות שפועלות במסך הפנימי של מכשיר מתקפל להציג תוכן נוסף בתצוגה החיצונית שפונה למשתמשים אחרים. לדוגמה, בתצוגה החיצונית יכולה להופיע תצוגה מקדימה של המצלמה לאדם שמצולם או מוקלט.

תצורת מכשיר

כדי לתמוך בהטמעה של תכונת הקיפול, יצרני ציוד מקורי (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 שבו התוספים ישתמשו.
  • כדי שהמזהה יהיה זמין לאפליקציות, צריך להוסיף אותו ב-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.

אימות

יצרני ציוד מקורי (OEM) צריכים לאמת את ההטמעות שלהם כדי לוודא שההתנהגות תהיה צפויה בתרחישים נפוצים. יצרני ציוד מקורי יכולים להשתמש בבדיקות 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 Studio:

1. פותחים את Android Studio.
2. מחברים מכשיר שבו מופעלות האפשרויות למפתחים וניפוי באגים ב-USB.
3. מאפשרים למחשב לנפות באגים במכשיר.
4. עוברים לבדיקה בספריית החלונות של מודול החלונות.
5. פותחים כיתת בדיקה ומריצים אותה באמצעות החצים הירוקים בצד שמאל של הכלי לעריכת קוד.

לחלופין, אפשר ליצור הגדרה ב-Android Studio כדי להריץ שיטת בדיקה, מחלקת בדיקה או את כל הבדיקות במודול.

אפשר לנתח את התוצאות באופן ידני על ידי עיון בפלט של המעטפת. חלק מהבדיקות מדלגות אם המכשיר לא עומד בהנחות מסוימות. התוצאות נשמרות במיקום סטנדרטי, והאנליסטים יכולים לכתוב סקריפט כדי לבצע ניתוח אוטומטי של התוצאות.