إنشاء تطبيق أساسي تفاعلي لرمي النرد

في هذا الدرس العملي، ستنشئ تطبيقًا على Android باسم Dice Roller يتيح للمستخدمين النقر على Button في التطبيق لرمي النرد. ستظهر نتيجة الرمية في TextView على الشاشة.

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

المتطلبات الأساسية

• كيفية إنشاء تطبيق "Hello, World!" وتشغيله في "استوديو Android"
• أن تكون على دراية باستخدام TextViews وImageViews في أحد التطبيقات
• كيفية تعديل سمات TextView في أداة تعديل التصميم
• كيفية استخراج النص إلى مورد سلسلة لتسهيل ترجمة تطبيقك وإعادة استخدام السلاسل
• أساسيات البرمجة بلغة Kotlin كما تم تدريسها في دروس الترميز السابقة

أهداف الدورة التعليمية

• كيفية إضافة Button إلى تطبيق Android
• كيفية إضافة سلوك عند النقر على Button في التطبيق
• كيفية فتح رمز تطبيق Activity وتعديله
• كيفية عرض الرسالة Toast
• كيفية تعديل محتوى TextView أثناء تشغيل التطبيق

ما ستنشئه

• تطبيق Dice Roller Android الذي يحتوي على Button لرمي النرد وتعديل النص على الشاشة بنتيجة الرمية

ما تحتاج إليه

• جهاز كمبيوتر مثبَّت عليه Android Studio

إليك الشكل الذي سيبدو عليه التطبيق عند إكمال هذا الدرس البرمجي.

إنشاء مشروع "نشاط فارغ"

1. إذا كان لديك مشروع حالي مفتوح في "استوديو Android"، انتقِل إلى ملف > جديد > مشروع جديد... لفتح شاشة إنشاء مشروع جديد.
2. في إنشاء مشروع جديد، أنشِئ مشروع Kotlin جديدًا باستخدام نموذج نشاط فارغ.
3. اسم التطبيق هو "Dice Roller"، والحد الأدنى لمستوى واجهة برمجة التطبيقات هو 19 (KitKat).

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

4. شغِّل التطبيق الجديد، ومن المفترض أن يظهر على النحو التالي.
   

فتح "محرّر التنسيق"

1. في نافذة المشروع، انقر نقرًا مزدوجًا على activity_main.xml (التطبيق > res > layout > activity_main.xml) لفتحه. من المفترض أن يظهر لك محرّر التصميم، مع ظهور TextView "Hello World" فقط في منتصف التطبيق.
   

بعد ذلك، ستضيف Button إلى تطبيقك. Button هو عنصر واجهة مستخدم (UI) في Android يمكن للمستخدم النقر عليه لتنفيذ إجراء.

في هذه المهمة، ستضيف Button أسفل TextView "Hello World". سيتم وضع TextView وButton داخل ConstraintLayout، وهو نوع من ViewGroup.

عندما تكون هناك Views ضمن ViewGroup، تُعتبر Views عناصر فرعية من العنصر الرئيسيViewGroup. في حالة تطبيقك، سيتم اعتبار TextView وButton من العناصر الفرعية للعنصر الرئيسي ConstraintLayout.

يمكنك المتابعة وإضافة Button كطفل في ConstraintLayout الحالي في تطبيقك.

ملاحظة: كما هو الحال في شجرة العائلة، في هيكلية طرق العرض، يمكن أن تكون طرق العرض الرئيسية نفسها طرق عرض ثانوية، ويمكن أن تكون طرق العرض الثانوية طرق عرض رئيسية لطرق عرض ثانوية أخرى.

إضافة زر إلى التصميم

1. اسحب Button من اللوحة إلى طريقة العرض التصميم، مع وضعه أسفل TextView "Hello World"
   .
2. أسفل لوحة الألوان في شجرة المكوّنات، تأكَّد من أنّ Button وTextView مدرَجان ضمن ConstraintLayout (كعناصر فرعية من ConstraintLayout).
3. لاحظ خطأً مفاده أنّ Button غير مقيّد. بما أنّ Button يقع ضمن ConstraintLayout، عليك ضبط قيود عمودية وأفقية لتحديد موقعه.

تحديد موضع الزر

