أنشئ تطبيق Android يعرض خريطة باستخدام نموذج بانوراميات في خرائط Google لاستوديو Android. إذا كان لديك مشروع حالي على "استوديو Android" وتريد إعداده، يمكنك الاطّلاع على المقالة إعداد مشروع على "استوديو Android".
تم تصميم دليل البدء السريع هذا للمطوّرين الذين لديهم دراية بأساسيات تطوير Android باستخدام لغة Kotlin أو Java.
لمحة عن بيئة التطوير
تم تطوير دليل البدء السريع هذا باستخدام استوديو Android Hedgehog ومكون Android المكوّن الإضافي Gradle الإصدار 8.2.
إعداد جهاز Android
لتشغيل تطبيق يستخدم حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android، يجب نشره على جهاز Android أو محاكي Android يستند إلى الإصدار 4.0 من نظام التشغيل Android أو الإصدارات الأحدث ويتضمّن Google APIs.
- لاستخدام جهاز Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز.
- لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام مدير جهاز Android الافتراضي (AVD) المتوفّر مع "استوديو Android".
إنشاء مشروع على "خرائط Google" في "استوديو Android"
تم تغيير إجراء إنشاء مشروع "خرائط Google" في "استوديو Android" في تطبيق Flamingo والإصدارات اللاحقة من "استوديو Android".
افتح "استوديو Android" وانقر على إنشاء مشروع جديد في نافذة مرحبًا بك في "استوديو Android".
في نافذة مشروع جديد، ضمن فئة الهاتف والجهاز اللوحي، اختَر ليس هناك نشاط، ثم انقر على التالي.
املأ نموذج مشروع جديد:
اضبط اللغة على Java أو Kotlin. يتم دعم كلتا اللغتين بالكامل بواسطة حزمة SDK لـ "خرائط Google" لنظام التشغيل Android. لمعرفة المزيد من المعلومات عن لغة Kotlin، يمكنك الاطّلاع على مقالة تطوير تطبيقات Android باستخدام Kotlin.
اضبط الحد الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة SDK متوافق مع جهازك الاختباري. يجب اختيار إصدار أحدث من الحد الأدنى المطلوب للإصدار 18.2.x من حزمة تطوير البرامج (SDK) لـ "خرائط Google" لنظام التشغيل Android، وهو الإصدار 18.2.x من واجهة برمجة تطبيقات Android، وهو المستوى 19 ("KitKat" أو Android 4.4) أو إصدار أحدث. راجِع ملاحظات الإصدار للاطّلاع على أحدث المعلومات عن متطلبات إصدار حزمة SDK.
اضبط لغة ضبط الإصدار على Kotlin DSL أو Groovy DSL. ويتم عرض مقتطفات لكل من لغتَي تهيئة الإصدار في الإجراءات التالية.
انقر على إنهاء.
يُطلق على "استوديو Android" مشروع Gradle ويقوم بإعداد المشروع. وقد تستغرق هذه العملية بعض الوقت.
أضف نشاط بانوراميات في خرائط Google:
- انقر بزر الماوس الأيمن على مجلد "
app
" في مشروعك. حدد جديد > Google > نشاط بانوراميات في خرائط Google.
في مربّع الحوار نشاط Android الجديد، ضَع علامة في مربّع الاختيار نشاط مشغِّل التطبيقات.
اختَر إنهاء.
لمزيد من المعلومات، اطّلِع على المقالة إضافة رمز من نموذج.
- انقر بزر الماوس الأيمن على مجلد "
عند انتهاء الإصدار، يفتح "استوديو Android" ملفَّي
AndroidManifest.xml
وMapsActivity
. قد يكون لنشاطك اسم مختلف، ولكنه هو الاسم الذي قمت بتهيئةه أثناء الإعداد.
إعداد مشروعك على Google Cloud
أكمِل خطوات إعداد Cloud Console المطلوبة من خلال النقر على علامات التبويب التالية:
الخطوة 1
وحدة التحكّم
-
في Google Cloud Console، انقر على إنشاء مشروع في صفحة أداة اختيار المشروع لبدء إنشاء مشروع جديد على Google Cloud.
-
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. تأكَّد من تفعيل الفوترة لمشروعك.
تقدّم خدمة Google Cloud فترة تجريبية مجانية تبلغ 0.00 دولار أمريكي. تنتهي الفترة التجريبية إما في نهاية 90 يومًا أو بعد تراكم مبلغ 300 دولار أمريكي (أو ما يعادله بالعملة المحلية) على الحساب، أيهما أقرب. ويمكنك إلغاء الاشتراك في أي وقت. تتميز "منصة خرائط Google" برصيد شهري متكرر بقيمة 200 دولار أمريكي. لمزيد من المعلومات، راجِع أرصدة حساب الفوترة والفوترة.
Cloud SDK
gcloud projects create "PROJECT"
يمكنك الاطّلاع على مزيد من المعلومات عن حزمة تطوير البرامج (SDK) في Google Cloud وتثبيت حزمة تطوير البرامج (SDK) في السحابة الإلكترونية والأوامر التالية:
الخطوة 2
ولاستخدام "منصة خرائط Google"، يجب تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي تخطط لاستخدامها مع مشروعك.
وحدة التحكّم
تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android
Cloud SDK
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
يمكنك الاطّلاع على مزيد من المعلومات عن حزمة تطوير البرامج (SDK) في Google Cloud وتثبيت حزمة تطوير البرامج (SDK) في السحابة الإلكترونية والأوامر التالية:
الخطوة 3
لا يتم تنفيذ هذه الخطوة إلا خلال عملية إنشاء مفتاح واجهة برمجة التطبيقات. إذا كنت تستخدم مفتاح واجهة برمجة التطبيقات في الإصدار العلني، ننصحك بشدة بحظر مفتاح واجهة برمجة التطبيقات. ويمكنك العثور على مزيد من المعلومات في صفحة استخدام مفاتيح واجهة برمجة التطبيقات الخاصة بالمنتج.
مفتاح واجهة برمجة التطبيقات هو معرّف فريد يصادق على الطلبات المرتبطة بمشروعك لأغراض الاستخدام والفوترة. يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات واحد على الأقل مرتبط بمشروعك.
لإنشاء مفتاح واجهة برمجة التطبيقات، يُرجى اتّباع الخطوات التالية:
وحدة التحكّم
-
انتقِل إلى صفحة منصة خرائط Google > بيانات الاعتماد.
-
في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
يعرض مربّع الحوار تم إنشاء مفتاح واجهة برمجة التطبيقات مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه حديثًا. -
انقر على إغلاق.
يتم إدراج مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
(لا تنسَ حظر مفتاح واجهة برمجة التطبيقات قبل استخدامه في عملية الإنتاج).
Cloud SDK
gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
يمكنك الاطّلاع على مزيد من المعلومات عن حزمة تطوير البرامج (SDK) في Google Cloud وتثبيت حزمة تطوير البرامج (SDK) في السحابة الإلكترونية والأوامر التالية:
إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك
يوضِّح هذا القسم طريقة تخزين مفتاح واجهة برمجة التطبيقات كي يتمكّن تطبيقك من الرجوع إليه بأمان. ويجب عدم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذا ننصح بتخزينه في ملف secrets.properties
المتوفّر في الدليل الجذري لمشروعك. لمزيد من المعلومات حول ملف secrets.properties
، يُرجى الاطّلاع على ملفات خصائص Gradle.
لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secret Gradle الإضافي لنظام Android.
لتثبيت المكوّن الإضافي Secret Gradle الإضافي لنظام التشغيل Android في مشروع "خرائط Google"، اتَّبِع الخطوات التالية:
-
في "استوديو Android"، افتح ملف
build.gradle
أوbuild.gradle.kts
ذي المستوى الأعلى وأضِف الرمز التالي إلى العنصرdependencies
ضمنbuildscript
.رائع
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") } }
-
افتح ملف
build.gradle
على مستوى الوحدة وأضِف الرمز التالي إلى العنصرplugins
.رائع
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
Kotlin
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- في ملف
build.gradle
على مستوى الوحدة، تأكَّد من ضبطtargetSdk
وcompileSdk
على 34. - احفظ الملف وزامِن مشروعك مع Gradle.
-
افتح ملف
secrets.properties
في دليل المستوى الأعلى، ثم أضِف الرمز التالي. استبدِلYOUR_API_KEY
بمفتاح واجهة برمجة التطبيقات. يمكنك تخزين مفتاحك في هذا الملف لأنّه تم استبعادsecrets.properties
من التسجيل في نظام التحكّم في الإصدار.MAPS_API_KEY=YOUR_API_KEY
- احفظ الملف.
-
أنشِئ ملف
local.defaults.properties
في دليل المستوى الأعلى، أي الملف نفسه الذي يتضمّن ملفsecrets.properties
، ثم أضِف الرمز التالي.MAPS_API_KEY=DEFAULT_API_KEY
الغرض من هذا الملف هو توفير موقع جغرافي احتياطي لمفتاح واجهة برمجة التطبيقات في حال عدم العثور على ملف
secrets.properties
لكي لا تفشل الإصدارات. وقد يحدث ذلك في حال استنساخ التطبيق من نظام تحكّم في الإصدارات يستبعدsecrets.properties
ولم تنشئ بعد ملفsecrets.properties
على الجهاز لتوفير مفتاح واجهة برمجة التطبيقات الخاص بك. - احفظ الملف.
-
في ملف
AndroidManifest.xml
، انتقِل إلىcom.google.android.geo.API_KEY
وعدِّلandroid:value attribute
. في حال عدم وجود العلامة<meta-data>
، عليك إنشاؤها كعلامة فرعية للعلامة<application>
.<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Note:
com.google.android.geo.API_KEY
is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the namecom.google.android.maps.v2.API_KEY
. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception. -
In Android Studio, open your module-level
build.gradle
orbuild.gradle.kts
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.defaults.properties
, and set any other properties.Groovy
secrets { // Optionally specify a different file name containing your secrets. // The plugin defaults to "local.properties" propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
Kotlin
secrets { // Optionally specify a different file name containing your secrets. // The plugin defaults to "local.properties" propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
انظر إلى الرمز
افحص الرمز الذي يوفّره النموذج. وعلى وجه التحديد، انظر إلى الملفات التالية في مشروع استوديو Android.
ملف نشاط "خرائط Google"
يُعد ملف نشاط الخرائط النشاط الرئيسي للتطبيق، ويحتوي على رمز لإدارة الخريطة وعرضها. يُسمى الملف الذي يحدّد النشاط تلقائيًا
MapsActivity.java
، أو إذا ضبطت Kotlin على أنها لغة تطبيقك،MapsActivity.kt
.العناصر الرئيسية لنشاط الخرائط:
يدير الكائن
SupportMapFragment
دورة حياة الخريطة، وهو العنصر الرئيسي في واجهة مستخدم التطبيق.يتيح الكائن
GoogleMap
الوصول إلى بيانات الخريطة وعرضها. هذه هي الفئة الرئيسية من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android. يصف دليل كائنات الخريطة كائناتSupportMapFragment
وGoogleMap
بمزيد من التفصيل.توسيط الخريطة دالة
moveCamera
عند إحداثياتLatLng
لمدينة سيدني في أستراليا. عادةً ما تكون الإعدادات الأولى التي يتم ضبطها عند إضافة خريطة هي إعدادات الموقع الجغرافي والكاميرا على الخريطة، مثل زاوية العرض واتجاه الخريطة ومستوى التكبير/التصغير. يمكنك الاطّلاع على دليل الكاميرا والعرض لمزيد من التفاصيل.تضيف الدالة
addMarker
علامة إلى إحداثيات سيدني. يمكنك الاطّلاع على دليل العلامات للحصول على التفاصيل.
ملف Gradle للوحدة
يتضمّن ملف الوحدة النمطية
build.gradle
تبعية الخرائط التالية، وهي مطلوبة من خلال حزمة تطوير البرامج (SDK) لـ "خرائط Google" لنظام التشغيل Android.dependencies { // Maps SDK for Android implementation 'com.google.android.gms:play-services-maps:18.2.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: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" />
نشر التطبيق وتشغيله
عند تشغيل التطبيق بنجاح، سيعرض خريطة تتمركز حول مدينة سيدني أستراليا مع علامة على المدينة كما هو موضح في لقطة الشاشة التالية.
لنشر التطبيق وتشغيله:
- في "استوديو Android"، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل) لتشغيل التطبيق.
- عندما يُطلب منك اختيار جهاز، حدِّد أحد الخيارات التالية:
- اختَر جهاز Android المتصل بجهاز الكمبيوتر.
- بدلاً من ذلك، انقر على زر الاختيار تشغيل المحاكي واختَر الجهاز الافتراضي الذي تم إعداده.
- انقر على موافق. سيبدأ "استوديو Android" في تشغيل Gradle لإنشاء تطبيقك، ثم عرض النتائج على جهازك أو المحاكي. قد يستغرق تشغيل التطبيق عدة دقائق.
الخطوات التالية
إعداد خريطة: يصف هذا المستند كيفية ضبط الإعدادات الأولية ووقت التشغيل لخريطتك، مثل موضع الكاميرا ونوع الخريطة ومكونات واجهة المستخدم والإيماءات.
إضافة خريطة إلى تطبيق Android (Kotlin): يرشدك هذا الدرس التطبيقي حول الترميز إلى تطبيق يعرض بعض الميزات الإضافية في حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android.
استخدام مكتبة KTX لنظام التشغيل Android في "خرائط Google": تتيح لك مكتبة إضافات Kotlin (KTX) هذه الاستفادة من العديد من ميزات لغة Kotlin أثناء استخدام حزمة تطوير البرامج (SDK) الخاصة بخرائط Google لنظام التشغيل Android.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2024-03-22 (حسب التوقيت العالمي المتفَّق عليه)
[] []