Hiển thị tuyến đường trên bản đồ 3D

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Bạn có thể tính toán và kết xuất tuyến đường trên một phần tử <gmp-map-3d> theo hai cách:

  • Khai báo bằng Route3DElement (<gmp-route-3d>): Thêm một thành phần web yêu cầu chỉ đường từ Routes API và kết xuất hình nhiều đường 3D của tuyến đường, điểm đánh dấu điểm xuất phát và điểm đến, cũng như cửa sổ bật lên tóm tắt tuyến đường.
  • Theo cách có lập trình bằng các phương thức trợ giúp Route: Gọi Route.computeRoutes rồi truyền tuyến đường đến create3DPolylines, createWaypointMarkers và createPopover khi bạn cần điểm tham chiếu trung gian, mặt nạ trường tuỳ chỉnh hoặc kiểu hình nhiều đường tuỳ chỉnh.

Cả hai phương pháp đều có trong kênh v=beta của Maps JavaScript API. Để biết hướng dẫn về cách tải kênh thử nghiệm beta, hãy xem phần Tạo phiên bản.

Điều kiện tiên quyết và thanh toán

Trước khi hiển thị tuyến đường 3D, hãy thiết lập dự án trên đám mây của Google Cloud và bật cả Maps JavaScript API và Routes API cho dự án đó. Tải cả thư viện maps3d và routes.

Tính năng kết xuất <gmp-map-3d> được tính phí theo Bản đồ 3D động (Immersive Maps Pro). Mỗi yêu cầu về tuyến đường do <gmp-route-3d> hoặc Route.computeRoutes thực hiện đều được tính phí theo SKU Compute Routes của Routes API dựa trên các tính năng được yêu cầu:

Cấu hình Cấp SKU của Routes
Yêu cầu về tuyến đường mặc định (TRAFFIC_UNAWARE hoặc WALKING, BICYCLING và TRANSIT phương thức di chuyển không có hình nhiều đường về tình hình giao thông) Compute Routes Essentials
routing-preference được đặt thành traffic-aware hoặc traffic-aware-optimal có bật traffic-polylines-disabled Compute Routes Pro
routing-preference được đặt thành traffic-aware hoặc traffic-aware-optimal khi bật hình nhiều đường có màu sắc thể hiện tình trạng giao thông (mặc định khi đặt lựa chọn ưu tiên nhận biết tình trạng giao thông) Compute Routes Enterprise

Để biết thông tin chi tiết về SKU, hãy xem bài viết Mức sử dụng và thông tin thanh toán của Maps JavaScript API.

Thêm tuyến đường 3D bằng HTML

Để hiển thị tuyến đường giữa điểm xuất phát và điểm đến bằng mã tối thiểu, hãy lồng <gmp-route-3d> vào bên trong <gmp-map-3d> và thêm autofits-camera để bản đồ tự động định khung tuyến đường:

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

Thay thế YOUR_API_KEY bằng khoá API Google Maps Platform của bạn.

Route3DElement tự động so khớp màu của hình nhiều đường và cửa sổ bật lên tóm tắt với bảng phối màu sáng hoặc tối của <gmp-map-3d> mẹ, đồng thời hỗ trợ các thuộc tính sau:

  • origin và destination: Chấp nhận một chuỗi toạ độ "lat,lng", tên tài nguyên địa điểm như "places/ChIJ-bfVTh8VkFQRDZLQnmioK9s" hoặc chuỗi địa chỉ. Trong JavaScript, các thuộc tính này cũng chấp nhận các đối tượng LatLng, LatLngLiteral, LatLngAltitude, LatLngAltitudeLiteral và Place.
  • travel-mode (travelMode): Chấp nhận driving (mặc định), walking, bicycling hoặc transit (hiển thị các đoạn đường đi bộ và phương tiện công cộng đa phương thức).
  • routing-preference (routingPreference): Chấp nhận traffic-unaware, traffic-aware hoặc traffic-aware-optimal.
  • traffic-polylines-disabled (trafficPolylinesDisabled): Tắt tính năng tô màu hình nhiều đường theo tốc độ giao thông trên các tuyến đường có thông tin giao thông để yêu cầu được tính phí theo Compute Routes Pro thay vì Compute Routes Enterprise.
  • departure-time (departureTime): Chấp nhận chuỗi dấu thời gian ISO 8601 trong HTML, chẳng hạn như "2027-03-15T16:00:00Z" hoặc đối tượng Date trong JavaScript.
  • autofits-camera (autofitsCamera): Đóng khung tuyến đường đã tải trong khung nhìn <gmp-map-3d>.

Xử lý sự kiện về tuyến đường và đọc dữ liệu về tuyến đường

Route3DElement gửi gmp-load khi một tuyến đường hoàn tất quá trình kết xuất và gmp-error nếu quá trình tính toán tuyến đường không thành công hoặc không trả về tuyến đường nào. Sau khi gmp-load kích hoạt, bạn có thể đọc các thuộc tính routes, fallbackInfo và geocodingResults đã tính toán:

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.');
});

Trường hợp nên sử dụng các phương thức trợ giúp của Route thay vì gmp-route-3d

<gmp-route-3d> hiển thị tuyến đường chính giữa một origin và destination bằng kiểu điểm đánh dấu và hình nhiều đường mặc định. Sử dụng Route.computeRoutes với các phương thức trợ giúp 3D khi bạn cần điểm tham chiếu trung gian, lựa chọn tuyến đường thay thế, mặt nạ trường phản hồi tuỳ chỉnh hoặc kiểu điểm đánh dấu và hình nhiều đường tuỳ chỉnh.

Tuỳ chỉnh kết xuất tuyến đường 3D bằng lớp Route

Đối với quy trình công việc tuỳ chỉnh của tuyến đường 3D, hãy gọi Route.computeRoutes và kết xuất thực thể Route được trả về vào <gmp-map-3d> bằng các phương thức trợ giúp 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>

Thay thế YOUR_API_KEY bằng khoá API Google Maps Platform của bạn.

Thêm các trường bắt buộc trong ComputeRoutesRequest.fields cho mỗi phương thức trợ giúp mà bạn gọi:

  • create3DPolylines: Yêu cầu 'path' hoặc 'legs' cho hình nhiều đường tiêu chuẩn, 'path' và 'legs' khi travelMode là 'TRANSIT' hoặc 'speedPaths' có extraComputations: ['TRAFFIC_ON_POLYLINE'] cho hình nhiều đường có màu sắc thể hiện tình trạng giao thông. Truyền RoutePolyline3DOptions để tuỳ chỉnh polylineOptions hoặc đặt trafficPolylinesDisabled.
  • createWaypointMarkers: Yêu cầu 'path' trong fields. Tạo điểm đánh dấu điểm xuất phát và điểm đến (Marker3DElement theo mặc định hoặc MarkerElement, MarkerInteractiveElement hoặc Marker3DInteractiveElement khi được chỉ định bằng markerClass trong CreateWaypointMarkersOptions). Phương thức này không tạo điểm tham chiếu trung gian.
  • createPopover: Yêu cầu 'path' và 'localizedValues' (cộng với 'legs' cho các tuyến phương tiện công cộng) để neo một bản tóm tắt PopoverElement ở giữa đường đi của tuyến đường.

Các bước tiếp theo