Visualizza i percorsi su una mappa 3D

Sviluppatori dello Spazio economico europeo (SEE)

Puoi calcolare ed eseguire il rendering dei percorsi su un elemento <gmp-map-3d> in due modi:

  • In modo dichiarativo con Route3DElement (<gmp-route-3d>): aggiungi un componente web che richiede le indicazioni stradali dall'API Routes ed esegue il rendering di polilinee del percorso in 3D, indicatori di origine e destinazione e un popover di riepilogo del percorso.
  • In modo programmatico con i metodi helper Route: chiama Route.computeRoutes e passa il percorso a create3DPolylines, createWaypointMarkers e createPopover quando hai bisogno di waypoint intermedi, maschere di campi personalizzate o stili di polilinee personalizzati.

Entrambi gli approcci sono disponibili nel canale v=beta dell'API Maps JavaScript. Per istruzioni su come caricare il canale beta, consulta Controllo delle versioni.

Prerequisiti e fatturazione

Prima di visualizzare i percorsi 3D, configura il tuo progetto Google Cloud e abilita sia l'API Maps JavaScript sia l'API Routes per quel progetto. Carica sia la libreria maps3d sia la libreria routes.

Il rendering di <gmp-map-3d> viene fatturato in base a Dynamic 3D Maps (Immersive Maps Pro). Ogni richiesta di percorso effettuata da <gmp-route-3d> o Route.computeRoutes viene fatturata con uno SKU Compute Routes dell'API Routes in base alle funzionalità richieste:

Configurazione Livello SKU Routes
Richieste di percorsi predefiniti (TRAFFIC_UNAWARE o modalità di viaggio WALKING, BICYCLING e TRANSIT senza polilinee del traffico) Compute Routes Essentials
routing-preference impostato su traffic-aware o traffic-aware-optimal con traffic-polylines-disabled abilitato Compute Routes Pro
routing-preference impostato su traffic-aware o traffic-aware-optimal con polilinee colorate in base al traffico attivate (impostazione predefinita quando è impostata una preferenza che tiene conto del traffico) Compute Routes Enterprise

Per i dettagli sugli SKU, consulta Utilizzo e fatturazione dell'API Maps JavaScript.

Aggiungi un percorso 3D utilizzando HTML

Per visualizzare un percorso tra un'origine e una destinazione con un codice minimo, nidifica <gmp-route-3d> all'interno di <gmp-map-3d> e aggiungi autofits-camera in modo che la mappa inquadri automaticamente il percorso:

<gmp-map-3d
  style="height: 400px; width: 100%;"
  mode="hybrid">
  <gmp-route-3d
    origin="Space Needle, Seattle, WA"
    destination="Tacoma Dome, Tacoma, WA"
    travel-mode="driving"
    routing-preference="traffic-aware"
    autofits-camera>
  </gmp-route-3d>
</gmp-map-3d>

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&libraries=maps3d,routes">
</script>

Sostituisci YOUR_API_KEY con la tua chiave API Google Maps Platform.

Route3DElement abbina automaticamente i colori della polilinea e del popover di riepilogo alla combinazione di colori chiari o scuri dell'elemento <gmp-map-3d> principale e supporta i seguenti attributi e proprietà:

  • origin e destination: accettano una stringa di coordinate "lat,lng", un nome della risorsa di un luogo come "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s" o una stringa di indirizzo. In JavaScript, queste proprietà accettano anche gli oggetti LatLng, LatLngLiteral, LatLngAltitude, LatLngAltitudeLiteral e Place.
  • travel-mode (travelMode): accetta driving (predefinito), walking, bicycling o transit (esegue il rendering di segmenti di linee di trasporto pubblico e a piedi multimodali).
  • routing-preference (routingPreference): accetta traffic-unaware, traffic-aware o traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled): disattiva la colorazione della polilinea in base alla velocità del traffico sui percorsi sensibili al traffico, in modo che la richiesta venga fatturata in base a Compute Routes Pro anziché a Compute Routes Enterprise.
  • departure-time (departureTime): accetta una stringa di timestamp ISO 8601 in HTML, ad esempio "2027-03-15T16:00:00Z", o un oggetto Date in JavaScript.
  • autofits-camera (autofitsCamera): inquadra il percorso caricato all'interno dell'area visibile <gmp-map-3d>.

