תוספי windowManager

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

WindowManager Extensions (Extensions) הוא מודול אופציונלי לפלטפורמת Android שמאפשר להשתמש במגוון תכונות של Jetpack WindowManager. המודול מוטמע ב-AOSP ב-frameworks/base/libs/WindowManager/Jetpack ומשווק במכשירים שתומכים בתכונות של WindowManager.

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

אם התוספים מופעלים בקובץ ה-makefile של המכשיר, הם מקובצים לספרייה .jar וממוקמים במחיצה system_ext במכשיר.

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

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

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

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

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

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

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

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

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

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

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

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

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

תאימות לאחור ולפנים

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

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

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

יכול להיות שלא תהיה תאימות לגרסאות של התוספים שפורסמו לפני ההשקה, לפני הגרסה הרלוונטית של פלטפורמת Android שפורסמת מדי רבעון או מדי שנה, שבה הגרסאות האלה מקבלות גרסה סופית. ההיסטוריה המלאה של ממשקי ה-API של התוספים מופיעה בהסתעפות של הגרסה המשוחררת window:extensions:extensions API text files.

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

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

ביצועים

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

מודולים

הטמעת פעילות

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

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

תצורת מכשיר

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

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

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

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

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

בתכונות מתקפלות, צריך לדווח על עדכוני המצב כשמיקום הציר משתנה בין המצבים היציבים. כברירת מחדל, במצב תצוגה רגילה, ה-API חייב לדווח על הערך FoldingFeature.State.FLAT. אם אפשר להשאיר את חומרת המכשיר במצב מקופל למחצה במצב יציב, ה-API חייב לדווח על הערך FoldingFeature.State.HALF_OPENED. אין מצב סגור ב-API, כי במקרה כזה חלון האפליקציה לא יהיה גלוי או לא יעבור את גבולות הציר.

תצורת מכשיר

כדי לתמוך בהטמעה של תכונת הקיפול, יצרני ציוד מקורי צריכים לבצע את הפעולות הבאות:

• מגדירים את מצבי המכשיר ב-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 זמינות ליצרני ציוד מקורי (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. בודקים את התוצאות.

כדי להריץ את הבדיקות מ-Android Studio:

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

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

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