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

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

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

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

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

מגניב

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

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

Kotlin

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

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

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

משוב

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

דיווח על בעיה חדשה

מידע נוסף זמין במסמכי התיעוד של Issue Tracker.

גירסה 1.0

גרסה 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 ב-Compose, ומבטל את השימוש ב-ViewBased SpatialPanel הקודם.
  • נוספו אובייקטים נלווים מסוג VolumeConstraints.Unbounded שמייצגים אילוצים ללא גבולות.
  • הוספנו את SubspaceModifier.onPointSourceParams כדי לאפשר מקור אודיו במיקום מרחבי.
  • נוספה ApplicationSubspace ציבורית, עם VolumeConstraints אופציונלי להגדרת אזור תלת-ממדי שבו האפליקציה יכולה ליצור תוכן מרחבי. כברירת מחדל, אם לא יצוינו אילוצים, מרחב המשנה יוגדר לפי שדה הראייה הנוכחי של SpatialUser ברוחב ובגובה. המשתמשים יכולים לספק אילוצים לשימוש במקרה שלא ניתן לקבוע את שדה הראייה. אחרת, המערכת תשתמש בערכים של רוחב וגובה שדה התצוגה כברירת מחדל.
  • נוספה התכונה SpatialExternalSurface, שאפשר להשתמש בה כדי ליצור תוכן סטריאופוני. אפשר להתאים אישית את SpatialExternalSurface באמצעות משתני אופן פעולה (למעט אלפא) ואפקט מעומעם של קצוות.
  • נוספה פונקציית שינוי מרחב משני חדשה (pointerHoverIcon) שמאפשרת למשתמשים להגדיר את הסמל של הסמן המרחבי.

שינויים ב-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.
  • עכשיו, תיבות SpatialPanel שמבוססות על כתיבת תוכן ותיבות SpatialPanel שמבוססות על תצוגה יכולות להתאים את הגודל שלהן בהתאם לתוכן שלהן.
  • עכשיו מפתחים יכולים להגדיר ערכים מותאמים אישית של SpatialElevationLevel, ולא מוגבלים לרמות שהוגדרו מראש.
  • עכשיו אפשר להתאים אישית את רמת הגובה של האורביטר באמצעות הפרמטר elevation.
  • עכשיו אפשר להגביל את המרחב המשני לפי שדה הראייה של SpatialUser ברוחב ובגובה כברירת מחדל. אם לא ניתן לקבוע את שדה הראייה, המערכת משתמשת בערכים ברירת המחדל של רוחב שדה הראייה וגובה שדה הראייה.
  • נוספו פונקציות קריאה חוזרת חדשות onMoveStart ו-onMoveEnd למערך הערכים של המשתנה Movable. פונקציות ה-callbacks onMoveStart ו-onMoveEnd נקראות כשהמשתמש מתחיל ומפסיק להזיז תת-מרחב שאפשר ליצור באמצעות המשתנה הניתן לשינוי.
  • הפרמטר name הוסר מממשקי API מרחביים כמו SpatialRow ו-SpatialPanel. כדי לנפות באגים בעצים של קומפוזיציות מרחביות, השתמשו במקום זאת ב-SubspaceModifier.testTag.
  • הוסר עומס יתר לא נתמך של SpatialPopup שכולל רק את spatialElevationLevel ו-content. צריך להשתמש בממשק שתומך ב-onDimissRequest.
  • הוסר קריאה חוזרת (callback) של onPoseChange מהמַעַדן Movable. במקום זאת, אתם צריכים להשתמש ב-onMove.
  • SubspaceModifiers לא יפעילו יותר את ההשפעות שלהם אם הם מנותקים או בתהליך ניתוק.
  • ממשק ה-API הקיים של SpatialRow פוצל ל-SpatialRow ול-SpatialCurvedRow. אם השתמשתם בעבר בפרמטר curveRadius של SpatialRow, השתמשו עכשיו בפרמטר SpatialCurvedRow במקום זאת, כי הוא מציע את אותה התנהגות.
  • ל-MainPanel ול-ActivityPanel כבר אין יותר שורת כותרת כשהם מופעלים בתמונת מערכת עדכנית דומה.
  • עכשיו אפשר לערום משתני אלפא ושינוי קנה מידה, והערכים שלהם יכופלו כדי לקבל את הערך הסופי של האלפא או שינוי קנה המידה.
  • הקריאה החוזרת (callback) onPoseChange מהמַעַדן Movable (נייד) עברה אופטימיזציה כדי לבצע תנועה חלקה יותר של תנוחות.
  • מעכשיו, המשתנים המשתנים והניתנים לשינוי גודל יבצעו את קריאות החזרה שלהם (callbacks) בשרשור הראשי, כדי להבטיח ששינויים במצב יגרמו ליצירה מחדש.
  • הוספנו מעקב אחרי המצב לשלבים של הפריסה והמדידה כדי להבטיח ששינויים במצב ב-SubspaceLayout יגרמו ליצירת פריסה מחדש.
  • עדכונים של שרשרת המשתנים שעברו אופטימיזציה, כדי שניתן יהיה לעשות שימוש חוזר טוב יותר במשתנים קיימים.

