Configurare una mappa

Seleziona la piattaforma: Android iOS

Questo documento 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 in base al fatto che tu abbia aggiunto il contenitore della mappa (SupportMapFragment o MapView) in modo statico o dinamico. Se il contenitore della mappa è stato aggiunto in modo statico, puoi configurare le impostazioni iniziali della mappa 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 di mappe, consulta Aggiungi una mappa.

Le impostazioni iniziali della mappa includono:

• La posizione della videocamera, tra cui: posizione, zoom, orientamento e inclinazione. Per informazioni dettagliate sul posizionamento della videocamera, consulta Videocamera e visualizzazione.
• Il tipo di mappa.
• I componenti della UI da visualizzare, come i pulsanti di zoom e la bussola.
• I gesti da attivare.
• Se la modalità Lite è attiva.

In fase di runtime puoi configurare queste impostazioni e alcune impostazioni aggiuntive 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 del traffico e la spaziatura interna della mappa.

Esempio

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

Le impostazioni iniziali sono configurate nel file di layout:

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

Le impostazioni di runtime:

• Centra la videocamera su Kyoto, Giappone.
• Attiva il tipo di mappa ibrida.
• 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 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 tramite le seguenti opzioni:

• Creare 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 contenitore della mappa e viene aggiunto in modo statico. Per maggiori dettagli, consulta la guida rapida.

• Configura manualmente il progetto 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.

Configura una mappa dopo averla aggiunta in modo statico

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

Maps SDK for Android definisce un insieme di attributi XML personalizzati per un SupportMapFragment o un MapView che puoi utilizzare per configurare lo stato iniziale della mappa direttamente dal file di layout. 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 videocamera. Per maggiori dettagli, consulta la guida su videocamera e visualizzazioni.

• uiZoomControls, uiCompass: specifica se vengono visualizzati i controlli di zoom e la bussola. Per i dettagli, consulta UiSettings.

• uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures: specifica se determinati gesti sono attivati. Per i dettagli, consulta UiSettings.

• zOrderOnTop: indica se la superficie della visualizzazione mappa viene visualizzata sopra la finestra della mappa, i controlli della mappa e 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 associato alla visualizzazione del frammento o al frammento stesso. Per i dettagli, consulta la documentazione di riferimento.

• liteMode: true per attivare la modalità Lite; in caso contrario, false.

• mapColorScheme: specifica la combinazione di colori per una mappa normale e una mappa del rilievo. I valori includono light, dark e follow_system (predefinito), che indica l'utilizzo dell'impostazione di sistema corrente in base all'impostazione del dispositivo per UI_NIGHT_MODE_MASK. Per saperne di più, consulta Combinazione di colori della mappa.

Per utilizzare questi attributi personalizzati nel file di layout, devi 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"

Puoi quindi aggiungere gli attributi con un prefisso map: nel file di layout.

Il seguente file di layout configura un oggetto SupportMapFragment con attributi della 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 for Android con una licenza del piano Premium di Google Maps Platform, devi anteporre m4b_ a ogni attributo. Ad esempio, quando specifichi l'attributo del tipo di mappa, utilizza m4b_mapType anziché mapType. Quando specifichi i controlli di zoom, utilizza m4b_uiZoomControls anziché uiZoomControls.

Configura una mappa dopo averla aggiunta dinamicamente

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

Se hai aggiunto un SupportMapFragment o un 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();

      

Poi configuralo 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 durante la creazione di una mappa, esegui una delle seguenti operazioni:

• Se utilizzi un SupportMapFragment, utilizza il metodo statico di fabbrica SupportMapFragment.newInstance(GoogleMapOptions options) per creare il frammento e trasmettere le impostazioni.
• Se utilizzi un MapView, utilizza il costruttore MapView(Context, GoogleMapOptions) e trasmetti le impostazioni.

Localizza la mappa

Quando aggiungi un MapView o un SupportMapFragment alla tua app, gli elementi di testo sulla mappa vengono visualizzati nella lingua appropriata in base alle impostazioni del dispositivo e alla posizione dell'utente. Puoi limitare le lingue utilizzate dalla tua app a un sottoinsieme di tutte le lingue supportate aggiungendo un elemento resConfigs al file Gradle. Questo è utile per rimuovere le lingue non utilizzate e ridurre le dimensioni del file binario dell'app. Ad esempio:

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

Scopri di più sulla localizzazione della tua app per Android.

Configura il livello Traffico

Puoi visualizzare i dati sul traffico sulla mappa attivando il livello Traffico. Puoi attivare e disattivare il livello Traffico chiamando il metodo setTrafficEnabled() e puoi determinare se il livello Traffico è attivo chiamando il metodo isTrafficEnabled(). Lo screenshot seguente mostra una mappa con il livello del traffico attivato.

Configura il livello Trasporto pubblico

Puoi visualizzare i dati sul trasporto pubblico sulla mappa attivando il livello Trasporto pubblico. Puoi attivare e disattivare il livello Trasporto pubblico chiamando il metodo setTransitEnabled() e puoi determinare se il livello Trasporto pubblico è attivo chiamando il metodo isTransitEnabled(). Lo screenshot seguente mostra una mappa con il livello Trasporto pubblico abilitato.

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

      

La seguente immagine mette a confronto i tipi di mappa Normale, Ibrida e Rilievo:

Configura gli edifici in 3D

In molte città, se visualizzate da vicino, saranno visibili gli edifici in 3D, come mostrato nell'immagine di Vancouver, in Canada, riportata di seguito. 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 di vendita al dettaglio e stazioni di transito. Queste planimetrie, chiamate mappe di interni, vengono visualizzate per i tipi di mappa "normale" e "satellite" (GoogleMap.MAP_TYPE_NORMAL e GoogleMap.MAP_TYPE_SATELLITE). Vengono attivate automaticamente quando l'utente aumenta lo zoom e scompaiono quando lo zoom viene diminuito.

