إعداد خريطة

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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

• ‫cameraTargetLat وcameraTargetLng وcameraZoom وcameraBearing cameraTilt: موضع الكاميرا الأولي اطّلِع على دليل الكاميرا والمشاهد للاطّلاع على التفاصيل.

• ‫uiZoomControls وuiCompass: لتحديد ما إذا كان سيتم عرض عناصر التحكّم في التكبير/التصغير وال Kompass يُرجى الاطّلاع على 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"/>

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

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

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

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

      

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

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

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

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

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

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

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

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

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

تستخدم الخريطة تلقائيًا الوضع الفاتح. تستند قيمة إعدادات النظام الحالية إلى إعدادات الجهاز لـ UI_NIGHT_MODE_MASK.

Kotlin

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

Java

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)

Java

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

Java

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

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

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