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

Una mappa di Kyoto con le impostazioni della mappa configurate. Dopo aver aggiunto una mappa all'app, puoi configurare le impostazioni iniziali e di runtime della mappa. Le impostazioni iniziali devono essere configurate in base al fatto che il container della mappa (SupportMapFragment o MapView) sia stato aggiunto in modo statico o dinamico. Se il container 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 OnCreate callback con un GoogleMapOptions oggetto.

Per informazioni dettagliate sull'aggiunta di un container della mappa, vedi Aggiungere una mappa.

Le impostazioni iniziali della mappa includono:

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

In fase di runtime puoi configurare queste impostazioni e alcune impostazioni aggiuntive aggiornando l'oggetto GoogleMap nel onMapReady callback. Le impostazioni aggiuntive vengono configurate tramite i metodi della GoogleMap classe, ad esempio quelli che configurano il livello 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, in 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:

  • Crea un'app utilizzando il modello Mappe per Android Studio. Il modello Mappe 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 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 in modo statico 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 relativa a videocamera e visualizzazioni.

  • uiZoomControls, uiCompass: specifica se vengono visualizzati i controlli dello zoom e la bussola. Per maggiori dettagli, vedi UiSettings.

  • uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures: specifica se sono attivati gesti specifici. Per maggiori dettagli, vedi UiSettings.

  • zOrderOnTop : indica se la superficie della visualizzazione della mappa viene visualizzata sopra la finestra della mappa, i controlli della mappa e qualsiasi oggetto nella finestra. Per maggiori dettagli, vedi 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 maggiori 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 terreno. I valori includono light (impostazione predefinita), dark e follow_system, il che significa utilizzare l'impostazione di sistema corrente in base all'impostazione del dispositivo per UI_NIGHT_MODE_MASK. Per maggiori informazioni, vedi 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 il prefisso map: al 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"/>

Configurare una mappa dopo averla aggiunta in modo dinamico

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

Se hai aggiunto un oggetto SupportMapFragment o 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 oggetto GoogleMapOptions nel seguente modo:

Kotlin

val options = GoogleMapOptions()

Java

GoogleMapOptions options = new GoogleMapOptions();

E poi configurarlo 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 quando crei una mappa, procedi in uno dei seguenti modi:

Localizzare la mappa

Quando aggiungi un oggetto MapView o SupportMapFragment all'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 dall'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.

Configurare il livello traffico

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

Livello traffico

Configurare il livello trasporti pubblici

Puoi visualizzare i dati sui trasporti pubblici sulla mappa attivando il livello trasporti pubblici. Puoi attivare e disattivare il livello trasporti pubblici chiamando il setTransitEnabled() metodo e puoi determinare se il livello trasporti pubblici è attivo chiamando il isTransitEnabled() metodo. Lo screenshot seguente mostra una mappa con il livello trasporti pubblici attivato.

Livello di trasporto pubblico

Impostare il tipo di mappa

Per impostare il tipo di mappa, chiama il setMapType metodo. 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 confronta i tipi di mappa normale, ibrida e del terreno:

Un confronto tra i tre tipi di mappe: normale, ibrida e rilievo.

Configurare gli edifici in 3D

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

Mappa di Vancouver, Canada

Configurare le impostazioni delle mappe di interni

A livelli di zoom elevati, la mappa mostra le planimetrie degli spazi interni come aeroporti, centri commerciali, grandi negozi 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 la mappa viene ridotta.

Avviso di ritiro: in una release futura, le mappe di interni saranno disponibili solo per il tipo di mappa normal. A partire da quella release futura, le mappe di interni non saranno supportate sulle mappe satellite, terrain o hybrid. Anche se le mappe di interni non sono supportate, 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 le mappe di interni non sarà più disponibile per questi tipi di mappa.

Una mappa interna di un centro commerciale che mostra le uscite e le sezioni di merce.

Ecco un riepilogo delle funzionalità delle mappe di interni 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 dal relativo elemento container, in genere un oggetto MapView o SupportMapFragment. Diversi aspetti dell'aspetto e del comportamento della mappa sono definiti dalle dimensioni del relativo container:

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

Puoi aggiungere un riempimento intorno ai bordi della mappa utilizzando il metodo GoogleMap.setPadding(). La mappa continuerà a riempire l'intero container, ma il posizionamento del testo e dei controlli, i gesti della mappa e i movimenti della videocamera si comporteranno come se fosse stata posizionata in uno spazio più piccolo. Di conseguenza, si verificano le seguenti modifiche:

  • I movimenti della videocamera che utilizzano chiamate API o pressioni di pulsanti (ad es. bussola, posizione attuale, pulsanti di zoom) sono relativi alla regione con riempimento.
  • Il metodo getCameraPosition restituisce il centro della regione con riempimento.
  • I metodi Projection e getVisibleRegion restituiscono la regione con riempimento.
  • I controlli dell'interfaccia utente sono spostati dal bordo del container del numero di pixel specificato.

Il riempimento può essere utile quando si progettano 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 visibili e il testo legale verranno visualizzati lungo i bordi della regione con riempimento, mostrata in verde, mentre la mappa continuerà a riempire l'intero container, mostrato in blu. In questo esempio, potresti far fluttuare 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 del terreno, puoi impostare dinamicamente la combinazione di colori della mappa su scura, chiara o per 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 del dispositivo all'interno o all'esterno.

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 o disattivare la combinazione di colori utilizzando il GoogleMap.setMapColorScheme() metodo per impostare lo stile corrente sulla modalità scura, sulla modalità chiara 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 chiari e scuri personalizzati per le tue mappe, utilizza la personalizzazione delle mappe basata su cloud.

Configurare il colore di sfondo

Quando lavori in modalità scura o passi da una visualizzazione della mappa all'altra, potrebbe essere utile configurare il colore di sfondo predefinito della mappa. Puoi farlo impostando 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));

Puoi anche utilizzare la personalizzazione delle mappe basata su cloud per configurare il colore di sfondo. Il colore di sfondo impostato negli stili della mappa ha una priorità maggiore rispetto al colore di sfondo locale. Per maggiori informazioni, vedi Modificare il colore di sfondo dell'app per la personalizzazione delle mappe basata su cloud.