أنشئ تطبيق Android يعرض خريطة باستخدام نموذج بانوراميات في خرائط Google لاستوديو Android. إذا كان لديك مشروع حالي على "استوديو Android" تريد إعداده، يمكنك الاطّلاع على مقالة إعداد مشروع استوديو Android.
هذه البداية السريعة مخصصة للمطورين الذين على دراية بتطوير Android الأساسي باستخدام Kotlin أو Java.
حول بيئة التطوير
تم تطوير هذه اللعبة السريعة باستخدام الإصدار 8.2 من Android Studio Hedgehog والمكوّن الإضافي Gradle المتوافق مع Android.
إعداد جهاز Android
لتشغيل تطبيق يستخدم "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لنظام التشغيل Android، يجب نشره على جهاز Android أو محاكي Android يعمل على الإصدار 5.0 أو إصدار أحدث من نظام التشغيل Android ويتضمّن واجهات برمجة التطبيقات من Google.
- لاستخدام جهاز Android، اتّبِع التعليمات الواردة في مقالة تشغيل التطبيقات على جهاز.
- لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي باستخدام مدير جهاز Android الافتراضي (AVD) الذي يتضمّن "استوديو Android".
إنشاء مشروع على "خرائط Google" في "استوديو Android"
تم تغيير إجراءات إنشاء مشروع "خرائط Google" في "استوديو Android" في إصدار Flamingo والإصدارات اللاحقة من "استوديو Android".
افتح "استوديو Android" وانقر على مشروع جديد في النافذة مرحبًا بك في "استوديو Android".
في نافذة مشروع جديد، ضمن فئة الهاتف والجهاز اللوحي، اختَر بلا نشاط، ثم انقر على التالي.
أكمل نموذج مشروع جديد:
اضبط اللغة على Java أو Kotlin. يتم دعم اللغتين بشكل كامل من حزمة SDK لخرائط Android. لمزيد من المعلومات حول Kotlin، يمكنك الاطّلاع على تطوير تطبيقات Android باستخدام Kotlin.
اضبط الحدّ الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة SDK متوافق مع جهاز الاختبار. يجب اختيار إصدار أعلى من الحد الأدنى للإصدار المطلوب في الإصدار 19.0.x من حزمة "SDK للخرائط" لنظام التشغيل Android، والذي يعمل بالمستوى 21 من واجهة برمجة تطبيقات Android ("Lollipop" والإصدار 5.0) من نظام التشغيل Android) أو الإصدارات الأحدث. راجِع ملاحظات الإصدار للاطّلاع على أحدث المعلومات حول متطلبات إصدار حزمة تطوير البرامج (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.
-
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. التأكّد من تفعيل الفوترة لمشروعك:
تقدّم خدمة Google Cloud فترة تجريبية مجانية لتحصيل 0.00 دولار أمريكي. تنتهي الفترة التجريبية إما في نهاية 90 يومًا أو بعد تراكم الرسوم المستحقة على الحساب بقيمة 300 دولار أمريكي (أو ما يعادلها بالعملة المحلية)، أيهما أقرب. ويمكنك الإلغاء في أي وقت. تتميز "منصة خرائط Google" برصيد شهري متكرر بقيمة 200 دولار أمريكي. لمزيد من المعلومات، يُرجى الاطّلاع على أرصدة حساب الفوترة والفوترة.
Cloud SDK
gcloud projects create "PROJECT"
يمكنك الاطّلاع على مزيد من المعلومات عن Google Cloud SDK وتثبيت Cloud SDK والأوامر التالية:
الخطوة 2
لاستخدام "منصة خرائط Google"، يجب تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (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 والأوامر التالية:
إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك
يوضّح هذا القسم طريقة تخزين مفتاح واجهة برمجة التطبيقات كي يتمكّن تطبيقك من الرجوع إليه بشكل آمن. ويجب عدم التحقّق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذا ننصحك بتخزينه في ملف secrets.properties
ضمن الدليل الجذري لمشروعك. لمزيد من المعلومات حول ملف secrets.properties
، راجِع ملفات خصائص Gradle.
لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secret Gradle لأجهزة Android.
لتثبيت مكوّن Secrets 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.
ملف نشاط الخرائط
يُعد ملف نشاط الخرائط هو النشاط الرئيسي للتطبيق، ويحتوي على رمز لإدارة الخريطة وعرضها. وبشكلٍ تلقائي، يكون اسم الملف الذي يعرِّف النشاط هو
MapsActivity.java
أو إذا ضبطت Kotlin كلغة لتطبيقك،MapsActivity.kt
.العناصر الرئيسية لنشاط الخرائط:
يدير الكائن
SupportMapFragment
دورة حياة الخريطة وهو العنصر الرئيسي في واجهة مستخدم التطبيق.يوفر الكائن
GoogleMap
الوصول إلى بيانات الخريطة وعرضها. هذه هي الفئة الرئيسية من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android. يصف دليل كائنات الخريطة الكائنينSupportMapFragment
وGoogleMap
بمزيد من التفاصيل.تعمل الدالة
moveCamera
على تركيز الخريطة على إحداثياتLatLng
لمدينة سيدني بأستراليا. عادةً ما تكون الإعدادات الأولى التي يجب ضبطها عند إضافة الخريطة هي إعدادات الموقع الجغرافي على الخريطة وإعدادات الكاميرا، مثل زاوية العرض واتجاه الخريطة ومستوى التكبير أو التصغير. يُرجى الاطّلاع على دليل الكاميرا والعرض للحصول على التفاصيل.تضيف الدالة
addMarker
علامة إلى إحداثيات سيدني. راجع دليل العلامات للحصول على التفاصيل.
ملف Gradle للوحدة
يتضمن ملف
build.gradle
للوحدة تبعية الخرائط التالية، وهي مطلوبة من خلال حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط 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
، وهو نوع الجزء المُستخدَم في ملف نشاط الخرائط.
يحتوي ملف تنسيق 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): يرشدك هذا الدرس التطبيقي إلى كيفية استخدام تطبيق يوضح بعض الميزات الإضافية لحزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل Android.
استخدام مكتبة KTX لتطبيق "خرائط Google": تتيح لك مكتبة إضافات Kotlin (KTX) هذه الاستفادة من العديد من ميزات لغة Kotlin أثناء استخدام "حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google" لنظام التشغيل Android.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2024-07-13 (حسب التوقيت العالمي المتفَّق عليه)
[{ "type": "thumb-down", "id": "missingTheInformationINeed", "label":"لا يحتوي على المعلومات التي أحتاج إليها." },{ "type": "thumb-down", "id": "tooComplicatedTooManySteps", "label":"الخطوات معقدة للغاية / كثيرة جدًا." },{ "type": "thumb-down", "id": "outOfDate", "label":"المحتوى قديم." },{ "type": "thumb-down", "id": "translationIssue", "label":"ثمة مشكلة في الترجمة." },{ "type": "thumb-down", "id": "samplesCodeIssue", "label":"مشكلة في العيّنات / التعليمات البرمجية" },{ "type": "thumb-down", "id": "otherDown", "label":"غير ذلك" }] [{ "type": "thumb-up", "id": "easyToUnderstand", "label":"يسهُل فهم المحتوى." },{ "type": "thumb-up", "id": "solvedMyProblem", "label":"ساعَدني المحتوى في حلّ مشكلتي." },{ "type": "thumb-up", "id": "otherUp", "label":"غير ذلك" }]