في هذه الخطوة، ستضيف قيدًا عموديًا من أعلى Button إلى أسفل TextView. سيؤدي ذلك إلى وضع Button أسفل TextView.

1. في طريقة عرض التصميم، في الحافة العلوية من Button، اضغط مع الاستمرار على الدائرة البيضاء ذات الحدود الزرقاء. اسحب المؤشر وسيتبعه سهم. حرِّر الشاشة عند الوصول إلى الحافة السفلية من TextView "Hello World". يؤدي ذلك إلى إنشاء قيد على التنسيق، وينزلق Button للأعلى إلى ما تحت TextView مباشرةً.
   
2. اطّلِع على السمات على يسار محرّر التصميم.
3. في أداة القيود، لاحظ قيدًا جديدًا للتصميم تم ضبطه على أسفل TextView، من الأعلى إلى أسفل TextView (0dp). (0dp) يعني أنّ هناك هامشًا يبلغ 0. يظهر لك أيضًا خطأ بشأن عدم توفّر قيود أفقية.
   
4. أضِف قيدًا أفقيًا من الجانب الأيمن من Button إلى الجانب الأيمن من العنصر الرئيسي ConstraintLayout.
5. كرِّر الخطوة على الجانب الأيسر، مع ربط الحافة اليسرى من Button بالحافة اليسرى من ConstraintLayout. يجب أن تبدو النتيجة على النحو التالي:

6. مع استمرار تحديد Button، من المفترض أن تبدو أداة القيود على النحو التالي. لاحظ قيدَين إضافيَّين تمت إضافتهما: البداية → بداية العنصر الرئيسي (0dp) والنهاية → نهاية العنصر الرئيسي (0dp). هذا يعني أنّ Button يتم توسيطه أفقيًا في العنصر الأصل، أي ConstraintLayout.
   

7. شغِّل التطبيق. من المفترض أن يظهر بالشكل الموضّح في لقطة الشاشة أدناه. يمكنك النقر على Button، ولكنّه لا ينفّذ أي إجراء بعد. لنواصل التقدّم!

تغيير نص الزر

ستجري بعض التغييرات الإضافية على واجهة المستخدم في محرّر التصميم.

بدلاً من عرض التصنيف Button "زر"، غيِّره إلى شيء يشير إلى ما سيفعله الزر: "تدوير".

1. في أداة تعديل التصميم، بعد تحديد Button، انتقِل إلى السمات، وغيِّر النص إلى Roll، واضغط على المفتاح Enter (Return على جهاز Mac).

2. في شجرة المكوّنات، يظهر مثلث تحذير برتقالي بجانب Button. إذا مرّرت المؤشر فوق المثلث، ستظهر رسالة. رصد "استوديو Android" سلسلة مرمّزة ("Roll") في رمز تطبيقك ويقترح استخدام مصدر سلسلة بدلاً من ذلك.

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

3. في شجرة المكوّنات ، انقر على المثلث البرتقالي.

يتم فتح رسالة التحذير الكاملة.

4. في أسفل الرسالة، ضمن الحلّ المقترَح، انقر على الزر إصلاح. (قد تحتاج إلى الانتقال لأسفل الصفحة).
5. يتم فتح مربّع الحوار استخراج المورد. يعني استخراج سلسلة نصية أخذ النص "Roll" وإنشاء مصدر سلسلة نصية باسم roll في strings.xml (app > res > values > strings.xml). القيم التلقائية صحيحة، لذا انقر على حسنًا.

6. لاحظ أنّه في السمات، تشير سمة النص الخاصة بـ Button الآن إلى @string/roll، في إشارة إلى المرجع الذي أنشأته للتو.
   

في طريقة عرض التصميم، يجب أن يظهر Button تجميع.

تنسيق TextView

النص "Hello World!‎" صغير جدًا، والرسالة غير ذات صلة بتطبيقك. في هذه الخطوة، ستستبدل الرسالة الصغيرة "Hello, World!‎" برقم لعرض القيمة التي تم الحصول عليها، وستكبّر حجم الخط لتسهيل رؤيته.

