Configurare una mappa

Seleziona la piattaforma: Android iOS

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

Panoramica

Screenshot di una mappa di Kyoto con le impostazioni della mappa configurate. Dopo aver aggiunto una mappa all'app, puoi configurarne le impostazioni iniziali e di runtime. Le impostazioni iniziali devono essere configurate in base al fatto che hai 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 della mappa, vedi Aggiungere una mappa.

Le impostazioni iniziali della mappa includono:

In fase di runtime puoi configurare queste impostazioni e alcune altre 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 il spazio interno alla 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:

  • Inquadra Kyoto, in Giappone, al centro dell'inquadratura.
  • 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 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 tramite le seguenti opzioni:

  • Crea un'app utilizzando il modello Maps per Android Studio. Il modello Maps configura automaticamente il progetto e aggiunge una mappa di base. Viene utilizzato un frammento 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.

Configurare 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. Attualmente 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 relativa a videocamere e visualizzazioni.

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

  • uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures: specifica se sono abilitati gesti specifici. Per maggiori dettagli, visita la pagina UiSettings.

  • zOrderOnTop: indica se la superficie della vista mappa viene visualizzata sopra la finestra della mappa, i controlli della mappa e qualsiasi oggetto nella finestra. Per informazioni dettagliate, 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 informazioni dettagliate, visita questa pagina.

  • 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 terreno. I valori includono light (predefinito), dark e follow_system, che indicano di utilizzare l'impostazione di sistema corrente in base all'impostazione del dispositivo per UI_NIGHT_MODE_MASK. Per ulteriori informazioni, consulta la sezione Schema di colori della mappa.

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

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

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

Il seguente file di layout configura un oggetto SupportMapFragment con attributi 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"/>

Configurare una mappa dopo averla aggiunta in modo dinamico

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

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 disponibili nel file di layout. Puoi creare un GoogleMapOptions come segue:

Kotlin

val options = GoogleMapOptions()

Java

GoogleMapOptions options = new GoogleMapOptions();

e configuralo nel seguente modo:

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, svolgi una delle seguenti operazioni:

Localizzare 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 e alla posizione del dispositivo 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. Questa operazione è utile per rimuovere le lingue inutilizzate 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 di traffico

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

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 normali, ibride e del terreno:

Confronto di MapType

Configurare gli edifici in 3D

Molte città, se viste da vicino, avranno edifici in 3D visibili, come si può vedere nella foto di Vancouver, in Canada, riportata di seguito. Puoi disattivare gli edifici in 3D chiamando GoogleMap.setBuildingsEnabled(false).

Una mappa di Vancouver, in Canada

Configurare le impostazioni delle mappe indoor

A livelli di zoom elevati, la mappa mostra i piani di gli spazi interni come aeroporti, centri commerciali, grandi negozi di vendita al dettaglio e stazioni di trasporto pubblico. Queste piante, chiamate mappe indoor, vengono visualizzate per i tipi di mappa "normale" e "satellitare" (GoogleMap.MAP_TYPE_NORMAL e GoogleMap.MAP_TYPE_SATELLITE). Vengono attivate automaticamente quando l'utente aumenta lo zoom e svaniscono quando si riduce lo zoom della mappa.

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

Esempio di mappa di interni

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

Configurare la spaziatura interna della mappa

Questo video mostra un esempio di spaziatura interna della mappa.

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

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

Puoi aggiungere spaziatura attorno 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 fossero stati posizionati in uno spazio più piccolo. Ciò comporta le seguenti modifiche:

  • I movimenti della fotocamera tramite chiamate API o pressioni dei pulsanti (ad es. bussola, la mia posizione, pulsanti 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 dell'interfaccia utente sono spostati dal bordo del contenitore per il numero di pixel specificato.

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

Spaziatura interna della mappa

Combinazione di colori della mappa

Per le mappe di tipo normale e in rilievo, puoi impostare dinamicamente la combinazione di colori della mappa su scura, chiara o 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'uso indoor o outdoor del dispositivo.

Per impostazione predefinita, la mappa utilizza la modalità chiara. 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à scura, sulla modalità chiara o sulle impostazioni del 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);

Configura il colore di sfondo

Quando lavori in modalità scura o passi da una visualizzazione della mappa all'altra, può essere utile configurare il colore di sfondo predefinito della mappa. Questo risultato può essere ottenuto impostando la proprietà backgroundColor opzioni 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));

Puoi anche utilizzare la personalizzazione delle mappe basata su cloud per configurare il colore di sfondo. Il colore di sfondo impostato nello stile delle mappe ha una priorità maggiore rispetto al colore di sfondo locale. Per ulteriori informazioni, vedi Modificare il colore dello sfondo dell'app per lo stile delle mappe basate su cloud.