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 l'iniziale e il runtime le impostazioni della mappa. 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 è stata aggiunta in modo dinamico, puoi configurare le impostazioni iniziali nel OnCreate richiamata con GoogleMapOptions .

Per informazioni dettagliate sull'aggiunta di un contenitore mappa, consulta la sezione 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 vista.
• 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 è abilitata la modalità Lite.

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 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 di Maps per Android Studio. Il modello di 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 sono: none, normal, hybrid, satellite e terrain.

• cameraTargetLat, cameraTargetLng, cameraZoom e cameraBearing cameraTilt: posizione iniziale della fotocamera. Consulta le videocamera e visualizzazioni per maggiori dettagli.

• uiZoomControls, uiCompass: specifica se vengono visualizzati i controlli di zoom e la bussola. Per informazioni dettagliate, 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 visualizzazione mappa è mostrata su parte superiore della finestra della mappa, dei controlli della mappa e di qualsiasi oggetto nella finestra. Consulta SurfaceView.setZOrderOnTop(boolean) per informazioni dettagliate.

• 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; altrimenti false.

• mapColorScheme: specifica la combinazione di colori per una mappa normale e una mappa del terreno. 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, è necessario includi 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 alla tua app in modo dinamico.

Se hai aggiunto un SupportMapFragment o un MapView in modo dinamico, puoi: imposta lo stato iniziale della mappa in un oggetto GoogleMapOptions. La 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 quando crei una mappa, procedi in uno dei seguenti modi:

• Se usi SupportMapFragment, usa SupportMapFragment.newInstance(GoogleMapOptions options) metodo statico di fabbrica per costruire il frammento e trasmetterlo nelle impostazioni.
• Se usi MapView, usa Costruttore MapView(Context, GoogleMapOptions) e passare nelle impostazioni.

Localizza la mappa

Quando aggiungi un elemento MapView o SupportMapFragment alla tua app, gli elementi testuali sulla mappa siano visualizzate nella lingua appropriata in base al dispositivo dell'utente impostazioni e posizione. Puoi limitare le lingue utilizzate dalla tua app a un un sottoinsieme di tutte le lingue supportate aggiungendo un elemento resConfigs a Gradle . Questo è utile per eliminare le lingue inutilizzate e riduce anche le dimensioni binarie 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.

Impostare il livello di traffico

Puoi visualizzare i dati sul traffico sulla mappa attivando il livello relativo al 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 normale, ibrida e del rilievo:

Configurazione di edifici in 3D

Per molte città, se viste da vicino, gli edifici in 3D saranno visibili. nell'immagine di seguito di Vancouver, in Canada. Puoi disattivare gli edifici in 3D chiamata GoogleMap.setBuildingsEnabled(false)

Configura le impostazioni della mappa di interni

A livelli di zoom elevati, la mappa mostra le planimetrie dei piani spazi interni come aeroporti, centri commerciali, grandi negozi e servizi di trasporto pubblico stazioni di servizio. Queste planimetrie, chiamate mappe di interni, vengono mostrate per il "normale" e "satellite" tipi di mappe (GoogleMap.MAP_TYPE_NORMAL e GoogleMap.MAP_TYPE_SATELLITE). Vengono attivate automaticamente quando l'utente aumenta lo zoom e sparisce quando la mappa viene diminuita.

Notifica di ritiro: in una release futura, 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 in ambienti interni supportato, isIndoorEnabled() continuerà a restituire il valore impostato tramite setIndoorEnabled(), come avviene ora. Per impostazione predefinita, setIndoorEnabled è true. La note di rilascio ti consentiranno sai quando l'assistenza interna non è più disponibile su 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) Le mappe di interni sono attive per impostazione predefinita. Le mappe di interni sono visualizzate su una mappa in una 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 maggiori dettagli, consulta 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 che si trova in il focus. Puoi quindi trovare il livello attivo chiamando IndoorBuilding.getActiveLevelIndex().
• Lo Stile della mappa base non influisce sulle mappe di interni.

Impostare 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 dell'area imbottita.
• I controlli mappa sono posizionati rispetto ai bordi mappa.
• Vengono mostrate informazioni legali, ad esempio dichiarazioni sul copyright o il logo Google lungo il bordo inferiore della mappa.

Puoi aggiungere spaziatura interna intorno ai bordi della mappa utilizzando lo GoogleMap.setPadding(). La mappa continuano a riempire l'intero container, ma il posizionamento di testo e controllo, i gesti e i movimenti della videocamera si comporteranno come se fossero per ridurre lo spazio disponibile. 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 dell'area riempita.
• I metodi Projection e getVisibleRegion restituiscono la regione riempita.
• I controlli UI sono spostati dal bordo del container in base al valore di pixel.

La spaziatura interna può essere utile quando si progettano UI che si sovrappongono in parte mappa. Nell'immagine seguente, la mappa è rifinita lungo i bordi superiore e destro. I controlli visibili della mappa e il testo legale verranno visualizzati lungo la i bordi della regione riempita, mostrati in verde, mentre la mappa che riempie l'intero contenitore, indicato 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 il dispositivo può essere usato in ambienti interni o esterni.

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 il metodo GoogleMap.setMapColorScheme() per impostare lo stile corrente sulla modalità Buio, sulla modalità Luce o sulle impostazioni del sistema.

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