أنشئ تطبيقًا تفاعليًا أساسيًا لرمي النرد.

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

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

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

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

ما ستتعرَّف عليه

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

العناصر التي سيتم إنشاؤها

• تطبيق رمي النرد على Android يتضمّن Button لرمي حجر نرد وتحديث النص الذي يظهر على الشاشة بنتائج اللف.

ما تحتاج إليه

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

في ما يلي مظهر التطبيق عند إكمال هذا الدرس التطبيقي حول الترميز.

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

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

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

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

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

1. في نافذة المشروع، انقر مرّتين على activity_main.xml (app > res > Layout > activity_main.xml) لفتحه. من المفترض أن يظهر لك محرر التنسيق، الذي يتضمّن &&quot؛مرحبًا بالعالم &&quot؛ TextView في منتصف التطبيق.
   

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

في هذه المهمة، أضِف Button أسفل &"مرحبًا بالعالم &&quot؛ TextView. سيكون TextView وButton ضمن ConstraintLayout، وهو نوع من ViewGroup.

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

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

ملاحظة: كما هو الحال في شجرة العائلة، في العرض الهرمي، يمكن أن تكون مرات المشاهدة للوالدَين عبارة عن مشاهدات للأطفال، في حين يمكن أن تكون مشاهدات الأطفال آباءً للأطفال الآخرين.

إضافة زر إلى التنسيق

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

وضع الزر

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

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

6. أثناء تحديد Button، يجب أن تظهر أداة التقييد على النحو التالي. لاحِظ قيودًا إضافية تمت إضافتها: Start Start(ابدأ) ← StartOfوار (0dp) وEnd (إنهاء) ← EndOf رئيسي (0dp). وهذا يعني أن Button يتم توسيطها أفقيًا في الأصل، ConstraintLayout.
   

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

تغيير نص الزر

ستتمكّن من إجراء تغييرَين إضافيَين في واجهة المستخدم في محرّر التنسيق.

بدلاً من عرض التصنيف Button &&&;;Button" يمكنك تغيير ذلك إلى شيء يشير إلى ما سيفعله الزر: "Roll"

1. في محرّر التنسيق، مع اختيار Button، انتقِل إلى السمات، وغيِّر النص إلى اللف، ثم اضغط على المفتاح Enter (Return في نظام التشغيل Mac).

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

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

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

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

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

6. يُرجى ملاحظة أنه في السمات، توضح السمة text للحقل Button الآن @string/roll، للإشارة إلى المورد الذي أنشأته للتو.
   

في عرض التصميم، يجب أن يستمر Button في الظهور على اللف.

اختيار نمط TextView

النص &&quot؛مرحبًا بالعالم!" صغير جدًا، والرسالة ليست ذات صلة بتطبيقك. في هذه الخطوة، سوف تستبدل الرسالة الصغيرة &&hl=ar;مرحبًا، العالم!" برقم لعرض القيمة التي تم عرضها وتكبير الخط، حتى يسهل رؤيتها.

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

3. أزِل سمة النص من TextView. لن تحتاج إلى عرض أي شيء في TextView حتى يرمي المستخدم النرد.

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

.

4. اختَر TextView في شجرة المكوّنات.
5. ضمن السمات الشائعة، ابحث عن السمة text، وأسفلها، سمة نصية تحتوي على رمز أداة. السمة text هي ما سيتم عرضه للمستخدم عند تشغيل التطبيق. السمة text التي تحمل رمز الأداة هي السمة &quot؛أدوات نص&quot؛ المخصّصة لك كمطوّر برامج.
6. اضبط نص الأدوات ليكون في &&;1" في TextView (للتظاهر بأن لديك رمي الزهر 1). لن يظهر &&quot؛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 وافتحه (app > 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" على اختيار عمليات الاستيراد الصحيحة عند استخدام الصفوف التي يوفرها الآخرون. في هذه الخطوة، سيكون عليك ضبط "استوديو Android" لإضافة عمليات الاستيراد تلقائيًا عند الإمكان، وإزالة عمليات الاستيراد غير المستخدمة تلقائيًا من الرمز.

1. في "استوديو Android"، افتح الإعدادات بالانتقال إلى الملف &gt؛ إعدادات أخرى &gt؛ الإعدادات المفضّلة للمشاريع الجديدة.
2. توسيع الإعدادات الأخرى &gt والاستيراد التلقائي. تأكَّد من وضع علامة في مربّعَي 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 تلقائيًا أرقام التعريف للموارد في تطبيقك. على سبيل المثال، يحتوي الزر Roll على رقم تعريف مورد، وتتضمّن سلسلة نص الزر رقم تعريف مورد أيضًا. تتكوّن أرقام تعريف الموارد من النموذج 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" أضاف عبارة 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"عدة اقتراحات. بالنسبة إلى هذه الحالة، حدّد الخيار 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. شغِّل التطبيق وانقر على الزر Roll. من المفترض أن تظهر رسالة توست في أسفل الشاشة وتختفي بعد فترة قصيرة.

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

تعديل عرض النص عند النقر على الزر

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

1. ارجِع إلى activity_main.xml (app > res >Layout >activity_main.xml).
2. انقر على TextView.
3. تجدر الإشارة إلى أن id هي textView.
   
4. افتح MainActivity.kt (app > 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"

يشبه هذا ما فعلته من خلال ضبط text في السمات، ولكنها الآن في الرمز، لذا يجب وضع النص داخل علامات الاقتباس المزدوجة. ويعني ضبط هذه السياسة صراحةً أنّ 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 من درس تطبيقي سابق حول الترميز، وهو سيعالج منطق رمي حجر النرد.

إضافة فئة نرد

1. بعد آخر قوس متعرّج في الصف MainActivity، يمكنك إنشاء الصف Dice باستخدام طريقة roll().

class Dice(val numSides: Int) {

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

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

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

4. يمكنك الآن إجراء الإصلاح المقترَح من "استوديو Android" بالنقر على Make 'numSides' 'private'.

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

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

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

rollButton.setOnClickListener {
   rollDice()
}

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

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

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

5. اختَر إنشاء دالة 'rollDice'. يُنشئ "استوديو Android" تعريفًا فارغًا للدالة داخل MainActivity.

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

إنشاء مثيل نرد جديد

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

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

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 Studio تعديل &gt؛ تحديد الكل.
2. مع تحديد النص بأكمله في الملف، انتقِل إلى قائمة "استوديو Android" الرمز > إعادة تنسيق الرمز أو استخدِم اختصار لوحة المفاتيح 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 Studio، نفِّذ ما يلي.

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

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

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

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

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

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

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

• Button صف
• Toast صف
• TextView صف
• دليل نمط Kotlin لمطوّري برامج Android

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

يُرجى تنفيذ ما يلي:

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

التحقق من عملك:

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