Jetpack Compose برای XR

Jetpack Compose برای XR

راهنمای کاربر نمونه کد Codelab

مرجع API
androidx.xr.compose.platform
androidx.xr.compose.spatial
androidx.xr.compose.subspace
androidx.xr.compose.subspace.layout
androidx.xr.compose.subspace.node
androidx.xr.compose.unit

طرح‌بندی‌های رابط کاربری فضایی را به‌طور اعلامی بسازید که از قابلیت‌های فضایی 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"
}

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")
}

برای اطلاعات بیشتر درباره وابستگی‌ها، به افزودن وابستگی‌های ساخت نگاه کنید.

بازخورد

بازخورد شما به بهتر شدن Jetpack کمک می کند. اگر مسائل جدیدی کشف کردید یا ایده هایی برای بهبود این کتابخانه دارید، به ما اطلاع دهید. لطفاً قبل از ایجاد کتابخانه جدید، به مسائل موجود در این کتابخانه نگاهی بیندازید. با کلیک کردن روی دکمه ستاره می توانید رای خود را به یک موضوع موجود اضافه کنید.

یک شماره جدید ایجاد کنید

برای اطلاعات بیشتر به مستندات ردیاب مشکل مراجعه کنید.

نسخه 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 حاوی این تعهدات است.

توجه: برای استفاده از این نسخه از کتابخانه به شبیه ساز Android نسخه 35.6.7 یا بالاتر نیاز دارید.

ویژگی های جدید

• رابط CompositionLocalConsumerSubspaceModifierNode اضافه شد تا به انواع SubspaceModifier سفارشی اجازه دسترسی به مقادیر محلی ترکیب را بدهد.
• یک SpatialPanel API جدید اضافه شد که از سبک پیاده‌سازی AndroidView پیروی می‌کند و از 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" در مانیفست اندروید مشخص کنید.
• Backhandling اکنون روی گفتگوهای فضایی کار می کند. برای اینکه بک هندلینگ کار کند، باید android:enableOnBackInvokedCallback="true" در مانیفست اندروید مشخص کنید.
• SpatialPanel های مبتنی بر Compose و View-based اکنون می توانند اندازه خود را بر اساس محتویاتشان اندازه بگیرند.
• توسعه دهندگان اکنون می توانند مقادیر SpatialElevationLevel سفارشی خود را تنظیم کنند و محدود به سطوح از پیش تعریف شده نیستند.
• اکنون ممکن است سطح ارتفاع مدارگرد از طریق پارامتر elevation تنظیم شود.
• اکنون زیرفضا می تواند به صورت پیش فرض توسط میدان دید SpatialUser در عرض و ارتفاع محدود شود. اگر نمی توان میدان دید را تعیین کرد، از مقادیر پیش فرض عرض و ارتفاع میدان دید استفاده می شود.
• تماس‌های جدید onMoveStart و onMoveEnd به اصلاح‌کننده Movable اضافه شد. تماس‌های onMoveStart و onMoveEnd زمانی فراخوانی می‌شوند که کاربر حرکت یک زیرفضای قابل ترکیب با تغییر دهنده متحرک را شروع و پایان می‌دهد.
• پارامتر name از APIهای فضایی مانند SpatialRow و SpatialPanel حذف شده است. برای اشکال زدایی درختان ترکیب فضایی از SubspaceModifier.testTag استفاده کنید.
• یک بار اضافی پشتیبانی نشده از SpatialPopup که فقط دارای spatialElevationLevel و content بود حذف شد. لطفاً از رابطی استفاده کنید که onDimissRequest پشتیبانی می کند.
• پاسخ تماس onPoseChange از اصلاح کننده Movable حذف شده است. به جای آن از onMove استفاده کنید.
• SubspaceModifiers اگر جدا شده باشند یا در حال حاضر جدا شوند دیگر جلوه های خود را اعمال نمی کنند.
• SpatialRow API موجود به SpatialRow و SpatialCurvedRow تقسیم شده است. اگر قبلاً از پارامتر curveRadius SpatialRow استفاده می کردید، اکنون به جای آن SpatialCurvedRow استفاده کنید که همان رفتار را ارائه می دهد.
• MainPanel و ActivityPanel وقتی روی یک تصویر سیستم مشابه اخیر اجرا می شوند، دیگر نوار عنوان ندارند.
• اصلاح‌کننده‌های آلفا و مقیاس اکنون قابل انباشته شدن هستند و مقادیر خود را برای آلفای اعمال شده نهایی یا مقدار مقیاس ضرب می‌کنند.
• پاسخ تماس onPoseChange از اصلاح کننده Movable بهینه شده است تا حرکات پوزی نرم‌تر را انجام دهد.
• اصلاح‌کننده‌های متحرک و قابل تغییر اندازه، اکنون تماس‌های خود را روی رشته اصلی انجام می‌دهند تا اطمینان حاصل کنند که تغییرات حالت باعث ترکیب مجدد می‌شود.
• مشاهده وضعیت به طرح و مراحل اندازه گیری اضافه شد تا اطمینان حاصل شود که تغییرات حالت در SubspaceLayout باعث ایجاد رله می شود.
• به‌روزرسانی‌های زنجیره اصلاح‌کننده برای استفاده مجدد بهتر از اصلاح‌کننده‌های موجود.

