‫Jetpack פיתוח נייטיב ל-XR

ליצור באופן הצהרתי פריסות של ממשקי משתמש מרחביים שמנצלות את היכולות המרחביות של Android XR.
העדכון האחרון גרסה יציבה גרסה מועמדת להפצה גרסת בטא גרסת אלפא
‫30 ביולי 2025 - - - 1.0.0-alpha05

הצהרה על יחסי תלות

כדי להוסיף תלות ב-XR Compose, צריך להוסיף את מאגר Google Maven לפרויקט. מידע נוסף זמין במאמר בנושא מאגר Maven של Google.

מוסיפים את יחסי התלות של הארטיפקטים שאתם צריכים בקובץ build.gradle של האפליקציה או המודול:

מגניב

dependencies {
    implementation "androidx.xr.compose:compose:1.0.0-alpha05"

    // Use to write unit tests
    testImplementation "androidx.xr.compose:compose-testing:1.0.0-alpha05"
}

Kotlin

dependencies {
    implementation("androidx.xr.compose:compose:1.0.0-alpha05")

    // Use to write unit tests
    testImplementation("androidx.xr.compose:compose-testing:1.0.0-alpha05")
}

מידע נוסף על יחסי תלות זמין במאמר הוספת יחסי תלות ב-Build.

משוב

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

יצירת בעיה חדשה

מידע נוסף זמין במאמרי העזרה בנושא כלי המעקב אחר בעיות.

גירסה 1.0

גרסה 1.0.0-alpha05

‫30 ביולי 2025

הגרסאות androidx.xr.compose:compose:1.0.0-alpha05 וandroidx.xr.compose:compose-testing:1.0.0-alpha05 יוצאות לאור. גרסה 1.0.0-alpha05 מכילה את הקומטים האלה.

תכונות חדשות

  • הגדרתי את סיווג ההערות SubspaceComposable כגלוי לכולם. (‫Ic2a34, ‏ b/399432430)
  • שני רכיבי SpatialExternalSurface חדשים שניתן להרכבה שמייצגים כדורים של 180 ו-360 מעלות. (I40ef2, b/391705799)
  • נוספו SubspaceModifier.aspectRatio (Ide5ab, ‏ b/399729509, ‏ b/414762147)
  • הוספנו את SceneCoreEntity API כדי לשפר את יכולת הפעולה ההדדית בין SceneCore לבין Compose for XR. (I50bb3, ‏ b/423020989)
  • הוספנו GravityAlignedsubspace API לתמיכה בתכונה 'ללא שינוי גודל' וGravityAligned (I07359)