Avviso di ritiro: in una versione futura, le mappe di interni saranno disponibili solo nel tipo di mappa normal. A partire da questa release futura, le mappe di interni non saranno supportate sulle mappe satellite, terrain o hybrid. Anche se la modalità per interni non è supportata, isIndoorEnabled() continuerà a restituire il valore impostato utilizzando setIndoorEnabled(), come avviene ora. Per impostazione predefinita, setIndoorEnabled è true. Le note di rilascio ti informeranno quando il supporto per interni non sarà più disponibile su questi tipi di mappa.

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

• Puoi disattivare le mappe di interni chiamando GoogleMap.setIndoorEnabled(false). Per impostazione predefinita, le mappe di interni sono attivate. Le mappe di interni vengono visualizzate una 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, quindi chiama setIndoorEnabled(true) sulla seconda mappa.
• Per disattivare il selettore di livello predefinito (selettore di piano), chiama GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false). Per maggiori dettagli, consulta Interagisci con la mappa.
• OnIndoorStateChangeListener: definisce i listener che rilevano quando un edificio viene messo a fuoco o quando viene attivato un livello in un edificio. Per maggiori dettagli, consulta Interagisci con la mappa.
• getFocusedBuilding: recupera l'edificio attivo. Puoi quindi trovare il livello attivo chiamando IndoorBuilding.getActiveLevelIndex().
• La personalizzazione dello stile della mappa base non influisce sulle mappe di interni.

Configura 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 contenitore, in genere un MapView o un SupportMapFragment. Diversi aspetti dell'aspetto e del comportamento della mappa sono definiti dalle dimensioni del suo contenitore:

• Il target della videocamera rifletterà il centro della regione con spaziatura interna.
• I controlli della mappa sono posizionati rispetto ai bordi della mappa.
• Le informazioni legali, come le dichiarazioni sul copyright o il logo Google, vengono visualizzate lungo il bordo inferiore della mappa.

Puoi aggiungere spaziatura interna intorno ai bordi della mappa utilizzando GoogleMap.Metodo setPadding(). La mappa continuerà a riempire l'intero contenitore, ma il posizionamento del testo e dei controlli, i gesti sulla mappa e i movimenti della fotocamera si comporteranno come se fosse stata posizionata in uno spazio più piccolo. Questo comporta le seguenti modifiche:

• I movimenti della fotocamera che utilizzano chiamate API o pressioni di pulsanti (ad es. bussola, la mia posizione, pulsanti di zoom) sono relativi alla regione con spaziatura interna.
• Il metodo getCameraPosition restituisce il centro della regione con spaziatura interna.
• I metodi Projection e getVisibleRegion restituiscono la regione con spaziatura interna.
• I controlli UI sono spostati rispetto al bordo del contenitore del numero di pixel specificato.

La spaziatura interna può essere utile quando si progettano UI che si sovrappongono a una parte della mappa. Nell'immagine seguente, la mappa è spaziatata lungo i bordi superiore e destro. I controlli della mappa visibili e il testo legale verranno visualizzati lungo i bordi della regione con spaziatura interna, mostrata in verde, mentre la mappa continuerà a riempire l'intero contenitore, mostrato in blu. In questo esempio, puoi posizionare un menu sul lato destro della mappa senza oscurare i controlli della mappa.

Nota: ai sensi dei Termini di servizio di Google Maps Platform, l'applicazione non deve rimuovere o oscurare il logo Google o le note sul copyright. La spaziatura interna della mappa ti consente di riposizionare questi elementi, se necessario. Se mostri una UI personalizzata nella parte inferiore della mappa, aggiungi un padding in modo che il logo e le note legali siano sempre visibili.

Combinazione di colori della mappa

Per le mappe di tipo normale e terreno, puoi impostare la combinazione di colori della mappa in modo dinamico su scuro, chiaro o in modo che utilizzi 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 del dispositivo all'interno o all'esterno.

A partire dalla versione 20.1.0 di Maps SDK for Android, la mappa segue l'impostazione di sistema corrente per impostazione predefinita. Nelle versioni precedenti, la mappa utilizza la modalità Luce per impostazione predefinita. Il valore dell'impostazione di sistema corrente 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 sulla modalità Buio, sulla modalità Luce o per 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);

Per creare stili personalizzati per le mappe in modalità Luce e Scura, utilizza la personalizzazione delle mappe basata su cloud.

Nota: la combinazione di colori della modalità Buio verrà applicata solo alle mappe che non utilizzano uno stile personalizzato o che utilizzano la personalizzazione delle mappe basata su cloud. Le mappe con stile JSON o che utilizzano la modalità Lite non mostreranno la combinazione di colori della modalità Buio.

Configura il colore di sfondo

Quando lavori in modalità Buio o passi da una visualizzazione mappa all'altra, può essere utile configurare il colore di sfondo predefinito della mappa. Per farlo, imposta la proprietà backgroundColor delle opzioni della mappa.

Kotlin

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

Java

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

Nota: il colore di sfondo non supporta i valori di opacità.

Puoi anche utilizzare la Personalizzazione delle mappe basata su cloud per configurare il colore di sfondo. Il colore di sfondo impostato nello stile di mappa ha una priorità maggiore rispetto al colore di sfondo locale. Per saperne di più, consulta Modifica il colore di sfondo dell'app per la personalizzazione delle mappe basata su cloud.