إضافة خريطة

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

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

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

  1. للحصول على حزمة تطوير البرامج (SDK)، والحصول على مفتاح واجهة برمجة التطبيقات (API)، وإضافة الأُطر المطلوبة، اتّبِع الخطوات التالية:

    1. الإعداد في "وحدة تحكّم Google Cloud"

    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 واضبطها على معرّف مورد R.id.map (@+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

if (context is FragmentActivity) {
    val mapFragment = SupportMapFragment.newInstance()
    context.supportFragmentManager
        .beginTransaction()
        .add(com.example.snippets.common.R.id.map_container, mapFragment)
        .commit()
}

جافا

SupportMapFragment mapFragment = SupportMapFragment.newInstance();
FragmentTransaction fragmentTransaction =
        getSupportFragmentManager().beginTransaction();
fragmentTransaction.add(R.id.map_container, mapFragment);
fragmentTransaction.commit();

تنفيذ واجهة OnMapReadyCallback

عدِّل تعريف النشاط على النحو التالي:

Kotlin

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

جافا

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

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

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

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

Kotlin

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

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

Kotlin

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

Kotlin

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

لقطة شاشة تظهر فيها الخريطة والعلامة في وسط &quot;جزيرة نول&quot;.

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

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

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

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

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