أنشئ تطبيق Android يعرض خريطة باستخدام نموذج بانوراميات في خرائط Google لاستوديو Android. إذا كان لديك مشروع حالي في "استوديو Android" تريد إعداده، يمكنك الاطّلاع على مقالة إعداد مشروع في "استوديو Android".
هذه البداية السريعة مخصصة للمطورين الذين على دراية بتطوير Android الأساسي باستخدام Kotlin أو Java.
لمحة عن بيئة التطوير
تم تطوير هذه المقالة السريعة باستخدام الإصدار 14 من "استوديو Android" Hedgehog والإصدار 8.2 من المكوّن الإضافي لنظام Gradle المتوافق مع Android .
إعداد جهاز Android
لتشغيل تطبيق يستخدم "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لنظام التشغيل Android، يجب نشره على جهاز يعمل بنظام التشغيل Android أو على محاكي يستند إلى الإصدار 5.0 من نظام التشغيل Android أو إصدار أحدث ويتضمّن واجهات برمجة التطبيقات من Google.
- لاستخدام جهاز Android، اتّبِع التعليمات الواردة في مقالة تشغيل التطبيقات على جهاز أجهزة.
- لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام مدير الأجهزة الافتراضية لنظام التشغيل Android (AVD) المُضمَّن في "استوديو Android".
إنشاء مشروع على "خرائط Google" في "استوديو Android"
تم تغيير الإجراء المُتّبع لإنشاء مشروع على "خرائط Google" في "استوديو Android" في الإصدار Flamingo والإصدارات الأحدث من "استوديو Android".
افتح "استوديو Android" وانقر على مشروع جديد في النافذة مرحبًا بك في "استوديو Android".
في نافذة مشروع جديد، ضمن فئة الهاتف والجهاز اللوحي، اختَر بلا نشاط، ثم انقر على التالي.
أكمل نموذج مشروع جديد:
اضبط اللغة على Java أو Kotlin. تتوفّر كلتا اللغتَين بالكامل في حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android. لمزيد من المعلومات حول Kotlin، يمكنك الاطّلاع على تطوير تطبيقات Android باستخدام Kotlin.
اضبط الحدّ الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة SDK متوافق مع جهاز الاختبار. يجب اختيار إصدار أعلى من الحد الأدنى للإصدار المطلوب من حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل Android 19.0.x، وهو المستوى 21 من واجهة برمجة تطبيقات Android ("Lollipop"، Android 5.0) أو إصدار أحدث. راجِع ملاحظات الإصدار للاطّلاع على أحدث المعلومات حول متطلبات إصدار حزمة تطوير البرامج (SDK).
اضبط لغة إعداد التصميم على Kotlin DSL أو Groovy DSL. يتم عرض مقتطفات لكلتا اللغتَين لإعدادات الإصدار في الخطوات التالية .
انقر على إنهاء.
يشغِّل "استوديو Android" Gradle وينشئ المشروع. وقد تستغرق هذه العملية بعض الوقت.
أضف نشاط بانوراميات في خرائط Google:
- انقر بزر الماوس الأيمن على المجلد "
app
" في مشروعك. حدد جديد > Google > نشاط طرق العرض في خرائط Google.
في مربع الحوار نشاط Android الجديد، ضع علامة في مربّع الاختيار نشاط مشغّل التطبيقات.
اختَر إنهاء.
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إضافة رمز من نموذج.
- انقر بزر الماوس الأيمن على المجلد "
عند اكتمال عملية التصميم، يفتح "استوديو Android" الملفَين
AndroidManifest.xml
وMapsActivity
. قد يكون لنشاطك باسم مختلف، ولكنه الاسم الذي قمت بتهيئته أثناء الإعداد.
إعداد مشروعك على Google Cloud
أكمِل خطوات إعداد Cloud Console المطلوبة من خلال النقر على علامات التبويب التالية:
الخطوة 1
وحدة التحكّم
-
في Google Cloud Console، انقر على إنشاء مشروع في صفحة أداة اختيار المشاريع لبدء إنشاء مشروع جديد على Cloud.
-
تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تأكَّد من تفعيل الفوترة لمشروعك.
تقدّم خدمة Google Cloud فترة تجريبية مجانية لتحصيل 0.00 دولار أمريكي. تنتهي الفترة التجريبية بعد 90 يومًا أو بعد تحصيل رسوم بقيمة 300 دولار أمريكي من الحساب، أيهما أقرب. يمكنك إلغاء الاشتراك في أي وقت. تتميز "منصة خرائط Google" برصيد شهري متكرر بقيمة 200 دولار أمريكي. لمزيد من المعلومات، يُرجى الاطّلاع على أرصدة حسابات الفوترة والفوترة.
SDK للسحاب
gcloud projects create "PROJECT"
يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت Cloud SDK والأوامر التالية:
الخطوة 2
لاستخدام Google Maps Platform، عليك تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي تخطّط لاستخدامها مع مشروعك.
وحدة التحكّم
تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android
SDK للسحاب
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت Cloud SDK والأوامر التالية:
الخطوة 3
لا تؤدي هذه الخطوة إلا إلى تنفيذ عملية إنشاء مفتاح واجهة برمجة التطبيقات. إذا كنت تستخدم مفتاح واجهة برمجة التطبيقات في مرحلة الإنتاج، ننصحك بشدة بتقييد مفتاح واجهة برمجة التطبيقات. يمكنك العثور على مزيد من المعلومات في صفحة استخدام مفاتيح واجهة برمجة التطبيقات الخاصة بالمنتج.
مفتاح واجهة برمجة التطبيقات هو معرّف فريد يصادق على الطلبات المرتبطة بمشروعك لأغراض الاستخدام والفوترة. يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات واحد على الأقل مرتبط بمشروعك.
لإنشاء مفتاح واجهة برمجة التطبيقات:
وحدة التحكّم
-
انتقِل إلى صفحة منصة خرائط Google > بيانات الاعتماد.
-
في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
يعرض مربّع الحوار مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه مفتاح واجهة برمجة التطبيقات الذي أنشأته حديثًا. -
انقر على إغلاق.
يظهر مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
(يُرجى الحرص على تقييد مفتاح واجهة برمجة التطبيقات قبل استخدامه في قناة الإصدار العلني).
SDK للسحاب
gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت Cloud SDK والأوامر التالية:
إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك
يوضّح هذا القسم طريقة تخزين مفتاح واجهة برمجة التطبيقات كي يتمكّن تطبيقك من الرجوع إليه بشكل آمن. ويجب عدم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدار، لذا ننصحك بتخزينه في ملف secrets.properties
ضمن الدليل الجذري لمشروعك. لمزيد من المعلومات عن ملف secrets.properties
، اطّلِع على
ملفات سمات Gradle.
لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secrets Gradle لأجهزة Android.
لتثبيت المكوّن الإضافي Secrets Gradle لأجهزة Android في مشروعك على "خرائط Google"، اتّبِع الخطوات التالية:
-
في "استوديو Android"، افتح ملف
build.gradle.kts
أوbuild.gradle
ذي المستوى الأعلى وأضِف الرمز التالي إلى العنصرdependencies
ضمنbuildscript
.Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
رائع
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
-
افتح ملف
build.gradle.kts
أوbuild.gradle
على مستوى الوحدة وأضِف رمز الربط التالي إلى عنصرplugins
.Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
رائع
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- في الملف
build.gradle.kts
أو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.kts
orbuild.gradle
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.Kotlin
secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file. // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY 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.*" }
رائع
secrets { // To add your Maps API key to this project: // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file. // 2. Add this line, where YOUR_API_KEY is your API key: // MAPS_API_KEY=YOUR_API_KEY 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.
ملف نشاط الخرائط
ملف نشاط الخرائط هو النشاط الرئيسي للتطبيق، ويحتوي على الرمز البرمجي لإدارة الخريطة وعرضها. وبشكلٍ تلقائي، يكون اسم الملف الذي يعرِّف النشاط هو
MapsActivity.java
أو إذا ضبطت Kotlin كلغة لتطبيقك،MapsActivity.kt
.العناصر الرئيسية لنشاط الخرائط:
يدير الكائن
SupportMapFragment
دورة حياة الخريطة وهو العنصر الرئيسي في واجهة مستخدم التطبيق.يوفر الكائن
GoogleMap
الوصول إلى بيانات الخريطة وعرضها. هذه هي الفئة الرئيسية لحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android. يصف دليل عناصر الخريطة عنصرَيSupportMapFragment
وGoogleMap
بمزيد من التفاصيل.تركّز الدالة
moveCamera
الخريطة عند إحداثياتLatLng
لمدينة سيدني في أستراليا. عادةً ما تكون الإعدادات الأولى التي يجب ضبطها عند إضافة الخريطة هي إعدادات الموقع الجغرافي على الخريطة وإعدادات الكاميرا، مثل زاوية العرض واتجاه الخريطة ومستوى التكبير أو التصغير. راجِع دليل الكاميرا والعرض للاطّلاع على التفاصيل.تضيف الدالة
addMarker
علامة إلى الإحداثيات الخاصة بمدينة Sydney. راجع دليل العلامات للحصول على التفاصيل.
ملف Gradle الخاص بالوحدة
يتضمن ملف
build.gradle.kts
للوحدة تبعية الخرائط التالية، وهي مطلوبة من خلال حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android.dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:19.0.0") }
لمزيد من المعلومات عن إدارة التبعيات في "خرائط Google"، اطّلِع على إدارة الإصدارات.
ملف تنسيق XML
ملف
activity_maps.xml
هو ملف تنسيق XML الذي يحدّد بنية واجهة المستخدم الخاصة بالتطبيق. يتوفّر الملف في الدليلres/layout
. يكشف ملفactivity_maps.xml
عن جزء يتضمن العناصر التالية:- تضبط
tools:context
النشاط التلقائي للجزء علىMapsActivity
، المحدّد في ملف نشاط الخرائط. - تُعدِّل
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" />
نشر التطبيق وتشغيله
عند تشغيل التطبيق بنجاح، سيعرض خريطة تركّز على مدينة سيدني في أستراليا مع علامة على المدينة كما هو موضّح في لقطة الشاشة التالية.
لنشر التطبيق وتشغيله:
- في Android Studio، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل) لتشغيل تطبيقك.
- عندما يُطلب منك اختيار جهاز، حدِّد أحد الخيارَين التاليَين:
- اختَر جهاز Android المتصل بجهاز الكمبيوتر.
- ويمكنك بدلاً من ذلك النقر على زر الاختيار إطلاق المحاكي واختيار الجهاز الافتراضي الذي أعددته.
- انقر على موافق. سيبدأ Android Studio Gradle لإنشاء تطبيقك، ثم سيعرض النتائج على جهازك أو المحاكي. قد يستغرق إطلاق التطبيق عدة دقائق.
الخطوات التالية
إعداد خريطة: يصف هذا المستند كيفية ضبط الإعدادات الأولية وإعدادات وقت التشغيل لخريطتك، مثل موضع الكاميرا، ونوع الخريطة، ومكونات واجهة المستخدم، والإيماءات.
إضافة خريطة إلى تطبيق Android (Kotlin): يرشدك هذا الدليل التدريبي حول الترميز إلى تطبيق يعرض بعض الميزات الإضافية لسمة "حزمة تطوير البرامج (SDK) للخرائط" لنظام التشغيل Android.
استخدام مكتبة KTX لتطبيق "خرائط Google": تتيح لك مكتبة إضافات Kotlin (KTX) هذه الاستفادة من العديد من ميزات لغة Kotlin أثناء استخدام "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لنظام التشغيل Android.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2024-11-04 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2024-11-04 (حسب التوقيت العالمي المتفَّق عليه)"],[],[]]