Configurare una mappa

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 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 maggiori dettagli sull'aggiunta di un contenitore di mappa, consulta Aggiungere una mappa.

Le impostazioni iniziali della mappa includono:

• La posizione della fotocamera, ad esempio: posizione, zoom, orientamento e inclinazione. Consulta la sezione Fotocamera e vista per maggiori dettagli sul posizionamento della videocamera.
• 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 è attiva la modalità Lite.

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

Esempio

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

Le impostazioni iniziali sono configurate nel file di layout:

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

Le impostazioni di runtime:

• Centra la fotocamera su Kyoto in Giappone.
• Attiva il tipo di mappa ibrida.
• Attiva il livello traffico.

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

    }
}

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 usato come container della mappa e viene aggiunto in modo statico. Per maggiori dettagli, consulta la quickstart.

• Configura il tuo progetto manualmente per l'SDK e aggiungi una mappa di base. In questo modo puoi usare 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. Attualmente sono definiti i seguenti attributi:

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

• cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt: la posizione iniziale della fotocamera. Per maggiori dettagli, consulta la guida Videocamera e visualizzazioni.

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

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

• zOrderOnTop: indica se la superficie della visualizzazione mappa è mostrata sopra la finestra, i controlli mappa e qualsiasi oggetto nella finestra. Per i 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.

Per poter 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 è necessario che sia map:

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

Dopodiché potrai aggiungere al file di layout gli attributi con un prefisso map:.

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: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 alla tua app in modo dinamico.

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

val options = GoogleMapOptions()

      

GoogleMapOptions options = new GoogleMapOptions();

      

Quindi, configurala nel seguente modo:

options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false)

      

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 elemento SupportMapFragment, usa il metodo di fabbrica statico SupportMapFragment.newInstance(GoogleMapOptions options) per creare il frammento e passare alle impostazioni.
• Se usi un MapView, usa il costruttore MapView(Context, GoogleMapOptions) e passa nelle impostazioni.

Configurare il livello di traffico

Puoi visualizzare i dati sul traffico sulla mappa attivando il livello 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:

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

      

La seguente immagine mette a confronto i tipi di mappe normale, ibrida e del terreno:

Configurare edifici in 3D

Molte città, se viste da vicino, mostrano gli edifici in 3D, come puoi vedere nell'immagine di seguito di Vancouver, Canada. Puoi disabilitare 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 degli 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 mappa "normale" e "satellite" (GoogleMap.MAP_TYPE_NORMAL e GoogleMap.MAP_TYPE_SATELLITE). Vengono attivate automaticamente quando l'utente aumenta lo zoom e spariscono con lo zoom ridotto.

Avviso di ritiro: in una release 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 supportate sulle mappe satellite, terrain o hybrid. Anche se la funzionalità per interni non è supportata, isIndoorEnabled() continuerà a restituire il valore impostato tramite setIndoorEnabled(), come avviene ora. Per impostazione predefinita, setIndoorEnabled è true. Le note di rilascio ti informano quando il supporto per interni non è più disponibile su questi tipi di mappa.

Ecco un riepilogo della funzionalità 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 sono 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 del livello predefinito (selettore del piano), chiama GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false). Per maggiori dettagli, consulta la sezione Interazione con la mappa.
• OnIndoorStateChangeListener: definisce i listener che rilevano quando un edificio diventa attivo o quando viene attivato un livello in un edificio. Per maggiori dettagli, consulta la sezione Interazione con la mappa.
• getFocusedBuilding: recupera l'edificio a fuoco. Puoi quindi trovare il livello attivo chiamando il numero IndoorBuilding.getActiveLevelIndex().
• L'applicazione di stili alla mappa base non influisce sulle mappe di interni.

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

• Il target della videocamera rifletterà il centro dell'area coperta.
• I controlli della mappa sono posizionati rispetto ai bordi della mappa.
• Informazioni legali, come dichiarazioni sul copyright o il logo Google, appaiono lungo il bordo inferiore della mappa.

Puoi aggiungere una spaziatura interna intorno ai bordi della mappa utilizzando l'GoogleMap.setPadding(). La mappa continuerà a riempire l'intero container, ma il posizionamento del testo e dei controlli, i gesti sulla mappa e i movimenti della fotocamera si comporteranno come se fossero stati collocati in uno spazio più piccolo. Ciò 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 espansa.
• Il metodo getCameraPosition restituisce il centro dell'area riempita.
• I metodi Projection e getVisibleRegion restituiscono l'area riempita.
• L'offset dei controlli UI dal bordo del container è determinato dal numero specificato di pixel.

La spaziatura interna può essere utile durante la progettazione di interfacce utente che si sovrappongono ad alcune parti della mappa. Nell'immagine seguente, la mappa viene riempita lungo i bordi superiore e destro. I controlli della mappa visibili e il testo legale verranno visualizzati lungo i bordi dell'area espansa, mostrati in verde, mentre la mappa continuerà a riempire l'intero container, mostrato in blu. In questo esempio, potresti far scorrere un menu sul lato destro della mappa senza occultare i controlli.