إضافة خريطة

اختيار النظام الأساسي: 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

    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. نفِّذ معاملة تضيف الجزء إلى النشاط. لمزيد من المعلومات، يُرجى الاطّلاع على عمليات Fragment.

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

Kotlin

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

جافا

SupportMapFragment mapFragment = SupportMapFragment.newInstance();
FragmentTransaction fragmentTransaction =
        getSupportFragmentManager().beginTransaction();
fragmentTransaction.add(R.id.map_container, mapFragment);
fragmentTransaction.commit();

تنفيذ واجهة OnMapReadyCallback

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

Kotlin

class MainActivity :
    AppCompatActivity(),
    OnMapReadyCallback {

    // ...
}

جافا

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

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

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

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

Kotlin

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

جافا

@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)

جافا

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"),
    )
}

جافا

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

لقطة شاشة تظهر فيها الخريطة والعلامة في وسط &quot;جزيرة نول&quot;

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

يمكنك الاطّلاع على الرمز البرمجي للنشاط الكامل:

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

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

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