שינויים ב-API

  • ‫SpatialDialog() יפעל לפי ההגדרה של לחיצה על SpatialDialogProperties.dismissOnBack. (Ib453b, ‏ b/416797132)
  • העדכון של minimumPanelDimension לגודל ברירת מחדל חדש של Dimensions(0.1f, 0.1f, 0.1f), בגלל הייצוג שלו במטרים. (Ib852a)
  • מרחבים משניים ו-Orbiters ישמרו עכשיו על המצב הפנימי שלהם במרחב הבית וכשהאפליקציה פועלת ברקע. במצב 'תצוגה מצומצמת', עדיין תוגדר הסצנה ב-Subspace לקראת המעבר למצב 'תצוגה מורחבת'. (I40317, ‏ b/416037751)
  • מעכשיו, SpatialDialogs ישמרו את המצב שלהם כשהאפליקציה פועלת ברקע. (I6aa56)
  • המערכת תעביר עכשיו את המיקום והגודל המומלצים אל ApplicationSubspace. (I4565f, b/418834194)
  • הוספנו הודעת שגיאה טובה יותר והפעלנו את השגיאה מוקדם יותר כשמשתמשים ב-SubspaceComposable בהקשר שהוא לא SubspaceComposable. (Iee2ae, b/416484684)
  • העדכון של ExperimentalSubspaceVolumeApi מאזהרה לשגיאה נובע מכך שפעמים רבות מתעלמים מאזהרות כשמשתמשים ב-API שאפשר להרכיב בצורה לא נכונה. (I427aa, ‏ b/424864286)
  • הגישה ל-Subspace ול-ApplicationSubspace מוגבלת עכשיו על ידי recommendedContentBoxInFullSpace. בעבר, המגבלה הייתה שדה הראייה של SpatialUser. (I41015, ‏ b/423074142)
  • עדכון SpatialElevation לשימוש בגודל מינימלי כדי להפסיק להשתמש בגודל שמוגדר בהארד קוד (I2dbe6, b/427785338)
  • עדכון של אופן ההקרנה של SpatialAcitivityPanel כדי שהעדכון יתבצע כשמשנים משתנה מרכזי. (I0f64d, ‏ b/427999029)
  • מומלץ להסיר את VolumeConstraints.Unbounded ולהגדיר את ערכי ברירת המחדל של האילוץ לערך המקביל. (Ie24ec, b/407938414)
  • התוכן של SpatialFeatheringSize כבר לא ציבורי (I1c15b, b/399432430)
  • שינינו את השם של XR Placeable ל-SubspacePlaceable כדי להבדיל אותו מ-Placeable של Compose. (I74874)
  • הסרת ההגדרות של Orbiter והוספת shouldRenderInNonSpatial כפרמטר חדש. בנוסף, מסירים את המחלקה EdgeOffset ומוסיפים את orbiterOffsetType כפרמטר חדש כדי לאחד את הפונקציות Orbiter(). וגם שינית את השם של OrbiterEdge ל-ContentEdge. (Iebf3d)
  • השם של Measurable שונה ל-SubspaceMeasurable כדי להבדיל בין הסוג הזה לבין הסוג Measurable של Compose. (I9726c)
  • שינוי השם של MeasureResult ל-SubspaceMeasureResult (I9f34d)
  • הסרנו את setSubspaceContent API לטובת שימוש ב-setContent של Compose עם Subspace composable. (Ifff4c, b/421427391, b/421427391)
  • השם של MeasurePolicy השתנה ל-SubspaceMeasurePolicy. (I37a9b, b/422553904)
  • הופכים את SubspaceSemanticsInfo לממשק סגור כי לא נוכל להוסיף חברים בלי ברירות המחדל. (I372f9, ‏ b/423704068)
  • עדכנו את התיעוד של SpatialExternalSurface, שינינו את השם של ContentSecurityLevel ל-SurfaceProtection (I3c460, ‏ b/420982808)
  • נוסף constructor עם עומס יתר לשינוי movable, שמאפשר הצמדה. (Ic0c70)
  • הוספנו עוד ספק מיקום לתיאורי הכלים, כך שעכשיו מפתחים יכולים לקבוע אם תיאור הכלי יוצב מעל, מתחת, משמאל או מימין לנקודת העיגון. הוספת API שמקבל צורה של חץ, כדי שאפשר יהיה לספק יותר צורות בהתאמה אישית. (Ie513c, b/374766087, b/418854637)
  • הוסר CoreEntity בתור PublishedApi (Ifee05)

תיקוני באגים

  • תוקנה בעיה שבה הסמל SpatialDialog הבהב בזמן העיבוד. ‫(Ife73c, ‏ b/401619909)
  • תוקנה בעיה שבה לא הייתה אפשרות להשתמש ב-SpatialDialog כדי להסתיר את חלונית הפעילות. (I8ca6c, b/367442109)
  • תוקנה בעיה שגרמה לכך שחלק מהתוכן לא הוצג בתיבת הדו-שיח של XR (I17cd5, ‏ b/418062437)
  • תוקנה הבעיה שבה חלון ההודעה SpatialPopup נסגר כשלוחצים בתוך התוכן. ‫(If262c, b/417245722)
  • תוקנה הבעיה שבה כשמשלבים resizable().movable(), גודל החלונית Spatial לא משתנה לגודל החדש. (I02ee3, b/422264230)
  • תוקנה בעיה שבה topBar חופף לתפריט ב-SpatialComposeVideoPlayer (Id33bc, ‏ b/427168167)
  • רדיוס פינה קבוע לא מוצג (I975fe, b/428261830)

