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

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

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

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

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

إعداد جهاز Android

لتشغيل تطبيق يستخدم حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android، عليك نشره على جهاز Android أو Android Emulator يستند إلى الإصدار Android 5.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، وهو المستوى 21 من واجهة برمجة التطبيقات Android ("Lollipop"؛ Android 5.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

أكمِل خطوات الإعداد المطلوبة على 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 هذه الاستفادة من عدة ميزات في لغة Kotlin أثناء استخدام حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android.