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 all'app, puoi configurarne le impostazioni iniziali e di runtime. Le impostazioni iniziali devono essere configurate a seconda che hai aggiunto il contenitore della mappa (SupportMapFragment oppure MapView) in modo statico o dinamico. Se il container mappa era 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:

• La posizione della fotocamera, inclusi posizione, zoom, orientamento e inclinazione. Per informazioni dettagliate sul posizionamento della videocamera, vedi Videocamera e visualizzazione.
• Il tipo di mappa.
• I componenti dell'interfaccia utente da visualizzare, ad esempio i pulsanti di zoom e la bussola.
• I gesti da attivare.
• Indica se la modalità Lite è attiva.

In fase di runtime, puoi configurare queste impostazioni e altre impostazioni aggiuntive aggiornare l'oggetto GoogleMap in onMapReady di Google. Le impostazioni aggiuntive vengono configurate tramite i metodi GoogleMap, ad esempio quelle che configurano livello di traffico e spaziatura della mappa.

Esempio

Nel codice di esempio riportato di seguito e nello screenshot riportato sopra, la mappa è configurato 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.

Le impostazioni di runtime:

• Centra la fotocamera su Kyoto, Giappone.
• Abilita il tipo di mappa ibrido.
• 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 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 guida rapida.

• Configura il progetto manualmente per l'SDK e aggiungi una mappa di base. In questo modo puoi utilizzare qualsiasi modello Android e aggiungere mappano 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 MapView che puoi utilizzare per configurare l'iniziale lo stato della mappa direttamente dal file di layout. I seguenti attributi attualmente definiti:

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

• cameraTargetLat, cameraTargetLng, cameraZoom e cameraBearing cameraTilt: posizione iniziale della fotocamera. 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 - Consente di specificare se attivare o meno gesti specifici. Consulta: UiSettings per i dettagli.

• 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 legato alla vista del frammento o il 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 rilievo. I valori includono light (valore predefinito), dark e follow_system, il che significa che utilizzano impostazione di sistema attuale 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 necessariamente map:

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

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

Il seguente file di layout configura un oggetto SupportMapFragment con impostazioni degli attributi della mappa. 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:

val options = GoogleMapOptions()

      

GoogleMapOptions options = new GoogleMapOptions();

      

Quindi configurala come segue:

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

• Se usi SupportMapFragment, usa SupportMapFragment.newInstance(GoogleMapOptions options) metodo statico di fabbrica per costruire il frammento e trasmetterlo nelle impostazioni.
• Se utilizzi un MapView, usa il costruttore MapView(Context, GoogleMapOptions) e passa 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 e alla posizione del dispositivo dell'utente. Puoi limitare le lingue utilizzate dalla tua app a un un sottoinsieme di tutte le lingue supportate aggiungendo un elemento resConfigs a 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"
}

Leggi ulteriori informazioni sulla localizzazione delle 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:

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

      

L'immagine seguente mette a confronto i tipi di mappe normali, ibride e del terreno:

Configurare gli edifici in 3D

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

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. Da lì nella prossima release, le mappe di interni non saranno supportate su satellite, terrain o hybrid mappe. 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.

Ecco un riepilogo della 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 indoor vengono visualizzate su una mappa alla volta. Per impostazione predefinita, si tratta della prima mappa aggiunta all'app. Per visualizzare le mappe indoor su un'altra mappa, 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 ulteriori dettagli, consulta la sezione Interazione con la mappa.
• OnIndoorStateChangeListener: definisce i listener che che rilevano quando un edificio viene messo a fuoco o un livello viene attivato in un edificio. Per maggiori dettagli, consulta Interagire con la mappa.
• getFocusedBuilding: recupera l'edificio in primo piano. Puoi quindi trovare il livello attivo chiamando IndoorBuilding.getActiveLevelIndex().
• Lo stile della mappa di base non influisce sulle mappe indoor.

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 suo container , in genere un 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 dell'area imbottita.
• I controlli mappa sono posizionati rispetto ai bordi mappa.
• Le informazioni legali, come le dichiarazioni sul copyright o il logo di Google, vengono visualizzate sul bordo inferiore della mappa.

Puoi aggiungere spaziatura attorno ai bordi della mappa utilizzando GoogleMap.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. Questo comporta le seguenti modifiche:

• Movimenti della videocamera tramite chiamate API o pressioni di pulsanti (ad es. bussola, posizione, pulsanti di zoom) sono relativi all'area riempita.
• 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 è rifinita 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, potresti far fluttuare una menu sul lato destro della mappa senza nascondere i controlli.

Combinazione di colori della mappa

Per mappe di tipo normale e rilievo, puoi impostare la combinazione di colori della mappa in modo dinamico a scuro, chiaro o per usare 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à Luce. Il valore attuale dell'impostazione di sistema si basa nell'impostazione del dispositivo per UI_NIGHT_MODE_MASK.

mapFragment = SupportMapFragment.newInstance(GoogleMapOptions().mapColorScheme(MapColorScheme.DARK).mapId(mapId2))

mapFragment = SupportMapFragment.newInstance(new GoogleMapOptions().mapColorScheme(MapColorScheme.DARK).mapId(mapId2));

Puoi attivare/disattivare la combinazione di colori utilizzando GoogleMap.setMapColorScheme() per impostare lo stile corrente in modalità Buio, modalità Luce o seguire il sistema impostazioni.

googleMap.setMapColorScheme(MapColorScheme.DARK)
googleMap.setMapColorScheme(MapColorScheme.LIGHT)
googleMap.setMapColorScheme(MapColorScheme.FOLLOW_SYSTEM)

googleMap.setMapColorScheme(MapColorScheme.DARK);
googleMap.setMapColorScheme(MapColorScheme.LIGHT);
googleMap.setMapColorScheme(MapColorScheme.FOLLOW_SYSTEM);

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. A questo scopo, imposta proprietà backgroundColor delle opzioni della mappa.

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

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, consulta Modificare il colore sfondo dell'app per lo stile delle mappe basato su cloud.