גרסה 1.0.0-alpha04

‫7 במאי 2025

הגרסאות androidx.xr.compose:compose:1.0.0-alpha04 וandroidx.xr.compose:compose-testing:1.0.0-alpha04 יוצאות לאור. גרסה 1.0.0-alpha04 מכילה את הקומטים האלה.

תכונות חדשות

  • נוסף ממשק CompositionLocalConsumerSubspaceModifierNode כדי לאפשר לסוגים מותאמים אישית של SubspaceModifier לגשת לערכים מקומיים של קומפוזיציה.
  • הוספנו API חדש,‏ SpatialPanel, שפועל לפי סגנון ההטמעה של AndroidView, והוצאנו משימוש את ViewBased SpatialPanel הקודם.
  • נוסף אובייקט נלווה VolumeConstraints.Unbounded שמייצג אילוצים לא מוגבלים.
  • נוספה האפשרות SubspaceModifier.onPointSourceParams לאפשר מקור אודיו מרחבי.
  • נוסף ApplicationSubspace ציבורי, עם VolumeConstraints אופציונלי להגדרת אזור תלת-ממדי שבו האפליקציה יכולה להציג תוכן מרחבי. כברירת מחדל, אם לא מציינים אילוצים, המרחב המשני יהיה מוגבל לרוחב ולגובה של שדה הראייה הנוכחי של SpatialUser. המשתמשים יכולים לספק אילוצים לשימוש במקרים שבהם לא ניתן לקבוע את שדה הראייה. אחרת, נעשה שימוש בערכי ברירת המחדל של רוחב וגובה שדה הראייה.
  • נוספה התכונה SpatialExternalSurface, שאפשר להשתמש בה כדי להציג תוכן סטריאוסקופי. אפשר להתאים אישית את SpatialExternalSurface באמצעות משנים (חוץ מאלפא), ואפקט של טשטוש הקצוות.
  • נוסף pointerHoverIcon Subspace Modifier חדש שמאפשר למשתמשים להגדיר את הסמל של המצביע המרחבי.

