تطوير التعليمات البرمجية التكرار

بصفتك مطوّر تطبيقات للأجهزة الجوّالة، غالبًا ما تُطوّر واجهة مستخدم تطبيقك خطوة بخطوة بدلاً من تطوير كل شيء دفعة واحدة. يتّبع "استوديو Android" هذا النهج في Jetpack Compose من خلال توفير أدوات لا تتطلب بنية كاملة لفحص القيم وتعديلها والتحقّق من النتيجة النهائية.

التعديل في الوقت الفعلي

تتيح لك ميزة "التعديل المباشر" تعديل العناصر القابلة للتجميع في المحاكيات والأجهزة الفعلية في الوقت الفعلي. تقلِّل هذه الوظيفة من عمليات تبديل السياق بين كتابة التطبيق وتصميمه، ما يتيح لك التركيز على كتابة الرموز البرمجية لفترة أطول بدون انقطاع.

تتوفّر ميزة "التعديل المباشر" بثلاثة أوضاع:

  • يدوي: يتم تطبيق تغييرات الرمز عند دفعها يدويًا باستخدام Control ‏+' (Command ‏+' على نظام التشغيل macOS)
  • تطبيق التغييرات يدويًا عند الحفظ: يتم تطبيق تغييرات الرمز عند حفظها يدويًا باستخدام Control ‏+ S (Command ‏+ S على نظام التشغيل macOS).
  • تلقائي: يتم تطبيق التغييرات في جهازك أو المحاكي عند تحديث دالة قابلة للإنشاء.

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

لا تُعدّ هذه الميزة بديلاً لبناء تطبيقك وتشغيله أو لميزة تطبيق التغييرات. بدلاً من ذلك، تم تصميمه لتحسين سير العمل أثناء إنشاء واجهة مستخدم Compose ونشرها وتكرارها لتطويرها.

في ما يلي سير العمل وفقًا لأفضل الممارسات:

  1. إعداد تطبيقك كي يتمكّن من التشغيل
  2. استخدِم ميزة "التعديل المباشر" قدر الإمكان إلى أن تحتاج إلى إجراء تغيير لا تتيحه هذه الميزة، مثل إضافة طرق جديدة أثناء تشغيل التطبيق.
  3. بعد إجراء تغيير غير متوافق، انقر على تشغيل رمز
لإعادة تشغيل التطبيق واستئناف ميزة "التعديل المباشر".

بدء استخدام ميزة "التعديل المباشر"

للبدء، اتبع الخطوات التالية لإنشاء "نشاط إنشاء" فارغ وتفعيل "التعديل المباشر" لمشروعك وإجراء التغييرات باستخدام ميزة "التعديل المباشر".

إعداد مشروعك الجديد

  1. قبل البدء، تأكَّد من تثبيت الإصدار Giraffe من "استوديو Android" أو إصدار أحدث، ومن أنّ مستوى واجهة برمجة التطبيقات في الجهاز أو المحاكي لا يقل عن 30.

  2. افتح "استوديو Android" واختَر مشروع جديد في مربّع الحوار مرحبًا بك في استوديو Android. إذا كان لديك مشروع مفتوح، يمكنك إنشاء مشروع جديد من خلال الانتقال إلى ملف > جديد > مشروع جديد.

  3. اختَر نموذج نشاط كتابة فارغ لـ الهاتف والجهاز اللوحي، ثم انقر على التالي.

    اختيار النماذج في "استوديو Android"
    الشكل 1. النماذج التي يمكنك الاختيار من بينها بالنسبة إلى ميزة "التعديل المباشر"، اختَر نشاط كتابة فارغ.
  4. أكمِل مربّع الحوار مشروع جديد بالمعلومات المطلوبة: الاسم، اسم الحزمة، ومكان الحفظ، والحد الأدنى لحزمة تطوير البرامج (SDK)، ولغة إعدادات الإنشاء.

    مثال على إعدادات المشروع من الخطوة 4 التي تم إدخالها في "استوديو Android"
    الشكل 2. مثال على إعدادات المشروع.
  5. انقر على إنهاء.

