سيتوفّر تصميم الخريطة الجديد قريبًا على "منصة خرائط Google". يتضمن هذا التحديث على تصميم الخريطة لوحة ألوان تلقائية جديدة وتحسينات على تجارب الخرائط وسهولة الاستخدام. سيتم تعديل جميع أنماط الخرائط تلقائيًا في آذار (مارس) 2025. للمزيد من المعلومات عن مدى التوفّر وكيفية تفعيل الميزة في وقت سابق، يُرجى الاطّلاع على نمط الخريطة الجديد في "منصة خرائط Google".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات السريعة على Android

إنشاء تطبيق 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"
ملاحظة: إذا اخترت استخدام محاكي Android، تأكَّد من اختيار جهاز يتضمّن رمز Play، ، المعروض ضمن عمود متجر Play. يشير هذا الرمز إلى أن هذه الملفات الشخصية عبارة عن CTS بالكامل. متوافق ويجوز له استخدام صور النظام التي تتضمّن تطبيق "متجر Play":

إنشاء مشروع على "خرائط 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.
  
  ملاحظة: إذا لم تكن متأكدًا من إصدار حزمة SDK الذي يجب اختياره، يُرجى اختيار رابط مساعدة في الاختيار لعرض معلومات التوزيع المتاحة حِزم تطوير البرامج (SDK) لنظام التشغيل Android. على سبيل المثال، إذا اخترت المستوى 21 من واجهة برمجة تطبيقات Android ("Lollipop" و"Android 5.0")، يجب أن يعمل تطبيقك على 99% من أجهزة Android
- اضبط لغة إعدادات الإنشاء على Kotlin DSL أو Groovy DSL. يتم عرض مقتطفات لكل من لغتي إعدادات الإصدار في ما يلي: الإجراءات.
انقر على إنهاء.

يبدأ "استوديو Android" في تشغيل Gradle وإنشاء المشروع. وقد تستغرق هذه العملية بعض الوقت.
أضِف نشاط المشاهدات على "خرائط Google":
1. انقر بزر الماوس الأيمن على المجلد "app" في مشروعك.
2. حدد جديد > Google > نشاط بانوراميات في خرائط Google.
3. في مربع الحوار نشاط Android الجديد، اختَر مربّع الاختيار نشاط مشغّل التطبيقات.
4. اختَر إنهاء.
  
  لمزيد من المعلومات، يُرجى مراجعة إضافة رمز من نموذج
بعد اكتمال عملية الإنشاء، يفتح "استوديو Android" واجهة AndroidManifest.xml وMapsActivity ملف. قد يحمل نشاطك اسمًا مختلفًا، ولكنه هو النظام الذي ضبطته أثناء الإعداد.

تنبيه: يحتوي ملف AndroidManifest.xml على تعليمات حول الحصول على مفتاح واجهة برمجة التطبيقات لخرائط Google، ثم إضافته إلى ملف local.properties. عدم إضافة مفتاح واجهة برمجة التطبيقات إلى ملف local.properties وسيؤدي ذلك إلى تخزين مفتاح واجهة برمجة التطبيقات بشكل أقل أمانًا. بدلاً من ذلك، اتّبِع التعليمات في مقالة إعداد مشروعك على Google Cloud لإنشاء مشروع على Google Cloud ضبط مفتاح واجهة برمجة التطبيقات

إعداد مشروعك على 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 ، بالإضافة إلى الأوامر التالية:

gcloud projects create

الخطوة 2

لاستخدام Google Maps Platform، عليك تفعيل واجهات برمجة التطبيقات أو حِزم تطوير البرامج (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 ، بالإضافة إلى الأوامر التالية:

gcloud alpha services api-keys create

إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

يوضّح هذا القسم كيفية تخزين مفتاح واجهة برمجة التطبيقات كي يمكن الرجوع إليه بشكل آمن من خلال تطبيقك. يجب عدم التحقق من مفتاح واجهة برمجة التطبيقات في نظام التحكم في الإصدار، لذا ننصحك تخزينه في ملف secrets.properties، الموجود في الدليل الجذري مشروعك. لمزيد من المعلومات عن ملف secrets.properties، اطّلِع على ملفات سمات Gradle.

لتبسيط هذه المهمة، نوصيك باستخدام المكوّن الإضافي السري لنظام Gradle المتوافق مع Android

لتثبيت مكوّن Secret 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 من التحقق من عنصر تحكّم الإصدار .
ملاحظة: إذا لم يكن ملف secrets.properties: عليك إنشاؤها، وعليك إنشاؤها في المجلد نفسه الذي يتضمّن ملف local.properties.
```
MAPS_API_KEY=YOUR_API_KEY
```
احفظ الملف.
أنشئ ملف local.defaults.properties في الدليل على المستوى الأعلى، وهو المجلد نفسه الذي يتضمّن ملف secrets.properties، ثم أضِف الرمز التالي.

ملاحظة: أدخِل الرمز كما هو موضّح. عدم الاستبدال DEFAULT_API_KEY باستخدام مفتاح واجهة برمجة التطبيقات.
```
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 name com.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 or build.gradle file and edit the secrets property. If the secrets property does not exist, add it.

Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.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".

ملف النشاط على "خرائط Google"

ملف نشاط الخرائط هو النشاط الرئيسي للتطبيق، يحتوي على رمز إدارة الخريطة وعرضها. بشكل افتراضي، الملف الذي النشاط يُسمى 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): يرشدك هذا الدليل التدريبي حول الترميز إلى تطبيق يعرض بعض الميزات الإضافية لسمة "حزمة تطوير البرامج (SDK) للخرائط" لنظام التشغيل Android.
استخدام مكتبة KTX في "خرائط Google": وتتيح لك مكتبة إضافات Kotlin (KTX) هذه الاستفادة من العديد من ميزات لغة Kotlin أثناء استخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android.