הצגת מסלולים במפה תלת-ממדית

מפתחים באזור הכלכלי האירופי (EEA)

יש שתי דרכים לחשב ולעבד מסלולים ברכיב <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 באמצע המסלול.

השלבים הבאים