Configurare una mappa

Seleziona la piattaforma: Android iOS

Questo argomento descrive come configurare una mappa aggiunta a un'app per Android utilizzando Maps SDK for Android.

Panoramica

Dopo aver aggiunto una mappa alla tua app, puoi configurare le impostazioni iniziali e di runtime della mappa. Le impostazioni iniziali devono essere configurate a seconda che tu abbia aggiunto il container della mappa (SupportMapFragment o MapView) in modo statico o dinamico. Se il container della mappa è stato aggiunto in modo statico, puoi configurare le impostazioni della mappa iniziali nel file di layout. Se è stato aggiunto in modo dinamico, puoi configurare le impostazioni iniziali nel callback OnCreate con un oggetto GoogleMapOptions.

Per informazioni dettagliate sull'aggiunta di un contenitore mappa, consulta la sezione Aggiungere una mappa.

Le impostazioni iniziali della mappa includono:

• La posizione della fotocamera, tra cui: posizione, zoom, orientamento e inclinazione. Per informazioni dettagliate sul posizionamento della videocamera, vedi Videocamera e vista.
• Il tipo di mappa.
• I componenti dell'interfaccia utente da visualizzare, come i pulsanti di zoom e la bussola.
• I gesti da attivare.
• Indica se è abilitata la modalità Lite.

In fase di runtime, puoi configurare queste impostazioni e alcune impostazioni di aggiunta aggiornando l'oggetto GoogleMap nel callback onMapReady. Le impostazioni aggiuntive vengono configurate tramite i metodi della classe GoogleMap, ad esempio quelli che configurano il livello di traffico e la spaziatura della mappa.

Esempio

Nel codice di esempio riportato di seguito e nello screenshot riportato sopra, la mappa è configurata con le seguenti impostazioni.

Le impostazioni iniziali sono configurate nel file di layout:

• Attiva i controlli zoom.
• Attiva i controlli di rotazione dei gesti.
• Imposta l'inclinazione della mappa su 30.

Le impostazioni di runtime:

• Centra la fotocamera su Kyoto, Giappone.
• Abilita il tipo di mappa ibrido.
• Attiva il livello traffico.

Impostazioni iniziali

<?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" />
    

Impostazioni di runtime

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

    }
}

Prima di iniziare

Prima di iniziare, puoi configurare un progetto e aggiungere una mappa di base utilizzando le seguenti opzioni:

• Crea un'app utilizzando il modello di Maps per Android Studio. Il modello di Maps configura automaticamente il progetto e aggiunge una mappa di base. Un frammento viene utilizzato come container della mappa e viene aggiunto in modo statico. Per maggiori dettagli, consulta la quickstart.

• Configura il progetto manualmente per l'SDK e aggiungi una mappa di base. In questo modo puoi utilizzare qualsiasi modello Android e aggiungere una mappa a un'app esistente.

Configurare una mappa dopo averla aggiunta in modo statico

Questa sezione descrive come impostare lo stato iniziale della mappa se l'hai aggiunta in modo statico al file di layout.

Maps SDK for Android definisce un insieme di attributi XML personalizzati per un elemento SupportMapFragment o MapView che puoi utilizzare per configurare lo stato iniziale della mappa direttamente dal file di layout. Al momento sono definiti i seguenti attributi:

• mapType: il tipo di mappa da visualizzare. I valori validi includono: none, normal, hybrid, satellite e terrain.

• cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt: la posizione iniziale della fotocamera. Per informazioni dettagliate, consulta la guida relativa a videocamere e visualizzazioni.

• uiZoomControls, uiCompass: specifica se vengono visualizzati i controlli dello zoom e la bussola. Per informazioni dettagliate, visita la pagina UiSettings.

• uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures: indica se sono attivi gesti specifici. Per informazioni dettagliate, visita la pagina UiSettings.

• zOrderOnTop: indica se la superficie della visualizzazione mappa è mostrata sulla parte superiore della finestra della mappa, dei controlli della mappa e di qualsiasi oggetto nella finestra. Per maggiori dettagli, consulta SurfaceView.setZOrderOnTop(boolean).

• useViewLifecycle: valido solo con un oggetto SupportMapFragment. Specifica se il ciclo di vita della mappa deve essere legato alla vista del frammento o al frammento stesso. Per informazioni dettagliate, visita questa pagina.

• liteMode - true per attivare la modalità Lite; altrimenti, false.

