مفاهيم Remote Compose وبنيتها

‫Remote Compose هي مكتبة في Jetpack تتيح لك إنشاء واجهة مستخدم باستخدام واجهات برمجة تطبيقات بنمط Compose في تطبيقك وعرضها في عمليات النظام، مثل تطبيقات مصغّرة أو تطبيقات مصغّرة لنظام التشغيل Wear OS. يسجّل تطبيقك واجهة المستخدم كمستند مضغوط، ويعرضها مشغّل في عملية المضيف ويتعامل مع التفاعلات وتغييرات الحالة والصور المتحركة محليًا، بدون معاودة الاتصال بتطبيقك.

يشرح هذا الدليل بنية Remote Compose ومدى اختلافها عن Jetpack Compose العادية. يركّز هذا الدليل على إنشاء واجهة مستخدم باستخدام المكوّنات.

حالات استخدام ميزة "الإنشاء عن بُعد"

يمكن استخدام ميزة Remote Compose على أي جهاز يتضمّن مشغّل وسائط متوافقًا. وعلى أجهزة Android، يتم تشغيل التطبيقات المصغّرة والتطبيقات المصغّرة لنظام التشغيل Wear OS.

طريقة العمل: بنية من ثلاث كتل

يكمن الاختلاف الأساسي في البنية بين Remote Compose وJetpack Compose العادي في فصل تعريف واجهة المستخدم عن التنفيذ في ثلاث مجموعات عالية المستوى:

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

توفّر هذه البنية مزايا أساسية تقلّل من وقت الاستجابة بشكل مباشر:

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

تشبيه صفحة الويب / HTML: تعمل ميزة "الإنشاء عن بُعد" بشكل مشابه لعرض صفحة ويب. ينشئ خادم التطبيق بنية HTML/مستند ويرسلها مرة واحدة، ويعرضها مضيف المتصفح ويتعامل مع التفاعلات محليًا بدون الاستعلام باستمرار عن الواجهة الخلفية.

المكونات

يوفّر Remote Compose مكوّنات واجهة مستخدم عالية المستوى لتنظيم التصاميم. استخدِم مكوّنات Remote Compose وRemoteModifier بدلاً من مكوّنات Compose العادية المكافئة لها. وتشمل هذه العناصر حاويات التنسيق الأساسية بالإضافة إلى المكوّنات التكيُّفية المصمّمة خصيصًا للتعامل مع أحجام الشاشات الديناميكية:

• مكوّنات التنسيق الأساسية: عناصر تنسيق شائعة تشبه Compose، مثل RemoteBox وRemoteRow وRemoteColumn.
• مكوّنات التنسيق التكيُّفي: مكوّنات متخصّصة، مثل RemoteFitBox وRemoteCollapsibleRow وRemoteCollapsibleColumn مصمَّمة للتكيّف بسلاسة مع مختلف مساحات العرض عن بُعد.
• تصميم المظاهر المتعددة الأبعاد: تعمل المظاهر بالطريقة نفسها مع تطبيقات Wear OS المصغّرة، مع تسلسل هرمي للألوان وأسلوب الخط الذي يوفّره RemoteMaterialTheme. يتيح ذلك تنفيذ نظام تصميم وعلامة تجارية متسقين عبر تطبيقك والتطبيقات المصغّرة.

رسم مخصّص باستخدام RemoteCanvas

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

الاختلافات الرئيسية

راجِع المفاهيم الأساسية التالية لفهم كيفية إدارة Remote Compose للحالة والمنطق والإجراءات.

المراجع الرمزية للحالة

في Compose العادي، تحتفظ حاويات الحالة بقيم نشطة وقابلة للقراءة في ذاكرة التطبيق المحلية التي يتم تغييرها بواسطة رمز التطبيق (lambdas) عند حدوث أحداث. في Remote Compose، تعمل تعريفات الحالة كمراجع رمزية. وبدلاً من الاحتفاظ بالقيم النشطة في ذاكرة التطبيق المحلية، يتم الإعلان عن عمليات الربط التي يديرها المشغّل عن بُعد ويعدّلها محليًا أثناء التشغيل. يُرجى مراعاة ما يلي عند تعريف الحالة في Remote Compose:

• استخدِم دوال مصنع Remote Compose للإعلان عن حالة مثل rememberMutableRemoteInt أو rememberMutableRemoteFloat أو rememberMutableRemoteString.
• لا يمكن لرمز تطبيقك فحص قيمة متغيّر الحالة عن بُعد أو قراءتها مباشرةً أثناء عملية الإنشاء.
• يخزّن المشغّل هذه القيم ويعدّلها على الجهاز أثناء تفاعل المستخدم مع المستند.

