Funzionalità della mappa vettoriale

Visualizza esempio

L'API Maps JavaScript offre due diverse implementazioni della mappa: raster e vettoriale. La mappa raster viene caricata come una griglia di riquadri di immagini raster basati su pixel, che vengono generati lato server da Google Maps Platform e poi pubblicati nella tua app web. La mappa vettoriale è composta da riquadri basati su vettori, che vengono disegnati al momento del caricamento lato client utilizzando WebGL, una tecnologia web che consente al browser di accedere alla GPU sul dispositivo dell'utente per eseguire il rendering di grafica 2D e 3D.

La mappa vettoriale è la stessa mappa di Google che gli utenti conoscono e offre una serie di vantaggi rispetto alla mappa di riquadri raster predefinita, in particolare la nitidezza delle immagini vettoriali e l'aggiunta di edifici 3D a livelli di zoom elevati. La mappa vettoriale supporta le seguenti funzionalità:

• Controllo programmatico dell'inclinazione e dell'orientamento
• Controllo avanzato della videocamera
• Zoom frazionario per uno zoom più fluido

• Contenuti e animazioni 3D

• Per le mappe caricate utilizzando un elemento div e JavaScript, il tipo di rendering predefinito è google.maps.RenderingType.RASTER.

• Per le mappe caricate utilizzando l'elemento gmp-map, il tipo di rendering predefinito è google.maps.RenderingType.VECTOR, con il controllo dell'inclinazione e dell'orientamento abilitato.

Guida introduttiva alle mappe vettoriali

Inclinazione e rotazione

Puoi impostare l'inclinazione e la rotazione (heading) sulla mappa vettoriale includendo le proprietà heading e tilt durante l'inizializzazione della mappa e chiamando i metodi setTilt e setHeading sulla mappa. L'esempio riportato di seguito aggiunge alla mappa alcuni pulsanti che mostrano l'inclinazione e l'orientamento regolati tramite programmazione in incrementi di 20 gradi.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: {
        lat: 37.7893719,
        lng: -122.3942,
      },
      zoom: 16,
      heading: 320,
      tilt: 47.5,
      mapId: "90f87356969d889c",
    }
  );

  const buttons: [string, string, number, google.maps.ControlPosition][] = [
    ["Rotate Left", "rotate", 20, google.maps.ControlPosition.LEFT_CENTER],
    ["Rotate Right", "rotate", -20, google.maps.ControlPosition.RIGHT_CENTER],
    ["Tilt Down", "tilt", 20, google.maps.ControlPosition.TOP_CENTER],
    ["Tilt Up", "tilt", -20, google.maps.ControlPosition.BOTTOM_CENTER],
  ];

  buttons.forEach(([text, mode, amount, position]) => {
    const controlDiv = document.createElement("div");
    const controlUI = document.createElement("button");

    controlUI.classList.add("ui-button");
    controlUI.innerText = `${text}`;
    controlUI.addEventListener("click", () => {
      adjustMap(mode, amount);
    });
    controlDiv.appendChild(controlUI);
    map.controls[position].push(controlDiv);
  });

  const adjustMap = function (mode: string, amount: number) {
    switch (mode) {
      case "tilt":
        map.setTilt(map.getTilt()! + amount);
        break;
      case "rotate":
        map.setHeading(map.getHeading()! + amount);
        break;
      default:
        break;
    }
  };
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: {
      lat: 37.7893719,
      lng: -122.3942,
    },
    zoom: 16,
    heading: 320,
    tilt: 47.5,
    mapId: "90f87356969d889c",
  });
  const buttons = [
    ["Rotate Left", "rotate", 20, google.maps.ControlPosition.LEFT_CENTER],
    ["Rotate Right", "rotate", -20, google.maps.ControlPosition.RIGHT_CENTER],
    ["Tilt Down", "tilt", 20, google.maps.ControlPosition.TOP_CENTER],
    ["Tilt Up", "tilt", -20, google.maps.ControlPosition.BOTTOM_CENTER],
  ];

  buttons.forEach(([text, mode, amount, position]) => {
    const controlDiv = document.createElement("div");
    const controlUI = document.createElement("button");

    controlUI.classList.add("ui-button");
    controlUI.innerText = `${text}`;
    controlUI.addEventListener("click", () => {
      adjustMap(mode, amount);
    });
    controlDiv.appendChild(controlUI);
    map.controls[position].push(controlDiv);
  });

  const adjustMap = function (mode, amount) {
    switch (mode) {
      case "tilt":
        map.setTilt(map.getTilt() + amount);
        break;
      case "rotate":
        map.setHeading(map.getHeading() + amount);
        break;
      default:
        break;
    }
  };
}

window.initMap = initMap;
index.js

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

