إعداد خريطة

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

مثال

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

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

• تفعيل عناصر التحكّم في التكبير/التصغير
• تفعيل عناصر التحكّم في إيماءة التدوير
• اضبط إمالة الخريطة على 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"/>

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

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

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

val options = GoogleMapOptions()

      

GoogleMapOptions options = new GoogleMapOptions();

      

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

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. على سبيل المثال، لعرض خريطة قمر صناعي:

// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID)
map.setIndoorEnabled(true)
val isIndoor = map.isIndoorEnabled()

      

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

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

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

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

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

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

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

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

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 لخيارات الخريطة.

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

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

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