إضافة خريطة

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

نظرة عامة

توفر حزمة SDK للخرائط لنظام التشغيل Android عدة صفوف يمكن لتطبيقك استخدامها لإدارة دورة حياة الخريطة ووظائفها وبياناتها. تدعم الفئات تفاعلات المستخدم استنادًا إلى نموذج واجهة مستخدم Android، مثل تعيين الحالة الأولية للخريطة، والرد على إدخال الإيماءة من المستخدم في وقت التشغيل.

الواجهة والفئات الأساسية للتعامل مع الخرائط:

• GoogleMap — نقطة الدخول لإدارة ميزات الخريطة والبيانات الأساسية. لا يمكن لتطبيقك الوصول إلى الكائن GoogleMap إلا بعد استرداده من الكائن SupportMapFragment أو MapView.

• SupportMapFragment — جزء لإدارة دورة حياة كائن GoogleMap.

• MapView — عرض لإدارة دورة حياة كائن GoogleMap.

• OnMapReadyCallback — واجهة استدعاء للتعامل مع الأحداث وتفاعل المستخدم للعنصر GoogleMap.

ينفذ الكائن GoogleMap تلقائيًا هذه العمليات:

• جارٍ الاتصال بخدمة خرائط Google.
• جارٍ تنزيل مربعات الخرائط.
• يتم عرض المربعات على شاشة الجهاز.
• عرض عناصر تحكم متنوعة مثل العرض الشامل والتكبير/التصغير.
• الاستجابة لإيماءات العرض الشامل والتكبير/التصغير من خلال تحريك الخريطة وتكبيرها أو تصغيرها.

لاستخدام كائن GoogleMap في تطبيقك، يجب استخدام إما كائن SupportMapFragment أو MapView ككائن حاوية للخريطة، وبعد ذلك يمكنك استرداد كائن GoogleMap من الحاوية. ونظرًا لأن فئات الحاوية تكون مشتقة من جزء من Android أو من طريقة عرض، فإنها تمد الخريطة بالإدارة وبإمكانيات واجهة المستخدم للصفوف الأساسية في Android. إنّ فئة SupportMapFragment هي الحاوية الأكثر شيوعًا وحداثة في عنصر GoogleMap.

عرض الشفرة

تأتي الشفرة التالية من نشاط جافا الكامل المستخدم في هذا الموضوع عند إضافة جزء بشكل ثابت. تم إنشاء مشروع 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. إجراء معاملة تضيف الجزء إلى النشاط. لمزيد من المعلومات، اطلع على معاملات التجزئة.

مثلاً:

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

      

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

      

تنفيذ واجهة OnMapReadyCallback

يُرجى تعديل بيان النشاط كما يلي:

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

      

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

      

تعيين عرض المحتوى

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

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

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

      

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

      

الحصول على مؤشر للكسر وتسجيل معاودة الاتصال

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

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

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

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

      

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

      

الحصول على اسم للعنصر GoogleMap

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

في هذا المثال، تسترد استدعاء onMapReady المقبض على الكائن GoogleMap، ثم تتم إضافة علامة إلى الخريطة:

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

      

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

      

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

عرض شفرة النشاط الكامل:

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

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

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