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

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

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

أنشئ تطبيق Android يعرض خريطة باستخدام نموذج "مشاهدات "خرائط Google لنظام التشغيل Android Studio. إذا كان لديك مشروع حالي في "استوديو Android" تريد إعداده، اطّلِع على مقالة إعداد مشروع في "استوديو Android".

يهدف دليل البدء السريع هذا إلى المطوّرين الذين لديهم معرفة أساسية بتطوير التطبيقات على Android باستخدام Kotlin أو Java.

لمحة عن بيئة التطوير

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

إعداد جهاز Android

لتشغيل تطبيق يستخدم حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل Android، يجب نشره على جهاز Android أو emulator Android يستند إلى الإصدار 5.0 من Android أو إصدار أحدث ويتضمن واجهات برمجة تطبيقات Google.

لاستخدام جهاز 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"، الإصدار 5.0 من Android)، من المفترض أن يعمل تطبيقك على أكثر من ‎99% من أجهزة Android.
- اضبط لغة إعدادات الإنشاء على Kotlin DSL أو Groovy DSL. يتم عرض مقتطفات لكلتا اللغتَين لإعدادات الإصدار في الخطوات التالية.
انقر على إنهاء.

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

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

إعداد مشروعك على Google Cloud

أكمِل خطوات إعداد Cloud Console المطلوبة من خلال النقر على علامات التبويب التالية:

الخطوة 1

وحدة التحكّم

في Google Cloud Console، في صفحة أداة اختيار المشاريع، انقر على إنشاء مشروع لبدء إنشاء مشروع جديد على Cloud.

الانتقال إلى صفحة اختيار المشروع
تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تأكَّد من تفعيل الفوترة لمشروعك.

توفّر Google Cloud فترة تجريبية بدون أي رسوم. تنتهي الفترة التجريبية بعد 90 يومًا أو بعد تحصيل رسوم بقيمة 300 دولار أمريكي من الحساب، أيهما أقرب. يمكنك الإلغاء في أي وقت. توفّر "منصة خرائط Google" رصيدًا شهريًا متكررًا بقيمة 200 دولار أمريكي. لمزيد من المعلومات، يُرجى الاطّلاع على أرصدة حسابات الفوترة والفوترة.

SDK للسحاب

gcloud projects create "PROJECT"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK و تثبيت Cloud SDK والأوامر التالية:

gcloud projects create

الخطوة 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 والأوامر التالية:

gcloud alpha services api-keys create

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

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

لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secrets Gradle لأجهزة Android.

لتثبيت المكوّن الإضافي Secrets Gradle لأجهزة Android في مشروعك على "خرائط Google"، اتّبِع الخطوات التالية:

في Android Studio، افتح ملف 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 أو MapsActivity.kt إذا ضبطت Kotlin على أنّه لغة تطبيقك.

العناصر الرئيسية لنشاط "خرائط Google":

يدير عنصر SupportMapFragment رحلة حياة الخريطة، وهو العنصر الرئيسي لواجهة مستخدِم التطبيق.
يوفر العنصر GoogleMap إمكانية الوصول إلى بيانات الخريطة و عرضها. هذه هي الفئة الرئيسية لحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android. يصف دليل عناصر الخريطة عنصرَي SupportMapFragment وGoogleMap بمزيد من التفاصيل.
تضع الدالة moveCamera الخريطة في منتصف الإحداثيات LatLng لمدينة سيدني في أستراليا. عادةً ما تكون الإعدادات الأولى التي يجب ضبطها عند إضافة خريطة هي موقع الخريطة وإعدادات الكاميرا، مثل زاوية العرض واتجاه الخريطة ومستوى التكبير/التصغير. راجِع دليل الكاميرا والعرض للاطّلاع على التفاصيل.
تضيف الدالة addMarker علامة إلى الإحداثيات الخاصة بمدينة Sydney. اطّلِع على دليل العلامات لمعرفة التفاصيل.

ملف Gradle الخاص بالوحدة

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