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

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

این سند نحوه پیکربندی نقشه ای را که با استفاده از Maps SDK برای Android به برنامه Android اضافه شده است، توضیح می دهد.

نمای کلی

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

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

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

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

مثال

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

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

  • فعال کردن کنترل های بزرگنمایی
  • چرخش کنترل های اشاره را فعال کنید.
  • شیب نقشه را روی 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);

    }
}

قبل از شروع

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

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

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

پس از افزودن یک نقشه، نقشه را پیکربندی کنید

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

Maps SDK برای 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 تنظیم کنید. گزینه های موجود همان گزینه هایی هستند که در فایل layout موجود هستند. شما می توانید یک 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);

برای اعمال این گزینه ها هنگام ایجاد نقشه، یکی از موارد زیر را انجام دهید:

نقشه خود را بومی سازی کنید

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

defaultConfig {
    resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}

درباره بومی سازی برنامه Android خود بیشتر بخوانید.

لایه ترافیک را تنظیم کنید

با فعال کردن لایه ترافیک می توانید داده های ترافیک را روی نقشه خود نمایش دهید. می توانید با فراخوانی متد setTrafficEnabled() لایه ترافیک را فعال و غیرفعال کنید و با فراخوانی متد isTrafficEnabled() مشخص کنید که لایه ترافیک روشن است یا خیر. تصویر زیر نقشه ای را نشان می دهد که لایه ترافیک فعال است.

نوع نقشه را تنظیم کنید

برای تنظیم نوع نقشه، متد setMapType را فراخوانی کنید. به عنوان مثال، برای نمایش یک نقشه ماهواره ای:

کاتلین 

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

تصویر زیر انواع نقشه های معمولی، ترکیبی و زمین را مقایسه می کند:

A comparison of the three map types: normal, hybrid, and terrain maps.

راه اندازی ساختمان های سه بعدی

بسیاری از شهرها، وقتی از نزدیک مشاهده شوند، ساختمان های سه بعدی قابل مشاهده خواهند بود، همانطور که در تصویر زیر از ونکوور، کانادا قابل مشاهده است. با تماس با GoogleMap.setBuildingsEnabled(false) می توانید ساختمان های سه بعدی را غیرفعال کنید.

نقشه ونکوور، کانادا

تنظیمات نقشه داخلی را تنظیم کنید

در سطوح زوم بالا، نقشه پلان های طبقات فضاهای داخلی مانند فرودگاه ها، مراکز خرید، فروشگاه های خرده فروشی بزرگ و ایستگاه های حمل و نقل را نشان می دهد. این نقشه‌های طبقه، که نقشه‌های داخلی نامیده می‌شوند، برای انواع نقشه‌های «عادی» و «ماهواره‌ای» ( GoogleMap.MAP_TYPE_NORMAL و GoogleMap.MAP_TYPE_SATELLITE ) نمایش داده می‌شوند. هنگامی که کاربر بزرگنمایی می کند، آنها به طور خودکار فعال می شوند و زمانی که نقشه کوچک می شود، محو می شوند.

اخطار منسوخ شدن: در نسخه بعدی، نقشه‌های داخلی فقط در نوع نقشه normal در دسترس خواهند بود. از زمان انتشار آینده، نقشه‌های داخلی در نقشه‌های satellite ، terrain یا hybrid پشتیبانی نمی‌شوند. حتی در جایی که indoor پشتیبانی نمی‌شود، isIndoorEnabled() همچنان مقداری را که با استفاده از setIndoorEnabled() تنظیم شده است، باز می‌گرداند، همانطور که اکنون انجام می‌دهد. به طور پیش فرض، setIndoorEnabled true است. یادداشت‌های انتشار به شما اطلاع می‌دهند که پشتیبانی داخلی در آن انواع نقشه در دسترس نباشد.

An indoor map of a shopping mall that shows the exits and merchandise sections.

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

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

بالشتک نقشه را تنظیم کنید

این ویدیو نمونه ای از بالشتک نقشه را نشان می دهد.

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

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

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

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

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

Map Padding

طرح رنگ نقشه

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

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

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