أنشئ تطبيق Android يعرض خريطة باستخدام نموذج خرائط Google لـ Android Studio. إذا كان لديك مشروع حالي في Android Studio وتريد إعداده، فراجع تهيئة المشروع.
يمكن استخدام هذه النصيحة لمطوّري البرامج الذين لديهم دراية بتطوير برامج Android الأساسية باستخدام جافا أو Kotlin.
إعداد بيئة التطوير
- مطلوب Android Studio Arctic Fox أو إصدار أحدث. في حال عدم إجراء ذلك من قبل، يمكنك تنزيله وتثبيته.
- تأكّد من استخدام الإصدار 7.0 من مكوّن Gradle الإضافي لنظام التشغيل Android أو إصدار أحدث في "استوديو Android".
إعداد جهاز Android
لتشغيل تطبيق يستخدم خرائط Google SDK لنظام التشغيل Android، يجب نشره على جهاز Android أو محاكي Android الذي يعتمد على Android 4.0 أو إصدار أحدث ويتضمن واجهات برمجة تطبيقات Google.
- لاستخدام جهاز يعمل بنظام التشغيل Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز.
- لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي من خلال استخدام مدير الأجهزة الافتراضية (AVD) من Android الذي يأتي مرفقًا مع Android Studio.
إنشاء مشروع على "خرائط Google" في "استوديو Android"
افتح "استوديو Android" وانقر على إنشاء مشروع جديد في نافذة مرحبًا بك في Android Studio.
في نافذة مشروع جديد، ضمن فئة الهاتف والجهاز اللوحي، حدّد نشاط خرائط Google، ثم انقر على التالي.
املأ نموذج نشاط خرائط Google:
اضبط اللغة على جافا أو Kotlin. وكلتا اللغتين مدعومتان بالكامل من خلال SDK للخرائط على نظام التشغيل Android. لمزيد من المعلومات عن لغة Kotlin، يمكنك الاطّلاع على تطوير تطبيقات متوافقة مع Android باستخدام لغة Kotlin.
اضبط الحد الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة تطوير البرامج (SDK) المتوافق مع جهازك الاختباري. يجب تحديد إصدار أكبر من الحد الأدنى للإصدار المطلوب في الإصدار 18.0.x من تطبيق SDK لخرائط Android، والذي يمثل حاليًا واجهة برمجة تطبيقات Android المستوى 19 (Android 4.4، KitKat) أو إصدارًا أحدث. اطلع على ملاحظات الإصدار للحصول على أحدث المعلومات حول متطلبات إصدار SDK.
انقر على إنهاء.
يبدأ "استوديو Android" تطبيق Gradle وينشئ المشروع. وقد تستغرق هذه العملية بعض الوقت.
عند الانتهاء من الإصدار، يفتح Android Studio الملفين
AndroidManifest.xml
وMapsActivity
. قد يحمل نشاطك اسمًا مختلفًا، ولكنه سيكون النشاط الذي هيأته أثناء الإعداد.يحتوي الملف
AndroidManifest.xml
على تعليمات حول الحصول على مفتاح API لخرائط Google ثم إضافته إلى ملف local.properties لديك. لا تُضف مفتاح API إلى ملفAndroidManifest.xml
. يؤدي ذلك إلى تخزين مفتاح واجهة برمجة التطبيقات بشكل أقل أمانًا. بدلاً من ذلك، اتّبع التعليمات الواردة في الأقسام التالية لإنشاء مشروع على السحابة الإلكترونية وضبط مفتاح واجهة برمجة التطبيقات.
إعداد مشروعك على Google Cloud
أكمل خطوات إعداد Cloud Console المطلوبة بالنقر على علامات التبويب التالية:
الخطوة 1
وحدة التحكّم
-
في Google Cloud Console، في صفحة أداة اختيار المشروع، انقر على Create Project (إنشاء مشروع) لبدء إنشاء مشروع Cloud جديد.
-
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. تأكد من تفعيل الفوترة لمشروعك.
تقدّم خدمة Google Cloud فترة تجريبية بدون رسوم. وتنتهي صلاحية النسخة التجريبية في آخر 90 يومًا أو بعد أن تتراكم على الحساب رسوم بقيمة 300 دولار أمريكي (أو ما يعادله بالعملة المحلية)، أيهما أقرب. يمكنك إلغاء الاشتراك في أي وقت. تقدم Google Maps Platform رصيدًا شهريًا بقيمة 200 دولار أمريكي (أو ما يعادله بالعملة المحلية) بشكل متكرر. لمزيد من المعلومات، اطّلِع على أرصدة حسابات الفوترة والفوترة.
Cloud SDK
gcloud projects create "PROJECT"
يمكنك الاطّلاع على مزيد من المعلومات عن Google Cloud SDK وتثبيت Cloud SDK والطلبات التالية:
الخطوة 2
لاستخدام "منصة خرائط Google"، يجب تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي تنوي استخدامها مع مشروعك.
وحدة التحكّم
تفعيل حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل Android
Cloud SDK
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
يمكنك الاطّلاع على مزيد من المعلومات عن Google Cloud SDK وتثبيت Cloud SDK والطلبات التالية:
الخطوة 3
تمر هذه الخطوة فقط خلال عملية إنشاء مفتاح واجهة برمجة التطبيقات. إذا كنت تستخدم مفتاح واجهة برمجة التطبيقات الخاص بك في مرحلة الإنتاج، ننصحك بشدة بتقييد مفتاح واجهة برمجة التطبيقات. ويمكنك العثور على مزيد من المعلومات في صفحة استخدام مفاتيح واجهة برمجة التطبيقات الخاصة بالمنتج.
مفتاح واجهة برمجة التطبيقات هو معرّف فريد يصادق على الطلبات المرتبطة بمشروعك لأغراض الاستخدام والفوترة. يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات واحد على الأقل مرتبط بمشروعك.
لإنشاء مفتاح واجهة برمجة تطبيقات:
وحدة التحكّم
-
انتقل إلى صفحة منصة خرائط Google > بيانات الاعتماد.
-
في صفحة بيانات الاعتماد، انقر على إنشاء بيانات الاعتماد > مفتاح واجهة برمجة التطبيقات.
يعرض مربع الحوار مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه حديثًا. -
انقر على إغلاق.
يتم إدراج مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
(تذكر تقييد واجهة برمجة التطبيقات قبل استخدامها في الإنتاج).
Cloud SDK
gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
يمكنك الاطّلاع على مزيد من المعلومات عن Google Cloud SDK وتثبيت Cloud SDK والطلبات التالية:
إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك
يصف هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات بحيث يمكن لتطبيقك الرجوع إليه بشكل آمن. ويجب عدم التحقق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذلك نوصي بتخزينه في ملف local.properties
، الموجود في الدليل الجذري لمشروعك. لمزيد من المعلومات حول ملف local.properties
، راجِع ملفات خصائص Gradle.
لتبسيط هذه المهمة، نقترح عليك استخدام Secrets Gradle Plugin for Android. لتثبيت المكون الإضافي وتخزين مفتاح واجهة برمجة التطبيقات:
- في "استوديو Android"، افتح ملف
build.gradle
على مستوى مشروعك وأضِف الرمز التالي إلى العنصرdependencies
ضمنbuildscript
.plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false }
- بعد ذلك، افتح ملف
build.gradle
على مستوى الوحدة الخاصة بك وأضِف الرمز التالي إلى العنصرplugins
.id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
- احفظ الملف وزامن مشروعك مع Gradle.
- افتح
local.properties
في الدليل على مستوى مشروعك، ثم أضِف الرمز التالي. استبدِلYOUR_API_KEY
بمفتاح واجهة برمجة التطبيقات.MAPS_API_KEY=YOUR_API_KEY
- احفظ الملف.
- في ملف
AndroidManifest.xml
، انتقِل إلىcom.google.android.geo.API_KEY
وعدِّلandroid:value attribute
على النحو التالي:<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
ملاحظة: كما هو موضّح أعلاه،
com.google.android.geo.API_KEY
هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على العديد من واجهات برمجة التطبيقات المستندة إلى "خرائط Google" على نظام التشغيل Android، بما في ذلك "حزمة تطوير البرامج (SDK) للخرائط" لنظام التشغيل Android. للتوافق مع الأنظمة القديمة، تتوافق واجهة برمجة التطبيقات أيضًا مع الاسم com.google.android.maps.v2.API_KEY
. يسمح هذا الاسم القديم بالمصادقة في الإصدار 2 من واجهة برمجة التطبيقات لخرائط Android فقط. يمكن للتطبيق
تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. وإذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.
انظر إلى الرمز
افحص الشفرة التي يقدمها النموذج. وعلى وجه الخصوص، اطلع على الملفات التالية في مشروع استوديو Android.
ملف أنشطة الخرائط
ملف أنشطة الخرائط هو النشاط الرئيسي للتطبيق، ويحتوي على الرمز لإدارة الخريطة وعرضها. ويتم تلقائيًا تسمية الملف الذي يحدد النشاط
على أنه MapsActivity.java
أو في حال ضبط لغة Kotlin
كلغة لتطبيقك MapsActivity.kt
.
العناصر الأساسية لنشاط الخرائط:
يدير الكائن
SupportMapFragment
دورة حياة الخريطة وهو العنصر الرئيسي في واجهة مستخدم التطبيق.يوفر الكائن
GoogleMap
إمكانية الوصول إلى بيانات الخريطة والعرض. هذه هي الفئة الرئيسية في SDK للخرائط على أجهزة Android. يصف دليل كائنات الخريطة الكائنينSupportMapFragment
وGoogleMap
بمزيد من التفصيل.تُركز الدالة
moveCamera
الخريطة على إحداثياتLatLng
لسيدني في أستراليا. الإعدادات الأولى المطلوب تهيئتها عند إضافة خريطة هي عادةً إعدادات الخريطة وموقع الكاميرا، مثل زاوية العرض، واتجاه الخريطة، ومستوى التكبير/التصغير. راجع دليل الكاميرا والعرض للحصول على التفاصيل.تضيف الدالة
addMarker
علامة إلى إحداثيات سيدني. راجع دليل العلامات للاطلاع على مزيد من التفاصيل.
يحتوي ملف نشاط الخرائط على الرمز التالي:
لغة Java
import android.os.Bundle; import androidx.appcompat.app.AppCompatActivity; import com.google.android.gms.maps.CameraUpdateFactory; import com.google.android.gms.maps.GoogleMap; import com.google.android.gms.maps.OnMapReadyCallback; import com.google.android.gms.maps.SupportMapFragment; import com.google.android.gms.maps.model.LatLng; import com.google.android.gms.maps.model.MarkerOptions; public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback { private GoogleMap mMap; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_maps); // Obtain the SupportMapFragment and get notified when the map is ready to be used. SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager() .findFragmentById(R.id.map); mapFragment.getMapAsync(this); } /** * Manipulates the map once available. * This callback is triggered when the map is ready to be used. * This is where we can add markers or lines, add listeners or move the camera. In this case, * we just add a marker near Sydney, Australia. * * If Google Play services is not installed on the device, the user will be prompted to install * it inside the SupportMapFragment. This method will only be triggered once the user has * installed Google Play services and returned to the app. */ @Override public void onMapReady(GoogleMap googleMap) { mMap = googleMap; // Add a marker in Sydney and move the camera LatLng sydney = new LatLng(-34, 151); mMap.addMarker(new MarkerOptions() .position(sydney) .title("Marker in Sydney")); mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney)); } }
Kotlin
import androidx.appcompat.app.AppCompatActivity import android.os.Bundle import com.google.android.gms.maps.CameraUpdateFactory import com.google.android.gms.maps.GoogleMap import com.google.android.gms.maps.OnMapReadyCallback import com.google.android.gms.maps.SupportMapFragment import com.google.android.gms.maps.model.LatLng import com.google.android.gms.maps.model.MarkerOptions internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback { private lateinit var mMap: GoogleMap override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_maps) // Obtain the SupportMapFragment and get notified when the map is ready to be used. val mapFragment = supportFragmentManager .findFragmentById(R.id.map) as SupportMapFragment mapFragment.getMapAsync(this) } /** * Manipulates the map once available. * This callback is triggered when the map is ready to be used. * This is where we can add markers or lines, add listeners or move the camera. In this case, * we just add a marker near Sydney, Australia. * If Google Play services is not installed on the device, the user will be prompted to install * it inside the SupportMapFragment. This method will only be triggered once the user has * installed Google Play services and returned to the app. */ override fun onMapReady(googleMap: GoogleMap) { mMap = googleMap // Add a marker in Sydney and move the camera val sydney = LatLng(-34.0, 151.0) mMap.addMarker(MarkerOptions() .position(sydney) .title("Marker in Sydney")) mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney)) } }
ملف Gradle Module
يشتمل ملف الوحدة build.gradle
على تبعية الخرائط التالية، والتي تتطلبها حزمة SDK للخرائط لنظام التشغيل Android.
dependencies { implementation 'com.google.android.gms:play-services-maps:18.1.0' // ... }
لمزيد من المعلومات حول إدارة الاعتمادية على "خرائط Google"، يُرجى الاطِّلاع على إصدار الإصدارات.
ملف تنسيق XML
ملف activity_maps.xml
هو ملف تنسيق XML الذي يحدد بنية واجهة مستخدم التطبيق. هذا الملف موجود في دليل res/layout
.
يعلن ملف activity_maps.xml
عن كسر يشتمل على العناصر التالية:
- يعيِّن
tools:context
النشاط الافتراضي للجزء إلىMapsActivity
، وهو ما يتم تحديده في ملف نشاط الخرائط. - تُعين
android:name
اسم الفئة للجزء إلىSupportMapFragment
، وهو نوع الجزء المستخدم في ملف نشاط الخرائط.
يحتوي ملف تنسيق XML على الشفرة التالية:
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:id="@+id/map"
tools:context=".MapsActivity"
android:name="com.google.android.gms.maps.SupportMapFragment" />
نشر التطبيق وتشغيله
عند تشغيل التطبيق بنجاح، سيتم عرض خريطة تتمركز حول سيدني سيدني في أستراليا، مع وضع علامة على المدينة كما هو موضح في لقطة الشاشة التالية.
لنشر التطبيق وتشغيله:
- في "استوديو Android"، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل) لتشغيل تطبيقك.
- عندما يُطلب منك اختيار جهاز، اختَر أحد الخيارات التالية:
- حدد جهاز Android المتصل بجهاز الكمبيوتر.
- بدلاً من ذلك، يمكنك اختيار زر الاختيار محاكي التشغيل واختيار الجهاز الافتراضي الذي أعددته.
- انقر على حسنًا. سيبدأ Android Studio تطبيق Gradle لتصميم تطبيقك، ثم سيعرض النتائج على جهازك أو من خلال المحاكي الذي تستخدمه. قد يستغرق إطلاق التطبيق عدة دقائق.
الخطوات التالية
إعداد خريطة: يصف هذا الموضوع كيفية ضبط الإعدادات الأولية وإعدادات وقت التشغيل لخريطتك، مثل موضع الكاميرا ونوع الخريطة ومكونات واجهة المستخدم والإيماءات.
إضافة خريطة إلى تطبيق Android (Kotlin): يرشدك هذا الدرس التطبيقي حول الترميز من خلال تطبيق يوضّح بعض الميزات الإضافية في "خرائط Google SDK" لنظام التشغيل Android.
استخدام مكتبة KTX في "خرائط Google" لنظام التشغيل Android: تتيح لك مكتبة إضافات لغة Kotlin (KTX) هذه الاستفادة من العديد من ميزات لغة Kotlin أثناء استخدام حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل Android.