1. في محرّر التصميم، اختَر TextView لكي تظهر سماته في نافذة السمات.
2. غيِّر textSize الخاص بـ TextView إلى 36sp، ليصبح كبيرًا ويسهل قراءته. قد تحتاج إلى الانتقال لأعلى أو لأسفل الشاشة للعثور على textSize.

3. محو السمة text الخاصة بالعنصر TextView ليس عليك عرض أي شيء في TextView إلى أن يرمي المستخدم النرد.

ومع ذلك، من المفيد جدًا رؤية بعض النصوص في TextView عند تعديل التنسيق والرمز الخاصين بتطبيقك. لهذا الغرض، يمكنك إضافة نص إلى TextView لا يظهر إلا في معاينة التنسيق، ولكن ليس عند تشغيل التطبيق.

.

4. انقر على TextView في شجرة المكوّنات.
5. ضمن السمات الشائعة، ابحث عن السمة نص، ثم ابحث عن السمة نص الأخرى التي تحتوي على رمز أداة. السمة text هي ما سيتم عرضه للمستخدم عند تشغيل التطبيق. السمة text التي تتضمّن رمز أداة هي سمة "نص الأدوات" المخصّصة لك كمطوّر.
6. اضبط نص الأدوات على "1" في TextView (للتظاهر بأنّك حصلت على نتيجة 1 عند رمي النرد). لن يظهر الرقم "1" إلا في محرّر التصميم ضِمن Android Studio، ولكنّه لن يظهر عند تشغيل التطبيق على جهاز فعلي أو محاكي.

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

7. انظر إلى تطبيقك في المعاينة. يظهر الرقم "1".

8. شغِّل تطبيقك. هذا هو الشكل الذي يظهر به التطبيق عند تشغيله على محاكي. لا يظهر الرقم "1". وهذا هو السلوك الصحيح.

رائع، لقد انتهيت من تغييرات التنسيق.

لديك تطبيق يتضمّن زرًا، ولكن إذا نقرت على الزر، لن يحدث أي شيء. لتغيير ذلك، عليك كتابة بعض رموز Kotlin التي تحرّك النرد وتعدّل الشاشة عند النقر على الزر.

لإجراء هذا التغيير، عليك معرفة المزيد عن كيفية تنظيم تطبيق Android.

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

في رمز MainActivity، عليك تقديم تفاصيل حول تخطيط Activity وكيفية تفاعل المستخدم معه.

• في تطبيق "بطاقة عيد الميلاد"، هناك Activity واحد يعرض رسالة عيد الميلاد والصورة.
• في تطبيق Dice Roller، هناك Activity واحد يعرض التنسيق TextView وButton الذي أنشأته للتو.

بالنسبة إلى التطبيقات الأكثر تعقيدًا، قد تكون هناك شاشات متعددة وأكثر من Activity. لكل Activity غرض محدّد.

على سبيل المثال، في تطبيق معرض الصور، يمكنك استخدام Activity لعرض شبكة من الصور، وActivity ثانٍ لعرض صورة فردية، وActivity ثالث لتعديل صورة فردية.

افتح ملف MainActivity.kt

ستضيف رمزًا برمجيًا للردّ على نقرة زر في MainActivity. لإجراء ذلك بشكلٍ صحيح، عليك فهم المزيد عن الرمز MainActivity المتوفّر حاليًا في تطبيقك.

1. انتقِل إلى ملف MainActivity.kt وافتحه (التطبيق > java > com.example.diceroller > MainActivity.kt). في ما يلي ما يجب أن يظهر لك. إذا رأيت الرمز import...، انقر على ... لتوسيع عمليات الاستيراد.

package com.example.diceroller

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

class MainActivity : AppCompatActivity() {

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)
   }
}

ليس عليك فهم كل كلمة في الرمز أعلاه، ولكن عليك أن تكون لديك فكرة عامة عن وظيفة هذا الرمز. كلّما عملت أكثر على رمز Android، أصبحت أكثر دراية به وفهمًا له.

2. اطّلِع على رمز Kotlin لفئة MainActivity، والذي يتم تحديده بالكلمة الرئيسية class ثم الاسم.

class MainActivity : AppCompatActivity() {
    ...
}

