إضافة خريطة

اختيار النظام الأساسي: Android iOS JavaScript

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

نظرة عامة

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

الواجهة الرئيسية والفئات الخاصة بمعالجة الخرائط:

  • GoogleMap: نقطة الدخول لإدارة الميزات والبيانات الأساسية للخريطة. لا يمكن لتطبيقك الوصول إلى عنصر GoogleMap إلا بعد استرداده من عنصر SupportMapFragment أو MapView.

  • SupportMapFragment: جزء لإدارة دورة حياة كائن GoogleMap.

  • MapView: طريقة عرض لإدارة مراحل نشاط عنصر GoogleMap.

  • OnMapReadyCallback: هي واجهة ردّ اتصال تعالج الأحداث وتفاعل المستخدم مع العنصر GoogleMap.

ينفّذ العنصر GoogleMap تلقائيًا العمليات التالية:

  • جارٍ الاتصال بخدمة "خرائط Google".
  • جارٍ تنزيل مربّعات الخرائط.
  • عرض المربّعات على شاشة الجهاز
  • عرض عناصر تحكّم متنوعة، مثل تحريك المحتوى وتكبيره/تصغيره
  • الاستجابة لإيماءات التحريك والتكبير/التصغير من خلال تحريك الخريطة وتكبيرها أو تصغيرها

لاستخدام عنصر GoogleMap في تطبيقك، يجب استخدام عنصر SupportMapFragment أو MapView كعنصر حاوٍ للخريطة، ثم استرداد عنصر GoogleMap من الحاوية. بما أنّ فئات الحاويات مشتقة من جزء أو عرض في Android، فإنّها توفّر للخريطة إمكانات إدارة مراحل النشاط وواجهة المستخدم لفئات Android الأساسية. الفئة SupportMapFragment هي الحاوية الأكثر حداثة وشيوعًا لكائن GoogleMap.

عرض الرمز

الرمز التالي مأخوذ من نشاط Java الكامل المستخدَم في هذا الموضوع عند إضافة جزء بشكل ثابت. تم إنشاء مشروع Android من نموذج "مشروع فارغ"، ثم تم تعديله استنادًا إلى دليل إعدادات المشروع. بعد تنفيذ الخطوات الواردة في هذا الموضوع، قد يختلف الرمز البرمجي استنادًا إلى نموذج المشروع.

  package com.example.mapsetup;

  import androidx.appcompat.app.AppCompatActivity;

  import android.os.Bundle;

  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;

  // Implement OnMapReadyCallback.
  public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          // Set the layout file as the content view.
          setContentView(R.layout.activity_main);

          // Get a handle to the fragment and register the callback.
          SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                  .findFragmentById(R.id.map);
          mapFragment.getMapAsync(this);

      }

      // Get a handle to the GoogleMap object and display marker.
      @Override
      public void onMapReady(GoogleMap googleMap) {
          googleMap.addMarker(new MarkerOptions()
                  .position(new LatLng(0, 0))
                  .title("Marker"));
      }
  }

لإضافة خريطة، اتّبِع الخطوات التالية:

يوضّح هذا القسم كيفية إضافة خريطة أساسية باستخدام جزء كحاوية للخريطة، ولكن يمكنك استخدام طريقة عرض بدلاً من ذلك. للاطّلاع على مثال، راجِع RawMapViewDemoActivity على Github.

الخطوات الأساسية:

  1. للحصول على حزمة SDK والحصول على مفتاح واجهة برمجة التطبيقات وإضافة الأُطر المطلوبة، اتّبِع الخطوات الواردة في:

    1. الإعداد في Google Cloud Console

    2. استخدام مفتاح واجهة برمجة التطبيقات

    3. إعداد مشروع في "استوديو Android"

  2. أضِف عنصر SupportMapFragment إلى النشاط الذي سيتعامل مع الخريطة. يمكنك إضافة الجزء بشكل ثابت أو ديناميكي.

  3. تنفيذ واجهة OnMapReadyCallback

  4. اضبط ملف التنسيق كطريقة عرض المحتوى.

  5. إذا أضفت الجزء بشكل ثابت، احصل على معرّف للجزء.

  6. تسجيل دالة معاودة الاتصال

  7. احصل على معرّف العنصر GoogleMap.

