Jetpack Compose للواقع المعزّز

إنشاء تصاميم واجهة مستخدم مكانية بشكل صريح تستفيد من الإمكانات المكانية لنظام Android XR
آخر تعديل الإصدار الثابت إصدار محتمل الإصدار التجريبي الإصدار الأولي
7 أيار (مايو) 2025 - - - 1.0.0-alpha04

تحديد التبعيات

لإضافة تبعية على XR compose، يجب إضافة مستودع Google Maven إلى مشروعك. اطّلِع على مستودع Maven من Google لمزيد من المعلومات.

أضِف التبعيات للعناصر التي تحتاج إليها في ملف build.gradle ل تطبيقك أو وحدتك:

GroovyKotlin 
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 عمليات الربط هذه.

الميزات الجديدة

  • تمت إضافة واجهة CompositionLocalConsumerSubspaceModifierNode للسماح بأنواع SubspaceModifier المخصّصة بالوصول إلى القيم المحلية للتركيب.
  • تمت إضافة واجهة برمجة تطبيقات SpatialPanel جديدة تتّبع أسلوب تنفيذ AndroidView للإنشاء وتوقّف عن استخدام ViewBased SpatialPanel السابقة.
  • تمت إضافة عنصر VolumeConstraints.Unbounded المصاحب الذي يمثّل قيودًا غير محدودة.
  • تمت إضافة SubspaceModifier.onPointSourceParams للسماح بمصدر صوت محيطي.
  • تمت إضافة ApplicationSubspace متاح للجميع، ويقدّم VolumeConstraints اختياريًا لتحديد منطقة ثلاثية الأبعاد يمكن للتطبيق عرض المحتوى المكاني فيها. بشكلٍ تلقائي، في حال عدم تحديد أي قيود، سيتم تقييد المساحة الفرعية بحقل الرؤية الحالي لعنصر SpatialUser في العرض والارتفاع. يمكن للمستخدمين تقديم قيود لاستخدامها إذا تعذّر تحديد مجال الرؤية. وبخلاف ذلك، يتم استخدام قيم العرض والارتفاع التلقائية لحقل العرض.
  • تمت إضافة SpatialExternalSurface، ويمكن استخدامه لعرض المحتوى المجسم. يمكن تخصيص SpatialExternalSurface باستخدام عوامل التعديل (باستثناء "القيمة ألفا") وتأثير تمويه الحواف.
  • تمت إضافة مُعدِّل pointerHoverIcon جديد للمساحة الفرعية يسمح للمستخدمين بضبط رمز المؤشر المكاني.

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

  • تمّت إزالة القيود المفروضة على RequiresApi(34) في جميع حِزم Jetpack XR. كان هذا القيد زائدًا لأنّ Jetpack XR لا يتوفّر حاليًا إلا على الأجهزة التي تعمل بمستوى واجهة برمجة التطبيقات 34 أو الإصدارات الأحدث. (Iae0f8)
  • تتطلّب المشاريع التي تم إصدارها باستخدام Kotlin 2.0 استخدام KGP 2.0.0 أو إصدار أحدث. (Idb6b5)
  • سيتم الآن التعامل مع الخلفية في اللوحات المكانية بدون أنشطة مضمّنة. لكي تعمل معالجة الرجوع، عليك تحديد android:enableOnBackInvokedCallback="true" في ملف بيان Android.
  • ستتم الآن معالجة الطلبات الخلفية في المحادثات المكانية. لكي تعمل ميزة "المعالجة الخلفية"، عليك تحديد android:enableOnBackInvokedCallback="true" في ملف بيان Android.
  • يمكن الآن لعناصر SpatialPanel المستندة إلى ميزة "الإنشاء" و"العرض" ضبط حجمها استنادًا إلى محتواها.
  • يمكن للمطوّرين الآن ضبط قيم SpatialElevationLevel المخصّصة الخاصة بهم ولا يقتصرون على المستويات المحدّدة مسبقًا.
  • يمكن الآن تخصيص مستوى ارتفاع المدارات من خلال المَعلمة elevation.
  • يمكن الآن أن تكون المساحة الفرعية محدودة تلقائيًا بحقل رؤية SpatialUser في العرض والارتفاع. إذا تعذّر تحديد مجال العرض، يتم استخدام قيم العرض والارتفاع التلقائية لحقل العرض.
  • تمت إضافة وظيفتَي استدعاء جديدة onMoveStart وonMoveEnd إلى المُعدِّل Movable. يتمّ استدعاء وظيفتَي الاستدعاء onMoveStart وonMoveEnd عندما يبدأ المستخدم بتحريك مساحة فرعية قابلة للتجميع مع المُعدِّل القابل للتحريك وينتهي من تحريكها.
  • تمّت إزالة المَعلمة name من واجهات برمجة التطبيقات المكانية، مثل SpatialRow وSpatialPanel. لتصحيح أخطاء أشجار الإنشاء المكاني، استخدِم SubspaceModifier.testTag بدلاً من ذلك.
  • تمت إزالة رمز SpatialPopup غير المتوافق الذي يتضمّن spatialElevationLevel وcontent فقط. يُرجى استخدام الواجهة المتوافقة مع onDimissRequest.
  • تمت إزالة طلب إعادة الاتصال onPoseChange من المُعدِّل القابل للنقل. استخدِم 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 على عمليات الربط التالية.

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

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

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

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

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

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

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

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

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

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

  • يجب حاليًا استخدام الإصدار 30 من حزمة تطوير البرامج (SDK) كحد أدنى لاستخدام Jetpack Compose مع تطبيقات الواقع المعزّز. كحل بديل، يمكنك إضافة إدخال البيان التالي <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> لتتمكّن من إنشاء التطبيق وتشغيله باستخدام الإصدار 23 من حزمة تطوير البرامج (SDK) كحد أدنى.
  • تتطلّب تطبيقات Jetpack XR حاليًا طلب إذن android.permission.SCENE_UNDERSTANDING في ملف AndroidManifest.
  • عند تشغيل تطبيق مباشرةً في "المساحة الكاملة" باستخدام الموقع PROPERTY_XR_ACTIVITY_START_MODE في البيان، يتم فتح "الأنشطة" أو "التطبيقات" في البداية في "المساحة الرئيسية" قبل الانتقال إلى "المساحة الكاملة".
  • قد تظهر ملفات glTF في "العناصر القابلة للتجميع في الحجم" في البداية بشكل متقطع في الموقع غير الصحيح.
  • سيؤدي استخدام SpatialDialog في لوحة تم نقلها بشكل كبير إلى دفع المحتوى في الاتجاه الخطأ.