3. لاحظ أنّه لا توجد دالة main() في MainActivity.
   
   لقد تعلّمت سابقًا أنّ كل برنامج Kotlin يجب أن يتضمّن دالة main(). تعمل تطبيقات Android بشكل مختلف. بدلاً من استدعاء الدالة main()، يستدعي نظام التشغيل Android الطريقة onCreate() الخاصة بـ MainActivity عند فتح تطبيقك للمرة الأولى.
   
4. ابحث عن طريقة onCreate() التي تبدو مثل الرمز البرمجي أدناه.

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)
   }

ستتعرّف على override في درس تطبيقي حول الترميز لاحقًا (لذلك لا داعي للقلق بشأنها الآن). تُعدّ بقية طريقة onCreate() MainActivity باستخدام رمز من عمليات الاستيراد وتضبط التنسيق الأوّلي باستخدام setContentView().

5. لاحظ الأسطر التي تبدأ بـ import.
   

يوفر نظام التشغيل Android إطار عمل يتضمّن العديد من الفئات لتسهيل كتابة تطبيقات Android، ولكن يجب أن يعرف النظام الفئة التي تقصدها تحديدًا. يمكنك تحديد الفئة التي تريد استخدامها في الرمز البرمجي من خلال استخدام عبارة import. على سبيل المثال، يتم تحديد الفئة Button في android.widget.Button.

تفعيل عمليات الاستيراد التلقائية

قد يصبح من الصعب تذكُّر إضافة عبارات import عند استخدام المزيد من الفئات. لحسن الحظ، يساعدك Android Studio في اختيار عمليات الاستيراد الصحيحة عند استخدام فئات يوفّرها الآخرون. في هذه الخطوة، ستضبط Android Studio على إضافة عمليات الاستيراد تلقائيًا عندما يكون ذلك ممكنًا، وإزالة عمليات الاستيراد غير المستخدَمة تلقائيًا من الرمز البرمجي.

1. في "استوديو Android"، افتح الإعدادات من خلال الانتقال إلى ملف (File) > إعدادات أخرى (Other Settings) > الإعدادات المفضّلة للمشاريع الجديدة (Preferences for New Projects).
2. وسِّع القسم إعدادات أخرى > الاستيراد التلقائي. في قسمَي Java وKotlin، تأكَّد من وضع علامة في المربّعين بجانب إضافة عمليات استيراد غير غامضة أثناء التنفيذ وتحسين عمليات الاستيراد أثناء التنفيذ (للمشروع الحالي). يُرجى العِلم أنّ هناك مربّعَي اختيار في كل قسم.
   
   تطلب إعدادات عمليات الاستيراد غير الغامضة من "استوديو Android" إضافة عبارة استيراد تلقائيًا، طالما أنّه يمكن تحديد العبارة التي يجب استخدامها. تطلب إعدادات تحسين عمليات الاستيراد من "استوديو Android" إزالة أي عمليات استيراد لا يستخدمها الرمز البرمجي.
   
3. احفظ التغييرات وأغلِق الإعدادات بالضغط على حسنًا.

بعد أن تعرّفت على MainActivity، ستعدّل التطبيق لكي يؤدي النقر على Button إلى تنفيذ إجراء على الشاشة.

عرض رسالة عند النقر على الزر

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

1. أضِف الرمز التالي إلى طريقة onCreate() بعد طلب setContentView(). تعثر الطريقة findViewById() على Button في التصميم. R.id.button هو معرّف المورد الخاص بـ Button، وهو معرّف فريد له. يحفظ الرمز مرجعًا إلى الكائن Button في متغيّر يُسمى rollButton، وليس الكائن Button نفسه.

val rollButton: Button = findViewById(R.id.button)

ملاحظة: يخصّص نظام التشغيل Android تلقائيًا أرقام تعريف للموارد في تطبيقك. على سبيل المثال، يحتوي الزر تشغيل على معرّف مورد، كما أنّ السلسلة النصية الخاصة بنص الزر تحتوي أيضًا على معرّف مورد. تكون معرّفات الموارد بالتنسيق R.<type>.<name>، مثل R.string.roll. بالنسبة إلى معرّفات View، يكون <type> هو id، على سبيل المثال، R.id.button.

يحفظ الرمز المرجعية إلى الكائن Button في متغيّر يُسمى rollButton، وليس الكائن Button نفسه.