שינויים ב-API

  • הוסרה ההגבלה RequiresApi(34) על כל חבילות Jetpack XR. המגבלה הזו הייתה מיותרת כי Jetpack XR זמין כרגע רק במכשירים עם רמת API‏ 34 ומעלה. (Iae0f8)
  • כדי להשתמש בפרויקטים שפורסמו עם Kotlin 2.0, צריך KGP בגרסה 2.0.0 ומעלה. (Idb6b5)
  • הטיפול בפעולת החזרה יפעל עכשיו בחלוניות מרחביות ללא פעילויות מוטמעות. כדי שהטיפול בפעולת החזרה יפעל, צריך לציין android:enableOnBackInvokedCallback="true" במניפסט של Android.
  • הטיפול בלחיצה על לחצן החזרה יפעל עכשיו בתיבות דו-שיח מרחביות. כדי שהטיפול בהחזרה יפעל, צריך לציין android:enableOnBackInvokedCallback="true" במניפסט של Android.
  • עכשיו, אפשר לשנות את הגודל של SpatialPanels מבוססי-כתיבה ומבוססי-תצוגה בהתאם לתוכן שלהם.
  • מפתחים יכולים עכשיו להגדיר ערכי SpatialElevationLevel מותאמים אישית משלהם, והם לא מוגבלים לרמות המוגדרות מראש.
  • עכשיו אפשר להתאים אישית את רמת הגובה של Orbiter באמצעות הפרמטר elevation.
  • מעכשיו, כברירת מחדל, אפשר להגביל את המרחב המשני לפי שדה הראייה של SpatialUser ברוחב ובגובה. אם אי אפשר לקבוע את שדה הראייה, המערכת משתמשת בערכי ברירת המחדל של הרוחב והגובה של שדה הראייה.
  • נוספו קריאות חוזרות חדשות onMoveStart ו-onMoveEnd לשינוי Movable. הקריאות החוזרות (callbacks) onMoveStart ו-onMoveEnd מופעלות כשהמשתמש מתחיל ומסיים להזיז מרחב משנה שניתן להרכבה עם שינוי המיקום.
  • הפרמטר name הוסר מממשקי API מרחביים כמו SpatialRow ו-SpatialPanel. לניפוי באגים בעצים של קומפוזיציה מרחבית, משתמשים במקום זאת ב-SubspaceModifier.testTag.
  • הוסרה עומס יתר לא נתמך של SpatialPopup שיש לו רק spatialElevationLevel ו-content. צריך להשתמש בממשק שתומך ב-onDimissRequest.
  • ההחזרה של onPoseChange מהמשנה הניתן להזזה הוסרה. במקום זאת, אתם צריכים להשתמש ב-onMove.
  • SubspaceModifiers לא יחולו יותר אם הן מנותקות או בתהליך ניתוק.
  • ממשק ה-API הקיים של SpatialRow פוצל ל-SpatialRow ול-SpatialCurvedRow. אם השתמשתם בעבר בפרמטר curveRadius של SpatialRow, עכשיו צריך להשתמש בפרמטר SpatialCurvedRow במקום, כי הוא מציע את אותה התנהגות.
  • ל-MainPanel ול-ActivityPanel אין יותר סרגלי כותרת כשהן מופעלות בתמונת מערכת עדכנית דומה.
  • עכשיו אפשר להשתמש בכמה משני אלפא ומשני גודל ביחד, והערכים שלהם יוכפלו כדי לקבל את ערך האלפא או הגודל הסופי.
  • התקשרות חזרה (callback) משינוי המיקום של המיקום הניתן לשינוי עברה אופטימיזציה כדי לאפשר תנועה חלקה יותר של התנוחה.onPoseChange
  • השינויים במצב יפעילו עכשיו את ההרכבה מחדש, כי הפונקציות של המאפיינים שניתנים להזזה ולשינוי גודל יופעלו ב-callback בשרשור הראשי.
  • הוספנו תצפית על מצב לשלבי הפריסה והמדידה כדי להבטיח ששינויים במצב ב-SubspaceLayout יפעילו פריסה מחדש.
  • עדכנו את שרשרת משני המחירים שעברה אופטימיזציה כדי לשפר את השימוש החוזר במשני מחירים קיימים.

תיקוני באגים

  • ההצללה מפסיקה לפעול כשמוצג SpatialDialog. (Ic4594)
  • בקשות לשינוי פריסה שנשלחות בזמן שצמתי שינוי מנותקים יקבלו מעכשיו התעלמות.
  • הוסרו שלבי פריסה מחדש שהופעלו על ידי משנים מסוג Movable ו-Resizable.
  • תוקנה קריסה ב-MainPanel() composable שהתרחשה כששני המאפיינים הוגדרו לאפס, באופן ישיר או במהלך חישוב פריסה, למשל חישוב של MainPanel().SpatialRow/SpatialColumn החלונית תוסתר במקום זאת. שימו לב שהתיקון הזה מתייחס ספציפית לקריסות במהלך שלב הפריסה. שינוי הגודל של החלונית לאפס באמצעות אינטראקציה של המשתמש יטופל בנפרד. בחלונית המוסתרת חסרים רכיבי ממשק משתמש.
  • תוקנה בעיה שקשורה ל-maintainAspectRatio מהמשנה של שינוי הגודל. יחס הגובה-רוחב אמור להישמר עכשיו.
  • תוקנה בעיה במרחבים משניים מוטמעים שבה הם ממוקמים בצורה שגויה בפריים בודד.
  • תוקנה הבעיה שבה פינות מעוגלות לא הוחלו לפעמים כשהיה צריך להחיל אותן.
  • התמונה של NestedSubspaces לא תופיע יותר במיקום הלא נכון באחת מהמסגרות.

