دليل البدء السريع لتطبيق "خرائط Google" لنظام التشغيل Android

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

يمكن استخدام هذه النصيحة لمطوّري البرامج الذين لديهم دراية بتطوير برامج Android الأساسية باستخدام جافا أو Kotlin.

إعداد بيئة التطوير

1. مطلوب Android Studio Arctic Fox أو إصدار أحدث. في حال عدم إجراء ذلك من قبل، يمكنك تنزيله وتثبيته.
2. تأكّد من استخدام الإصدار 7.0 من مكوّن Gradle الإضافي لنظام التشغيل Android أو إصدار أحدث في "استوديو Android".

• لاستخدام جهاز يعمل بنظام التشغيل Android، اتّبِع التعليمات الواردة في تشغيل التطبيقات على جهاز.
• لاستخدام محاكي Android، يمكنك إنشاء جهاز افتراضي وتثبيت المحاكي من خلال استخدام مدير الأجهزة الافتراضية (AVD) من Android الذي يأتي مرفقًا مع Android Studio.

إنشاء مشروع على "خرائط Google" في "استوديو Android"

1. افتح "استوديو Android" وانقر على إنشاء مشروع جديد في نافذة مرحبًا بك في Android Studio.

2. في نافذة مشروع جديد، ضمن فئة الهاتف والجهاز اللوحي، حدّد نشاط خرائط Google، ثم انقر على التالي.

3. املأ نموذج نشاط خرائط Google:

   • اضبط اللغة على جافا أو Kotlin. وكلتا اللغتين مدعومتان بالكامل من خلال SDK للخرائط على نظام التشغيل Android. لمزيد من المعلومات عن لغة Kotlin، يمكنك الاطّلاع على تطوير تطبيقات متوافقة مع Android باستخدام لغة Kotlin.

   • اضبط الحد الأدنى لحزمة تطوير البرامج (SDK) على إصدار حزمة تطوير البرامج (SDK) المتوافق مع جهازك الاختباري. يجب تحديد إصدار أكبر من الحد الأدنى للإصدار المطلوب في الإصدار 18.0.x من تطبيق SDK لخرائط Android، والذي يمثل حاليًا واجهة برمجة تطبيقات Android المستوى 19 (Android 4.4، KitKat) أو إصدارًا أحدث. اطلع على ملاحظات الإصدار للحصول على أحدث المعلومات حول متطلبات إصدار SDK.

4. انقر على إنهاء.

   يبدأ "استوديو Android" تطبيق Gradle وينشئ المشروع. وقد تستغرق هذه العملية بعض الوقت.

5. عند الانتهاء من الإصدار، يفتح Android Studio الملفين AndroidManifest.xml وMapsActivity. قد يحمل نشاطك اسمًا مختلفًا، ولكنه سيكون النشاط الذي هيأته أثناء الإعداد.

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

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

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

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

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

لتبسيط هذه المهمة، نقترح عليك استخدام Secrets Gradle Plugin for Android. لتثبيت المكون الإضافي وتخزين مفتاح واجهة برمجة التطبيقات:

1. في "استوديو Android"، افتح ملف build.gradle على مستوى مشروعك وأضِف الرمز التالي إلى العنصر dependencies ضمن buildscript.

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }

2. بعد ذلك، افتح ملف build.gradle على مستوى الوحدة الخاصة بك وأضِف الرمز التالي إلى العنصر plugins.

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
       

3. احفظ الملف وزامن مشروعك مع Gradle.
4. افتح local.properties في الدليل على مستوى مشروعك، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات.

   MAPS_API_KEY=YOUR_API_KEY
       

5. احفظ الملف.
6. في ملف AndroidManifest.xml، انتقِل إلى com.google.android.geo.API_KEY وعدِّل android:value attribute على النحو التالي:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

