إعداد خريطة

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

يصف هذا الموضوع كيفية تهيئة خريطة تمت إضافتها إلى تطبيق Android باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android.

نظرة عامة

لقطة شاشة لخريطة Kyto مع ضبط إعدادات الخريطة. بعد إضافة خريطة إلى تطبيقك، يمكنك ضبط الإعدادات الأولية ووقت التشغيل للخريطة. يجب ضبط الإعدادات الأولية استنادًا إلى ما إذا كنت أضفت حاوية الخريطة (SupportMapFragment أو MapView) بشكل ثابت أو ديناميكي. إذا تمت إضافة حاوية الخريطة بشكلٍ ثابت، يمكنك ضبط الإعدادات الأولية للخريطة في ملف التنسيق. إذا تمت إضافتها بشكل ديناميكي، يمكنك ضبط الإعدادات الأولية في عملية معاودة الاتصال OnCreate باستخدام كائن GoogleMapOptions.

لمعرفة التفاصيل حول إضافة حاوية خريطة، يُرجى الاطّلاع على مقالة إضافة خريطة.

تشمل الإعدادات الأولية للخريطة ما يلي:

في وقت التشغيل، يمكنك ضبط هذه الإعدادات وبعض إعدادات الإضافات من خلال تعديل العنصر GoogleMap في استدعاء onMapReady. يتم ضبط الإعدادات الإضافية من خلال طرق الفئة GoogleMap، مثل الإعدادات التي تضبط طبقة حركة المرور والمساحة المتروكة للخريطة.

مثال

في الرمز النموذجي أدناه ولقطة الشاشة أعلاه، يتم ضبط الخريطة باستخدام الإعدادات التالية.

يتمّ ضبط الإعدادات الأولية في ملف التنسيق:

  • تفعيل عناصر التحكم في التكبير/التصغير
  • تفعيل عناصر التحكّم بتدوير الإيماءات
  • اضبط إمالة الخريطة على 30.

إعدادات وقت التشغيل:

  • توسيط الكاميرا في كيوتو اليابان.
  • تفعيل نوع الخريطة المختلطة.
  • شغّل طبقة حركة المرور.

الإعدادات الأولية


<?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"
    xmlns:tools="http://schemas.android.com/tools"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    map:uiZoomControls="true"
    map:uiRotateGestures="true"
    map:cameraTilt="30" />
    

إعدادات وقت التشغيل

package com.example.mapsetup;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

import com.google.android.gms.maps.CameraUpdateFactory;
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;

public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

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

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

    }

    // Update the map configuration at runtime.
    @Override
    public void onMapReady(GoogleMap googleMap) {
        // Set the map coordinates to Kyoto Japan.
        LatLng kyoto = new LatLng(35.00116, 135.7681);
        // Set the map type to Hybrid.
        googleMap.setMapType(GoogleMap.MAP_TYPE_HYBRID);
        // Add a marker on the map coordinates.
        googleMap.addMarker(new MarkerOptions()
                .position(kyoto)
                .title("Kyoto"));
        // Move the camera to the map coordinates and zoom in closer.
        googleMap.moveCamera(CameraUpdateFactory.newLatLng(kyoto));
        googleMap.moveCamera(CameraUpdateFactory.zoomTo(15));
        // Display traffic.
        googleMap.setTrafficEnabled(true);

    }
}

قبل البدء

قبل أن تبدأ، يمكنك إعداد مشروع وإضافة خريطة أساسية من خلال الخيارات التالية:

  • يمكنك إنشاء تطبيق باستخدام نموذج "خرائط Google" لـ "استوديو Android". يقوم قالب الخرائط بتكوين مشروعك تلقائيًا ويضيف خريطة أساسية. يُستخدم جزء كحاوية خريطة وتتم إضافته بشكل ثابت. ولمزيد من التفاصيل، يُرجى الاطّلاع على quickstart.

  • يجب ضبط مشروعك يدويًا لحزمة تطوير البرامج (SDK) وإضافة خريطة أساسية. يتيح لك هذا استخدام أي نموذج Android وإضافة خريطة إلى تطبيق حالي.

تهيئة خريطة بعد إضافتها بشكل ثابت

يصف هذا القسم كيفية تعيين الحالة الأولية للخريطة إذا أضفتها بشكل ثابت إلى ملف التخطيط.

