إعداد خريطة

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

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

نظرة عامة

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

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

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

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

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

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

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

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

نظام ألوان الخريطة

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

تستخدم الخريطة تلقائيًا الوضع الفاتح. تستند قيمة إعداد النظام الحالي إلى إعداد الجهاز لـ 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));

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