پیکربندی نقشه

پلاتفرم را انتخاب کنید: Android iOS

این سند نحوه پیکربندی نقشه‌ای را که بااستفاده از «کیت توسعه نرم‌افزار Google Maps برای Android» به برنامه Android اضافه شده است شرح می‌دهد.

نمای کلی

نقشه‌ای از کیوتو با تنظیمات نقشه پیکربندی‌شده. پس‌از افزودن نقشه به برنامه‌تان، می‌توانید تنظیمات اولیه و زمان اجرای نقشه را پیکربندی کنید. تنظیمات اولیه باید براساس اینکه محفظه نقشه (SupportMapFragment یا MapView) را به‌صورت ایستا یا پویا اضافه کرده‌اید پیکربندی شود. اگر محفظه نقشه به‌صورت ایستا اضافه شده باشد، می‌توانید تنظیمات اولیه نقشه را در فایل چیدمان پیکربندی کنید. اگر به‌صورت پویا اضافه شده است، می‌توانید تنظیمات اولیه را در فراخوانی برگشتی OnCreate با شیء GoogleMapOptions پیکربندی کنید.

برای جزئیات بیشتر درباره افزودن محفظه نقشه، به افزودن نقشه مراجعه کنید.

تنظیمات اولیه نقشه شامل موارد زیر است:

در زمان اجرا می‌توانید این تنظیمات و برخی تنظیمات اضافی را با به‌روزرسانی شیء GoogleMap در callback onMapReady پیکربندی کنید. تنظیمات اضافی ازطریق روش‌های کلاس GoogleMap پیکربندی می‌شود، مثل روش‌هایی که لایه ترافیک و حاشیه نقشه را پیکربندی می‌کنند.

مثال

در کد مثال زیر و نماگرفت بالا، نقشه با تنظیمات زیر پیکربندی شده است.

تنظیمات اولیه در فایل چیدمان پیکربندی می‌شود:

  • کنترل‌های بزرگ‌نمایی را فعال کنید.
  • کنترل‌های اشاره چرخاندن را فعال کنید.
  • کجی نقشه را روی ۳۰ تنظیم کنید.

تنظیمات زمان اجرا:

  • دوربین را روی کیوتو ژاپن متمرکز کنید.
  • نوع نقشه ترکیبی را فعال کنید.
  • لایه ترافیک را روشن کنید.

تنظیمات اولیه

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

    }
}

قبل‌از شروع

قبل‌از شروع، می‌توانید پروژه‌ای راه‌اندازی کنید و نقشه پایه‌ای را ازطریق گزینه‌های زیر اضافه کنید:

  • بااستفاده از الگوی Maps برای «استودیو Android»، برنامه‌ای بسازید. الگوی Maps به‌طور خودکار پروژه شما را پیکربندی می‌کند و نقشه پایه‌ای اضافه می‌کند. از یک قطعه به‌عنوان محفظه نقشه استفاده می‌شود و به‌صورت ایستا اضافه می‌شود. برای جزئیات، به شروع سریع مراجعه کنید.

  • به‌صورت دستی پروژه‌تان را برای کیت توسعه نرم‌افزار پیکربندی کنید و نقشه پایه اضافه کنید. این کار به شما امکان می‌دهد از هر الگوی Android استفاده کنید و نقشه‌ای به برنامه موجود اضافه کنید.

پیکربندی نقشه پس‌از افزودن آن به‌صورت ایستا

این بخش نحوه تنظیم وضعیت اولیه نقشه را درصورتی‌که آن را به‌صورت ایستا به فایل چیدمان خود اضافه کرده باشید شرح می‌دهد.

«کیت توسعه نرم‌افزار Google Maps برای 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.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 تنظیم شده است. یادداشت‌های انتشار به شما اطلاع خواهد داد که پشتیبانی از داخل ساختمان چه زمانی در این نوع نقشه‌ها دردسترس نخواهد بود.

