שדרוג יישום JavaScript API של מפות Google מ-V2 ל-V3

החל מ-26 במאי 2021 גרסה 2 של Maps JavaScript API לא תהיה זמינה יותר. כתוצאה מכך, המפות בגרסה 2 של האתר יפסיקו לפעול ויחזירו שגיאות JavaScript. על מנת להמשיך להשתמש במפות באתר שלכם, עברו ל-Maps JavaScript API v3. מדריך זה יעזור לכם בתהליך.

סקירה כללית

לכל אפליקציה יהיה תהליך העברה שונה במקצת. עם זאת, יש כמה שלבים שמשותפים לכל הפרויקטים:

  1. לקבלת מפתח חדש ה-API ל-JavaScript של מפות Google משתמש עכשיו במסוף Google Cloud כדי לנהל מפתחות. אם אתם עדיין משתמשים במפתח v2, חשוב לקבל את מפתח ה-API החדש לפני שמתחילים בהעברה.
  2. עדכון ה-API Bootstrap. רוב האפליקציות יטענו את הממשק Maps JavaScript API v3 עם הקוד הבא:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    
  3. מעדכנים את הקוד. היקף השינוי הנדרש יהיה תלוי במידה רבה באפליקציה שלך. דוגמאות לשינויים נפוצים:
    • חשוב להפנות תמיד למרחב השמות של google.maps. בגרסה 3, כל קוד ה-API ל-JavaScript של מפות Google מאוחסן במרחב השמות של google.maps.* במקום במרחב השמות הגלובלי. השם של רוב האובייקטים השתנה גם כחלק מהתהליך הזה. לדוגמה, במקום GMap2, תטען עכשיו google.maps.Map.
    • מסירים את כל ההפניות לשיטות מיושנות. הוסרו מספר שיטות לשימוש כללי, כמו GDownloadURL ו-GLog. צריך להחליף את הפונקציונליות הזו בספריות שירות של צד שלישי או להסיר את ההפניות האלה מהקוד שלכם.
    • (אופציונלי) מוסיפים ספריות לקוד. הרבה תכונות הוכנסו לספריות של כלי עזר, כך שכל אפליקציה תצטרך לטעון רק את החלקים של ה-API שיהיו בשימוש.
    • (אופציונלי) מגדירים את הפרויקט לשימוש בתוספים v3. אפשר להשתמש בתוספים v3 כדי לאמת את הקוד באמצעות מהדר חסימות, או כדי להפעיל השלמה אוטומטית בסביבת הפיתוח המשולבת (IDE). מידע נוסף על הידור מתקדם ותוספים נוספים.
  4. בודקים וחוזרים על התהליך. בשלב הזה יהיה לך עדיין חלק מהעבודה, אבל החדשות הטובות הן שתהיה לך אפשרות להשתמש באפליקציית מפות v3 החדשה!

שינויים בגרסה 3 של Maps JavaScript API

לפני שמתכננים את ההעברה, כדאי להבין את ההבדלים בין Maps JavaScript API v2 לבין Maps JavaScript API v3. הגרסה החדשה ביותר של Maps JavaScript API נכתבה מהיסוד, תוך התמקדות בטכניקות תכנות מודרניות של JavaScript, שימוש מוגבר בספריות וממשק API פשוט יותר. הרבה תכונות חדשות נוספו ל-API, ומספר תכונות מוכרות השתנו או אפילו הוסרו. בקטע הזה מתוארים כמה מההבדלים העיקריים בין שתי הגרסאות.

חלק מהשינויים ב-v3 API כוללים:

  • ספרייה מרכזית פשוטה ונוחה. חלק גדול מהפונקציות המשלימות הועברו לספריות, כדי לקצר את זמני הטעינה והניתוח של ה-Core API, שמאפשר לטעון את המפה במהירות בכל מכשיר.
  • ביצועים משופרים של מספר תכונות, כמו עיבוד פוליגונים ומיקום סמנים.
  • גישה חדשה למגבלות השימוש בצד הלקוח, כדי להתאים טוב יותר לכתובות משותפות שמשמשות שרתי proxy לנייד וחומות אש ארגוניות.
  • נוספה תמיכה במספר דפדפנים מודרניים ודפדפנים לנייד. התמיכה ב-Internet Explorer 6 הוסרה.
  • הוסרו רבות ממחלקות המסייעות לשימוש כללי ( GLog או GDownloadUrl). כיום יש הרבה ספריות JavaScript מצוינים שמספקות פונקציונליות דומה, כמו Closure או jQuery.
  • הטמעת Street View של HTML5 שתיטען בכל מכשיר נייד.
  • תמונות פנורמה של Street View בהתאמה אישית עם תמונות משלך, כדי לשתף תמונות פנורמיות של מדרונות סקי, בתים למכירה או מקומות מעניינים אחרים.
  • התאמות אישיות של מפות מעוצבות שמאפשרות לשנות את התצוגה של האלמנטים במפה הבסיסית כך שיתאימו לסגנון החזותי הייחודי שלכם.
  • תמיכה במספר שירותים חדשים, כמו ElevationService ו-גיאוגרפי Matrix.
  • שירות מסלולים משופר כולל מסלולים חלופיים, אופטימיזציה של מסלולים (פתרונות משוערים לבעיה של אנשי המכירות בנסיעות), מסלולי רכיבה על אופניים (עם שכבת רכיבה על אופניים), מסלולים לתחבורה ציבורית ו מסלולים שניתן לגרור.
  • פורמט מעודכן של קידוד גיאוגרפי שמספק מידע מדויק יותר על הסוג מאשר הערך accuracy מ-Geocoding API גרסה 2.
  • תמיכה במספר חלונות מידע במפה אחת