رفع اشکال

• هنگامی که SpatialDialog نشان داده می‌شود، قیام کردن متوقف شد. ( IC4594 )
• درخواست‌های تغییر شکلی که هنگام جدا شدن گره‌های اصلاح‌کننده انجام می‌شوند، اکنون نادیده گرفته می‌شوند.
• حذف فازهای رله‌ای که توسط اصلاح‌کننده‌های Movable و Resizable فعال شده‌اند.
• یک خرابی در MainPanel() composable که زمانی رخ داد که هر یک از ابعاد به طور مستقیم یا در حین محاسبه طرح‌بندی، به عنوان مثال، یک محاسبه 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 حاوی این commit ها است

نسخه 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 را به نزدیک‌ترین والد composable مبتنی بر SubspaceLayout متصل می‌کند.
• LayoutCoordinatesAwareModifierNode معرفی کرد تا به اصلاح کننده های مبتنی بر موقعیت یابی سفارشی اجازه دهد.
• روش‌های چرخه حیات پیوست/جدا کردن به SubspaceModifier.Node اضافه شد.
• scaleWithDistance به اصلاح کننده متحرک اضافه شد. وقتی scaleWithDistance فعال باشد، عنصر زیرفضای منتقل شده رشد یا کوچک می شود. همچنین هر مقیاس صریحی را که قبل از حرکت داشت حفظ می کند.

تغییرات API

• SessionCallbackProvider به نفع SpatialCapabilities حذف شد.

تغییرات دیگر

• minSDK به 24 کاهش داد. همه APIهای Jetpack XR همچنان به API 34 در زمان اجرا نیاز دارند.
• سازندگان Orbiter EdgeOffset.inner ، EdgeOffset.outer و EdgeOffset.overlap دیگر متدهای @Composable نیستند، که به آنها اجازه می دهد در زمینه های غیرقابل ترکیب استفاده شوند.
• سطوح ارتفاع مکانی را برای مطابقت با آخرین مشخصات UX به روز کنید.
• رابط SubspaceSemanticsInfo را در MeasurableLayout پیاده سازی کنید.
• SubspaceModifierElement به SubspaceModifierNodeElement تغییر نام داد.

رفع اشکال

• رفع تثبیت سفارش SubspaceModifier . SubspaceModifier باید قابل اعتمادتر رفتار کند. اصلاح کننده افست، چرخش، مقیاس، متحرک و قابل تغییر اندازه اکنون باید به هر ترتیبی قابل استفاده باشد.

نسخه 1.0.0-alpha01

12 دسامبر 2024

androidx.xr.compose:compose-*1.0.0-alpha01 منتشر شد.

ویژگی های Initial Release

