התאמה אוטומטית של המצלמה לרכיבי המפה

אפשר למרכז באופן אוטומטי סמנים, קווים פוליגוניים, פוליגונים ומסלולים תלת-ממדיים בתוך אזור תצוגה של <gmp-map-3d>. כדי לעשות את זה, מגדירים את מאפיין ה-HTML‏ autofits-camera או את המאפיין autofitsCamera ברכיבי הצאצא הנתמכים. כשמפעילים את האפשרות הזו ברכיב צאצא אחד או יותר, המפה מחשבת את מיקום המצלמה כך שכל הרכיבים שהאפשרות הופעלה בהם יוצגו.

התאמה אוטומטית של המצלמה זמינה בערוץ v=beta של Maps JavaScript API. הוראות לטעינת ערוץ הבטא מופיעות במאמר ניהול גרסאות.

רכיבים נתמכים

בטבלה הבאה מפורטים רכיבי המשנה של Map3DElement שתומכים ב-autofits-camera (autofitsCamera):

רכיב HTML מחלקה ב-JavaScript ספרייה הערות
<gmp-marker-3d>, <gmp-marker-3d-interactive> Marker3DElement, Marker3DInteractiveElement maps3d ממסגר את position של הסמן.
<gmp-marker>, <gmp-marker-interactive> MarkerElement, MarkerInteractiveElement maps3d ממסגר את position של הסמן.
<gmp-polyline-3d>, <gmp-polyline-3d-interactive> Polyline3DElement, Polyline3DInteractiveElement maps3d ממסגר את כל הקואורדינטות ב-path של הקו הפוליגוני.
<gmp-polygon-3d>, <gmp-polygon-3d-interactive> Polygon3DElement, Polygon3DInteractiveElement maps3d מציג את כל הקואורדינטות ב-path של הפוליגון.
<gmp-route-3d> Route3DElement routes ממתין לפתרון של בקשת המסלול, ואז ממסגר את נתיב המסלול.

רכיבים לא נתמכים

‫Model3DElement,‏ PopoverElement ו-FlattenerElement לא תומכים ב-autofitsCamera. כדי להגדיר את הרכיבים האלה, צריך להגדיר את center ו-range ב- <gmp-map-3d> או להפעיל את flyCameraTo.

התאמת המצלמה בטעינה הראשונית

כדי להציג רכיבים בפריים כשהמפה נטענת, מוסיפים את המאפיין autofits-camera לכל רכיב משני שרוצים להציג באזור התצוגה הראשוני. אין צורך לחשב את center או את range ב-<gmp-map-3d>:

<gmp-map-3d
  style="height: 400px; width: 100%;"
  mode="hybrid">
  <gmp-marker-3d
    position="47.6205,-122.3493"
    title="Space Needle"
    autofits-camera>
  </gmp-marker-3d>
  <gmp-marker-3d
    position="47.6097,-122.3425"
    title="Pike Place Market"
    autofits-camera>
  </gmp-marker-3d>
  <gmp-polyline-3d
    path="47.6205,-122.3493,0 47.6097,-122.3425,0"
    stroke-color="#4285F4"
    stroke-width="8"
    altitude-mode="clamp-to-ground"
    autofits-camera>
  </gmp-polyline-3d>
</gmp-map-3d>

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&libraries=maps3d">
</script>

מחליפים את הערך YOUR_API_KEY במפתח ה-API של Google Maps Platform.

התאמה ואנימציה של עדכונים דינמיים

כשמוסיפים רכיב שהצטרף אחרי הטעינה הראשונית, מעדכנים את הקואורדינטות או את נקודות הקצה של המסלול, או מגדירים את autofitsCamera ל-true, המפה מחשבת מחדש את המצלמה כדי להציג את כל הרכיבים שהצטרפו. אם מסירים רכיב או מגדירים את autofitsCamera לערך false, המצלמה נשארת במיקום שלה והרכיב הזה לא נכלל בעדכונים עתידיים.

כדי לקבוע אם עדכונים דינמיים יתבצעו בהצמדה או באנימציה, מגדירים את autofitsCameraAnimation (autofits-camera-animation) ב-Map3DElement לערך AutofitsCameraAnimation:

  • ‫AutofitsCameraAnimation.NONE ("none", ברירת המחדל): המצלמה עוברת למיקום המעודכן בלי אנימציה.
  • ‫AutofitsCameraAnimation.FLY_TO ("fly-to"): מעבר חלק למיקום המעודכן. הטעינה הראשונית של המפה מתבצעת ללא אנימציה, והפונקציה FLY_TO חוזרת למצב של הצמדה כשהמשתמש מבקש להפחית את התנועה במערכת ההפעלה.

כדי להגדיר את autofitsCamera ו-AutofitsCameraAnimation.FLY_TO באופן פרוגרמטי, אפשר להיעזר בדוגמה הבאה:

<div id="map-container" style="height: 400px; width: 100%;"></div>

<script>
  async function initMap() {
    const {
      AutofitsCameraAnimation,
      Map3DElement,
      Marker3DElement,
      MapMode,
    } = await google.maps.importLibrary('maps3d');

    const map = new Map3DElement({
      mode: MapMode.HYBRID,
      autofitsCameraAnimation: AutofitsCameraAnimation.FLY_TO,
    });
    document.getElementById('map-container').append(map);

    const originMarker = new Marker3DElement({
      position: { lat: 37.7955, lng: -122.3937 },
      autofitsCamera: true,
    });
    map.append(originMarker);

    /* Adding a second opted-in marker flies the camera to frame both. */
    const destinationMarker = new Marker3DElement({
      position: { lat: 37.8080, lng: -122.4177 },
      autofitsCamera: true,
    });
    map.append(destinationMarker);
  }
</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.

איך המאפיינים וההגבלות של המצלמה משפיעים זה על זה

אם לפחות רכיב צאצא אחד מצטרף באמצעות autofits-camera, ‏Map3DElement משלב את הגדרות המפה עם הגבולות המחושבים לפי הכללים הבאים:

  • ‫center ו-range: מוחלפים על ידי המסגור המחושב, שמוסיף 20% ריפוד לטווח ואוכף טווח מינימלי של 80 מטר. אם לאף אחד מרכיבי הצאצא שהביעו הסכמה אין קואורדינטות, המפה תשתמש בערכים של center ו-range שהוגדרו כחלופות.
  • ‫tilt ו-heading: המערכת מתייחסת אליהם כערכים מוצעים במהלך הגדרת הפריים. אם משמיטים את הפרמטרים האלה, ברירת המחדל של שניהם היא 0°, כדי לקבל תצוגה מלמעלה למטה שפונה לכיוון צפון.
  • ‫roll ו-fov: נשמרים כמו שהוגדר ב-Map3DElement.
  • רכיבי צאצא אסינכרוניים: לפני העיבוד של התצוגה הראשונית, Map3DElement ממתין עד שרכיבי צאצא אסינכרוניים שהצטרפו, כמו <gmp-route-3d>, יסיימו לטעון את הגיאומטריה של המסלול.
  • הגבלות על המפה והמצלמה: הגבלות גיאוגרפיות (bounds) והגבלות על המצלמה (minAltitude,‏ maxAltitude,‏ minTilt,‏ maxTilt,‏ minHeading ו-maxHeading) עדיין מגבילות את התצוגה שמותאמת אוטומטית. מידע נוסף זמין במאמר הגבלת התצוגה והגבולות של המצלמה.

השלבים הבאים