שדרוג האפליקציה שלך

המפתח החדש שלך

Maps JavaScript API v3 משתמש במערכת מפתחות חדשה מגרסה 2. יכול להיות שכבר נעשה שימוש במפתח v3 עם האפליקציה, ובמקרה כזה אין צורך בשינוי. כדי לאמת, בודקים את כתובת ה-URL שממנה טוענים את Maps JavaScript API עבור הפרמטר key. אם ערך המפתח מתחיל ב-'ABQIAA', אתם משתמשים במפתח v2. אם יש לכם מפתח v2, עליכם לשדרג למפתח v3 כחלק מההעברה, כי:

המפתח מועבר כשטוענים את Maps JavaScript API v3. מידע נוסף על יצירת מפתחות API

לתשומת ליבכם: אם אתם לקוחות של Google Maps APIs for Work, יכול להיות שאתם משתמשים במזהה לקוח עם הפרמטר client במקום להשתמש בפרמטר key. מזהי לקוחות עדיין נתמכים בגרסה 3 של Maps JavaScript API, ולא צריך לעבור את תהליך שדרוג המפתח.

ה-API בטעינה

השינוי הראשון שתצטרכו לבצע בקוד כרוך באופן הטעינה של ה-API. בגרסה 2, טוענים את ה-API של JavaScript במפות באמצעות בקשה אל http://maps.google.com/maps. אם אתם טוענים את Maps JavaScript API v3, עליך לבצע את השינויים הבאים:

  1. טעינת ה-API מ-//maps.googleapis.com/maps/api/js
  2. צריך להסיר את הפרמטר file.
  3. מעדכנים בפרמטר key את מפתח v3 החדש. לקוחות Google Maps API for Work צריכים להשתמש בפרמטר client.
  4. (בתוכנית הפרימיום של הפלטפורמה של מפות Google בלבד) צריך לוודא שהפרמטר client מסופק כפי שמוסבר במדריך למפתחים של תוכנית הפרימיום של מפות Google.
  5. צריך להסיר את הפרמטר v כדי לבקש את הגרסה האחרונה או לשנות את הערך שלו בהתאם לסכימה של ניהול גרסאות v3.
  6. (אופציונלי) מחליפים את הפרמטר hl בערך language ושומרים את הערך שלו.
  7. (אופציונלי) אפשר להוסיף פרמטר libraries כדי לטעון ספריות אופציונליות.

במקרה הפשוט ביותר, אתחול האתחול של v3 יציין רק את הפרמטר של מפתח ה-API שלך:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

הדוגמה הבאה מבקשת את הגרסה העדכנית ביותר של Maps JavaScript API v2 בגרמנית:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

הדוגמה הבאה היא בקשה מקבילה ל-v3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

נעים להכיר: מרחב השמות google.maps

השינוי הבולט ביותר ב-Maps JavaScript API v3 הוא כנראה מרחב השמות של google.maps. ה-API של גרסה 2 מציב את כל האובייקטים במרחב השמות הגלובלי כברירת מחדל, מה שעלול לגרום להתנגשויות בין שמות. בגרסה 3, כל האובייקטים נמצאים במרחב השמות של google.maps.

בעת העברת האפליקציה ל-v3, יהיה עליך לשנות את הקוד כדי להשתמש במרחב השמות החדש. לצערנו, לא ניתן לחפש את האות G והחלפה ב-'google.maps'. אבל בכל מקרה, כדאי ליישם את הכלל. בהמשך מוצגות כמה דוגמאות למחלקות המקבילות ב-v2 וב-v3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