• انتشار اولیه توسعه دهنده Jetpack Compose برای XR. از مفاهیم آشنای Compose مانند سطرها و ستون‌ها برای ایجاد طرح‌بندی‌های UI فضایی در XR استفاده کنید، چه در حال انتقال یک برنامه دو بعدی موجود به XR یا ایجاد یک برنامه XR جدید از ابتدا باشید. این کتابخانه زیرفضا و قابلیت‌های فضایی را فراهم می‌کند: مانند پانل‌های فضایی و مدارگردها، که به شما امکان می‌دهند UI دو بعدی یا مبتنی بر Views خود را در یک طرح‌بندی فضایی قرار دهید. زیرفضای Volume composable را معرفی می کند که به شما امکان می دهد موجودیت های SceneCore مانند مدل های سه بعدی را نسبت به رابط کاربری خود قرار دهید. در این راهنمای توسعه دهنده بیشتر بیاموزید:

  • Subspace : این قابل ترکیب را می توان در هر جایی در سلسله مراتب UI برنامه شما قرار داد، به شما این امکان را می دهد که طرح بندی ها را برای UI دو بعدی و فضایی بدون از دست دادن زمینه بین فایل ها حفظ کنید. این کار اشتراک‌گذاری مواردی مانند معماری برنامه‌های موجود بین XR و سایر فاکتورهای شکل را بدون نیاز به بالا بردن حالت در کل درخت رابط کاربری یا معماری مجدد برنامه‌تان آسان‌تر می‌کند.

  • SpatialPanel : یک پانل فضایی یک زیرفضای قابل ترکیب است که به شما امکان می دهد محتوای برنامه را نمایش دهید – برای مثال، می توانید پخش ویدیو، تصاویر ثابت یا هر محتوای دیگری را در یک پانل فضایی نمایش دهید.

  • مدارگرد : مدارگرد یک جزء رابط کاربری فضایی است. طراحی شده است تا به یک پانل فضایی مربوطه متصل شود و شامل موارد ناوبری و کنش متنی مربوط به آن پانل فضایی است. برای مثال، اگر یک پانل فضایی برای نمایش محتوای ویدیویی ایجاد کرده‌اید، می‌توانید کنترل‌های پخش ویدیو را در یک مدارگرد اضافه کنید.

  • حجم : موجودیت های SceneCore، مانند مدل های سه بعدی را نسبت به رابط کاربری خود قرار دهید.

• Spatial Layout: می‌توانید چندین پانل فضایی ایجاد کنید و با استفاده از SpatialRow ، SpatialColumn ، SpatialBox و SpatialLayoutSpacer آنها را در یک Spatial Layout قرار دهید. از SubspaceModifier s برای سفارشی کردن چیدمان خود استفاده کنید.

• اجزای فضایی رابط کاربری: این عناصر را می‌توان در رابط کاربری دوبعدی شما استفاده مجدد کرد و ویژگی‌های فضایی آن‌ها تنها زمانی قابل مشاهده خواهند بود که قابلیت‌های فضایی فعال باشند.

  • SpatialDialog : پانل کمی به عقب در عمق z فشار می آورد تا یک گفتگوی بالا را نمایش دهد.
  • SpatialPopUp : پانل کمی به عقب در عمق z فشار می آورد تا یک پنجره بازشوی بالا نمایش داده شود.
  • SpatialElevation : SpatialElevationLevel را می توان برای اضافه کردن ارتفاع تنظیم کرد.

• قابلیت‌های فضایی: قابلیت‌های فضایی می‌تواند با تعامل کاربران با برنامه یا سیستم شما تغییر کند، یا حتی می‌تواند توسط خود برنامه شما تغییر کند—مثلاً حرکت به فضای خانه یا فضای کامل. برای جلوگیری از مشکلات، برنامه شما باید LocalSpatialCapabilities.current را بررسی کند تا مشخص کند کدام API در محیط فعلی پشتیبانی می‌شود. isSpatialUiEnabled : عناصر رابط کاربری فضایی (مثلاً SpatialPanel) isContent3dEnabled : اشیاء سه بعدی isAppEnvironmentEnabled : محیط isPassthroughControlEnabled : این که آیا برنامه می تواند وضعیت عبور را کنترل کند یا نه isSpatialAudioEnabled audio :

مسائل شناخته شده

• در حال حاضر برای استفاده از Jetpack Compose برای XR به minSDK 30 نیاز است. به عنوان یک راه حل، می توانید ورودی مانیفست زیر را اضافه کنید <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> تا بتوانید با minSDK 23 بسازید و اجرا کنید.
• برنامه‌های Jetpack XR در حال حاضر به درخواست مجوز android.permission.SCENE_UNDERSTANDING در AndroidManifest نیاز دارند.
• هنگامی که یک برنامه مستقیماً با استفاده از ویژگی PROPERTY_XR_ACTIVITY_START_MODE در مانیفست خود به فضای کامل راه‌اندازی می‌شود، فعالیت‌ها/برنامه‌ها ابتدا قبل از انتقال به فضای کامل در Home Space باز می‌شوند.
• glTFها در Volume Composables ممکن است در ابتدا در مکان اشتباه سوسو بزنند.
• استفاده از SpatialDialog در پانلی که به طور قابل توجهی جابجا شده است، محتوا را در جهت اشتباه سوق می دهد.