إضافة خريطة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختَر النظام الأساسي: Android iOS JavaScript

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

عرض الرمز

يأتي الرمز التالي من نشاط 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"));
      }
  }

لإضافة خريطة

يصف هذا القسم كيفية إضافة خريطة أساسية باستخدام جزء كحاوية خريطة، ولكن يمكنك استخدام طريقة عرض بدلاً من ذلك. على سبيل المثال، اطّلع على Raw MapViewDemoActivity على 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).

على سبيل المثال، في ما يلي ملف تنسيق كامل يتضمّن عنصر 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")
    )
}

      

لقطة شاشة تتوسطها الخريطة ومحدّد الخريطة في جزيرة نول.

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

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

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


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

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