إعداد خريطة

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

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

نظرة عامة

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

• ضبط مشروعك يدويًا لاستخدام حزمة تطوير البرامج وإضافة خريطة أساسية يتيح لك ذلك استخدام أي نموذج 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"/>

ملاحظة: إذا كنت تستخدم حزمة تطوير البرامج لنظام التشغيل Android من "خرائط Google" مع ترخيص "الخطة المميزة" من Google Maps Platform، يجب إضافة البادئة m4b_ إلى كل سمة. على سبيل المثال، عند تحديد سمة نوع الخريطة، استخدِم m4b_mapType بدلاً من mapType. عند تحديد عناصر التحكّم في التكبير/التصغير، استخدِم m4b_uiZoomControls بدلاً من uiZoomControls.

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

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

إذا أضفت 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);

      

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

• إذا كنت تستخدم SupportMapFragment، استخدِم طريقة المصنع الثابتة SupportMapFragment.newInstance(GoogleMapOptions options) لإنشاء الجزء وتمرير إعداداتك.
• إذا كنت تستخدم MapView، استخدِم الدالة الإنشائية MapView(Context, GoogleMapOptions) وقدِّم إعداداتك.

تحديد اللغة المناسبة لخريطتك

عند إضافة 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 المنطقة المضمّنة.
• يتم إزاحة عناصر التحكّم في واجهة المستخدم عن حافة الحاوية بمقدار عدد البكسلات المحدّد.

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

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

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

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

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

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

ملاحظة: لن يتم تطبيق نظام الألوان في "الوضع الداكن" إلا على الخرائط التي لا تستخدم أنماطًا مخصّصة، أو على الخرائط التي تستخدم تصميم الخرائط باستخدام السحابة الإلكترونية. لن تعرض الخرائط التي تستخدم تنسيق JSON أو الوضع البسيط نظام الألوان الخاص بالوضع الداكن.

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

عند العمل في الوضع الداكن أو التبديل بين طرق عرض الخريطة، قد يكون من المفيد ضبط لون الخلفية التلقائي للخريطة. ويمكن تحقيق ذلك من خلال ضبط السمة 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));

ملاحظة: لا يتيح لون الخلفية استخدام قيم الشفافية.

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