تحدّد حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android مجموعة من سمات XML المخصّصة لـ SupportMapFragment أو MapView يمكنك استخدامها لضبط الحالة الأولية للخريطة مباشرةً من ملف التنسيق. السمات التالية معرَّفة حاليًا:

  • mapType - نوع الخريطة المطلوب عرضها وتشمل القيم الصالحة: none وnormal وhybrid وsatellite وterrain.

  • cameraTargetLat، cameraTargetLng، cameraZoom، cameraBearing، cameraTilt: الموضع الأولي للكاميرا. يمكنك الاطّلاع على دليل الكاميرا وطرق العرض للحصول على مزيد من التفاصيل.

  • uiZoomControls، uiCompass — لتحديد ما إذا كان سيتم عرض عناصر التحكم في التكبير/التصغير والبوصلة أم لا. لمزيد من التفاصيل، يمكنك الاطّلاع على UiSettings.

  • uiZoomGestures وuiScrollGestures وuiRotateGestures وuiTiltGestures - يحدد ما إذا كانت إيماءات محددة مفعّلة أم لا. يمكنك الاطّلاع على UiSettings للحصول على التفاصيل.

  • zOrderOnTop: يشير إلى ما إذا كان سطح عرض الخريطة معروضًا أعلى نافذة الخريطة وعناصر التحكّم في الخريطة وما إذا كان أي عنصر في النافذة. راجِع SurfaceView.setZOrderOnTop(boolean) لمعرفة التفاصيل.

  • useViewLifecycle: صالح فقط مع عنصر SupportMapFragment. لتحديد ما إذا كانت دورة حياة الخريطة مرتبطة بعرض الجزء أو الجزء نفسه. انقر هنا للاطّلاع على مزيد من التفاصيل.

  • liteMode - true لتفعيل الوضع البسيط، وإلا سيتم استخدام false.

لاستخدام هذه السمات المخصّصة ضمن ملف التنسيق، يجب أن يتضمّن بيان مساحة الاسم التالي. يمكنك اختيار أي مساحة اسم بدون أن تكون map:

xmlns:map="http://schemas.android.com/apk/res-auto"

يمكنك بعد ذلك إضافة السمات التي تحتوي على بادئة map: إلى ملف التنسيق.

يضبط ملف التنسيق التالي كائن SupportMapFragment بسمات خريطة مخصّصة. يمكن أيضًا تطبيق السمات نفسها على كائن MapView.

<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"
  map:cameraBearing="112.5"
  map:cameraTargetLat="-33.796923"
  map:cameraTargetLng="150.922433"
  map:cameraTilt="30"
  map:cameraZoom="13"
  map:mapType="normal"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

إعداد خريطة بعد إضافتها ديناميكيًا

يصف هذا القسم كيفية تعيين الحالة الأولية للخريطة في حال إضافتها إلى تطبيقك ديناميكيًا.

إذا أضفت SupportMapFragment أو MapView ديناميكيًا، يمكنك عندها ضبط الحالة الأولية للخريطة في كائن GoogleMapOptions. الخيارات المتاحة هي نفسها الخيارات المتوفرة في ملف التخطيط. يمكنك إنشاء GoogleMapOptions على النحو التالي:

Kotlin



val options = GoogleMapOptions()

      

Java


GoogleMapOptions options = new GoogleMapOptions();

      

وبعد ذلك، يمكنك ضبطها على النحو التالي:

Kotlin



options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false)

      

Java


options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false);

      

لتطبيق هذه الخيارات عند إنشاء خريطة، يمكنك تنفيذ أحد الإجراءات التالية:

إعداد طبقة حركة المرور

يمكنك عرض بيانات حركة المرور على الخريطة من خلال تمكين طبقة حركة المرور. يمكنك تفعيل طبقة حركة المرور وإيقافها عن طريق استدعاء الطريقة setTrafficEnabled()، ويمكنك تحديد ما إذا كانت طبقة حركة المرور مفعّلة حاليًا من خلال استدعاء الطريقة isTrafficEnabled(). تعرض لقطة الشاشة التالية خريطة مع تمكين طبقة حركة المرور.

ضبط نوع الخريطة

لضبط نوع الخريطة، يمكنك استدعاء طريقة setMapType. على سبيل المثال، لعرض خريطة القمر الصناعي:

Kotlin



// Sets the map type to be "hybrid"
map.mapType = GoogleMap.MAP_TYPE_HYBRID

      

Java


// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

      

تقارن الصورة التالية بين أنواع خرائط الطرق العادية والهجينة وخرائط التضاريس:

مقارنة نوع الخريطة

إعداد المباني الثلاثية الأبعاد

عندما يُنظر إلى العديد من المدن عن قرب، ستظهر مبانٍ ثلاثية الأبعاد كما يمكن رؤيتها في الصورة التالية لفانكوفر بكندا. يمكنك إيقاف المباني الثلاثية الأبعاد من خلال طلب الرمز GoogleMap.setBuildingsEnabled(false).

خريطة لفانكوفر، كندا

ضبط إعدادات الخريطة الداخلية

