إنشاء تطبيق Android يعرض خريطة باستخدام طرق العرض في "خرائط Google" نموذج لـ "استوديو Android" إذا كان لديك مشروع حالي على "استوديو Android" التي تريد إعدادها، يمكنك الاطّلاع على مقالة إعداد مشروع على "استوديو Android".
تم تصميم هذه البداية السريعة للمطوّرين الذين هم على دراية بالأساسيات تطوير Android باستخدام Kotlin أو Java.
حول بيئة التطوير
تم تطوير نقطة البداية السريعة هذه باستخدام استوديو Android تطبيق Hedgehog وAndroid المكوّن الإضافي Gradle الإصدار 8.2.
إعداد جهاز Android
لتشغيل تطبيق يستخدم حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android، عليك نشره على جهاز Android أو جهاز Android. يستند إلى الإصدار 5.0 من نظام التشغيل Android أو الإصدارات الأحدث ويتضمن Google APIs.
- لاستخدام جهاز Android، يُرجى اتّباع التعليمات الواردة في تشغيل التطبيقات على جهاز
- لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي من خلال أداة إدارة الأجهزة الافتراضية التي تعمل بنظام التشغيل Android (AVD) المتوفّرة ضمن "استوديو Android"
إنشاء مشروع على "خرائط Google" في "استوديو Android"
تم تغيير إجراء إنشاء مشروع "خرائط Google" في "استوديو Android" في شركة Flamingo والإصدارات اللاحقة من "استوديو Android".
افتح "استوديو Android" وانقر على مشروع جديد في مرحبًا بك في "استوديو Android".
في نافذة مشروع جديد، ضمن فئة الهاتف والجهاز اللوحي، اختَر ما مِن نشاط، ثم انقر على التالي.
أكمل نموذج مشروع جديد:
اضبط اللغة على Java أو Kotlin. كلتا اللغتين متوافقتان بشكل كامل من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android لمعرفة المزيد من المعلومات عن لغة Kotlin، يمكنك الاطّلاع على تطوير تطبيقات Android باستخدام لغة Kotlin
اضبط الحدّ الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة SDK متوافق مع جهاز الاختبار. يجب تحديد إصدار أكبر من الحد الأدنى للإصدار المطلوب بواسطة حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للإصدار 19.0.x من نظام التشغيل Android وهو المستوى 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 جديد مشروعك.
-
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. التأكّد من تفعيل الفوترة لمشروعك:
تقدّم خدمة Google Cloud فترة تجريبية مجانية لتحصيل 0.00 دولار أمريكي. تنتهي الفترة التجريبية في نهاية 90 يوم أو بعد تراكم نفقات على الحساب بقيمة 300 دولار أمريكي (أو ما يعادله بالعملة المحلية)، أيهما أقرب. إلغاء في أي وقت. تتميز "منصة خرائط Google" برصيد شهري متكرر بقيمة 200 دولار أمريكي. لمزيد من المعلومات، المعلومات، راجع أرصدة حساب الفوترة والفوترة:
SDK للسحاب
gcloud projects create "PROJECT"
يمكنك قراءة المزيد عن حزمة تطوير البرامج (SDK) في Google Cloud , تثبيت Cloud SDK ، بالإضافة إلى الأوامر التالية:
الخطوة 2
لاستخدام "منصة خرائط Google"، يجب تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي تخطط لاستخدامها مع مشروعك.
وحدة التحكّم
تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android
SDK للسحاب
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
يمكنك قراءة المزيد عن حزمة تطوير البرامج (SDK) في Google Cloud , تثبيت Cloud SDK ، بالإضافة إلى الأوامر التالية:
الخطوة 3
هذه الخطوة تمر خلال عملية إنشاء مفتاح واجهة برمجة التطبيقات فقط. في حال استخدام مفتاح واجهة برمجة التطبيقات في ننصح بشدة بتقييد مفتاح واجهة برمجة التطبيقات يمكنك الاطّلاع على المزيد في صفحة استخدام مفاتيح واجهة برمجة التطبيقات الخاصة بالمنتج.
مفتاح واجهة برمجة التطبيقات هو معرّف فريد يصادق على الطلبات المرتبطة بمشروعك لأغراض الاستخدام والفوترة. يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات واحد على الأقل مرتبط بمشروعك.
لإنشاء مفتاح واجهة برمجة التطبيقات:
وحدة التحكّم
-
انتقل إلى Google Maps Platform > بيانات الاعتماد.
-
في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
يعرض مربع الحوار تم إنشاء مفتاح واجهة برمجة التطبيقات مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه حديثًا. -
انقر على إغلاق.
يتم إدراج مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
(تذكَّر تقييد واجهة برمجة التطبيقات قبل استخدامه في الإنتاج).
SDK للسحاب
gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
يمكنك قراءة المزيد عن حزمة تطوير البرامج (SDK) في Google Cloud , تثبيت Cloud SDK ، بالإضافة إلى الأوامر التالية:
إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك
يوضّح هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات كي يمكن الرجوع إليه بشكل آمن من خلال
تطبيقك. يجب عدم التحقق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذا ننصحك
تخزينه في ملف secrets.properties
، الموجود في الدليل الجذري
مشروعك. لمزيد من المعلومات عن ملف secrets.properties
، يمكنك الاطّلاع على
ملفات خصائص Gradle:
لتبسيط هذه المهمة، نوصيك باستخدام المكوّن الإضافي السري لنظام 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") } }
Groovy
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") }
Groovy
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.*" }
Groovy
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
علامة إلى إحداثيات سيدني. راجع دليل العلامات للحصول على التفاصيل.
ملف 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
، وهو نوع الجزء المستخدَم في نشاط الخرائط الملف.
يحتوي ملف تنسيق 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 Studio في إنشاء Gradle لإنشاء تطبيقك، ثم ستعرض النتائج على جهازك أو المحاكي. قد يستغرق الأمر عدة دقائق قبل أن يتم تثبيت التطبيق عمليات الإطلاق.
الخطوات التالية
إعداد خريطة: هذا المستند طريقة ضبط الإعدادات الأولية وإعدادات وقت التشغيل لخريطتك، مثل مثل موضع الكاميرا ونوع الخريطة ومكونات واجهة المستخدم والإيماءات.
إضافة خريطة إلى تطبيق Android (Kotlin): هذا الدرس التطبيقي حول الترميز عبر تطبيق يوضح بعض الميزات الإضافية حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android
استخدام مكتبة KTX في "خرائط Google": وتتيح لك مكتبة إضافات Kotlin (KTX) هذه الاستفادة من العديد من ميزات لغة Kotlin أثناء استخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2024-08-21 (حسب التوقيت العالمي المتفَّق عليه)
[] [] { "last_modified": "تاريخ التعديل الأخير: 2024-08-21 (حسب التوقيت العالمي المتفَّق عليه)", "state": "" }