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ọiRoute.computeRoutesrồi truyền tuyến đường đếncreate3DPolylines,createWaypointMarkersvàcreatePopoverkhi 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:
originvà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ượngLatLng,LatLngLiteral,LatLngAltitude,LatLngAltitudeLiteralvàPlace.travel-mode(travelMode): Chấp nhậndriving(mặc định),walking,bicyclinghoặctransit(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ậntraffic-unaware,traffic-awarehoặctraffic-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ượngDatetrong 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'khitravelModelà'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ềnRoutePolyline3DOptionsđể tuỳ chỉnhpolylineOptionshoặc đặttrafficPolylinesDisabled.createWaypointMarkers: Yêu cầu'path'trongfields. Tạo điểm đánh dấu điểm xuất phát và điểm đến (Marker3DElementtheo mặc định hoặcMarkerElement,MarkerInteractiveElementhoặcMarker3DInteractiveElementkhi được chỉ định bằngmarkerClasstrongCreateWaypointMarkersOptions). 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ắtPopoverElementở giữa đường đi của tuyến đường.
Các bước tiếp theo
- Tự động điều chỉnh camera cho vừa với các thành phần trên bản đồ
- Tổng quan về lớp tuyến đường
- Cửa sổ bật lên