.ui-button {
  background-color: #fff;
  border: 0;
  border-radius: 2px;
  box-shadow: 0 1px 4px -1px rgba(0, 0, 0, 0.3);
  margin: 10px;
  padding: 0 0.5em;
  font: 400 18px Roboto, Arial, sans-serif;
  overflow: hidden;
  height: 40px;
  cursor: pointer;
}
.ui-button:hover {
  background: rgb(235, 235, 235);
}
style.css

<html>
  <head>
    <title>Tilt and Rotation</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Usare i gesti del mouse e della tastiera

Se sono state attivate le interazioni utente per l'inclinazione e la rotazione (heading) (in modo programmatico o nella console Google Cloud), gli utenti possono regolare l'inclinazione e la rotazione utilizzando il mouse e la tastiera:

• Con il mouse, tieni premuto il tasto Maiusc, quindi fai clic e trascina il mouse su e giù per regolare l'inclinazione e a destra e a sinistra per regolare la direzione.
• Utilizzando la tastiera, tieni premuto il tasto Maiusc, quindi utilizza i tasti Freccia su e Freccia giù per regolare l'inclinazione e i tasti Freccia destra e Freccia sinistra per regolare l'orientamento.

Regolare l'inclinazione e l'orientamento in modo programmatico

Utilizza i metodi setTilt() e setHeading() per regolare in modo programmatico l'inclinazione e l'orientamento su una mappa vettoriale. L'orientamento indica la direzione in cui è rivolta la videocamera in gradi antiorario a partire da nord, quindi map.setHeading(90) ruota la mappa in modo che l'est sia rivolto verso l'alto. L'angolo di inclinazione viene misurato dal zenit, quindi map.setTilt(0) guarda verso il basso, mentre map.setTilt(45) produrrà una vista obliqua.

• Chiama setTilt() per impostare l'angolo di inclinazione della mappa. Utilizza getTilt() per ottenere il valore dell'inclinazione corrente.
• Chiama setHeading() per impostare l'intestazione della mappa. Utilizza getHeading() per ottenere il valore dell'intestazione corrente.

Per modificare il centro della mappa mantenendo l'inclinazione e la direzione, usa map.setCenter() o map.panBy().

Tieni presente che l'intervallo di angolazioni che può essere utilizzato varia in base al livello di zoom corrente. I valori che non rientrano in questo intervallo verranno bloccati all'intervallo attualmente consentito.

Puoi anche utilizzare il metodo moveCamera per modificare in modo programmatico orientamento, inclinazione, centratura e zoom. Scopri di più.

Impatto su altri metodi

Quando l'inclinazione o la rotazione viene applicata alla mappa, il comportamento di altri metodi dell'API Maps JavaScript viene modificato:

• map.getBounds() restituisce sempre la scatola delimitante più piccola che include la regione visibile. Quando viene applicato l'inclinazione, i limiti restituiti possono rappresentare una regione più grande della regione visibile dell'area visibile della mappa.
• map.fitBounds() reimposta l'inclinazione e la direzione su zero prima di adattare i limiti.
• map.panToBounds() reimposta l'inclinazione e la direzione su zero prima di eseguire la panoramica dei limiti.
• map.setTilt() accetta qualsiasi valore, ma limita l'inclinazione massima in base al livello di zoom della mappa corrente.
• map.setHeading() accetta qualsiasi valore e lo modifica in modo che rientri nell'intervallo [0, 360].

Controllare la videocamera

Utilizza la funzione map.moveCamera() per aggiornare contemporaneamente qualsiasi combinazione di proprietà della videocamera. map.moveCamera() accetta un singolo parametro contenente tutte le proprietà della videocamera da aggiornare. L'esempio seguente mostra la chiamata map.moveCamera() per impostare center, zoom, heading e tilt contemporaneamente:

map.moveCamera({
  center: new google.maps.LatLng(37.7893719, -122.3942),
  zoom: 16,
  heading: 320,
  tilt: 47.5
});

Puoi animare le proprietà della videocamera chiamando map.moveCamera() con un loop di animazione, come mostrato di seguito:

const degreesPerSecond = 3;

function animateCamera(time) {
  // Update the heading, leave everything else as-is.
  map.moveCamera({
    heading: (time / 1000) * degreesPerSecond
  });

  requestAnimationFrame(animateCamera);
}

// Start the animation.
requestAnimationFrame(animateCamera);

La posizione della videocamera

La visualizzazione mappa è modellata come una fotocamera che guarda verso il basso su un piano piatto. La posizione della fotocamera (e quindi il rendering della mappa) è specificata dalle seguenti proprietà: target (posizione latitudine/longitudine), bearing, tilt e zoom.

Target (località)

Il target della fotocamera è la posizione del centro della mappa, specificata come coordinate di latitudine e longitudine.

Inclinazione (orientamento)

L'azimut della fotocamera specifica la direzione della bussola, misurata in gradi dal nord vero, corrispondente al bordo superiore della mappa. Se disegni una linea verticale dal centro della mappa al suo bordo superiore, l'azimut corrisponde alla direzione della videocamera (misurata in gradi) rispetto al nord vero.