• mapColorScheme: specifica la combinazione di colori per una mappa normale e una mappa del rilievo. I valori includono light (predefinito), dark e follow_system, il che significa che utilizza l'impostazione di sistema attuale in base all'impostazione del dispositivo per UI_NIGHT_MODE_MASK. Per ulteriori informazioni, vedi Combinazione di colori della mappa.

Per utilizzare questi attributi personalizzati all'interno del file di layout, è necessario includere la seguente dichiarazione dello spazio dei nomi. Puoi scegliere qualsiasi spazio dei nomi, non deve essere necessariamente map:

xmlns:map="http://schemas.android.com/apk/res-auto"

Potrai quindi aggiungere gli attributi con un prefisso map: al file di layout.

Il seguente file di layout configura un oggetto SupportMapFragment con attributi di mappa personalizzati. Gli stessi attributi possono essere applicati anche a un oggetto 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"/>

Nota: se utilizzi Maps SDK per Android con una licenza per il piano Premium di Google Maps Platform, devi anteporre m4b_ a ogni attributo. Ad esempio, quando specifichi l'attributo tipo di mappa, utilizza m4b_mapType anziché mapType. Quando specifichi i controlli di zoom, utilizza m4b_uiZoomControls anziché uiZoomControls e così via.

Configurare una mappa dopo averla aggiunta in modo dinamico

Questa sezione descrive come impostare lo stato iniziale della mappa se l'hai aggiunta alla tua app in modo dinamico.

Se hai aggiunto SupportMapFragment o MapView in modo dinamico, puoi impostare lo stato iniziale della mappa in un oggetto GoogleMapOptions. Le opzioni disponibili sono le stesse del file di layout. Puoi creare un GoogleMapOptions nel seguente modo:

Kotlin

val options = GoogleMapOptions()

      

Java

GoogleMapOptions options = new GoogleMapOptions();

      

Quindi configurala come segue:

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

      

Per applicare queste opzioni quando crei una mappa, procedi in uno dei seguenti modi:

• Se usi un SupportMapFragment, usa il metodo di fabbrica statico SupportMapFragment.newInstance(GoogleMapOptions options) per costruire il frammento e trasferirlo nelle impostazioni.
• Se usi un MapView, usa il costruttore MapView(Context, GoogleMapOptions) e supera le impostazioni.

Impostare il livello di traffico

Puoi visualizzare i dati sul traffico sulla mappa attivando il livello relativo al traffico. Puoi abilitare e disabilitare il livello di traffico chiamando il metodo setTrafficEnabled() e puoi determinare se il livello di traffico è attualmente attivo chiamando il metodo isTrafficEnabled(). Il seguente screenshot mostra una mappa con il livello di traffico attivato.

Impostare il tipo di mappa

Per impostare il tipo di mappa, chiama il metodo setMapType. Ad esempio, per visualizzare una mappa satellitare:

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

      

L'immagine seguente mette a confronto i tipi di mappe normale, ibrida e del rilievo:

Configurazione di edifici in 3D

Per molte città, viste da vicino, gli edifici in 3D saranno visibili, come puoi vedere nell'immagine di Vancouver in Canada che segue. Puoi disattivare gli edifici in 3D chiamando GoogleMap.setBuildingsEnabled(false).

Configura le impostazioni della mappa di interni

A livelli di zoom elevati, la mappa mostra le planimetrie di spazi interni come aeroporti, centri commerciali, grandi negozi e stazioni di trasporto pubblico. Queste planimetrie, chiamate mappe di interni, vengono visualizzate per i tipi di mappe "normali" e "satellitari" (GoogleMap.MAP_TYPE_NORMAL e GoogleMap.MAP_TYPE_SATELLITE). Vengono attivate automaticamente quando l'utente aumenta lo zoom e spariscono quando diminuisci lo zoom sulla mappa.

Notifica di ritiro: in una versione futura, le mappe di interni saranno disponibili solo per il tipo di mappa normal. A partire da quella versione futura, le mappe di interni non saranno più supportate sulle mappe satellite, terrain o hybrid. Anche se gli ambienti interni non sono supportati, isIndoorEnabled() continuerà a restituire il valore impostato tramite setIndoorEnabled(), come avviene ora. Per impostazione predefinita, il valore di setIndoorEnabled è true. Nelle note di rilascio ti verrà comunicato quando l'assistenza interna non sarà disponibile per questi tipi di mappe.

Ecco un riepilogo della funzionalità delle mappe di interni nell'API:

• Puoi disattivare le mappe di interni chiamando il numero GoogleMap.setIndoorEnabled(false). Le mappe di interni sono attive per impostazione predefinita. Le mappe di interni vengono visualizzate su una mappa alla volta. Per impostazione predefinita, questa è la prima mappa aggiunta alla tua app. Per visualizzare le mappe di interni su una mappa diversa, disattivale sulla prima mappa, poi chiama setIndoorEnabled(true) sulla seconda mappa.
• Per disattivare il selettore dei livelli predefinito (selettore del piano), chiama GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false). Per ulteriori dettagli, consulta la sezione Interazione con la mappa.
• OnIndoorStateChangeListener: definisce i listener che rilevano quando un edificio diventa attivo o un livello è attivato in un edificio. Per maggiori dettagli, consulta la sezione Interazione con la mappa.
• getFocusedBuilding: recupera l'edificio attivo. Potrai quindi trovare il livello attivo chiamando IndoorBuilding.getActiveLevelIndex().
• L'impostazione di uno stile per la mappa base non influisce sulle mappe di interni.

Impostare la spaziatura interna della mappa

Questo video mostra un esempio di spaziatura interna della mappa.

Una mappa Google è progettata per riempire l'intera regione definita dal suo elemento container, in genere MapView o SupportMapFragment. Diversi aspetti dell'aspetto e del comportamento della mappa sono definiti dalle dimensioni del suo contenitore:

• L'obiettivo della videocamera rifletterà il centro dell'area imbottita.
• I controlli mappa sono posizionati rispetto ai bordi della mappa.
• Le informazioni legali, come le dichiarazioni sul copyright o il logo di Google, vengono visualizzate sul bordo inferiore della mappa.

Puoi aggiungere spaziatura interna intorno ai bordi della mappa utilizzando l'GoogleMap.setPadding(). La mappa continuerà a riempire l'intero container, ma il posizionamento di testo e controlli, gesti sulla mappa e movimenti della videocamera si comporteranno come se fosse stato posizionato in uno spazio più piccolo. Questo comporta le seguenti modifiche:

• I movimenti della videocamera tramite chiamate API o pressioni di pulsanti (ad es. bussola, La mia posizione, pulsanti di zoom) sono relativi all'area riempita.
• Il metodo getCameraPosition restituisce il centro della regione riempita.
• I metodi Projection e getVisibleRegion restituiscono la regione riempita.
• I controlli UI sono spostati dal bordo del container del numero di pixel specificato.

La spaziatura interna può essere utile durante la progettazione di UI che si sovrappongono a una parte della mappa. Nell'immagine seguente, la mappa è riempita lungo i bordi superiore e destro. I controlli della mappa e il testo legale visibili verranno visualizzati lungo i bordi dell'area riempita, mostrati in verde, mentre la mappa continuerà a riempire l'intero contenitore, mostrato in blu. In questo esempio, puoi far fluttuare un menu sul lato destro della mappa senza nascondere i controlli.

Nota: in base ai Termini di servizio di Google Maps Platform, la tua applicazione non deve rimuovere o oscurare il logo di Google o le note sul copyright. La spaziatura interna della mappa consente di riposizionare questi elementi, se necessario. Se visualizzi un'interfaccia utente personalizzata nella parte inferiore della mappa, aggiungi una spaziatura interna nella parte inferiore della mappa in modo che il logo e le note legali siano sempre visibili.

Combinazione di colori della mappa

Per le mappe di tipo normale e rilievo, puoi impostare la combinazione di colori della mappa in modo dinamico su scura, chiara oppure utilizzare l'impostazione di sistema corrente. Ad esempio, puoi scurire o schiarire la combinazione di colori della mappa in base all'ora del giorno o all'utilizzo all'interno o all'esterno del dispositivo.

Per impostazione predefinita, la mappa utilizza la modalità Luce. L'attuale valore dell'impostazione di sistema si basa sull'impostazione del dispositivo per 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));

Puoi attivare/disattivare la combinazione di colori utilizzando il metodo GoogleMap.setMapColorScheme() per impostare lo stile corrente in modalità Buio o Luce oppure seguire le impostazioni di sistema.

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

Nota: la combinazione di colori della modalità Buio avrà effetto solo sulle mappe che non utilizzano lo stile delle mappe o che usano la nuova versione della Personalizzazione delle mappe basata su cloud. Le mappe con la Personalizzazione delle mappe basata su cloud legacy o JSON non mostrano la combinazione di colori della modalità Buio.