תיקוני באגים

  • הפסקת הסריקה כשמוצג SpatialDialog. (Ic4594)
  • בקשות לפריסה מחדש שנשלחות בזמן שצמתים של מודификаторים מנותקים יידחו מעכשיו.
  • הוסרו שלבי פריסה מחדש שמופעל על ידי משתני Movable ו-Resizable.
  • תוקנה קריסה ב-MainPanel() composable שהתרחשה כאשר אחד מהמאפיינים הוגדר לאפס, באופן ישיר או במהלך חישוב פריסה, למשל חישוב של SpatialRow/SpatialColumn. במקום זאת, החלונית תוסתר. לתשומת ליבכם: התיקון הזה מטפל באופן ספציפי בקריסות במהלך שלב הפריסה. שינוי הגודל של החלונית לאפס דרך אינטראקציה של משתמש יטופל בנפרד. בחלונית המוסתרת חסרים רכיבי ממשק משתמש.
  • תוקנה בעיה ב-maintainAspectRatio מהמַעַדן שניתן לשינוי גודל. עכשיו יחס הגובה-רוחב אמור להישמר.
  • תוקנה בעיה ב-Subspaces בתצוגת עץ, שבה הם היו ממוקמים בצורה שגויה בפריים יחיד.
  • תוקנה בעיה שבה לפעמים לא הוחלו פינות מעוגלות כשהיה צריך.
  • 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 כוללת את ההוספות האלה.

תכונות חדשות

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

שינויים ב-API

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

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

  • הפחתת minSDK ל-24. כל ממשקי ה-API של Jetpack XR עדיין דורשים API 34 בסביבת זמן הריצה.
  • ה-constructors של 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, בין שאתם מעבירים אפליקציה קיימת 2D ל-XR ובין שאתם יוצרים אפליקציית XR חדשה מאפס. הספרייה הזו מספקת רכיבים שאפשר ליצור מהם מרחבים משניים ומרחבים תלת-ממדיים, כמו לוחות תלת-ממדיים ורכיבי 'מסלול', שמאפשרים למקם את ממשק המשתמש הקיים שלכם ב-Compose 2D או מבוסס-Views בפריסה תלת-ממדית. הוא כולל את הרכיב Volume subspace composable, שמאפשר למקם ישויות של SceneCore, כמו מודלים תלת-ממדיים, ביחס לממשק המשתמש. מידע נוסף זמין במדריך למפתחים:

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

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

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

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

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

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

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

  • SpatialCapabilities: יכולות המרחב יכולות להשתנות כאשר המשתמשים יוצרים אינטראקציה עם האפליקציה או עם המערכת, או אפילו על ידי האפליקציה עצמה – לדוגמה, מעבר למרחב הבית או למרחב המלא. כדי למנוע בעיות, האפליקציה צריכה לבדוק את LocalSpatialCapabilities.current כדי לקבוע אילו ממשקי API נתמכים בסביבה הנוכחית. isSpatialUiEnabled: רכיבי ממשק משתמש מרחבי (למשל, SpatialPanel) isContent3dEnabled: אובייקטים תלת-ממדיים isAppEnvironmentEnabled: הסביבה isPassthroughControlEnabled: האם האפליקציה יכולה לשלוט במצב העברה או לא isSpatialAudioEnabled: אודיו מרחבי

בעיות מוכרות

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