ملاحظة مهمة: عندما تُعيّن Kotlin عنصرًا إلى متغيّر، لا تنسخ العنصر بأكمله في كل مرة، بل تحفظ مرجعًا إلى العنصر. يمكنك اعتبار المرجع بمثابة رقم التأمين الاجتماعي أو رقم تعريف وطني آخر: يشير الرقم إلى شخص، ولكنّه ليس الشخص نفسه. عند نسخ الرقم، لن يتم نسخ الشخص.

من المفترض أن تبدو طريقة onCreate() الآن على النحو التالي.

override fun onCreate(savedInstanceState: Bundle?) {
   super.onCreate(savedInstanceState)
   setContentView(R.layout.activity_main)

   val rollButton: Button = findViewById(R.id.button)
}

2. تأكَّد من أنّ Android Studio أضاف تلقائيًا عبارة import لـ Button.
   لاحظ أنّ هناك 3 عبارات استيراد الآن، وقد تمت إضافة العبارة الثالثة تلقائيًا.
   

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.widget.Button

ملاحظة: إذا لم ينجح تفعيل عمليات الاستيراد التلقائي، سيتم تمييز Button باللون الأحمر. يمكنك إضافة عملية الاستيراد الصحيحة يدويًا عن طريق وضع مؤشر النص داخل الكلمة Button، ثم الضغط على Alt+Enter (Option+Enter على جهاز Mac).

بعد ذلك، عليك ربط الرمز بـ Button، حتى يمكن تنفيذ الرمز عند النقر على Button. معالج النقر هو جزء من الرمز البرمجي يحدّد الإجراء الذي يجب تنفيذه عند النقر. يمكنك اعتبارها رمزًا برمجيًا ينتظر أن ينقر المستخدم على Button.

3. استخدِم العنصر rollButton واضبط أداة معالجة النقرات عليه من خلال استدعاء الطريقة setOnClickListener().

rollButton.setOnClickListener {
}

أثناء الكتابة، قد يعرض Android Studio اقتراحات متعددة. في هذه الحالة، اختَر الخيار setOnClickListener {...}.

داخل الأقواس المتعرّجة، يمكنك وضع تعليمات بشأن ما يجب أن يحدث عند النقر على الزر. في الوقت الحالي، سيعرض تطبيقك Toast، وهي رسالة موجزة تظهر للمستخدم.

4. أنشئ Toast بالنص "Dice Rolled!" من خلال الاتصال بـ Toast.makeText().

val toast = Toast.makeText(this, "Dice Rolled!", Toast.LENGTH_SHORT)

5. بعد ذلك، اطلب من Toast عرض نفسه من خلال استدعاء الطريقة show().

toast.show()

إليك شكل الصف MainActivity بعد التعديل، ولا يزال البيانان package وimport في أعلى الملف:

class MainActivity : AppCompatActivity() {

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)

       val rollButton: Button = findViewById(R.id.button)
       rollButton.setOnClickListener {
           val toast = Toast.makeText(this, "Dice Rolled!", Toast.LENGTH_SHORT)
           toast.show()
       }
   }
}

يمكنك دمج السطرَين في أداة معالجة النقرات في سطر واحد بدون متغير. هذا نمط شائع قد تجده في رموز أخرى.

Toast.makeText(this, "Dice Rolled!", Toast.LENGTH_SHORT).show()

6. شغِّل التطبيق وانقر على الزر تدوير. من المفترض أن تظهر رسالة إشعار في أسفل الشاشة وتختفي بعد فترة قصيرة.

رائع! أدى النقر على الزر إلى ظهور الرسالة. هذه هي المرة الأولى التي تكتب فيها رمز Kotlin برمجيًا لنظام Android.

تعديل TextView عند النقر على الزر

بدلاً من عرض الرسالة المؤقتة Toast، ستكتب رمزًا برمجيًا لتعديل TextView على الشاشة عند النقر على الزر رمي النرد.

1. ارجع إلى activity_main.xml (التطبيق > res > layout >activity_main.xml)
2. انقر على TextView.
3. يُرجى العِلم أنّ المعرّف هو textView.
   
