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

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

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

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

1. يجب إدخال الإصدار Android Studio Fox أو أحدث. تنزيل وتثبيته إذا لم يسبق لك تنزيله
2. تأكَّد من استخدام الإصدار 7.0 من مكوّن Gradle الإضافي من Android أو إصدار أحدث في "استوديو Android".

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

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

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

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

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

   • اضبط اللغة على Java أو Kotlin. وكلتا اللغتين متوافقان بالكامل مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع Android. لمعرفة المزيد من المعلومات حول لغة Kotlin، يُرجى الاطّلاع على تطوير تطبيقات Android باستخدام لغة Kotlin.

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

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

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

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

6. يتضمّن الملف AndroidManifest.xml تعليمات حول الحصول على مفتاح لواجهة برمجة التطبيقات في "خرائط Google" ثم إضافته إلى ملفlocal.property. لا تضِف مفتاح واجهة برمجة التطبيقات إلى ملف 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) لتطبيق "خرائط Google" لنظام التشغيل Android. للتوافق مع الأنظمة القديمة، تتوافق واجهة برمجة التطبيقات أيضًا مع الاسم com.google.android.maps.v2.API_KEY. يسمح هذا الاسم القديم بالمصادقة في الإصدار 2 من واجهة برمجة تطبيقات "خرائط Google" فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. وإذا تم تحديد كلا النوعَين، ستعرض واجهة برمجة التطبيقات استثناءً.

الاطّلاع على الرمز

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

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

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

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

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

• يوفر الكائن GoogleMap إمكانية الوصول إلى بيانات الخريطة وطريقة عرضها. هذا هو الفئة الرئيسية من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع 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 للوحدة

يتضمّن ملف الوحدة build.gradle الاعتمادية التالية على الخرائط، وهي مطلوبة من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع 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، والذي يتم تحديده في ملف نشاط "خرائط Google".
• تضبط السمة 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"، انقر على خيار القائمة Run (تشغيل) (أو رمز زر التشغيل) لتشغيل تطبيقك.
2. عندما يُطلب منك اختيار جهاز، حدِّد أحد الخيارات التالية:
   • اختَر جهاز Android المتّصل بجهاز الكمبيوتر.
   • بدلاً من ذلك، انقر على زر الاختيار تشغيل محاكي واختَر الجهاز الافتراضي الذي أعددته.
3. انقر على حسنًا. سيبدأ "استوديو Android" في برنامج Gradle لإنشاء تطبيقك ثم عرض النتائج على جهازك أو محاكيك. قد يستغرق إطلاق التطبيق عدة دقائق.

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

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

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

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