הסרת קוד מיושן

ל-Maps JavaScript API v3 יש מקבילות עבור רוב הפונקציות ב-v2. עם זאת, חלק מהמחלקות אינן נתמכות יותר. במסגרת ההעברה, צריך להחליף את המחלקות האלה בספריות שירות של צד שלישי או להסיר את ההפניות האלה מהקוד. יש הרבה ספריות JavaScript מצוינות שמספקות פונקציונליות דומה כמו Closure או jQuery.

למחלקות הבאות אין מקבילה ב-Maps JavaScript API v3:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

השוואת קוד

נשווה בין שתי אפליקציות פשוטות יחסית שנכתבו באמצעות ממשקי ה-API של v2 ו-v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

כפי שאפשר לראות, יש כמה הבדלים בין שתי האפליקציות. השינויים הבולטים כוללים:

  • הכתובת שממנה ה-API נטען השתנתה.
  • השיטות GBrowserIsCompatible() ו-GUnload() לא נחוצות יותר בגרסה 3, והן הוסרו מה-API.
  • האובייקט GMap2 מוחלף ב-google.maps.Map בתור האובייקט המרכזי ב-API.
  • המאפיינים נטענים עכשיו דרך מחלקות של Options. בדוגמה שלמעלה, הגדרנו את שלושת המאפיינים הנדרשים כדי לטעון מפה – center, zoom ו-mapTypeId – באמצעות אובייקט MapOptions מוטבע.
  • כברירת מחדל, ממשק המשתמש שבגרסה 3 פועל כברירת מחדל. אפשר להשבית את התכונה הזו על ידי הגדרת המאפיין disableDefaultUI כ-True באובייקט MapOptions.

סיכום

בשלב הזה תהיה לך טעימה לגבי כמה מהנקודות העיקריות הקשורות למעבר מגרסה 2 לגרסה 3 של Maps JavaScript API. יש עוד מידע שחשוב לדעת, אבל תלוי באפליקציה. בקטעים הבאים כללנו הוראות להעברה למקרים ספציפיים שאתם עשויים להיתקל בהם. בנוסף, יש כמה מקורות מידע שעשויים להועיל לך בתהליך השדרוג.

אם נתקלת בבעיות או שיש לך שאלות לגבי המאמר הזה, אפשר להשתמש בקישור שליחת משוב שבראש הדף.

חומר עזר מפורט

בקטע זה מופיעה השוואה מפורטת של התכונות הפופולריות ביותר בגרסה 2 וב-v3 של Maps JavaScript API. כל קטע של קובץ העזר מיועד לקריאה בנפרד. מומלץ לא לקרוא את חומר העזר הזה במלואו. במקום זאת, כדאי להשתמש בחומר הזה כדי לבצע את ההעברה על בסיס כל מקרה לגופו.

  • אירועים – רישום וטיפול באירועים.
  • פקדים - שינוי פקדי הניווט שמופיעים במפה.
  • שכבות-על – הוספה ועריכה של אובייקטים במפה.
  • סוגי מפה - המשבצות שמרכיבים את המפה הבסיסית.
  • שכבות – הוספה ועריכה של תוכן כקבוצה, כמו שכבות KML או תנועה.
  • שירותים – עבודה עם קידוד גיאוגרפי של Google, מסלולי נסיעה או שירותי Street View של Google.

אירועים

מודל האירועים של Maps JavaScript API v3 דומה למודל שבו נעשה שימוש ב-v2, אם כי הרבה השתנה בפועל.

אמצעי בקרה

ה-API ל-JavaScript של מפות Google מציג פקדים בממשק המשתמש שמאפשרים למשתמשים לבצע אינטראקציה עם המפה שלך. אפשר להשתמש ב-API כדי להתאים אישית את האופן שבו אמצעי הבקרה האלה מופיעים.

שכבות-על

שכבות-על משקפות אובייקטים ש'מוסיפים' למפה כדי לציין נקודות, קווים, אזורים או אוספים של אובייקטים.

סוגי מפות

סוגי המפות שזמינים ב-v2 וב-v3 שונים מעט, אבל כל סוגי המפות הבסיסיים זמינים בשתי הגרסאות של ה-API. כברירת מחדל, גרסה 2 משתמשת באריחי מפת דרכים "צבועים" רגילים. עם זאת, ב-v3 נדרש סוג מפה ספציפי כשיוצרים אובייקט google.maps.Map.

שכבות

שכבות הן אובייקטים במפה שמורכבות משכבת-על אחת או יותר. אפשר לשנות אותם כיחידה אחת ולרוב משקפים אוספים של אובייקטים.

שירותים