حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات السريعة على Android

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

هذا دليل البدء السريع مخصّص للمطوّرين الذين لديهم معرفة أساسية بتطوير تطبيقات Android باستخدام لغتَي Kotlin أو Java.

لمحة عن بيئة التطوير

تم تطوير دليل البدء السريع هذا باستخدام استوديو Android Hedgehog والإصدار 8.2 من المكوّن الإضافي Android Gradle .

إعداد جهاز Android

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

• لاستخدام جهاز Android، اتّبِع التعليمات الواردة في مقالة تشغيل التطبيقات على جهاز مادي.
• لاستخدام Android Emulator، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام أداة إدارة الأجهزة الافتراضية المتوافقة مع Android (AVD) المضمّنة في "استوديو Android".

إنشاء مشروع "خرائط Google" في "استوديو Android"

تم تغيير إجراء إنشاء مشروع "خرائط Google" في "استوديو Android" في الإصدارَين Flamingo والإصدارات الأحدث من "استوديو Android".

1. افتح "استوديو Android" وانقر على مشروع جديد في نافذة مرحبًا بك في "استوديو Android".

2. في نافذة مشروع جديد ، ضمن فئة الهاتف والجهاز اللوحي، اختر بدون نشاط، ثم انقر على التالي.

3. أكمِل نموذج مشروع جديد:

   • اضبط اللغة على Java أو Kotlin. تتوافق حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android مع كلتا اللغتَين بشكل كامل. لمزيد من المعلومات عن لغة Kotlin، يُرجى الاطّلاع على مقالة تطوير تطبيقات Android باستخدام لغة Kotlin.

   • اضبط الحد الأدنى من حزمة تطوير البرامج (SDK) على إصدار حزمة تطوير البرامج المتوافق مع جهاز الاختبار. عليك اختيار إصدار أكبر من الحد الأدنى للإصدار المطلوب في حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android الإصدار 20.0.x، وهو المستوى 23 من واجهة برمجة التطبيقات Android ("Marshmallow"؛ Android 6.0) أو إصدار أحدث. يُرجى الاطّلاع على ملاحظات الإصدار للحصول على أحدث المعلومات عن متطلبات إصدار حزمة تطوير البرامج.

   • اضبط لغة إعدادات التصميم على Kotlin DSL أو Groovy DSL. تظهر مقتطفات لغتَي إعدادات الإصدار في الإجراءَين التاليَين.

4. انقر على إنهاء.

   يبدأ "استوديو Android" تشغيل Gradle وينشئ المشروع. وقد تستغرق هذه العملية بعض الوقت.

5. أضِف النشاط "عرض خرائط Google":

   1. انقر بزر الماوس الأيمن على مجلد app في مشروعك.

   2. اختَر جديد > Google > النشاط "عرض خرائط Google".

      

   3. في مربّع حوار نشاط Android جديد ، ضَع علامة في مربّع الاختيار نشاط مشغّل التطبيق.

   4. اختَر إنهاء.

      لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إضافة رمز من نموذج.

6. عند اكتمال عملية الإنشاء، يفتح "استوديو Android" الملفَين AndroidManifest.xml وMapsActivity. قد يكون للنشاط اسم مختلف، ولكنّه النشاط الذي ضبطته أثناء الإعداد.

إعداد مشروع على السحابة الإلكترونية في Google

أكمِل خطوات الإعداد المطلوبة في Cloud Console من خلال النقر على علامات التبويب التالية:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

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

لتبسيط هذه المهمة، ننصحك باستخدام الـ مكوّن الإضافي Secrets Gradle لأجهزة Android.

لتثبيت المكوّن الإضافي Secrets Gradle لأجهزة Android وتخزين مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

1. في "استوديو Android"، افتح ملف build.gradle على مستوى الجذر وأضِف الرمز التالي إلى العنصر dependencies ضمن buildscript.

   Groovy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

2. افتح ملف build.gradle على مستوى التطبيق وأضِف الرمز التالي إلى عنصر plugins.

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. إذا كنت تستخدم "استوديو Android"، زامِن مشروعك مع Gradle.
4. افتح local.properties في دليل مستوى المشروع، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات.

   MAPS_API_KEY=YOUR_API_KEY