Gestisci gli eventi del percorso e leggi i dati del percorso

Route3DElement invia gmp-load quando un percorso termina il rendering e gmp-error se il calcolo del percorso non va a buon fine o restituisce zero percorsi. Dopo l'attivazione di gmp-load, puoi leggere le proprietà calcolate routes, fallbackInfo e geocodingResults:

const routeElement = document.querySelector('gmp-route-3d');

routeElement.addEventListener('gmp-load', () => {
  const primaryRoute = routeElement.routes?.[0];
  console.log('Distance (m):', primaryRoute?.distanceMeters);
  console.log('Duration:', primaryRoute?.localizedValues?.duration);
});

routeElement.addEventListener('gmp-error', () => {
  console.error('Failed to load the 3D route.');
});

Quando utilizzare i metodi helper di Route anziché gmp-route-3d

<gmp-route-3d> esegue il rendering del percorso principale tra un singolo origin e destination con lo stile predefinito di indicatori e polilinee. Utilizza Route.computeRoutes con i metodi helper 3D quando hai bisogno di waypoint intermedi, selezione di percorsi alternativi, maschere di campi di risposta personalizzati o stili di polilinee e indicatori personalizzati.

Personalizza il rendering del percorso 3D con la classe Route

Per i workflow di percorsi 3D personalizzati, chiama Route.computeRoutes ed esegui il rendering dell'istanza Route restituita su <gmp-map-3d> utilizzando i relativi metodi helper 3D:

<div id="map-container" style="height: 400px; width: 100%;"></div>

<script>
  async function initMap() {
    const { Map3DElement, MapMode } =
      await google.maps.importLibrary('maps3d');
    const { Route } = await google.maps.importLibrary('routes');

    const map = new Map3DElement({
      mode: MapMode.HYBRID,
    });
    document.getElementById('map-container').append(map);

    const { routes } = await Route.computeRoutes({
      origin: '1800 Amphibious Blvd., Mountain View, CA 94045',
      destination: 'San Francisco Ferry Building, San Francisco, CA',
      travelMode: 'DRIVING',
      routingPreference: 'TRAFFIC_AWARE',
      extraComputations: ['TRAFFIC_ON_POLYLINE'],
      fields: ['path', 'speedPaths', 'localizedValues'],
    });

    const route = routes?.[0];
    if (!route) return;

    const [polylines, markers, popover] = await Promise.all([
      route.create3DPolylines({
        polylineOptions: {
          strokeWidth: 10,
          autofitsCamera: true,
        },
      }),
      route.createWaypointMarkers(),
      route.createPopover(),
    ]);

    map.append(...polylines, ...markers, popover);
  }
</script>
<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&loading=async&callback=initMap">
</script>

Sostituisci YOUR_API_KEY con la tua chiave API Google Maps Platform.

Includi i campi obbligatori in ComputeRoutesRequest.fields per ogni metodo helper che chiami:

  • create3DPolylines: richiedi 'path' o 'legs' per le polilinee standard, 'path' e 'legs' quando travelMode è 'TRANSIT' o 'speedPaths' con extraComputations: ['TRAFFIC_ON_POLYLINE'] per le polilinee colorate in base al traffico. Passa RoutePolyline3DOptions per personalizzare polylineOptions o impostare trafficPolylinesDisabled.
  • createWaypointMarkers: richiedi 'path' in fields. Crea indicatori di origine e destinazione (Marker3DElement per impostazione predefinita o MarkerElement, MarkerInteractiveElement o Marker3DInteractiveElement se specificati con markerClass in CreateWaypointMarkersOptions). I waypoint intermedi non vengono generati da questo metodo.
  • createPopover: richiedi 'path' e 'localizedValues' (più 'legs' per i percorsi con il trasporto pubblico) per ancorare un riepilogo PopoverElement a metà del percorso.

Passaggi successivi