גרסה 1.0.0-alpha03

‫26 בפברואר 2025

הגרסאות androidx.xr.compose:compose:1.0.0-alpha03 ו-androidx.xr.compose:compose-testing:1.0.0-alpha03 הושקו ללא שינויים משמעותיים מאז גרסת האלפא האחרונה. גרסה 1.0.0-alpha03 מכילה את הקומטים האלה

גרסה 1.0.0-alpha02

‫12 בפברואר 2025

הגרסאות androidx.xr.compose:compose:1.0.0-alpha02 וandroidx.xr.compose:compose-testing:1.0.0-alpha02 יוצאות לאור. גרסה 1.0.0-alpha02 מכילה את ההתחייבויות האלה.

תכונות חדשות

  • עכשיו, כשמפעילים את התכונה 'דיאלוג מרחבי', אפשר להסתיר את התוכן של חלונית הפעילות.
  • אפשר להשתמש עכשיו ב-Orbiter API בהקשרים של SubspaceComposable, והוא יצרף את ה-Orbiters ליחידת ההורה הקרובה ביותר שניתנת להרכבה ומבוססת על SubspaceLayout.
  • הוספנו את LayoutCoordinatesAwareModifierNode כדי לאפשר שינויים מותאמים אישית שמבוססים על מיקום.
  • נוספו שיטות מחזור חיים של צירוף/ניתוק ל-SubspaceModifier.Node.
  • הוספת scaleWithDistance לשינוי המיקום. כשהאפשרות scaleWithDistance מופעלת, רכיב המרחב שמועבר יגדל או יקטן. הוא גם ישמור על כל סולם מפורש שהיה לו לפני ההעברה.

שינויים ב-API

  • הסרנו את SessionCallbackProvider לטובת SpatialCapabilities.

שינויים אחרים

  • הפחתנו את minSDK ל-24. כל ממשקי Jetpack XR API עדיין דורשים API 34 בזמן הריצה.
  • הקונסטרקטורים Orbiter EdgeOffset.inner,‏ EdgeOffset.outer ו-EdgeOffset.overlap הם כבר לא מתודות של @Composable, ולכן אפשר להשתמש בהם בהקשרים שאינם ניתנים להרכבה.
  • עדכון של רמות הגובה המרחביות בהתאם למפרט העדכני של חוויית המשתמש.
  • הטמעת הממשק SubspaceSemanticsInfo ב-MeasurableLayout.
  • השם של SubspaceModifierElement שונה ל-SubspaceModifierNodeElement.

תיקוני באגים

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

גרסה 1.0.0-alpha01

‫12 בדצמבר 2024

androidx.xr.compose:compose-*1.0.0-alpha01 משוחרר.