تفعيل ميزة "التعديل في الوقت الفعلي"

  1. انتقِل إلى الإعدادات لتفعيل ميزة "التعديل المباشر".

    • على نظام التشغيل Windows أو Linux، انتقِل إلى ملف > الإعدادات > محرِّر > التعديل المباشر.
    • على نظام التشغيل macOS، انتقِل إلى Android Studio > الإعدادات > المحرِّر > التعديل المباشر.
  2. اختَر الخيار التعديل المباشر والوضع الذي تريد تشغيله من الإعدادات.

    في الوضع اليدوي، يتم تطبيق تغييرات الرموز في كل مرة تضغط فيها على Control+' (Command+' على نظام التشغيل macOS). في الوضع اليدوي للحفظ، يتم تطبيق تغييرات الرمز في كل مرة تحفظ فيها يدويًا باستخدام Control+S (Command+S على macOS). في الوضع التلقائي، يتم تطبيق تغييرات الرمز على جهازك أو المحاكي أثناء إجراء التغييرات.

    واجهة مستخدم مربّع الاختيار "التعديل المباشر" في إعدادات "استوديو Android"
    الشكل 3. إعدادات ميزة "التعديل المباشر"
  3. في المحرِّر، افتح ملف MainActivity، وهو نقطة دخول تطبيقك.

  4. انقر على تشغيل زر واجهة المستخدم لنشر تطبيقك.

  5. بعد تفعيل ميزة "التعديل المباشر"، تظهر علامة الاختيار الخضراء معدَّل البيانات محدَّث في أعلى يسار نافذة أداة الأجهزة التي تعمل:

    واجهة مستخدم علامة الاختيار الخضراء في التعديل المباشر

إجراء التغييرات ومراجعتها

عند إجراء تغييرات متوافقة في المحرِّر، يتم تعديل الجهاز الاختباري الافتراضي أو المادي تلقائيًا.

على سبيل المثال، عدِّل طريقة Greeting الحالية في MainActivity إلى النحو التالي:

@Composable
fun Greeting(name: String) {
    Text(
        text = "Hello $name!",
        Modifier
            .padding(80.dp) // Outer padding; outside background
            .background(color = Color.Cyan) // Solid element background color
            .padding(16.dp) // Inner padding; inside background, around text)
    )
}

تظهر التغييرات على الفور على الجهاز الاختباري، كما هو موضّح في الشكل 4.

تم تطبيق التغييرات التي تم إجراؤها على طريقة الترحيب على أحد الأجهزة.
الشكل 4. اختبار الجهاز الذي يعرض تغييرات ميزة "التعديل المباشر" التي تم إجراؤها على طريقة Greeting

تحديد المشاكل وحلّها في ميزة "التعديل في الوقت الفعلي"

إذا لم تظهر لك تعديلاتك على الجهاز التجريبي، قد يكون قد تعذّر على Android Studio تعديلها. تحقّق مما إذا كان مؤشر التعديل المباشر يشير إلى غير محدّث كما هو موضّح في الشكل 5، ما يشير إلى خطأ في عملية الترجمة. للحصول على معلومات حول الخطأ واقتراحات حول كيفية حله، انقر فوق المؤشر.

رمز "التعديل المباشر" غير صالح
الشكل 5. مؤشر حالة ميزة "التعديل المباشر"

قيود ميزة "التعديل في الوقت الفعلي"

في ما يلي قائمة بالقيود الحالية.

  • [لا ينطبق ذلك إلا على الإصدار Giraffe من Android Studio والإصدارات الأحدث] تتطلّب ميزة "التعديل المباشر" استخدام Compose Runtime 1.3.0 أو إصدار أحدث. إذا كان مشروعك يستخدم إصدارًا أقدم من ميزة "الإنشاء"، يتم إيقاف ميزة "التعديل المباشر".

  • [لا ينطبق إلا على الإصدار Giraffe من Android Studio والإصدارات الأحدث] تتطلّب ميزة "التعديل المباشر" استخدام الإصدار 8.1.0-alpha05 من AGP أو إصدار أحدث. إذا كان مشروعك يستخدم إصدارًا سابقًا من AGP، سيتم إيقاف ميزة "التعديل في الوقت الفعلي".

  • تتطلّب ميزة "التعديل المباشر" استخدام جهاز فعلي أو محاكي يعمل بالمستوى 30 من واجهة برمجة التطبيقات أو إصدار أحدث.

  • لا تتيح ميزة "التعديل المباشر" سوى تعديل نص الدالة، ما يعني أنّه لا يمكنك تغيير اسم الدالة أو توقيعها أو إضافة دالة أو إزالتها أو تغيير الحقول غير الدالة.

  • تُعيد ميزة "التعديل المباشر" ضبط حالة التطبيق في المرة الأولى التي تغيّر فيها دالة كتابة في ملف. ولا يحدث ذلك إلا بعد إجراء أول تغيير على الرمز، ولا تتم إعادة ضبط حالة التطبيق بواسطة التغييرات اللاحقة التي تجريها على وظائف Compose في هذا الملف.

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

  • يجب إجراء عملية تشغيل كاملة ليتمكّن مصحِّح الأخطاء من العمل على الصفوف التي عدّلتها باستخدام ميزة "التعديل المباشر".

  • قد يتعطّل تطبيق قيد التشغيل عند تعديله باستخدام ميزة "التعديل المباشر". وفي هذه الحالة، يمكنك إعادة نشر التطبيق باستخدام الزر تشغيل واجهة المستخدم
