Configurare una mappa

Seleziona la piattaforma: Android iOS

Questo argomento descrive come configurare una mappa che è stata aggiunta a un'app per Android utilizzando l'SDK di Maps per 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 di mappa è stato aggiunto in modo statico, puoi configurare le impostazioni 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 ulteriori dettagli sull'aggiunta di un contenitore di mappa, consulta la sezione Aggiungere una mappa.

Le impostazioni iniziali della mappa includono:

• La posizione della fotocamera, ad esempio: posizione, zoom, rilevamento e inclinazione. Per informazioni dettagliate sul posizionamento della videocamera, vedi Videocamera e vista.
• Il tipo di mappa.
• I componenti UI da visualizzare, come i pulsanti di zoom e la bussola.
• I gesti da attivare.
• Indica se la modalità Lite è attiva.

In fase di esecuzione, puoi configurare queste e alcune impostazioni aggiuntive aggiornando l'oggetto GoogleMap nel callback onMapReady. Le impostazioni aggiuntive vengono 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 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 di rotazione dei gesti.
• Imposta l'inclinazione della mappa su 30 gradi.

Le impostazioni di runtime:

• Centra la fotocamera 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 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 tuo 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.

L'SDK di Maps per 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 includono: none, normal, hybrid, satellite e terrain.

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

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

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

• zOrderOnTop: indica se la superficie della visualizzazione mappa è visualizzata sopra la finestra della mappa, i controlli della mappa e qualsiasi altro 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 associato alla visualizzazione del frammento o al frammento stesso. Per ulteriori dettagli, fai clic qui.

• liteMode - true per abilitare la modalità Lite; in caso contrario, false.

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

In seguito, puoi aggiungere gli attributi con un prefisso map: nel 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:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

Nota: se utilizzi l'SDK Maps per Android con una licenza relativa al piano Premium di Google Maps Platform, devi aggiungere il prefisso m4b_ a ciascun attributo. Ad esempio, quando specifichi l'attributo tipo di mappa, utilizza m4b_mapType anziché mapType. Quando specifichi i controlli di zoom, utilizza m4b_uiZoomControls invece di 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 all'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 disponibili nel file di layout. Puoi creare un GoogleMapOptions nel seguente modo:

Java

GoogleMapOptions options = new GoogleMapOptions();

      

Kotlin

val options = GoogleMapOptions()

      

Quindi, configuralo nel seguente modo:

Java

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

      

Kotlin

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

      

Per applicare queste opzioni durante la creazione di una mappa, procedi in uno dei seguenti modi:

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

Configurare il livello di traffico

Attivando il livello di traffico puoi mostrare i dati sul traffico sulla mappa. 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 in cui è attivato il livello traffico.

Imposta il tipo di mappa

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

Java

// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

      

Kotlin

// Sets the map type to be "hybrid"
map.mapType = GoogleMap.MAP_TYPE_HYBRID

      

L'immagine seguente confronta i tipi di mappe normali, ibride e con rilievo:

Configurare edifici 3D

Molte città, se viste da vicino, possono vedere edifici 3D, come visibile nell'immagine di seguito di Vancouver, Canada. Puoi disattivare gli edifici 3D chiamando GoogleMap.setBuildingsEnabled(false).

Configura le impostazioni della mappa di interni

Ad alti livelli di zoom, la mappa mostra le planimetrie di spazi interni come aeroporti, centri commerciali, grandi negozi e stazioni di transito. Le planimetrie, chiamate mappe interne, vengono visualizzate per i tipi di mappa "normali" e "satellitari" (GoogleMap.MAP_TYPE_NORMAL e GoogleMap.MAP_TYPE_SATELLITE). Vengono attivate automaticamente quando l'utente aumenta lo zoom e svaniscono 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 questa versione futura, le mappe di interni non saranno più supportate su satellite, terrain o hybrid. Anche se indoor non è supportato, 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 per questi tipi di mappe.

Ecco un riepilogo della funzionalità di mappatura degli interni nell'API:

• Puoi disattivare le mappe interne chiamando GoogleMap.setIndoorEnabled(false). Per impostazione predefinita, le mappe di interni sono abilitate. Le mappe di interni sono visualizzate su una mappa alla volta. Per impostazione predefinita, si tratta della prima mappa aggiunta alla tua app. Per visualizzare le mappe di interni su un'altra mappa, disattivale sulla prima mappa, quindi chiama setIndoorEnabled(true) sulla seconda mappa.
• Per disattivare il selettore di livelli predefinito (selettore dei piani), chiama GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false). Per ulteriori dettagli, consulta Interazione con la mappa.
• OnIndoorStateChangeListener: definisce i listener che rilevano quando un edificio diventa attivo o viene attivato un livello all'interno di un edificio. Per ulteriori dettagli, consulta Interazione con la mappa.
• getFocusedBuilding: recupera l'edificio attivo. Puoi quindi trovare il livello attivo chiamando IndoorBuilding.getActiveLevelIndex().
• L'applicazione di stili alla mappa base non influisce sulle mappe di interni.

Configura 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 suo elemento contenitore, in genere un elemento 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 imbottita.
• 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 la spaziatura interna intorno ai bordi della mappa utilizzando il GoogleMap.setPadding(). La mappa continuerà a riempire l'intero contenitore, ma il testo e il controllo del posizionamento, dei gesti della mappa e dei movimenti della videocamera si comporteranno come se fossero stati posizionati in uno spazio più piccolo. Questo comporta le seguenti modifiche:

• I movimenti della fotocamera tramite chiamate API o pressioni dei pulsanti (ad es. bussola, posizione, pulsanti di zoom) sono relativi alla regione imbottita.
• Il metodo getCameraPosition restituisce il centro della regione imbottita.
• I metodi Projection e getVisibleRegion restituiscono l'area geografica imbottita.
• I controlli UI sono sfalsati dal bordo del container rispetto al numero specificato di pixel.

La spaziatura interna può essere utile durante la progettazione di interfacce utente 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 dell'area geografica imbottita, mostrata in verde, mentre la mappa continuerà a riempire l'intero contenitore, mostrato in blu. In questo esempio, un menu potrebbe essere visualizzato sul lato destro della mappa senza oscurare i controlli della mappa.

Nota: secondo i Termini di servizio di Google Maps Platform, la tua applicazione non deve rimuovere né oscurare il logo Google o le note sul copyright. La spaziatura interna della mappa consente di riposizionare questi elementi, se necessario. Se visualizzi una UI personalizzata in fondo alla mappa, aggiungi una spaziatura interna in fondo alla mappa, in modo che il logo e le note legali siano sempre visibili.