4. افتح MainActivity.kt (التطبيق > java > com.example.diceroller > MainActivity.kt).
5. احذف أسطر الرمز التي تنشئ Toast وتعرضه.

rollButton.setOnClickListener {
  
}

6. بدلاً من ذلك، أنشِئ متغيّرًا جديدًا باسم resultTextView لتخزين TextView.
7. استخدِم findViewById() للعثور على textView في التصميم باستخدام رقم التعريف الخاص به، وخزِّن مرجعًا إليه.

val resultTextView: TextView = findViewById(R.id.textView)

8. اضبط النص على resultTextView ليكون "6" بين علامتَي اقتباس.
   

resultTextView.text = "6"

يشبه ذلك ما فعلته من خلال ضبط النص في السمات، ولكن الآن أصبح النص في الرمز، لذا يجب أن يكون النص داخل علامتَي اقتباس مزدوجتَين. يعني ضبط هذا الإعداد بشكل صريح أنّه في الوقت الحالي، يعرض TextView دائمًا القيمة 6. ستضيف الرمز لرمي النرد وعرض قيم مختلفة في المهمة التالية.

يجب أن تبدو الفئة MainActivity على النحو التالي:

class MainActivity : AppCompatActivity() {

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)

       val rollButton: Button = findViewById(R.id.button)
       rollButton.setOnClickListener {
           val resultTextView: TextView = findViewById(R.id.textView)
           resultTextView.text = "6"
       }
   }
}

9. شغِّل التطبيق وانقر على الزر. يجب أن يتم تعديل TextView إلى "6".

الشيء الوحيد المتبقي هو رمي النرد. يمكنك إعادة استخدام فئة Dice من الدرس العملي السابق الذي يتناول منطق رمي النرد.

إضافة فئة Dice

1. بعد القوس المعقوف الأخير في الفئة MainActivity، أنشئ الفئة Dice باستخدام الطريقة roll().

class Dice(val numSides: Int) {

   fun roll(): Int {
       return (1..numSides).random()
   }
}

2. لاحظ أنّ "استوديو Android" يضع خطًا رماديًا مموجًا تحت numSides. (قد يستغرق ظهورها بعض الوقت).
3. مرِّر المؤشر فوق numSides، وسيظهر عنصر منبثق يقول قد تكون السمة "numSides" خاصة.
   

سيؤدي وضع علامة numSides على أنّه private إلى إتاحة الوصول إليه داخل صف Dice فقط. بما أنّ الرمز الوحيد الذي سيستخدم numSides يقع داخل الفئة Dice، لا بأس في جعل هذا الوسيط private للفئة Dice. ستتعرّف على المزيد من المعلومات حول المتغيرات private مقابل المتغيرات public في الوحدة التالية.

4. يمكنك إجراء التعديل المقترَح من "استوديو Android" من خلال النقر على جعل "numSides" "خاصة".

إنشاء طريقة rollDice()

بعد إضافة فئة Dice إلى تطبيقك، عليك تعديل MainActivity لاستخدامها. لتنظيم الرمز البرمجي بشكل أفضل، ضَع كل منطق رمي النرد في دالة واحدة.

1. استبدِل الرمز في أداة معالجة النقرات التي تضبط النص على "6" باستدعاء rollDice().

rollButton.setOnClickListener {
   rollDice()
}

2. بما أنّ rollDice() لم يتم تعريفه بعد، يضع Android Studio علامة على الخطأ ويعرض rollDice() باللون الأحمر.
3. إذا مرّرت مؤشر الماوس فوق rollDice()، سيعرض Android Studio المشكلة وبعض الحلول المحتملة.

4. انقر على المزيد من الإجراءات... التي تعرض قائمة. يوفّر لك "استوديو Android" إمكانية إنجاز المزيد من المهام.

ملاحظة: إذا كنت تواجه صعوبة في تمرير المؤشر ثم النقر على المزيد من الإجراءات...، يمكنك النقر على rollDice() والضغط على Alt+Enter (Option+Enter على جهاز Mac) لإظهار القائمة.

5. انقر على إنشاء الدالة "rollDice". ينشئ Android Studio تعريفًا فارغًا للدالة داخل MainActivity.

private fun rollDice() {
    TODO("Not yet implemented")
}

