‫Jetpack Compose للواقع الموسّع

تعريف التبعيات

لإضافة تبعية إلى 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"
}

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

لمزيد من المعلومات حول العناصر التابعة، يُرجى الاطّلاع على إضافة عناصر تابعة للإنشاء.

الملاحظات

تساعدنا ملاحظاتك في تحسين Jetpack. يُرجى إعلامنا إذا اكتشفت مشاكل جديدة أو كانت لديك أفكار لتحسين هذه المكتبة. يُرجى الاطّلاع على المشاكل الحالية في هذه المكتبة قبل إنشاء مشكلة جديدة. يمكنك إضافة صوتك إلى مشكلة حالية من خلال النقر على زر النجمة.

إنشاء مشكلة جديدة

يُرجى الاطّلاع على مستندات Issue Tracker للحصول على مزيد من المعلومات.

الإصدار 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 Composables يمثّلان كرتين بزاوية 180 و360 درجة. (I40ef2، b/391705799)
• تمت إضافة SubspaceModifier.aspectRatio (Ide5ab، b/399729509، b/414762147)
• تمت إضافة واجهة برمجة التطبيقات SceneCoreEntity لتحسين إمكانية التشغيل التفاعلي بين SceneCore وCompose for XR. (I50bb3، b/423020989)
• تم توفير واجهة برمجة التطبيقات GravityAlignedsubspace لدعم ميزة "غير معدَّلة" GravityAligned (I07359)

تغييرات واجهة برمجة التطبيقات

• سيتم تنفيذ الإجراء الذي تم ضبطه عند الضغط على SpatialDialog().SpatialDialogProperties.dismissOnBack (Ib453b، b/416797132)
• عدِّل minimumPanelDimension إلى حجم سمة تلقائي جديد يبلغ Dimensions(0.1f, 0.1f, 0.1f) بسبب تمثيله بالأمتار. (Ib852a)
• ستحتفظ المساحات الفرعية و"الكائنات الفضائية" الآن بحالتها الداخلية في المساحة الرئيسية وعندما يكون التطبيق في الخلفية. في وضع "مساحات منزلية"، سيستمر تطبيق Subspace في إعداد المشهد استعدادًا للتبديل إلى وضع "مساحات كاملة". (I40317، b/416037751)
• سيحتفظ SpatialDialogs الآن بحالته عندما يكون التطبيق في الخلفية. (I6aa56)
• سيرث جهاز ApplicationSubspace الآن المقياس والموضع المقترَحَين من النظام. (I4565f, b/418834194)
• تمت إضافة رسالة خطأ أفضل وتفعيل الخطأ في وقت مبكر عند استخدام SubspaceComposable في سياق غير SubspaceComposable. (Iee2ae، b/416484684)
• تعديل ExperimentalSubspaceVolumeApi من "تحذير" إلى "خطأ" لأنّه غالبًا ما يتم تجاهل التحذيرات عند إساءة استخدام واجهات برمجة التطبيقات القابلة للإنشاء (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)
• تمت إعادة تسمية Placeable في XR إلى SubspacePlaceable للتمييز بينه وبين Placeable في Compose. (I74874)
• إزالة إعدادات Orbiter وإضافة shouldRenderInNonSpatial كمعلَمة جديدة بالإضافة إلى ذلك، تمت إزالة الفئة EdgeOffset وإضافة orbiterOffsetType كمعلَمة جديدة لدمج الدوال Orbiter(). بالإضافة إلى إعادة تسمية OrbiterEdge إلى ContentEdge. (Iebf3d)
• تمت إعادة تسمية Measurable إلى SubspaceMeasurable للتمييز بين النوع ونوع Measurable في Compose. (I9726c)
• إعادة تسمية "MeasureResult" إلى "SubspaceMeasureResult" (I9f34d)
• تمت إزالة واجهة برمجة التطبيقات setSubspaceContent لصالح استخدام setContent في Compose مع عنصر قابل للإنشاء Subspace. (Ifff4c، b/421427391، b/421427391)
• تمت إعادة تسمية MeasurePolicy إلى SubspaceMeasurePolicy. (I37a9b، b/422553904)
• حوِّل SubspaceSemanticsInfo إلى واجهة محكمة الإغلاق لأنّه لن نتمكّن من إضافة أعضاء بدون القيم التلقائية. (I372f9، b/423704068)
• تم تعديل مستندات SpatialExternalSurface، وتمت إعادة تسمية ContentSecurityLevel إلى SurfaceProtection (I3c460، b/420982808)
• تم توفير أداة إنشاء محمّلة بشكل زائد للمعدِّل القابل للنقل الذي يسمح بالتثبيت. (Ic0c70)
• إضافة المزيد من موفّري المواضع لتلميحات الأدوات، ما يتيح للمطوّرين الآن التحكّم في ما إذا كان سيتم وضع تلميح الأداة أعلى أو أسفل أو يمين أو يسار العنصر الأساسي أضِف واجهة برمجة تطبيقات تقبل شكلاً للعلامات الإدراج، حتى يمكن توفير المزيد من الأشكال المخصّصة. (Ie513c، b/374766087، b/418854637)
• تمت إزالة CoreEntity من قائمة PublishedApi (Ifee05)

