إضافة خريطة

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

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

نظرة عامة

توفر حزمة SDK للخرائط لنظام 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).

على سبيل المثال، إليك ملف تنسيق كامل يتضمّن عنصر 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 ثم تتم إضافة marker إلى الخريطة:

لغة 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")
    )
}

لقطة شاشة للخريطة والمحدد في وسط جزيرة Null

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

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

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

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

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