إضافة عنصر SupportMapFragment

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

لإضافة جزء بشكل ثابت

في ملف التصميم للنشاط الذي سيتعامل مع الخريطة:

  1. أضِف عنصر fragment.
  2. أضِف تعريف الاسم xmlns:map="http://schemas.android.com/apk/res-auto". يتيح ذلك استخدام maps سمات XML مخصّصة.
  3. في العنصر fragment، اضبط السمة android:name على com.google.android.gms.maps.SupportMapFragment.
  4. في العنصر fragment، أضِف السمة android:id واضبطها على معرّف المورد R.id.map (@+id/map).

على سبيل المثال، إليك ملف تخطيط كامل يتضمّن عنصر fragment:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

لإضافة جزء بشكل ديناميكي، اتّبِع الخطوات التالية:

في النشاط:

  1. أنشئ مثيلاً من SupportMapFragment.
  2. إجراء معاملة تضيف الجزء إلى النشاط لمزيد من المعلومات، اطّلِع على معاملات الأجزاء.

على سبيل المثال:

Kotlin

val mapFragment = SupportMapFragment.newInstance()
supportFragmentManager
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit()

Java

SupportMapFragment mapFragment = SupportMapFragment.newInstance();
getSupportFragmentManager()
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit();

تنفيذ الواجهة OnMapReadyCallback

عدِّل تعريف النشاط على النحو التالي:

Kotlin

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

Java

class MainActivity extends AppCompatActivity implements OnMapReadyCallback {
    // ...
}

ضبط طريقة عرض المحتوى

في طريقة onCreate الخاصة بنشاطك، استدعِ طريقة setContentView واضبط ملف التنسيق كطريقة عرض المحتوى.

على سبيل المثال، إذا كان اسم ملف التصميم هو main.xml:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)
}

Java

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
}

الحصول على معرّف للجزء وتسجيل وظيفة رد الاتصال

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

  2. استدعِ طريقة getMapAsync لضبط رد الاتصال في الجزء.

على سبيل المثال، إذا أضفت الجزء بشكل ثابت:

Kotlin

val mapFragment = supportFragmentManager
    .findFragmentById(R.id.map) as SupportMapFragment
mapFragment.getMapAsync(this)

Java

SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

الحصول على معرّف الكائن GoogleMap

استخدِم طريقة رد الاتصال onMapReady للحصول على معرّف للعنصر GoogleMap. يتم تشغيل دالة الرجوع عند توفّر الخريطة لتلقّي إدخالات المستخدم. يوفّر هذا الرمز مثيلاً غير فارغ لفئة GoogleMap يمكنك استخدامه لتعديل الخريطة.

في هذا المثال، تستردّ دالة رد الاتصال onMapReady معرّفًا للعنصر GoogleMap، ثم تتم إضافة علامة إلى الخريطة:

Kotlin

override fun onMapReady(googleMap: GoogleMap) {
    googleMap.addMarker(
        MarkerOptions()
            .position(LatLng(0.0, 0.0))
            .title("Marker")
    )
}

Java

@Override
public void onMapReady(GoogleMap googleMap) {
    googleMap.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}

لقطة شاشة للخريطة والعلامة في وسط جزيرة Null Island

عند إنشاء التطبيق وتشغيله بنجاح، سيتم عرض خريطة تتضمّن علامة على جزيرة Null (صفر درجة خط عرض وصفر درجة خط طول).

عرض رمز النشاط الكامل:

عرض إكمال النشاط

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

بعد إكمال هذه الخطوات، يمكنك ضبط إعدادات الخريطة.