Un rilevamento pari a 0 indica che la parte superiore della mappa punta a nord vero. Un valore di rilevamento pari a 90 indica che la parte superiore della mappa punta a est (90 gradi su una bussola). Un valore di 180 indica che la parte superiore della mappa punta a sud.

L'API Maps ti consente di modificare l'azimut di una mappa. Ad esempio, chi guida un'auto spesso gira una mappa stradale per allinearla alla direzione di marcia, mentre gli escursionisti che utilizzano una mappa e una bussola di solito la orientano in modo che una linea verticale indichi nord.

Inclinazione (angolo di visualizzazione)

L'inclinazione definisce la posizione della videocamera su un arco direttamente sopra la posizione centrata della mappa, misurata in gradi dal nadir (la direzione che punta direttamente sotto la videocamera). Un valore pari a 0 corrisponde a una fotocamera rivolta direttamente verso il basso. I valori maggiori di 0 corrispondono a una fotocamera inclinata verso l'orizzonte per il numero di gradi specificato. Quando modifichi l'angolo di visualizzazione, la mappa viene visualizzata in prospettiva, con gli elementi lontani che appaiono più piccoli e quelli vicini più grandi. Le seguenti illustrazioni lo dimostrano.

Nelle immagini seguenti, l'angolo di visualizzazione è di 0 gradi. La prima immagine mostra un esquematico di questo; la posizione 1 è la posizione della fotocamera e la posizione 2 è la posizione attuale della mappa. La mappa risultante viene visualizzata sotto.

Nelle immagini seguenti, l'angolo di visualizzazione è di 45 gradi. Tieni presente che la fotocamera si muove a metà di un arco tra la posizione in alto (0 gradi) e il suolo (90 gradi) fino alla posizione 3. La fotocamera è ancora puntata sul punto centrale della mappa, ma ora è visibile l'area rappresentata dalla linea in posizione 4.

La mappa in questo screenshot è ancora centrata sullo stesso punto della mappa originale, ma nella parte superiore sono presenti più elementi. Man mano che aumenti l'angolo oltre i 45 gradi, gli elementi tra la fotocamera e la posizione sulla mappa appaiono proporzionalmente più grandi, mentre gli elementi oltre la posizione sulla mappa appaiono proporzionalmente più piccoli, creando un effetto tridimensionale.

Zoom

Il livello di zoom della fotocamera determina la scala della mappa. Con livelli di zoom più elevati, sullo schermo sono visibili più dettagli, mentre con livelli di zoom più ridotti, sullo schermo è visibile una porzione più ampia del mondo.

Il livello di zoom non deve essere un numero intero. L'intervallo di livelli di zoom consentito dalla mappa dipende da una serie di fattori, tra cui target, tipo di mappa e dimensioni dello schermo. Qualsiasi numero fuori dall'intervallo verrà convertito nel valore valido più vicino successivo, che può essere il livello di zoom minimo o il livello di zoom massimo. L'elenco seguente mostra il livello approssimativo di dettaglio che puoi aspettarti di vedere a ogni livello di zoom:

• 1: Mondo
• 5: massa continentale/continente
• 10: Città
• 15: Strade
• 20: Edifici

Zoom frazionario

Le mappe vettoriali supportano lo zoom frazionario, che ti consente di aumentare lo zoom utilizzando valori frazionari anziché interi. Sebbene sia le mappe raster che quelle vettoriali supportino lo zoom frazionario, quest'ultimo è attivo per impostazione predefinita per le mappe vettoriali e disattivato per le mappe raster. Utilizza l'opzione della mappa isFractionalZoomEnabled per attivare e disattivare lo zoom frazionario.

L'esempio seguente mostra come attivare lo zoom frazionario durante l'inizializzazione della mappa:

map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8,
  isFractionalZoomEnabled: true
});

Puoi anche attivare e disattivare lo zoom frazionario impostando l'opzione mappa isFractionalZoomEnabled come mostrato di seguito:

// Using map.set
map.set('isFractionalZoomEnabled', true);

// Using map.setOptions
map.setOptions({isFractionalZoomEnabled: true});

Puoi impostare un ascoltatore per rilevare se lo zoom frazionario è attivo. Questa funzionalità è più utile se non hai impostato esplicitamente isFractionalZoomEnabled su true o false. Il seguente codice di esempio verifica se lo zoom frazionario è attivo:

map.addListener('isfractionalzoomenabled_changed', () => {
  const isFractionalZoomEnabled = map.get('isFractionalZoomEnabled');
  if (isFractionalZoomEnabled === false) {
    console.log('not using fractional zoom');
  } else if (isFractionalZoomEnabled === true) {
    console.log('using fractional zoom');
  } else {
    console.log('map not done initializing yet');
  }
});