إضافة خريطة

اختيار النظام الأساسي: نظام التشغيل 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"));
      }
  }

لإضافة خريطة

يصف هذا القسم كيفية إضافة خريطة أساسية باستخدام جزء كخريطة container; مع ذلك، يمكنك استخدام طريقة عرض بدلاً من ذلك. على سبيل المثال، راجع RawMapViewDemoActivity على جيت هب.

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

  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. رقم تعريف المورد (@+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

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

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

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

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

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