أنشئ تطبيق Android يعرض خريطة باستخدام نموذج "خرائط Google" لاستوديو Android. إذا كان لديك مشروع حالي على "استوديو Android" تريد إعداده، يمكنك مراجعة ضبط المشروع.
تم تصميم بداية الاستخدام السريعة لمطوّري البرامج الذين لديهم دراية بتطوير Android الأساسي من خلال Java أو Kotlin.
إعداد بيئة التطوير
- يجب إدخال الإصدار Android Studio Fox أو أحدث. تنزيل وتثبيته إذا لم يسبق لك تنزيله
- تأكَّد من استخدام الإصدار 7.0 من مكوّن Gradle الإضافي من Android أو إصدار أحدث في "استوديو Android".
إعداد جهاز Android
لتشغيل تطبيق يستخدم حزمة تطوير البرامج (SDK) في "خرائط Google" لأجهزة Android، يجب نشره على جهاز Android أو محاكي Android يستند إلى الإصدار 4.0 من نظام التشغيل Android أو إصدار أحدث، ويتضمن ذلك واجهات برمجة تطبيقات Google.
- لاستخدام جهاز Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز.
- لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام مدير الأجهزة الافتراضية (AVD) من Android الذي يحتوي على "استوديو Android".
إنشاء مشروع على "خرائط Google" في "استوديو Android"
افتح "استوديو Android"، وانقر على إنشاء مشروع جديد في نافذة مرحبًا بك في "استوديو Android".
في نافذة مشروع جديد، ضمن فئة الهاتف والجهاز اللوحي، اختر نشاط "خرائط Google"، ثم انقر على التالي.
املأ نموذج نشاط "خرائط Google":
اضبط اللغة على Java أو Kotlin. وكلتا اللغتين متوافقان بالكامل مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع Android. لمعرفة المزيد من المعلومات حول لغة Kotlin، يُرجى الاطّلاع على تطوير تطبيقات Android باستخدام لغة Kotlin.
اضبط الحد الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة تطوير برامج (SDK) متوافق مع جهاز الاختبار. يجب اختيار إصدار أكبر من الحد الأدنى للإصدار المطلوب من حزمة تطوير البرامج (SDK) في "خرائط Google" للإصدار 18.0.x من نظام Android، وهو حاليًا المستوى 19 من واجهة برمجة تطبيقات Android (الإصدار 4.4 من نظام التشغيل Marshmallow) أو إصدار أحدث. يُرجى الاطّلاع على ملاحظات الإصدار للحصول على أحدث المعلومات حول متطلبات إصدار حزمة SDK.
انقر على إنهاء.
يبدأ "استوديو Android" برنامج Gradle وسينشئ المشروع. وقد تستغرق هذه العملية بعض الوقت.
عند انتهاء الإصدار، يفتح "استوديو Android"
AndroidManifest.xml
وMapsActivity
ملف. قد يكون لنشاطك اسم مختلف، ولكنه سيكون الإعداد الذي تم إعداده أثناء الإعداد.يتضمّن الملف
AndroidManifest.xml
تعليمات حول الحصول على مفتاح لواجهة برمجة التطبيقات في "خرائط Google" ثم إضافته إلى ملفlocal.property. لا تضِف مفتاح واجهة برمجة التطبيقات إلى ملفAndroidManifest.xml
. يؤدي ذلك إلى تخزين مفتاح واجهة برمجة التطبيقات بشكل أقل أمانًا. وبدلاً من ذلك، اتّبِع التعليمات الواردة في الأقسام التالية لإنشاء مشروع على السحابة الإلكترونية وضبط مفتاح واجهة برمجة تطبيقات.
إعداد مشروعك على Google Cloud
أكمِل خطوات إعداد Cloud Console المطلوبة عن طريق النقر على علامات التبويب التالية:
الخطوة 1
وحدة التحكّم
-
في Google Cloud Console، انقر على إنشاء مشروع في صفحة أداة اختيار المشروع لبدء إنشاء مشروع Cloud جديد.
-
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. تأكَّد من تفعيل الفوترة لمشروعك.
تقدّم Google Cloud فترة تجريبية بدون أي رسوم. تنتهي صلاحية الفترة التجريبية في نهاية 90 يومًا أو بعد أن يتم تحصيل رسوم بقيمة 300 دولار أمريكي (أو ما يعادله بالعملة المحلية) في الحساب، أيهما أقرب. يمكنك إلغاء الاشتراك متى شئت. يقدّم "منصة خرائط Google" رصيدًا شهريًا بقيمة 200 دولار أمريكي (أو ما يعادلها بالعملة المحلية). لمزيد من المعلومات، راجِع رصيد حساب الفوترة والفوترة.
Cloud SDK
gcloud projects create "PROJECT"
اطّلِع على مزيد من المعلومات عن حزمة تطوير برامج Google Cloud SDK و تثبيت حزمة تطوير برامج Google Cloud والطلبات التالية:
الخطوة 2
لاستخدام "منصة خرائط Google"، يجب تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي تنوي استخدامها مع مشروعك.
وحدة التحكّم
تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع Android
Cloud SDK
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
اطّلِع على مزيد من المعلومات عن حزمة تطوير برامج Google Cloud SDK و تثبيت حزمة تطوير برامج Google Cloud والطلبات التالية:
الخطوة 3
تخضع هذه الخطوة لعملية إنشاء مفتاح واجهة برمجة التطبيقات فقط. إذا كنت تستخدم مفتاح واجهة برمجة التطبيقات في مرحلة الإنتاج، ننصحك بشدة بحظر مفتاح واجهة برمجة التطبيقات الخاص بك. يمكنك العثور على المزيد من المعلومات في صفحة استخدام مفاتيح واجهة برمجة التطبيقات الخاصة بالمنتج.
مفتاح واجهة برمجة التطبيقات هو معرّف فريد يصادق على الطلبات المرتبطة بمشروعك لأغراض الاستخدام والفوترة. يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات واحد على الأقل مرتبط بمشروعك.
لإنشاء مفتاح لواجهة برمجة التطبيقات:
وحدة التحكّم
-
انتقِل إلى صفحة منصة خرائط Google > بيانات الاعتماد.
-
في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
يعرض مربّع الحوار مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه حديثًا. -
انقر على إغلاق.
يتم إدراج مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
(تذكَّر حظر واجهة برمجة التطبيقات قبل استخدامها في الإنتاج).
Cloud SDK
gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
اطّلِع على مزيد من المعلومات عن حزمة تطوير برامج Google Cloud SDK و تثبيت حزمة تطوير برامج Google Cloud والطلبات التالية:
إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك
يوضّح هذا القسم طريقة تخزين مفتاح واجهة برمجة التطبيقات بحيث يمكن الرجوع إليه بأمان من خلال تطبيقك. عليك عدم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكّم بالإصدار، لذلك ننصحك
بتخزينه في ملف 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) لتطبيق "خرائط Google" لنظام التشغيل Android. للتوافق مع الأنظمة القديمة، تتوافق واجهة برمجة التطبيقات أيضًا مع الاسم com.google.android.maps.v2.API_KEY
. يسمح هذا الاسم القديم بالمصادقة في الإصدار 2 من واجهة برمجة تطبيقات "خرائط Google" فقط. يمكن للتطبيق
تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. وإذا تم تحديد كلا النوعَين، ستعرض واجهة برمجة التطبيقات استثناءً.
الاطّلاع على الرمز
افحص الرمز المقدّم من خلال النموذج. وعلى وجه الخصوص، اطّلِع على الملفات التالية في مشروع "استوديو Android".
ملف نشاط الخرائط
ملف نشاط الخرائط هو النشاط الرئيسي للتطبيق، ويحتوي على الرمز لإدارة الخريطة وعرضها. وبشكل تلقائي، يُطلق على الملف الذي
يحدّد النشاط اسم MapsActivity.java
أو إذا ضبطت لغة Kotlin
على تطبيقك، MapsActivity.kt
.
العناصر الرئيسية لنشاط الخرائط:
يدير الكائن
SupportMapFragment
دورة حياة الخريطة، وهو العنصر الرئيسي في واجهة مستخدم التطبيق.يوفر الكائن
GoogleMap
إمكانية الوصول إلى بيانات الخريطة وطريقة عرضها. هذا هو الفئة الرئيسية من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع 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 للوحدة
يتضمّن ملف الوحدة build.gradle
الاعتمادية التالية على الخرائط، وهي مطلوبة من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع 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
، والذي يتم تحديده في ملف نشاط "خرائط Google". - تضبط السمة
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"، انقر على خيار القائمة Run (تشغيل) (أو رمز زر التشغيل) لتشغيل تطبيقك.
- عندما يُطلب منك اختيار جهاز، حدِّد أحد الخيارات التالية:
- اختَر جهاز Android المتّصل بجهاز الكمبيوتر.
- بدلاً من ذلك، انقر على زر الاختيار تشغيل محاكي واختَر الجهاز الافتراضي الذي أعددته.
- انقر على حسنًا. سيبدأ "استوديو Android" في برنامج Gradle لإنشاء تطبيقك ثم عرض النتائج على جهازك أو محاكيك. قد يستغرق إطلاق التطبيق عدة دقائق.
الخطوات التالية
إعداد خريطة: يصف هذا الموضوع كيفية ضبط إعدادات مبدئية ووقت التشغيل للخريطة، مثل موضع الكاميرا، ونوع الخريطة، ومكوّنات واجهة المستخدم، والإيماءات.
إضافة خريطة إلى تطبيق Android (Kotlin): يرشدك هذا الدرس التطبيقي حول الترميز في تطبيق يوضّح بعض الميزات الإضافية لحزمة تطوير البرامج (SDK) في "خرائط Google" لنظام التشغيل Android.
استخدام مكتبة "خرائط KTX" لنظام التشغيل Android: تتيح لك مكتبة Kotlin (KTSlin) هذه الاستفادة من العديد من ميزات اللغة Kotlin أثناء استخدام SDK لـ "خرائط Google" لأجهزة Android.