إضافة خريطة

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

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

نظرة عامة

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

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

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

  • ‫SupportMapFragment: وحدة مقتطعة لإدارة دورة حياة عنصر GoogleMap

  • MapView — ملف شخصي لإدارة دورة حياة نشاط عنصر GoogleMap.

  • ‫OnMapReadyCallback: واجهة طلب استدعاء تهدف إلى التعامل مع الأحداث وتفاعل المستخدم مع العنصر GoogleMap.

ينفذ كائن GoogleMap العمليات التالية تلقائيًا:

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

لاستخدام عنصر GoogleMap في تطبيقك، يجب استخدام عنصر SupportMapFragment أو MapView كعنصر حاوية للخريطة، ثم retrievingGoogleMap من الحاوية. بما أنّ فئات الحاوية تستمد من جزء أو عرض 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 واضبطها على رقم تعريف المورد (@+id/map) في R.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

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

عرض التعليمة البرمجية للنشاط بالكامل:

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

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

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