יש שתי דרכים לחשב ולעבד מסלולים ברכיב <gmp-map-3d>:
- באופן הצהרתי באמצעות
Route3DElement(<gmp-route-3d>): מוסיפים רכיב אינטרנט שמבקש מסלולים מ-Routes API ומציג קווים פוליגוניים תלת-ממדיים של מסלולים, סמנים של נקודת המוצא והיעד וחלון קופץ עם סיכום המסלול. - באופן פרוגרמטי באמצעות שיטות עזר של
Route: מפעילים אתRoute.computeRoutesומעבירים את המסלול אלcreate3DPolylines, אלcreateWaypointMarkersואלcreatePopoverכשצריך נקודות דרך, מסכות שדות בהתאמה אישית או סגנונות של קווים פוליגוניים בהתאמה אישית.
שתי הגישות זמינות בערוץ v=beta של Maps JavaScript API. הוראות לטעינת ערוץ הבטא מופיעות במאמר ניהול גרסאות.
דרישות מוקדמות וחיוב
לפני שאתם מציגים מסלולים בתלת-ממד, אתם צריכים להגדיר את הפרויקט ב-Google Cloud ולהפעיל את Maps JavaScript API ואת Routes API בפרויקט הזה. טוענים את הספריות maps3d ו-routes.
העיבוד של <gmp-map-3d> מחויב במסגרת מפות דינמיות בתלת-ממד (Immersive Maps Pro).
כל בקשת מסלול שבוצעה על ידי <gmp-route-3d> או Route.computeRoutes מחויבת במסגרת מק"ט Compute Routes של Routes API, בהתאם לתכונות שהתבקשו:
| הגדרות אישיות | רמת המק"ט של Routes |
|---|---|
בקשות למסלול שמוגדר כברירת מחדל (TRAFFIC_UNAWARE, או
WALKING, BICYCLING, ו-TRANSIT
אמצעי תחבורה ללא קווים פוליגוניים של תנועה)
|
Compute Routes Essentials |
routing-preference מוגדר לערך traffic-aware או traffic-aware-optimal עם traffic-polylines-disabled מופעל
|
Compute Routes Pro |
routing-preference מוגדר לערך traffic-aware או traffic-aware-optimal, והפעלתם קווים פוליגוניים בצבעי תנועה (ברירת המחדל כשמוגדרת העדפה שקשורה לתנועה)
|
Compute Routes Enterprise |
פרטים על המק"טים זמינים במאמר שימוש וחיוב ב-Maps JavaScript API.
הוספת מסלול תלת-ממדי באמצעות HTML
כדי להציג מסלול בין נקודת מוצא לנקודת יעד עם קוד מינימלי, צריך להוסיף את <gmp-route-3d> בתוך <gmp-map-3d> ולהוסיף את autofits-camera כדי שהמפה תציג את המסלול באופן אוטומטי:
<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>
מחליפים את הערך YOUR_API_KEY במפתח ה-API של Google Maps Platform.
הרכיב Route3DElement מתאים באופן אוטומטי את הצבעים של הקו הפוליגוני ושל החלון הקופץ של הסיכום לערכת הצבעים הבהירה או הכהה של רכיב ההורה <gmp-map-3d>, ותומך במאפיינים הבאים:
-
originו-destination: מקבלים מחרוזת קואורדינטות של"lat,lng", שם משאב של מקום כמו"places/ChIJ-bfVTh8VkFQRDZLQnmioK9s"או מחרוזת כתובת. ב-JavaScript, המאפיינים האלה מקבלים גם אובייקטים מסוגLatLng,LatLngLiteral,LatLngAltitude,LatLngAltitudeLiteralו-Place. -
travel-mode(travelMode): מקבל את הערכיםdriving(ברירת המחדל),walking,bicyclingאוtransit(מציג קטעי קווים של הליכה ושל תחבורה ציבורית). -
routing-preference(routingPreference): מקבל את הערכיםtraffic-unaware,traffic-awareאוtraffic-aware-optimal. -
traffic-polylines-disabled(trafficPolylinesDisabled): משבית את הצביעה של קווים פוליגוניים לפי מהירות התנועה במסלולים עם מידע על מצב התנועה, כדי שהבקשה תחויב במסגרת Compute Routes Pro במקום Compute Routes Enterprise. -
departure-time(departureTime): מקבל מחרוזת של חותמת זמן לפי תקן ISO 8601 ב-HTML, כמו"2027-03-15T16:00:00Z", או אובייקטDateב-JavaScript. -
autofits-camera(autofitsCamera): ממסגר את המסלול שנטען בתוך אזור התצוגה של<gmp-map-3d>.
טיפול באירועים במסלול וקריאת נתוני מסלול
Route3DElement שולח את gmp-load כשהעיבוד של המסלול מסתיים, ואת gmp-error אם חישוב המסלול נכשל או מחזיר אפס מסלולים. אחרי ש-gmp-load מופעל, אפשר לקרוא את המאפיינים המחושבים routes, fallbackInfo ו-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.');
});
מתי כדאי להשתמש בשיטות של רכיב העזר Route במקום ב-gmp-route-3d
<gmp-route-3d> מציג את המסלול הראשי בין origin אחד ל-destination אחד, עם סגנון ברירת המחדל של הסמן והקו הפוליגוני. משתמשים ב-Route.computeRoutes עם שיטות העזר לתלת-ממד כשצריך נקודות ציון ביניים, בחירת מסלול חלופי, מסכות שדות של תשובות בהתאמה אישית או סגנונות של קווים פוליגוניים וסמנים בהתאמה אישית.
התאמה אישית של עיבוד מסלול בתלת-ממד באמצעות המחלקה Route
בתהליכי עבודה מותאמים אישית של מסלולים בתלת-ממד, צריך להפעיל את Route.computeRoutes ולעבד את המכונה Route שמוחזרת ב-<gmp-map-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>
מחליפים את הערך YOUR_API_KEY במפתח ה-API של Google Maps Platform.
ב-ComputeRoutesRequest.fields, כוללים את שדות החובה לכל שיטת עזר שקוראים לה:
-
create3DPolylines: מבקשים את'path'או את'legs'לקווים פוליגוניים רגילים, את'path'ואת'legs'כש-travelModeהוא'TRANSIT', או את'speedPaths'עםextraComputations: ['TRAFFIC_ON_POLYLINE']לקווים פוליגוניים בצבעי תנועה. מעבירים אתRoutePolyline3DOptionsכדי להתאים אישית אתpolylineOptionsאו להגדיר אתtrafficPolylinesDisabled. -
createWaypointMarkers: בקשה של'path'ב-fields. יוצרת סמנים של נקודת המוצא ונקודת היעד (Marker3DElementכברירת מחדל, אוMarkerElement,MarkerInteractiveElementאוMarker3DInteractiveElementכשמצוין עםmarkerClassב-CreateWaypointMarkersOptions). השיטה הזו לא יוצרת נקודות דרך ביניים. -
createPopover: מבקשים את'path'ואת'localizedValues'(וגם את'legs'למסלולי תחבורה ציבורית) כדי לעגן סיכוםPopoverElementבאמצע המסלול.