ملاحظة: كما هو موضّح أعلاه، com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على العديد من واجهات برمجة التطبيقات المستندة إلى "خرائط Google" على نظام التشغيل Android، بما في ذلك "حزمة تطوير البرامج (SDK) للخرائط" لنظام التشغيل Android. للتوافق مع الأنظمة القديمة، تتوافق واجهة برمجة التطبيقات أيضًا مع الاسم com.google.android.maps.v2.API_KEY. يسمح هذا الاسم القديم بالمصادقة في الإصدار 2 من واجهة برمجة التطبيقات لخرائط Android فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. وإذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

انظر إلى الرمز

افحص الشفرة التي يقدمها النموذج. وعلى وجه الخصوص، اطلع على الملفات التالية في مشروع استوديو Android.

ملف أنشطة الخرائط

ملف أنشطة الخرائط هو النشاط الرئيسي للتطبيق، ويحتوي على الرمز لإدارة الخريطة وعرضها. ويتم تلقائيًا تسمية الملف الذي يحدد النشاط على أنه MapsActivity.java أو في حال ضبط لغة Kotlin كلغة لتطبيقك MapsActivity.kt.

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

• يدير الكائن SupportMapFragment دورة حياة الخريطة وهو العنصر الرئيسي في واجهة مستخدم التطبيق.

• يوفر الكائن GoogleMap إمكانية الوصول إلى بيانات الخريطة والعرض. هذه هي الفئة الرئيسية في SDK للخرائط على أجهزة Android. يصف دليل كائنات الخريطة الكائنين SupportMapFragment وGoogleMap بمزيد من التفصيل.

• تُركز الدالة moveCamera الخريطة على إحداثيات LatLng لسيدني في أستراليا. الإعدادات الأولى المطلوب تهيئتها عند إضافة خريطة هي عادةً إعدادات الخريطة وموقع الكاميرا، مثل زاوية العرض، واتجاه الخريطة، ومستوى التكبير/التصغير. راجع دليل الكاميرا والعرض للحصول على التفاصيل.

• تضيف الدالة addMarker علامة إلى إحداثيات سيدني. راجع دليل العلامات للاطلاع على مزيد من التفاصيل.

يحتوي ملف نشاط الخرائط على الرمز التالي:

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}

      

ملف Gradle Module

يشتمل ملف الوحدة build.gradle على تبعية الخرائط التالية، والتي تتطلبها حزمة SDK للخرائط لنظام التشغيل Android.

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.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:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

نشر التطبيق وتشغيله

عند تشغيل التطبيق بنجاح، سيتم عرض خريطة تتمركز حول سيدني سيدني في أستراليا، مع وضع علامة على المدينة كما هو موضح في لقطة الشاشة التالية.

لنشر التطبيق وتشغيله:

1. في "استوديو Android"، انقر على خيار القائمة تشغيل (أو رمز زر التشغيل) لتشغيل تطبيقك.
2. عندما يُطلب منك اختيار جهاز، اختَر أحد الخيارات التالية:
   • حدد جهاز Android المتصل بجهاز الكمبيوتر.
   • بدلاً من ذلك، يمكنك اختيار زر الاختيار محاكي التشغيل واختيار الجهاز الافتراضي الذي أعددته.
3. انقر على حسنًا. سيبدأ Android Studio تطبيق Gradle لتصميم تطبيقك، ثم سيعرض النتائج على جهازك أو من خلال المحاكي الذي تستخدمه. قد يستغرق إطلاق التطبيق عدة دقائق.

الخطوات التالية

• إعداد خريطة: يصف هذا الموضوع كيفية ضبط الإعدادات الأولية وإعدادات وقت التشغيل لخريطتك، مثل موضع الكاميرا ونوع الخريطة ومكونات واجهة المستخدم والإيماءات.

• إضافة خريطة إلى تطبيق Android (Kotlin): يرشدك هذا الدرس التطبيقي حول الترميز من خلال تطبيق يوضّح بعض الميزات الإضافية في "خرائط Google SDK" لنظام التشغيل Android.

• استخدام مكتبة KTX في "خرائط Google" لنظام التشغيل Android: تتيح لك مكتبة إضافات لغة Kotlin (KTX) هذه الاستفادة من العديد من ميزات لغة Kotlin أثناء استخدام حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل Android.