הרחבות WindowManager

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

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

איור 1. הרחבות WindowManager נטענות בתהליך היישום בדומה לקוד הפלטפורמה.

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

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

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

מודולי הרחבות

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

הטמעות OEM של הרחבות יכולות לספק רכיבים או רכיבים null עם יישומי ברירת מחדל או סתומים של השיטות בממשק 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 עומדים בסטנדרטים של פיתוח אפליקציות אנדרואיד מודרניות ונועדו לספק יכולת פעולה הדדית נוחה על ידי שילוב טוב עם בסיסי קוד המשתמשים בספריות AndroidX אחרות.

גרסאות ועדכונים של הרחבות

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

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

גרסת פלטפורמת אנדרואיד רמת ה-API של WindowManager Extensions גרסת ה-API של androidx.window.extensions
אנדרואיד 14 3 1.2.0
אנדרואיד 13 QPR3 2 1.1.0
אנדרואיד 13 1 1.0.0
אנדרואיד 12L 1 1.0.0

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

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

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

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

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

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

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

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

ביצועים

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

מודולים

הטבעת פעילות

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

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

תצורת המכשיר

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

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

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

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

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

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

אזור חלונות

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

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

בדיקות CTS

להפעלת בדיקות CTS, ראה הפעלת בדיקות CTS . מבחני ה-CTS הקשורים ל-Jetpack WindowManager נמצאים תחת cts/tests/framework/base/windowmanager/jetpack/ . שם מודול הבדיקה הוא CtsWindowManagerJetpackTestCases .

בדיקות WindowManager

כדי להוריד את מבחני Jetpack WindowManager, עקוב אחר הוראות Android Jetpack . הבדיקות ממוקמות בספריית החלונות מתחת למודול window: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 להפעלת שיטת בדיקה, מחלקת בדיקה או כל הבדיקות במודול.

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