نقشه داخلی مرکز خریدی که خروجی‌ها و بخش‌های کالا را نشان می‌دهد.

در اینجا خلاصه‌ای از قابلیت‌های نقشه‌های داخلی در API ارائه شده است:

  • می‌توانید نقشه‌های داخلی را با فراخوانی GoogleMap.setIndoorEnabled(false) غیرفعال کنید. به‌طور پیش‌فرض، نقشه‌های داخلی فعال است. نقشه‌های داخلی در هر زمان روی یک نقشه نمایش داده می‌شوند. به‌طور پیش‌فرض، این اولین نقشه‌ای است که به برنامه‌تان اضافه شده است. برای نمایش نقشه‌های داخلی در نقشه‌ای دیگر، آن‌ها را در نقشه اول غیرفعال کنید، سپس setIndoorEnabled(true) را در نقشه دوم فراخوانی کنید.
  • برای غیرفعال کردن انتخابگر سطح پیش‌فرض (انتخابگر طبقه)، GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false) را فراخوانی کنید. برای جزئیات بیشتر، تعامل با نقشه را ببینید.
  • OnIndoorStateChangeListener — شنوندگانی را تعریف می‌کند که وقتی ساختمانی در کانون توجه قرار می‌گیرد یا طبقه‌ای در ساختمانی فعال می‌شود، آن را تشخیص می‌دهند. برای جزئیات بیشتر، تعامل با نقشه را ببینید.
  • getFocusedBuilding — ساختمانی را که در کانون است بازیابی می‌کند. سپس می‌توانید با تماس با IndoorBuilding.getActiveLevelIndex()، سطح فعال را پیدا کنید.
  • سبک‌پردازی نقشه پایه بر نقشه‌های داخلی تأثیر نمی‌گذارد.

راه‌اندازی لایه‌گذاری نقشه

این ویدیو نمونه‌ای از حاشیه‌گذاری نقشه را نشان می‌دهد.

نقشه Google طوری طراحی شده است که کل منطقه تعریف‌شده توسط عنصر نگهدارنده خود را پر کند، معمولاً MapView یا SupportMapFragment. چندین جنبه از نحوه ظاهر و رفتار نقشه توسط ابعاد ظرف آن تعریف می‌شود:

  • هدف دوربین مرکز منطقه حاشیه‌دار را منعکس خواهد کرد.
  • کنترل‌های نقشه نسبت‌به لبه‌های نقشه قرار گرفته‌اند.
  • اطلاعات حقوقی، مانند بیانیه‌های حق نشر یا نشان‌واره Google، در امتداد لبه پایین نقشه ظاهر می‌شود.

می‌توانید بااستفاده از GoogleMap، در اطراف لبه‌های نقشه لایه اضافه کنید.روش setPadding(). نقشه همچنان کل ظرف را پر خواهد کرد، اما موقعیت‌یابی نوشتار و کنترل، اشاره‌های نقشه، و حرکات دوربین به‌گونه‌ای رفتار خواهند کرد که گویی در فضای کوچک‌تری قرار گرفته‌اند. این امر منجر به تغییرات زیر می‌شود:

  • حرکات دوربین بااستفاده از فراخوانی‌های API یا فشردن دکمه‌ها (مثلاً قطب‌نما، مکان من، دکمه‌های بزرگ‌نمایی) نسبت‌به منطقه حاشیه‌دار است.
  • روش 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));

همچنین می‌توانید از سبک‌پردازی نقشه بااستفاده از فضای ابری برای پیکربندی رنگ پس‌زمینه استفاده کنید. رنگ پس‌زمینه‌ای که در سبک‌بندی نقشه تنظیم شده است اولویت بالاتری نسبت به رنگ پس‌زمینه محلی دارد. برای اطلاعات بیشتر، به تغییر رنگ پس‌زمینه برنامه برای سبک‌دهی نقشه‌های ابری مراجعه کنید.