إضافة خريطة

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

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

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

نظرة عامة

توفّر حزمة تطوير البرامج (SDK) لتطبيق "خرائط 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 Island (صفر درجة عرض وصفر درجة طول).

يمكنك الاطّلاع على رمز النشاط الكامل باتّباع الخطوات التالية:

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

---

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

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