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

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

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

نمای کلی

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

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

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

در زمان اجرا می‌توانید این تنظیمات و برخی تنظیمات اضافی را با به‌روزرسانی شیء GoogleMap در بازگشت تماس 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);

    }
}

قبل‌از شروع

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

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

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

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

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

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

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

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

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

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

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

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

  • حرکات دوربین بااستفاده از فراخوانی‌های API یا فشردن دکمه‌ها (مثلاً قطب‌نما، مکان من، دکمه‌های بزرگ‌نمایی) نسبت‌به منطقه حاشیه‌دار است.
  • روش getCameraPosition مرکز منطقه حاشیه‌دار را برمی‌گرداند.
  • روش‌های Projection و getVisibleRegion منطقه حاشیه‌دار را برمی‌گردانند.
  • کنترل‌های میانای کاربر با تعداد پیکسل‌های مشخص‌شده از لبه محفظه فاصله دارند.

حاشیه‌گذاری می‌تواند هنگام طراحی واسط‌های کاربری که بخشی از نقشه را هم‌پوشانی می‌کنند مفید باشد. در تصویر زیر، نقشه در امتداد لبه‌های بالا و راست حاشیه‌گذاری شده است. کنترل‌های نقشه قابل‌مشاهده و متن قانونی در امتداد لبه‌های منطقه حاشیه‌دار (به رنگ سبز) نمایش داده می‌شود، درحالی‌که نقشه همچنان کل ظرف (به رنگ آبی) را پر می‌کند. در این مثال، می‌توانید منویی را در سمت راست نقشه شناور کنید بدون اینکه کنترل‌های نقشه را بپوشاند.

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

آرایش رنگ‌های نقشه

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

از نسخه ۲۰.۱.۰ کیت توسعه نرم‌افزار Google Maps برای Android، نقشه به‌طور پیش‌فرض از تنظیمات فعلی سیستم پیروی می‌کند. در نسخه‌های قبلی، نقشه به‌طور پیش‌فرض از حالت روشن استفاده می‌کند. مقدار تنظیم فعلی سیستم براساس تنظیم دستگاه برای 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));

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