תוספי windowManager

הכלי 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, פעולה שדומה לקוד של framework בצד הלקוח, כפי שמוצג איור:

איור 1. תוספי windowManager נטענו לאפליקציה דומה לקוד הפלטפורמה.

המודול androidx.window.extensions הוא מודול התוספים הנוכחי תחת ופיתוח פעיל. המודול androidx.window.sidecar הוא מודול מדור קודם כלול לצורך תאימות לגרסאות המוקדמות ביותר של Jetpack windowManager, אבל החלונית הצדדית כבר לא מתוחזקת באופן פעיל.

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

איור 2. עץ החלטות לקבלת גישה androidx.window.extensions או androidx.window.sidecar.

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

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

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

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

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

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

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

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

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

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

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

הגרסה של פלטפורמת Android	רמת ה-API של תוספי windowManager	גרסת API של androidx.window.extensions
15 Android	6	1.5.0 (בקרוב)
Android 14 QPR3	5	1.4.0 (בקרוב)
Android 14 QPR1	4	1.3.0
Android 14	3	1.2.0
Android 13 QPR3	2	1.1.0
Android 13	1	1.0.0
Android 12L	1	1.0.0

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

הערה: יצרני ציוד מקורי לא נדרשים לתמוך בעדכוני QPR, אבל הם צריכים לתאם גרסת הפלטפורמה ורמת ה-API של התוספים באופן הבא:

• כל גרסת תוכנה של פלטפורמה בסיסית שנשלחת על ידי יצרני ציוד מקורי חייבת לכלול לפחות גרסה זהה של תוספים כפי שהוגדרה בטבלה.
• אפשר לשלוח גרסה ישנה יותר של הפלטפורמה עם גרסה חדשה יותר של אבל בדרך כלל ההטמעה מצריכה גם תוספים בליבה של windowManager כדי לתמוך בפונקציונליות.
• הטמעות שכוללות גרסה ישנה יותר של הפלטפורמה וגרסה חדשה יותר של התוספים חייבים לעבור את החבילה המתאימה של בדיקות התאימות (CTS) תוספים חדשים יותר. ההטמעה לא מקבלת אימות אוטומטי באמצעות בדיקות CTS של הבדיקות גרסת הפלטפורמה.

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

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

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

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

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

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

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

ביצועים

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

מודולים

הטמעת פעילויות

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

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

תצורת מכשיר

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

ב-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 כדי שיהיה זמין לאפליקציות.

אימות

יצרני ציוד מקורי (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 כדי להריץ בדיקה כיתת מבחן, או כל הבדיקות במודול מסוים.

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