إضافة خريطة

يصف هذا الموضوع كيفية إضافة خريطة أساسية إلى تطبيق 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 على جيت هب.

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

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

مثال:

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

      

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

      

تنفيذ واجهة OnMapReadyCallback

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

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

      

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

      

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

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

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

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 لضبط معاودة الاتصال على الجزء.

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

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 ثم تتم إضافة علامة إلى الخريطة:

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

      

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

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

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

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

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