Wyświetlanie tras na mapie 3D

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Trasy możesz obliczać i renderować w elemencie <gmp-map-3d> na 2 sposoby:

  • Deklaratywnie za pomocą Route3DElement (<gmp-route-3d>): dodaj komponent internetowy, który żąda wskazówek dojazdu z interfejsu Routes API i renderuje linie łamane trasy 3D, znaczniki miejsca początkowego i docelowego oraz wyskakujące okienko z podsumowaniem trasy.
  • Automatycznie za pomocą metod pomocniczych Route: wywołaj metodę Route.computeRoutes i przekaż trasę do metod create3DPolylines, createWaypointMarkers i createPopover, gdy potrzebujesz pośrednich punktów orientacyjnych, niestandardowych masek pól lub niestandardowych stylów linii łamanych.

Oba podejścia są dostępne w kanale v=beta interfejsu Maps JavaScript API. Instrukcje dotyczące wczytywania wersji beta znajdziesz w sekcji Wersje.

Wymagania wstępne i płatności

Zanim wyświetlisz trasy 3D, skonfiguruj projekt Google Cloud i włącz w nim interfejsy Maps JavaScript API i Routes API. Wczytaj biblioteki maps3d i routes.

Renderowanie <gmp-map-3d> jest rozliczane w ramach dynamicznych map 3D (Immersive Maps Pro). Każde żądanie trasy wysłane przez <gmp-route-3d> lub Route.computeRoutes jest rozliczane w ramach kodu SKU Compute Routes interfejsu Routes API na podstawie żądanych funkcji:

Konfiguracja Poziom SKU tras
Domyślne żądania trasy (TRAFFIC_UNAWARE lub WALKING, BICYCLING i TRANSIT, tryby podróży bez linii łamanych natężenia ruchu) Compute Routes Essentials
routing-preference ustawiono na traffic-aware lub traffic-aware-optimal z włączoną opcją traffic-polylines-disabled Compute Routes Pro
routing-preference ustawione na traffic-aware lub traffic-aware-optimal z włączonymi poliliniami w kolorach natężenia ruchu (domyślnie, gdy ustawione jest ustawienie uwzględniające natężenie ruchu) Compute Routes Enterprise

Szczegółowe informacje o kodach SKU znajdziesz w artykule Maps JavaScript API – wykorzystanie i płatności.

Dodawanie trasy 3D za pomocą kodu HTML

Aby wyświetlić trasę między miejscem początkowym a docelowym przy użyciu minimalnej ilości kodu, umieść <gmp-route-3d> wewnątrz <gmp-map-3d> i dodaj autofits-camera, aby mapa automatycznie wykadrowała trasę:

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

Zastąp YOUR_API_KEY kluczem interfejsu API Google Maps Platform.

Route3DElement automatycznie dopasowuje kolory linii łamanej i podsumowania do jasnego lub ciemnego schematu kolorów elementu nadrzędnego <gmp-map-3d> oraz obsługuje te atrybuty i właściwości:

  • origin i destination: akceptują ciąg współrzędnych "lat,lng", nazwę zasobu miejsca, np. "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s", lub ciąg adresu. W języku JavaScript te właściwości akceptują też obiekty LatLng, LatLngLiteral, LatLngAltitude, LatLngAltitudeLiteral i Place.
  • travel-mode (travelMode): akceptuje wartości driving (domyślna), walking, bicycling lub transit (renderuje multimodalne odcinki piesze i odcinki linii transportu publicznego).
  • routing-preference (routingPreference): akceptuje wartości traffic-unaware, traffic-aware lub traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled): wyłącza kolorowanie linii łamanej prędkości ruchu na trasach uwzględniających natężenie ruchu, dzięki czemu żądanie jest rozliczane w ramach Compute Routes Pro, a nie Compute Routes Enterprise.
  • departure-time (departureTime): akceptuje ciąg znaków sygnatury czasowej ISO 8601 w kodzie HTML, np. "2027-03-15T16:00:00Z", lub obiekt Date w kodzie JavaScript.
  • autofits-camera (autofitsCamera): kadruje wczytaną trasę w <gmp-map-3d> widocznym obszarze.

Obsługa zdarzeń związanych z trasą i odczytywanie danych o trasie

Route3DElement wysyła gmp-load, gdy trasa zakończy renderowanie, oraz gmp-error, jeśli obliczanie trasy nie powiedzie się lub nie zwróci żadnych tras. Po wywołaniu zdarzenia gmp-load możesz odczytać obliczone właściwości routes, fallbackInfo i 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.');
});

Kiedy używać metod pomocniczych Route zamiast gmp-route-3d

<gmp-route-3d> renderuje główną trasę między pojedynczymi punktami origin i destination z domyślnym stylem znacznika i linii łamanej. Używaj Route.computeRoutes z metodami pomocniczymi 3D, gdy potrzebujesz pośrednich punktów trasy, wyboru trasy alternatywnej, niestandardowych masek pól odpowiedzi lub niestandardowych stylów linii łamanych i znaczników.

Dostosowywanie renderowania trasy 3D za pomocą klasy Route

W przypadku niestandardowych przepływów pracy dotyczących tras 3D wywołaj Route.computeRoutes i wyrenderuj zwróconą instancję Route na <gmp-map-3d>, korzystając z metod pomocniczych 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>

Zastąp YOUR_API_KEY kluczem interfejsu API Google Maps Platform.

W przypadku każdej wywoływanej metody pomocniczej uwzględnij wymagane pola w parametrze ComputeRoutesRequest.fields:

  • create3DPolylines: poproś o 'path' lub 'legs' w przypadku standardowych linii łamanych, 'path' i 'legs', gdy travelMode to 'TRANSIT', lub 'speedPaths' z extraComputations: ['TRAFFIC_ON_POLYLINE'] w przypadku linii łamanych z kolorami natężenia ruchu. Przekaż RoutePolyline3DOptions, aby dostosować polylineOptions lub ustawić trafficPolylinesDisabled.
  • createWaypointMarkers: poproś o 'path' w fields. Tworzy znaczniki miejsca początkowego i docelowego (domyślnie Marker3DElement lub MarkerElement, MarkerInteractiveElement albo Marker3DInteractiveElement, jeśli określono za pomocą markerClass w CreateWaypointMarkersOptions). Ta metoda nie generuje punktów pośrednich.
  • createPopover: poproś o 'path' i 'localizedValues' (oraz 'legs' w przypadku tras transportu publicznego), aby zakotwiczyć podsumowanie PopoverElement w połowie trasy.

Dalsze kroki