إضافة خريطة

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

يصف هذا الموضوع كيفية إضافة خريطة أساسية إلى تطبيق Android بعد ضبط المشروع لاستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط 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 واضبطها على رقم تعريف المورد (@+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 (خط عرض صفر درجة وخط طول صفر درجة).

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

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

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

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