שדרוג של אפליקציה של Maps JavaScript API מגרסה 2 לגרסה 3

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

סקירה כללית

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

  1. לקבל מפתח חדש. בממשק API של JavaScript במפות Google נעשה עכשיו שימוש במסוף Google Cloud לניהול מפתחות. אם אתם עדיין משתמשים במפתח מגרסה 2, חשוב לקבל את מפתח ה-API החדש לפני שמתחילים את ההעברה.
  2. עדכון ה-Bootstrap של ה-API רוב האפליקציות יטענו את 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 שבהם היא תשתמש.
    • (אופציונלי) מגדירים את הפרויקט כך שישתמש ב-externs של v3. אפשר להשתמש ב-externs של גרסה 3 כדי לאמת את הקוד באמצעות Closure Compiler, או כדי להפעיל השלמה אוטומטית בסביבת הפיתוח המשולבת (IDE). מידע נוסף על פירושים מתקדמים ו-externs
  4. בדיקה וחזרה על התהליך בשלב הזה עדיין תצטרכו לבצע כמה פעולות, אבל החדשות הטובות הן שאתם כבר בדרך לאפליקציית מפות Google בגרסה 3.0.

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

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

חלק מהשינויים ב-API בגרסה 3 כוללים:

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

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

המפתח החדש

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

המפתח מועבר בזמן טעינת Maps JavaScript API v3. מידע נוסף על יצירת מפתחות API

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

טעינת ה-API

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

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

במקרה הפשוט ביותר, ה-bootstrap של 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>

הדוגמה הבאה היא בקשה מקבילה לגרסה 3.

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

חדש: מרחב השמות google.maps

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

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

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 יש מקבילות לרוב הפונקציות של הגרסה הקודמת, אבל יש כמה כיתות שכבר לא נתמכות. כחלק מההעברה, צריך להחליף את הכיתות האלה בספריות שירות של צד שלישי או להסיר את ההפניות האלה מהקוד. יש הרבה ספריות 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 של גרסה 2 ושל גרסה 3.

<!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.
  • הנכסים נטענים עכשיו באמצעות כיתות של אפשרויות. בדוגמה שלמעלה, הגדרנו את שלושת המאפיינים הנדרשים כדי לטעון מפה – center, ‏ zoom ו-mapTypeId – באמצעות אובייקט MapOptions מוטמע.
  • ממשק המשתמש שמוגדר כברירת מחדל מופעל כברירת מחדל בגרסה 3. אפשר להשבית את האפשרות הזו על ידי הגדרת המאפיין disableDefaultUI לערך true באובייקט MapOptions.

סיכום

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

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

מידע מפורט

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

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

אירועים

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

פקדים

ב-Maps JavaScript API מוצגים רכיבי בקרה של ממשק המשתמש שמאפשרים למשתמשים לבצע פעולות במפה. אפשר להשתמש ב-API כדי להתאים אישית את המראה של אמצעי הבקרה האלה.

שכבות-על

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

סוגי מפות

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

שכבות

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

שירותים