الحالة عن بُعد مقابل التحكّم في التدفق في Kotlin

يتم تشغيل رمز Kotlin فقط عندما ينشئ تطبيقك المستند. يمكن لعبارات Kotlin، مثل if وwhen وfor، تشكيل المستند استنادًا إلى القيم المعروفة في ذلك الوقت، مثل تكرار صف لكل عنصر في قائمة، ولكن لا يمكنها التفاعل مع حالة عن بُعد تتغيّر لاحقًا. يُرجى مراعاة ما يلي عند العمل في "الإنشاء عن بُعد":

• منطق التفريع: يتم تبديل واجهة المستخدم الديناميكية باستخدام RemoteStateLayout من خلال ربط الحالة بفتحات RemoteComposable مختلفة.
• تقييم النص: تجنَّب استخدام الاستكمال النصي العادي في Kotlin ("$remoteValue")، والذي يتم تقييمه فقط عند إنشاء المستند. بدلاً من ذلك، مرِّر RemoteString إلى RemoteText.

الأنماط الديناميكية باستخدام RemoteModifier

لا يؤدي التصميم الديناميكي على المضيف إلى إعادة تشغيل التركيب، بل يتم تمرير متغيّرات الحالة عن بُعد مباشرةً إلى المُعدِّلات، مثل RemoteModifier.background(remoteColor).

سياق النظام عن بُعد

لا تعكس مقدِّمات CompositionLocal، مثل LocalConfiguration أو LocalDensity، سوى بيئة التطبيق المحلية في وقت تسجيل المستند. ولا يتم تعديلها ديناميكيًا على المضيف البعيد عند تغيير حجم السطح أو تغيير حالة العرض أو التقدّم بمرور الوقت. بدلاً من ذلك، استخدِم القيم التي يحلّها المشغّل على المضيف في وقت التشغيل، مثل حجم المكوّن الحالي أو RemoteConfiguration أو RemoteDensity.

الإجراءات التعريفية

في Compose العادي، تكون معالِجات النقر عبارة عن دوال lambda يتم تشغيلها في تطبيقك. لا يمكن للمضيف تشغيل رمز تطبيقك، لذا في Remote Compose، يمكنك إرفاق الإجراءات بدلاً من ذلك، على سبيل المثال باستخدام RemoteModifier.clickable(action). يمكن أن يؤدي الإجراء إلى تعديل الحالة عن بُعد مباشرةً على المضيف باستخدام valueChange، أو نقله إلى تطبيقك أو المضيف باستخدام pendingIntentAction أو hostAction. لتنفيذ عدة إجراءات بنقرة واحدة، يمكنك استخدام combinedAction.

مقارنة بين النماذج العالية المستوى

نطاق الميزة	Standard Jetpack Compose	Remote Compose
أحداث النقر وأحداث اللمس	دوال Lambda المتزامنة قيد المعالجة	كائنات Action تسلسلية تعريفية
المنطق الشرطي	التحكّم في التدفق باستخدام if وwhen في Kotlin	تعمل دالة if/when العادية في Kotlin بشكل طبيعي مع الحالة الثابتة المعروفة عند إنشاء المستند. يستخدم التفريع الديناميكي RemoteStateLayout (للعروض التدرّجية لواجهة المستخدم).
حلقات التحكّم في التدفق	حلقات التكرار for وwhile العادية في Kotlin	لا يتم تشغيل حلقات Kotlin العادية (repeat وfor وforEach) إلا عند إنشاء المستند. لا يمكنهم تكرار الحالة عن بُعد على المضيف
مضيف التنفيذ	عملية التطبيق	مشغّل التطبيقات (AppWidget) أو تطبيقات Wear OS المصغّرة أو أي شكل جهاز يتضمّن مشغّل وسائط متوافقًا
مراحل العملية	يجب أن تظل العملية نشطة لإعادة الإنشاء والعرض	يسجّل Process مستند لقطة واجهة المستخدم، ويحلّل محرّك Remote Player شجرة المكوّنات، ويتتبّع تغييرات الحالة، ويعيد الرسم محليًا بدون معاودة الاتصال بالتطبيق.
الآثار الجانبية	مراحل نشاط الكوروتين (LaunchedEffect)	غير متاح على المضيف. يتم تشغيل Composition في تطبيقك لإنشاء المستند، لذا لا يمكن لتأثيرات الكوروتين تشغيل واجهة المستخدم عن بُعد، ما لم يحافظ الدمج على فتح Composition.
نموذج الحالة	قيم حالة الذاكرة المحلية	دوال المصنع (rememberMutableRemoteInt()‎ وrememberNamedRemoteColor()‎) التي تعرض مراجع الحالة الرمزية بدلاً من القيم الأولية