إضافة خريطة

اختَر النظام الأساسي: 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". يؤدي هذا إلى تفعيل استخدام سمات XML المخصّصة للسمة maps.
  3. في العنصر fragment، اضبط السمة android:name على com.google.android.gms.maps.SupportMapFragment.
  4. في العنصر fragment، أضِف السمة android: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. تنفيذ معاملة تضيف الجزء إلى النشاط. ولمزيد من المعلومات، يُرجى الاطّلاع على المعاملات المجزأة.

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

لغة Java


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

Kotlin


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

تنفيذ واجهة OnMapReadyCallback

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

لغة Java


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

Kotlin


class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

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

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

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

لغة Java


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

Kotlin


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

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

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

  2. يمكنك استدعاء طريقة getMapAsync لضبط معاودة الاتصال على الجزء.

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

لغة Java


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

Kotlin


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

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

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

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

لغة Java


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

Kotlin


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

لقطة شاشة تعرض خريطة ومحدّد موقع في وسط جزيرة &quot;نول&quot;

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

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

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

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

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