إصلاح الأخطاء

• تم إصلاح المشكلة التي كانت تؤدي إلى وميض SpatialDialog عند عرضه. (Ife73c، b/401619909)
• تم إصلاح المشكلة التي كانت تتسبّب في عدم إمكانية SpatialDialog إخفاء "لوحة الأنشطة". (I8ca6c، b/367442109)
• إصلاح مشكلة عدم عرض بعض المحتوى في مربّع حوار XR (I17cd5، b/418062437)
• تم إصلاح المشكلة التي كانت تؤدي إلى إغلاق SpatialPopup عند النقر داخل المحتوى. (If262c، b/417245722)
• تم إصلاح المشكلة التي كانت تؤدي إلى عدم تغيير حجم SpatialPanel بشكل صحيح إلى الحجم الجديد عند ربط resizable().movable(). (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 المخصّصة بالوصول إلى القيم المحلية للتركيب.
• تمت إضافة واجهة برمجة تطبيقات SpatialPanel جديدة تتّبع أسلوب التنفيذ AndroidView في Compose، وتم إيقاف ViewBased SpatialPanel السابقة نهائيًا.
• تمت إضافة عنصر مصاحب VolumeConstraints.Unbounded يمثّل قيودًا غير محدودة.
• تمت إضافة SubspaceModifier.onPointSourceParams للسماح بمصدر صوتي مكاني.
• تمت إضافة ApplicationSubspace عام، ما يوفّر VolumeConstraints اختياريًا لتحديد مساحة ثلاثية الأبعاد يمكن للتطبيق عرض المحتوى المكاني فيها. بشكلٍ تلقائي، إذا لم يتم تحديد أي قيود، سيتم تحديد حدود Subspace من خلال مجال الرؤية الحالي لـ SpatialUser من حيث العرض والارتفاع. يمكن للمستخدمين تقديم قيود لاستخدامها في حال تعذّر تحديد مجال الرؤية. بخلاف ذلك، يتم استخدام القيم التلقائية لعرض وارتفاع مجال الرؤية.
• تمت إضافة SpatialExternalSurface، ويمكن استخدامها لعرض المحتوى المجسّم. يمكن تخصيص SpatialExternalSurface باستخدام أدوات التعديل (باستثناء قناة ألفا)، وتأثير تمويه الحواف.
• تمت إضافة pointerHoverIcon أداة تعديل المساحة الفرعية الجديدة التي تتيح للمستخدمين ضبط رمز المؤشر المكاني.

تغييرات واجهة برمجة التطبيقات

• تمت إزالة القيود المفروضة على RequiresApi(34) في جميع حِزم Jetpack XR. كان هذا القيد غير ضروري لأنّ Jetpack XR لا يتوفّر حاليًا إلا على الأجهزة التي تعمل بالإصدار 34 من واجهة برمجة التطبيقات أو الإصدارات الأحدث. (Iae0f8)
• تتطلّب المشاريع التي تم إصدارها باستخدام Kotlin 2.0 استخدام الإصدار 2.0.0 أو إصدار أحدث من KGP. (Idb6b5)
• ستعمل الآن ميزة "الرجوع" على اللوحات المكانية بدون أنشطة مضمّنة. لكي يعمل معالج الرجوع، عليك تحديد android:enableOnBackInvokedCallback="true" في ملف البيان Android.
• ستعمل ميزة "التعامل مع الرجوع" الآن على مربّعات الحوار المكانية. لكي يعمل معالج الرجوع، عليك تحديد android:enableOnBackInvokedCallback="true" في ملف البيان Android.
• يمكن الآن تغيير حجم SpatialPanels المستندة إلى Compose وView استنادًا إلى محتواها.
• يمكن للمطوّرين الآن ضبط قيم SpatialElevationLevel المخصّصة الخاصة بهم، ولا يقتصر الأمر على المستويات المحدّدة مسبقًا.
• يمكن الآن تخصيص مستوى ارتفاع القمر الصناعي باستخدام المَعلمة elevation.
• يمكن الآن تحديد نطاق المساحة الفرعية حسب مجال رؤية SpatialUser في العرض والارتفاع تلقائيًا. إذا تعذّر تحديد مجال الرؤية، يتم استخدام قيم العرض والارتفاع التلقائية لمجال الرؤية.
• تمت إضافة وظيفتَي ردّ الاتصال الجديدتَين onMoveStart وonMoveEnd إلى المعدِّل Movable. يتم استدعاء عمليات معاودة الاتصال onMoveStart وonMoveEnd عندما يبدأ المستخدم وينتهي من تحريك عنصر قابل للإنشاء في مساحة فرعية باستخدام المعدِّل movable.
• تمّت إزالة المَعلمة name من واجهات برمجة التطبيقات المكانية، مثل SpatialRow وSpatialPanel. لتصحيح أخطاء العروض التدرّجية المكانية، استخدِم SubspaceModifier.testTag بدلاً من ذلك.
• تمت إزالة حمولة زائدة غير متوافقة من SpatialPopup تحتوي فقط على spatialElevationLevel وcontent. يُرجى استخدام الواجهة التي تتوافق مع onDimissRequest.
• تمت إزالة عملية رد الاتصال onPoseChange من أداة التعديل Movable. يمكنك استخدام onMove كبديل.
• لن تطبّق SubspaceModifiers تأثيراتها إذا تم فصلها أو إذا كانت في طور الفصل.
• تم تقسيم واجهة برمجة التطبيقات SpatialRow الحالية إلى SpatialRow وSpatialCurvedRow. إذا كنت تستخدم المَعلمة curveRadius الخاصة بـ SpatialRow سابقًا، استخدِم SpatialCurvedRow الآن بدلاً منها لأنّها تقدّم السلوك نفسه.
• لم يعُد MainPanel وActivityPanel يتضمّنان أشرطة عناوين عند تشغيلهما على صورة نظام حديثة بالمثل.
• أصبحت معدِّلات ألفا والمقياس قابلة للتجميع وسيتم ضرب قيمها للحصول على قيمة ألفا أو المقياس النهائية.
• تم تحسين onPoseChange دالة معاودة الاتصال من أداة التعديل "قابلة للنقل" لتنفيذ حركة أكثر سلاسة للوضع.
• ستنفِّذ الآن المعدِّلات القابلة للنقل وتغيير الحجم عمليات معاودة الاتصال في سلسلة التعليمات الرئيسية لضمان أنّ تغييرات الحالة ستؤدي إلى إعادة التركيب.
• تمت إضافة مراقبة الحالة إلى مرحلتَي التنسيق والقياس لضمان أنّ تغييرات الحالة في SubspaceLayout ستؤدي إلى إعادة التنسيق.
• تحسينات على سلسلة المعدِّلات المحسَّنة لإعادة استخدام المعدِّلات الحالية بشكلٍ أفضل

إصلاح الأخطاء

• تم إيقاف التعتيم عند عرض SpatialDialog. (Ic4594)
• سيتم الآن تجاهل طلبات إعادة التخطيط التي يتم إجراؤها أثناء فصل عُقد المعدِّل.
• تمت إزالة مراحل إعادة التخطيط التي يتم تشغيلها بواسطة المعدِّلَين Movable وResizable.
• تم إصلاح عُطل في العنصر القابل للإنشاء 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 في سياقات SubspaceComposable، وسيتم ربط Orbiters بأقرب عنصر رئيسي قابل للإنشاء يستند إلى SubspaceLayout.
• تمّت إضافة LayoutCoordinatesAwareModifierNode للسماح بمعدّلات مخصّصة مستندة إلى المواضع.
• تمت إضافة طريقتَي ربط/فصل دورة الحياة إلى SubspaceModifier.Node.
• تمت إضافة scaleWithDistance إلى مفتاح التعديل القابل للنقل. عند تفعيل scaleWithDistance، سيتمدد أو يتقلص عنصر المساحة الفرعية الذي تم نقله. سيحتفظ أيضًا بأي مقياس صريح كان لديه قبل النقل.

تغييرات واجهة برمجة التطبيقات

• تمت إزالة SessionCallbackProvider واستبدالها بـ SpatialCapabilities.

التغييرات الأخرى

• تم خفض minSDK إلى 24. ستظل جميع واجهات برمجة تطبيقات Jetpack XR تتطلّب استخدام المستوى 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 جديدًا من البداية. توفّر هذه المكتبة عناصر قابلة للإنشاء في المساحات الفرعية والمساحات: مثل اللوحات المكانية والأجرام السماوية، ما يتيح لك وضع واجهة المستخدم الحالية المستندة إلى Compose أو Views في تصميم مكاني. تقدّم هذه المكتبة العنصر القابل للإنشاء Volume subspace، الذي يتيح لك وضع عناصر SceneCore، مثل النماذج الثلاثية الأبعاد، بالنسبة إلى واجهة المستخدم. يمكنك الاطّلاع على مزيد من المعلومات في دليل المطوِّر التالي:

  • Subspace: يمكن وضع هذا العنصر القابل للإنشاء في أي مكان ضمن هيكل واجهة المستخدم لتطبيقك، ما يتيح لك الحفاظ على التصاميم لواجهة المستخدم الثنائية الأبعاد والمكانية بدون فقدان السياق بين الملفات. يسهّل ذلك مشاركة عناصر مثل بنية التطبيق الحالية بين تجارب الواقع الممتد وأشكال الأجهزة الأخرى بدون الحاجة إلى نقل الحالة إلى أعلى شجرة واجهة المستخدم بأكملها أو إعادة تصميم بنية تطبيقك.

  • SpatialPanel: لوحة Spatial هي مساحة فرعية قابلة للإنشاء تتيح لك عرض محتوى التطبيق، على سبيل المثال، يمكنك عرض تشغيل الفيديو أو الصور الثابتة أو أي محتوى آخر في لوحة Spatial.

  • الجسيم الدوّار: الجسيم الدوّار هو أحد مكوّنات واجهة المستخدم المكانية. وهو مصمّم ليتم ربطه بلوحة مكانية مقابلة، ويتضمّن عناصر التنقّل والإجراءات المستنِدة إلى السياق ذات الصلة بهذه اللوحة المكانية. على سبيل المثال، إذا أنشأت لوحة مكانية لعرض محتوى فيديو، يمكنك إضافة عناصر التحكّم في تشغيل الفيديو داخل أداة Orbiter.

  • الحجم: يمكنك وضع عناصر SceneCore، مثل التصاميم الثلاثية الأبعاد، بالنسبة إلى واجهة المستخدم.

• التخطيط المكاني: يمكنك إنشاء لوحات مكانية متعددة ووضعها ضمن تخطيط مكاني باستخدام SpatialRow وSpatialColumn وSpatialBox وSpatialLayoutSpacer. استخدِم SubspaceModifier لتخصيص التنسيق.

• مكوّنات واجهة المستخدم المكانية: يمكن إعادة استخدام هذه العناصر في واجهة المستخدم الثنائية الأبعاد، ولن تكون سماتها المكانية مرئية إلا عند تفعيل الإمكانات المكانية.

  • SpatialDialog: سيتم إرجاع اللوحة قليلاً إلى الخلف في العمق z لعرض مربّع حوار مرتفع.
  • SpatialPopUp: سيتم إرجاع اللوحة قليلاً إلى الخلف في العمق z لعرض نافذة منبثقة مرتفعة
  • SpatialElevation: يمكن ضبط SpatialElevationLevel لإضافة ارتفاع.

• ‫SpatialCapabilities: يمكن أن تتغيّر الإمكانات المكانية عندما يتفاعل المستخدمون مع تطبيقك أو النظام، أو يمكن أن يغيّرها تطبيقك نفسه، مثلاً عند الانتقال إلى "المساحة الرئيسية" أو "المساحة الكاملة". لتجنُّب حدوث مشاكل، يجب أن يتحقّق تطبيقك من LocalSpatialCapabilities.current لتحديد واجهات برمجة التطبيقات المتوافقة مع البيئة الحالية. ‫isSpatialUiEnabled: عناصر واجهة المستخدم المكانية (مثل SpatialPanel) ‫isContent3dEnabled: الكائنات الثلاثية الأبعاد ‫isAppEnvironmentEnabled: البيئة ‫isPassthroughControlEnabled: ما إذا كان التطبيق يمكنه التحكّم في حالة العرض المباشر ‫isSpatialAudioEnabled: الصوت المكاني

المشاكل المعروفة

• في الوقت الحالي، يجب أن يكون الحد الأدنى لإصدار حزمة تطوير البرامج (SDK) هو 30 لاستخدام Jetpack Compose في الواقع الممتد (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 في لوحة تم نقلها بشكل كبير إلى دفع المحتوى في الاتجاه الخاطئ.