5. في ملف AndroidManifest.xml ، انتقِل إلى com.google.android.geo.API_KEY وعدِّل السمة android:value على النحو التالي:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

   ملاحظة: com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على واجهات برمجة تطبيقات متعددة تستند إلى "خرائط Google" على نظام Android الأساسي، بما في ذلك حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android. لضمان التوافق مع الإصدارات السابقة، تتوافق واجهة برمجة التطبيقات أيضًا مع الاسم com.google.android.maps.v2.API_KEY. يسمح هذا الاسم القديم بالمصادقة على Android Maps API v2 فقط. لا يمكن للتطبيق تحديد سوى أحد أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

الاطّلاع على الرمز

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

ملف النشاط على "خرائط Google"

ملف النشاط على "خرائط Google" هو النشاط الرئيسي للتطبيق، ويحتوي على الرمز اللازم لإدارة الخريطة وعرضها. يكون اسم الملف الذي يحدّد النشاط تلقائيًا MapsActivity.java أو MapsActivity.kt إذا ضبطت لغة Kotlin كلغة لتطبيقك.

العناصر الرئيسية للنشاط على "خرائط Google":

• يدير العنصر SupportMapFragment دورة حياة الخريطة وهو العنصر الرئيسي لواجهة مستخدم التطبيق.

• يتيح العنصر GoogleMap الوصول إلى بيانات الخريطة و عرضها. وهو الفئة الرئيسية في حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android. يصف دليل عناصر الخريطة العنصرَين SupportMapFragment وGoogleMap بمزيد من التفصيل.

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

• تضيف الدالة addMarker علامة إلى إحداثيات سيدني. يُرجى الاطّلاع على دليل العلامات لمعرفة التفاصيل.

ملف Gradle على مستوى الوحدة

يتضمّن ملف build.gradle.kts على مستوى الوحدة ملحق الخرائط التالي، المطلوب في حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android.

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

لمزيد من المعلومات عن إدارة الاعتمادية على الخرائط، يُرجى الاطّلاع على مقالة تحديد الإصدار.

ملف تنسيق XML

ملف activity_maps.xml هو ملف تنسيق XML الذي يحدّد بنية واجهة مستخدم التطبيق. يقع الملف في الدليل res/layout. يصرّح ملف activity_maps.xml عن جزء يتضمّن العناصر التالية:

• tools:context يضبط النشاط التلقائي للجزء على MapsActivity، الذي تم تحديده في ملف النشاط على "خرائط Google".
• android:name يضبط اسم فئة الجزء على SupportMapFragment، وهو نوع الجزء المستخدَم في ملف النشاط على "خرائط Google" .

يحتوي ملف تنسيق XML على الرمز التالي:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

نشر التطبيق وتشغيله

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

لنشر التطبيق وتشغيله، اتّبِع الخطوات التالية:

1. في "استوديو Android"، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل) لـ تشغيل تطبيقك.
2. عندما يُطلب منك اختيار جهاز، اختَر أحد الخيارَين التاليَين:
   • اختَر جهاز Android المتصل بجهاز الكمبيوتر.
   • بدلاً من ذلك، انقر على زر الخيار تشغيل المحاكي واختَر الجهاز الافتراضي الذي أعددته.
3. انقر على حسنًا. سيبدأ "استوديو Android" تشغيل Gradle لإنشاء تطبيقك، ثم يعرض النتائج على جهازك أو المحاكي. قد يستغرق الأمر عدة دقائق قبل تشغيل التطبيق.

الخطوات التالية

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

• إضافة خريطة إلى تطبيق Android (Kotlin): يرشدك هذا الدرس التطبيقي حول الترميز خلال تطبيق يعرض بعض الميزات الإضافية لحزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android.

• استخدام مكتبة Maps Android KTX: تتيح لك مكتبة Kotlin Extensions (KTX) الاستفادة من العديد من ميزات لغة Kotlin أثناء استخدام حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android.