תכונות של הגרסה הראשונית

  • גרסת פיתוח ראשונית של Jetpack Compose ל-XR. אפשר להשתמש במושגים מוכרים מ-Compose, כמו שורות ועמודות, כדי ליצור פריסות מרחביות של ממשקי משתמש ב-XR, בין אם אתם מעבירים אפליקציית דו-ממד קיימת ל-XR או יוצרים אפליקציית XR חדשה מאפס. הספרייה הזו מספקת רכיבים מרחביים ורכיבים שניתן להרכיב מהם ממשקי משנה מרחביים: כמו פאנלים מרחביים ורכיבי Orbiters, שמאפשרים לכם למקם את ממשק המשתמש הקיים שלכם מבוסס-Views או מבוסס-Compose דו-ממדי בפריסה מרחבית. הוא כולל את רכיב המשנה Volume, שמאפשר למקם ישויות של SceneCore, כמו מודלים תלת-ממדיים, ביחס לממשק המשתמש. מידע נוסף זמין במדריך למפתחים:

    • ‫Subspace: אפשר למקם את רכיב ה-Composable הזה בכל מקום בהיררכיית ממשק המשתמש של האפליקציה, וכך לשמור על פריסות לממשקי משתמש דו-ממדיים ומרחביים בלי לאבד את ההקשר בין הקבצים. כך קל יותר לשתף דברים כמו ארכיטקטורת אפליקציה קיימת בין XR ובין גורמי צורה אחרים, בלי להעביר את המצב דרך כל עץ ממשק המשתמש או לשנות את הארכיטקטורה של האפליקציה.

    • ‫SpatialPanel: חלונית מרחבית היא רכיב שניתן להרכבה במרחב, שמאפשר להציג תוכן של אפליקציה – למשל, אפשר להציג הפעלת סרטון, תמונות סטילס או כל תוכן אחר בחלונית מרחבית.

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

    • נפח: מיקום ישויות SceneCore, כמו מודלים תלת-ממדיים, ביחס לממשק המשתמש.

  • פריסה מרחבית: אפשר ליצור כמה חלונות מרחביים ולמקם אותם בפריסה מרחבית באמצעות SpatialRow, SpatialColumn, SpatialBox ו-SpatialLayoutSpacer. משתמשים ב-SubspaceModifiers כדי להתאים אישית את הפריסה.

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

    • ‫SpatialDialog: החלונית תזוז מעט אחורה בעומק כדי להציג תיבת דו-שיח מוגבהת.
    • ‫SpatialPopUp: החלונית תזוז מעט אחורה בעומק בציר Z כדי להציג חלון קופץ מוגבה
    • ‫SpatialElevation: אפשר להגדיר את SpatialElevationLevel להוספת גובה.

  • ‫SpatialCapabilities: היכולות המרחביות יכולות להשתנות כשהמשתמשים יוצרים אינטראקציה עם האפליקציה או עם המערכת, או אפילו להשתנות על ידי האפליקציה עצמה – למשל, מעבר למרחב הבית או למרחב מלא. כדי להימנע מבעיות, האפליקציה צריכה לבדוק את LocalSpatialCapabilities.current כדי לקבוע אילו ממשקי API נתמכים בסביבה הנוכחית. ‫isSpatialUiEnabled: Spatial UI elements (e.g. SpatialPanel) ‫isContent3dEnabled: 3D objects ‫isAppEnvironmentEnabled: The environment ‫isPassthroughControlEnabled: Whether or not the application can control the passthrough state ‫isSpatialAudioEnabled: Spatial audio

בעיות מוכרות

  • נכון לעכשיו, כדי להשתמש ב-Jetpack Compose ל-XR, נדרשת גרסת minSDK של 30. כפתרון עקיף, אפשר להוסיף את רשומת המניפסט הבאה <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> כדי לבצע build ולהפעיל עם minSDK בערך 23.
  • כדי להשתמש באפליקציות Jetpack XR, צריך לבקש הרשאה android.permission.SCENE_UNDERSTANDING ב-AndroidManifest.
  • כשמפעילים אפליקציה ישירות במרחב מלא באמצעות המאפיין PROPERTY_XR_ACTIVITY_START_MODE במניפסט שלה, הפעילויות או האפליקציות נפתחות בהתחלה במרחב הבית לפני שהן עוברות למרחב מלא.
  • יכול להיות שקובצי glTF ב-Volume Composables יהבהבו בהתחלה במיקום שגוי.
  • שימוש ב-SpatialDialog בחלונית שהוזזה באופן משמעותי ידחוף את התוכן בכיוון הלא נכון.