في مستويات التكبير/التصغير العالية، تُظهر الخريطة خطط المباني للمساحات الداخلية مثل المطارات ومراكز التسوق ومتاجر البيع بالتجزئة الكبيرة ومحطات النقل العام. يتم عرض مخططات الطوابق هذه، المسماة بالخرائط الداخلية، لأنواع الخرائط "العادية" و"الأقمار الصناعية" (GoogleMap.MAP_TYPE_NORMAL وGoogleMap.MAP_TYPE_SATELLITE). ويتم تفعيل هذه المخططات تلقائيًا عندما يكبّر المستخدم الصورة، وتتلاشى عند تصغير الخريطة.

إشعار الإيقاف: في إصدار مستقبلي، لن تتوفر الخرائط الداخلية إلا على نوع الخريطة normal. واعتبارًا من ذلك الإصدار المستقبلي، لن تكون الخرائط الداخلية متاحة على خرائط satellite أو terrain أو hybrid. حتى في حال عدم توفُّر خيار "داخل المنزل"، سيواصل isIndoorEnabled() عرض القيمة التي تم ضبطها من خلال setIndoorEnabled()، كما هو الحال الآن. وتكون السمة setIndoorEnabled هي true تلقائيًا. سيتم إعلامك من خلال ملاحظات الإصدار عندما يصبح دعم الأماكن الداخلية غير متوفّر على أنواع الخرائط هذه.

مثال على خريطة داخلية

في ما يلي ملخّص لوظيفة الخرائط الداخلية في واجهة برمجة التطبيقات:

  • يمكنك إيقاف الخرائط الداخلية عن طريق طلب الرمز GoogleMap.setIndoorEnabled(false). تكون الخرائط الداخلية مفعَّلة تلقائيًا. يتم عرض الخرائط الداخلية على خريطة واحدة في كل مرة. بشكل تلقائي، تكون هذه هي الخريطة الأولى التي تتم إضافتها إلى تطبيقك. لعرض الخرائط الداخلية على خريطة مختلفة، يُرجى إيقافها على الخريطة الأولى، ثم استدعاء "setIndoorEnabled(true)" على الخريطة الثانية.
  • لإيقاف أداة اختيار المستوى التلقائي (أداة اختيار الطابق)، عليك طلب الرمز GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false). لمزيد من التفاصيل، راجِع التفاعل مع الخريطة.
  • OnIndoorStateChangeListener - يحدد المستمعين الذين يرصدون متى يتم التركيز على مبنى أو عند تفعيل مستوى في مبنى. للحصول على التفاصيل، راجع التفاعل مع الخريطة.
  • getFocusedBuilding — لاسترداد المبنى محل التركيز. يمكنك بعد ذلك العثور على مستوى النشاط من خلال طلب الرقم IndoorBuilding.getActiveLevelIndex().
  • لا يؤثر تصميم الخريطة الأساسية على الخرائط الداخلية.

إعداد المساحة المتروكة على الخريطة

يعرض هذا الفيديو مثالاً على المساحة المتروكة في الخريطة.

تم تصميم خريطة Google لملء المنطقة بأكملها المحدّدة بواسطة عنصر الحاوية الخاص بها، والذي يكون عادةً MapView أو SupportMapFragment. يتم تحديد عدة جوانب لكيفية ظهور الخريطة وسلوكها من خلال أبعاد حاويتها:

  • وسيعكس هدف الكاميرا وسط المنطقة المبطّنة.
  • يتم وضع عناصر التحكم في الخريطة بشكل متناسب مع حواف الخريطة.
  • تظهر المعلومات القانونية، مثل بيانات حقوق الطبع والنشر أو شعار Google، على طول الحافة السفلية من الخريطة.

يمكنك إضافة مساحة متروكة حول حواف الخريطة باستخدام علامة GoogleMap.setPadding(). ستستمر الخريطة في ملء الحاوية بالكامل، ولكن ستعمل النصوص والتحكُّم في تحديد الموضع والإيماءات على الخريطة وحركات الكاميرا كما لو تم وضعها في مساحة أصغر. ينتج عن ذلك التغييرات التالية:

  • ترتبط حركات الكاميرا من خلال طلبات البيانات من واجهة برمجة التطبيقات أو الضغط على الأزرار (على سبيل المثال، بوصلة، وموقعي، وأزرار التكبير أو التصغير) بالمنطقة المبطّنة.
  • تعرض الطريقة getCameraPosition مركز المنطقة المحشوة.
  • تعرض الطريقتان Projection وgetVisibleRegion المنطقة المبطّنة.
  • تتم إزاحة عناصر تحكم واجهة المستخدم من حافة الحاوية بعدد وحدات البكسل المحدد.

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

المساحة المتروكة للخريطة