إنشاء مثيل جديد لكائن Dice

في هذه الخطوة، ستجعل طريقة rollDice() تنشئ نردًا وتدحرجه، ثم تعرض النتيجة في TextView.

1. داخل rollDice()، احذف مكالمة TODO().
2. أضِف رمزًا برمجيًا لإنشاء نرد بستة أوجه.

val dice = Dice(6)

3. ارمي النرد من خلال استدعاء الطريقة roll()، واحفظ النتيجة في متغيّر باسم diceRoll.

val diceRoll = dice.roll()

4. ابحث عن TextView من خلال الاتصال بالرقم findViewById().

val resultTextView: TextView = findViewById(R.id.textView)

المتغيّر diceRoll هو رقم، ولكن TextView يستخدم نصًا. يمكنك استخدام طريقة toString() على diceRoll لتحويلها إلى سلسلة.

5. حوِّل diceRoll إلى سلسلة واستخدِمها لتعديل نص resultTextView.

resultTextView.text = diceRoll.toString()

إليك الشكل الذي تبدو عليه طريقة rollDice():

private fun rollDice() {
    val dice = Dice(6)
    val diceRoll = dice.roll()
    val resultTextView: TextView = findViewById(R.id.textView)
    resultTextView.text = diceRoll.toString()
}

6. شغِّل تطبيقك. من المفترض أن تتغيّر نتيجة النرد إلى قيم أخرى غير 6. بما أنّه رقم عشوائي من 1 إلى 6، قد تظهر القيمة 6 في بعض الأحيان أيضًا.

تهانينا، أنت رائع!

من الطبيعي أن يبدو الرمز البرمجي غير مرتّب قليلاً بعد تعديل أجزاء هنا وهناك لجعل تطبيقك يعمل. ولكن قبل إغلاق التعليمات البرمجية، عليك تنفيذ بعض مهام التنظيف السهلة. بعد ذلك، سيكون التطبيق في حالة جيدة وسيسهل الحفاظ عليه من الآن فصاعدًا.

هذه العادات هي ما يتبعه مطوّرو تطبيقات Android المحترفون عند كتابة الرموز البرمجية.

دليل أسلوب Android

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

في ما يلي طريقتان يمكنك من خلالهما الالتزام بدليل الأسلوب.

تنظيف الرمز

اختصار الرمز

يمكنك جعل الرمز البرمجي أكثر إيجازًا من خلال تكثيفه في عدد أقل من الأسطر. على سبيل المثال، إليك الرمز الذي يضبط أداة معالجة النقرات على Button.

rollButton.setOnClickListener {
    rollDice()
}

بما أنّ تعليمات معالج النقرات تتألف من سطر واحد فقط، يمكنك اختصار استدعاء الدالة rollDice() والأقواس المعقوفة في سطر واحد. إليك الشكل الذي يظهر به. سطر واحد بدلاً من ثلاثة أسطر!

rollButton.setOnClickListener { rollDice() }

إعادة تنسيق الرمز البرمجي

عليك الآن إعادة تنسيق الرمز البرمجي للتأكّد من أنّه يتّبع اصطلاحات تنسيق الرموز البرمجية الموصى بها لنظام التشغيل Android.

1. في صف MainActivity.kt، حدِّد كل النص في الملف باستخدام اختصار لوحة المفاتيح Control+A على جهاز Windows (أو Command+A على جهاز Mac). يمكنك أيضًا الانتقال إلى القائمة في "استوديو Android" تعديل > تحديد الكل.
2. بعد تحديد كل النص في الملف، انتقِل إلى قائمة Android Studio الرمز > إعادة تنسيق الرمز أو استخدِم اختصار لوحة المفاتيح Ctrl+Alt+L (أو Command+Option+L على جهاز Mac).

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

إضافة تعليقات إلى الرمز البرمجي

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

من الشائع إضافة تعليق لكل فئة (MainActivity وDice هما الفئتان الوحيدتان المتوفّرتان في تطبيقك) وكل طريقة تكتبها. استخدِم الرمزين /** و**/ في بداية التعليق ونهايته لإعلام النظام بأنّ هذا ليس رمزًا برمجيًا. سيتم تجاهل هذه الأسطر عندما ينفّذ النظام الرمز البرمجي.