زر.

  • لا تُجري ميزة "التعديل المباشر" أيّ تعديل على الرمز الثنائي الذي تم تحديده فيملف إنشاء مشروعك، مثل تعديل الرمز الثنائي الذي سيتم تطبيقه عند إنشاء المشروع باستخدام الخيارات في قائمة الإنشاء أو من خلال النقر على الزرَّين إنشاء أو تشغيل.

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

  • لا يتم استئناف ميزة "التعديل المباشر" عند إعادة تشغيل التطبيق. يجب تشغيل التطبيق مرة أخرى.

  • لا تتيح ميزة "التعديل المباشر" سوى العمليات التي يمكن تصحيح أخطاءها.

  • لا تتوافق ميزة "التعديل المباشر" مع المشاريع التي تستخدم قيمًا مخصّصة للسمة moduleName ضمن kotlinOptions في إعدادات الإصدار.

  • لا تعمل ميزة "التعديل المباشر" مع عمليات النشر المتعدّدة. وهذا يعني أنه لا يمكنك النشر على أحد الأجهزة، ثم إلى آخر. لا تكون ميزة "التعديل المباشر" مفعّلة إلا على المجموعة الأخيرة من الأجهزة التي تم نشر التطبيق عليها.

  • تعمل ميزة "التعديل المباشر" مع عمليات النشر على أجهزة متعددة (عمليات النشر على أجهزة متعددة تم إنشاؤها من خلال اختيار أجهزة متعددة في القائمة المنسدلة للجهاز المستهدَف). ومع ذلك، لا يُنصح باستخدام هذه الطريقة رسميًا وقد تواجهك مشاكل. إذا واجهت مشاكل، يُرجى الإبلاغ عنها.

  • لا تتوافق ميزة "تطبيق التغييرات"/"تطبيق تغييرات الرمز" مع ميزة "التعديل في الوقت الفعلي" وتتطلّب إعادة تشغيل التطبيق قيد التشغيل.

  • لا تتيح ميزة "التعديل المباشر" حاليًا مشاريع Android Automotive.

الأسئلة الشائعة حول ميزة "التعديل المباشر"

  • ما هي الحالة الحالية لميزة "التعديل في الوقت الفعلي"؟

    تتوفّر ميزة "التعديل المباشر" في الزرّ Giraffe في "استوديو Android". لتفعيل هذه الميزة، انتقِل إلى ملف > الإعدادات > المحرِّر > التعديل المباشر (Android Studio > الإعدادات > المحرِّر > التعديل المباشر على نظام التشغيل macOS).

  • متى يجب استخدام ميزة "التعديل المباشر"؟

    استخدِم ميزة "التعديل المباشر" إذا أردت معرفة تأثير التحديثات التي أُجريت على عناصر تجربة المستخدم (مثل تعديلات عناصر التعديل والصور المتحركة) بسرعة في تجربة التطبيق بشكل عام.

  • متى يجب تجنُّب استخدام ميزة "التعديل المباشر"؟

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

  • متى يجب استخدام ميزة "معاينة الإنشاء"؟

    استخدِم ميزة "معاينة الإنشاء" عند تطوير عناصر قابلة للتجميع فردية. تعرِض ميزة "المعاينة" عناصر "الإنشاء" وتُحدِّث الشاشة تلقائيًا لعرض أثر التغييرات في الرمز البرمجي. تتيح ميزة "المعاينة" أيضًا عرض عناصر واجهة المستخدم ضمن إعدادات وحالات مختلفة، مثل المظهر الداكن واللغات وحجم الخط.

التعديل المباشر للقيم الحرفية (ميزة متوقّفة نهائيًا)

يمكن لخدمة Android Studio تعديل بعض القيم الثابتة المستخدَمة في العناصر القابلة للتجميع في الوقت الفعلي ضمن معاينات التطبيق والمحاكي والجهاز الفعلي. في ما يلي بعض الأنواع المتوافقة:

  • Int
  • String
  • Color
  • Dp
  • Boolean

فيديو للمستخدم يغيّر القيم الثابتة في رمز المصدر، ومعاينة تتم
تحديثها
ديناميكيًا

يمكنك عرض القيم الثابتة التي تؤدي إلى إجراء تعديلات في الوقت الفعلي بدون خطوة compilation (الترجمة والنشر) من خلال تفعيل زخارف القيم الثابتة من خلال مؤشر واجهة مستخدم التعديل المباشر للقيم الثابتة:

تفعيل التعديل المباشر للكلمات الثابتة

تطبيق التغييرات

تتيح لك ميزة تطبيق التغييرات تعديل الرموز البرمجية والموارد بدون الحاجة إلى إعادة نشر تطبيقك على جهاز محاكاة أو جهاز فعلي (مع بعض القيود).

عند إضافة مكونات قابلة للتجميع أو تعديلها أو حذفها، يمكنك تعديل تطبيقك بدون الحاجة إلى إعادة نشره من خلال النقر على الزر تطبيق تغييرات الرمز:

ينقر المستخدم على الزر
"تطبيق التغييرات"