إعداد خريطة

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

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

نظرة عامة

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

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

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

At runtime you can configure these settings and some addition settings by updating the GoogleMap object in the onMapReady callback. يتم ضبط الإعدادات الإضافية من خلال طرق فئة GoogleMap، مثل تلك التي تضبط طبقة حركة المرور وتحجيم الخريطة.

مثال

In the example code below and the screenshot above, the map is configured with the following settings.

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

  • تفعيل عناصر التحكّم في التكبير/التصغير
  • تفعيل عناصر التحكّم في إيماءة التدوير
  • اضبط إمالة الخريطة على 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". يضبط نموذج "خرائط Google" مشروعك تلقائيًا ويضيف خريطة أساسية. يتم استخدام جزء كحاوية للخريطة ويتم إضافته بشكل ثابت. لمعرفة التفاصيل، يُرجى الاطّلاع على دليل البدء السريع.

  • اضبط مشروعك يدويًا لحزمة تطوير البرامج (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.

  • ‫mapColorScheme: تحدّد هذه المَعلمة الألوان لخريطة عادية وخريطة تضاريس. تشمل القيم light وdark وfollow_system (تلقائي)، ما يعني استخدام إعداد النظام الحالي استنادًا إلى إعداد الجهاز لـ UI_NIGHT_MODE_MASK. لمزيد من المعلومات، يُرجى الاطّلاع على مخطط ألوان الخريطة.

لاستخدام هذه السمات المخصّصة في ملف التنسيق، يجب أن يتضمّن الملف تعريف مساحة الاسم التالي. يمكنك اختيار أي مساحة اسم، وليس من الضروري أن تكون 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:mapColorScheme="dark"
  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()

جافا

GoogleMapOptions options = new GoogleMapOptions();

ثم اضبطها على النحو التالي:

Kotlin

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

جافا

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

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

أقلمة خريطتك

عند إضافة MapView أو SupportMapFragment إلى تطبيقك، يتم عرض العناصر النصية على الخريطة باللغة المناسبة استنادًا إلى إعدادات جهاز المستخدم وموقعه الجغرافي. يمكنك حصر اللغات التي يستخدمها تطبيقك في مجموعة فرعية من جميع اللغات المتاحة، وذلك من خلال إضافة عنصر resConfigs إلى ملف Gradle. ويُعدّ ذلك مفيدًا لإزالة اللغات غير المستخدَمة، كما يقلّل من حجم الملف الثنائي لتطبيقك. على سبيل المثال:

defaultConfig {
    resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}

مزيد من المعلومات حول أقلمة تطبيق Android

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

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

طبقة حركة المرور

إعداد طبقة النقل العام

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

طبقة النقل العام

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

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

Kotlin

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

جافا

// 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() method. ستستمر الخريطة في ملء الحاوية بالكامل، ولكن سيتم وضع النص وعناصر التحكم وإيماءات الخريطة وحركات الكاميرا كما لو تم وضعها في مساحة أصغر. يؤدي ذلك إلى التغييرات التالية:

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

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

تحجيم الخريطة

الألوان في الخريطة

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

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

Kotlin

mapFragment = SupportMapFragment.newInstance(GoogleMapOptions().mapColorScheme(MapColorScheme.DARK).mapId(mapId2))

جافا

mapFragment = SupportMapFragment.newInstance(new GoogleMapOptions().mapColorScheme(MapColorScheme.DARK).mapId(mapId2));

يمكنك تبديل الألوان باستخدام الطريقة GoogleMap.setMapColorScheme() لضبط النمط الحالي على الوضع الداكن أو الفاتح أو اتّباع إعدادات النظام.

Kotlin

googleMap.setMapColorScheme(MapColorScheme.DARK)
googleMap.setMapColorScheme(MapColorScheme.LIGHT)
googleMap.setMapColorScheme(MapColorScheme.FOLLOW_SYSTEM)

جافا

googleMap.setMapColorScheme(MapColorScheme.DARK);
googleMap.setMapColorScheme(MapColorScheme.LIGHT);
googleMap.setMapColorScheme(MapColorScheme.FOLLOW_SYSTEM);

لإنشاء أنماط مخصّصة فاتحة وداكنة لخرائطك، استخدِم ميزة تصميم الخرائط باستخدام السحابة الإلكترونية.

ضبط لون الخلفية

عند العمل في الوضع الداكن أو التبديل بين طرق عرض الخريطة، قد يكون من المفيد ضبط لون خلفية الخريطة التلقائي. ويمكن تحقيق ذلك من خلال ضبط السمة backgroundColor لخيارات الخريطة.

Kotlin

private val googleMapOptions: GoogleMapOptions =
    GoogleMapOptions().backgroundColor(Color.argb(255, 255, 0, 0));

جافا

private GoogleMapOptions options = new GoogleMapOptions().backgroundColor(Color.argb(255, 255, 0, 0));

يمكنك أيضًا استخدام ميزة "تصميم الخرائط باستخدام السحابة الإلكترونية" لضبط لون الخلفية. لون الخلفية الذي تم ضبطه في نمط الخرائط له أولوية أعلى من لون الخلفية المحلي. لمزيد من المعلومات، يُرجى الاطّلاع على تغيير لون خلفية التطبيق لميزة "تصميم الخرائط باستخدام السحابة الإلكترونية".