مثال على تعليق على صف:

/**
* This activity allows the user to roll a dice and view the result
* on the screen.
*/
class MainActivity : AppCompatActivity() {

مثال على تعليق على طريقة:

/**
* Roll the dice and update the screen with the result.
*/
private fun rollDice() {

يمكنك إضافة تعليقات داخل إحدى الطرق إذا كان ذلك سيساعد قارئ الرمز البرمجي. تذكَّر أنّه يمكنك استخدام الرمز // في بداية تعليقك. يُعدّ كل ما يلي الرمز // في السطر تعليقًا.

مثال على تعليقَين داخل طريقة:

private fun rollDice() {
   // Create new Dice object with 6 sides and roll it
   val dice = Dice(6)
   val diceRoll = dice.roll()

   // Update the screen with the dice roll
   val resultTextView: TextView = findViewById(R.id.textView)
   resultTextView.text = diceRoll.toString()
}

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

اطّلِع على رمز الحلّ لمعرفة إحدى الطرق التي كان بإمكانك من خلالها إضافة تعليقات إلى الرمز.

يتوفّر رمز الحلّ لهذا الدرس العملي في المشروع والوحدة النمطية الموضّحَين أدناه.

عنوان URL لرمز الحل: https://github.com/google-developer-training/android-basics-kotlin-create-dice-roller-with-button-app-solution

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

1. ابدأ تشغيل "استوديو Android".
2. في نافذة مرحبًا بك في "استوديو Android"، انقر على الاطّلاع على المشروع من نظام التحكّم في الإصدار.
3. اختَر Git.

4. في مربّع الحوار استنساخ المستودع، الصِق عنوان URL للرمز البرمجي المقدَّم في مربّع عنوان URL.
5. انقر على الزر اختبار وانتظِر، وتأكَّد من ظهور فقاعة منبثقة خضراء اللون مكتوب فيها تم الاتصال بنجاح.
6. يمكنك تغيير الدليل إلى قيمة مختلفة عن القيمة التلقائية المقترَحة.

7. انقر على استنساخ. يبدأ Android Studio في جلب الرمز.
8. في النافذة المنبثقة الخروج من نظام إدارة الإصدارات، انقر على نعم.

9. انتظِر إلى أن يتم فتح Android Studio.
10. اختَر الوحدة الصحيحة لبداية الدرس العملي أو رمز الحل.

11. انقر على الزر تشغيل لإنشاء الرمز وتشغيله.

مساعدة: راجِع دليل المساعدة وتحديد المشاكل وحلّها إذا لم يتم تحميل الرمز الذي تم تنزيله أو تشغيله بشكل صحيح.

• أضِف Button في تطبيق Android باستخدام أداة تعديل التصميم.
• عدِّل الفئة MainActivity.kt لإضافة سلوك تفاعلي إلى التطبيق.
• عرض رسالة Toast كحلّ مؤقت للتأكّد من أنّك على المسار الصحيح
• اضبط أداة معالجة النقر على Button باستخدام setOnClickListener() لإضافة سلوك عند النقر على Button.
• عند تشغيل التطبيق، يمكنك تعديل الشاشة من خلال استدعاء طرق في TextView أو Button أو عناصر أخرى في واجهة المستخدم في التصميم.
• أضِف تعليقات إلى الرمز البرمجي لمساعدة المستخدمين الآخرين في فهم أسلوبك.
• إعادة تنسيق الرمز البرمجي وتنظيفه

• Button صف
• Toast صف
• TextView صف
• دليل الإرشادات حول أسلوب كتابة Kotlin لمطوّري تطبيقات Android

ملاحظة: الممارسات اختيارية. وهي تتيح لك فرصة التدرب على ما تعلمته في هذا الدرس البرمجي.

يُرجى اتّباع الخطوات التالية:

1. أضِف نردًا آخر إلى التطبيق. يجب أن يؤدي النقر على الزر رمي النرد إلى رمي نردَين. يجب عرض النتائج في TextViews مختلفَين على الشاشة.

مراجعة عملك:

يجب أن يعمل تطبيقك النهائي بدون أخطاء وأن يعرض نردَين في التطبيق.