שדרוג יישום 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 כחלק מההעברה, כי:

• ניתן לך לעקוב אחרי השימוש ב-API במסוף Google Cloud.
• מאפשרים לכם לרכוש מכסה נוספת לפי הצורך.
• אפשר ל-Google ליצור איתך קשר לגבי הבקשה שלך.

המפתח מועבר כשטוענים את 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:

GBounds	GLanguage
GBrowserIsCompatible	GLayer
GControl	GLog
GControlAnchor	GMercatorProjection
GControlImpl	GNavLabelControl
GControlPosition	GObliqueMercator
GCopyright	GOverlay
GCopyrightCollection	GPhotoSpec
GDownloadUrl	GPolyEditingOptions
GDraggableObject	GScreenOverlay
GDraggableObjectOptions	GStreetviewFeatures
GFactualGeocodeCache	GStreetviewLocation
GGeoAddressAccuracy	GStreetviewOverlay
GGeocodeCache	GStreetviewUserPhotosOptions
GGoogleBar	GTileLayerOptions
GGoogleBarAdsOptions	GTileLayerOverlayOptions
GGoogleBarLinkTarget	GTrafficOverlayOptions
GGoogleBarListingTypes	GUnload
GGoogleBarOptions	GXml
GGoogleBarResultList	GXmlHttp
GInfoWindowTab	GXslt
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. יש עוד מידע שחשוב לדעת, אבל תלוי באפליקציה. בקטעים הבאים כללנו הוראות להעברה למקרים ספציפיים שאתם עשויים להיתקל בהם. בנוסף, יש כמה מקורות מידע שעשויים להועיל לך בתהליך השדרוג.

• המאמר תיעוד למפתחים של Maps JavaScript API v3 הוא המקום הטוב ביותר לקבלת מידע נוסף על ה-API ועל אופן הפעולה שלו.
• ב-Maps JavaScript API v3 חומר עזר מפורט מידע נוסף על המחלקות והשיטות החדשות בממשק ה-API של v3.
• כדאי לשאול את קהילת Stack Overflow שאלות שקשורות לקוד. באתר, שאלות ותשובות הקשורות ל-Maps JavaScript API משתמשות בתגים 'google-maps' או 'google-maps-api-3'.
• לקוחות של תוכנית הפרימיום של מפות Google ירצו לקרוא את מסמכי התיעוד של תוכנית הפרימיום של מפות Google.
• Google Geo Developers Blog הוא דרך מצוינת לגלות את השינויים האחרונים ב-API.

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

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

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

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

אירועים

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

אירוע חדש לתמיכה ב-MVC

גרסה 3 של ה-API מוסיפה סוג חדש של אירוע כדי לשקף שינויים במצב של MVC. יש עכשיו שני סוגים של אירועים:

• אירועי משתמש (כמו אירועי "לחיצה" בעכבר) מופצים מה-DOM ל-API JavaScript של מפות Google. האירועים האלה נפרדים מאירועי DOM רגילים.
• התראות על שינויים במצב MVC משקפות שינויים באובייקטים של API של מפות Google, והשמות שלהן מבוססים על המוסכמה property_changed.

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

GEvent.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

google.maps.event.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

הסרת פונקציות event listener

כדי לשפר את הביצועים, עדיף להסיר event listener כשאין בו יותר צורך. ההסרה של event listener פועלת באותו אופן בגרסאות v2 ו-v3:

1. כשיוצרים האזנה לאירוע, מוחזר אובייקט אטום (GEventListener בגרסה 2, MapsEventListener בגרסה v3).
2. אם רוצים להסיר את ה-event listener, צריך להעביר את האובייקט הזה ל-method removeListener() (GEvent.removeListener() בגרסה 2 או google.maps.event.removeListener() בגרסה 3) כדי להסיר את event listener.

האזנה לאירועי DOM

אם רוצים לתעד אירועי DOM (Document Object Model) ולהגיב עליהם, הגרסה 3 מספקת את השיטה הסטטית google.maps.event.addDomListener(), שמקבילה לשיטה GEvent.addDomListener() בגרסה 2.

שימוש בארגומנטים שהועברו באירועים

לעיתים קרובות, אירועים בממשק המשתמש מעבירים ארגומנט של אירוע שאליו ה-event listener יכול לגשת. רוב הארגומנטים של האירועים בגרסה 3 פשוטים יותר כדי להיות עקביים יותר ביחס לאובייקטים ב-API. (פרטים נוספים זמינים בחומר העזר בנושא גרסה 3).

לא קיים ארגומנט overlay בפונקציות event listener לגרסה 3. אם רושמים אירוע click במפה מגרסה 3, הקריאה החוזרת תתבצע רק כשהמשתמש ילחץ על המפה הבסיסית. אם צריך להגיב לקליקים האלה, אפשר לרשום קריאות חוזרות (callback) נוספות בשכבות-על שניתן ללחוץ עליהן.

// Passes an overlay argument when clicking on a map

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

GEvent.addListener(map,'click', function(overlay, latlng) {
  if (latlng) {
    var marker = new GMarker(latlng);
    map.addOverlay(marker);
  }
});

// Passes only an event argument

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

google.maps.event.addListener(map, 'click', function(event) {
  var marker = new google.maps.Marker({
      position: event.latLng,
      map: map
  });
});

אמצעי בקרה

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

שינויים בסוגי הבקרה

כמה שינויים בסוגים של control הוכנסו ל-API של גרסה 3.

1. v3 API תומך בסוגי מפות נוספים, כולל מפות פני שטח והאפשרות להוסיף סוגי מפות מותאמים אישית.
2. אמצעי הבקרה ההיררכי V2, GHierarchicalMapTypeControl, לא זמין יותר. אפשר להשיג אפקט דומה באמצעות הפקד google.maps.MapTypeControlStyle.HORIZONTAL_BAR.
3. הפריסה האופקית שסופקה על ידי GMapTypeControl בגרסה 2 לא זמינה ב-v3.

הוספת פקדים למפה

ב-Maps JavaScript API v2 אפשר להוסיף פקדים למפה באמצעות השיטה addControl() של אובייקט המפה. בגרסה 3, במקום לגשת לפקדים או לשנות אותם ישירות, משנים את האובייקט MapOptions המשויך. הדוגמה הבאה מראה איך להתאים אישית את המפה כדי להוסיף את הפקדים הבאים:

• לחצנים שמאפשרים למשתמש לעבור בין סוגי מפות זמינים.
• קנה מידה של מפה

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add controls
map.addControl(new GMapTypeControl());
map.addControl(new GScaleControl());

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP,

    // Add controls
    mapTypeControl: true,
    scaleControl: true
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

פקדי מיקום במפה

בקרות המיקום השתנו מאוד בגרסה 3. בגרסה 2, השיטה addControl() מקבלת פרמטר שני אופציונלי שמאפשר לציין את המיקום של אמצעי הבקרה ביחס לפינות המפה.

בגרסה 3, מגדירים את המיקום של פקד באמצעות המאפיין position של אפשרויות הבקרה. המיקום של אמצעי הבקרה האלה אינו מוחלט. במקום זאת, ה-API יפרוס את אמצעי הבקרה בצורה חכמה על ידי 'הזרמת' אותם מסביב לרכיבי מפה קיימים במסגרת אילוצים נתונים (כמו גודל המפה). כך אפשר להבטיח שבקרות ברירת המחדל תואמות לאמצעי הבקרה שלכם. למידע נוסף, ראה שליטה במיקום בגרסה 3.

הקוד הבא ממקם מחדש את הפקדים מהדוגמאות שלמעלה:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add map type control
map.addControl(new GMapTypeControl(), new GControlPosition(
    G_ANCHOR_TOP_LEFT, new GSize(10, 10)));

// Add scale
map.addControl(new GScaleControl(), new GControlPosition(
    G_ANCHOR_BOTTOM_RIGHT, new GSize(20, 20)));

var myOptions = {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP,

  // Add map type control
  mapTypeControl: true,
  mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
      position: google.maps.ControlPosition.TOP_LEFT
  },

  // Add scale
  scaleControl: true,
  scaleControlOptions: {
      position: google.maps.ControlPosition.BOTTOM_RIGHT
  }
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

פקדים בהתאמה אישית

Maps JavaScript API מאפשר לך ליצור פקדי ניווט מותאמים אישית. כדי להתאים אישית את אמצעי הבקרה באמצעות v2 API, צריך לתת סיווג משנה למחלקה GControl ולהגדיר רכיבי handler לשיטות initialize() ו-getDefaultPosition(). אין מקביל למחלקה GControl ב-v3. במקום זאת, אמצעי הבקרה מיוצגים כרכיבי DOM. כדי להוסיף אמצעי בקרה בהתאמה אישית באמצעות v3 API, צריך ליצור מבנה DOM לפקד ב-constructor כצאצא של Node (למשל רכיב <div>) ולהוסיף פונקציות event listener לטיפול בכל אירועי DOM. מכניסים את Node למערך controls[position] של המפות כדי להוסיף למפה מופע של הפקד המותאם אישית.

בהינתן הטמעה של מחלקה HomeControl שעומדת בדרישות הממשק שפורטו למעלה (לפרטים, עיינו במסמכי התיעוד של אמצעי בקרה מותאמים אישית), דוגמאות הקוד הבאות מראות איך להוסיף פקד מותאם אישית למפה.

map.addControl(new HomeControl(),
    GControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(10, 10)));

var homeControlDiv = document.createElement('DIV');
var homeControl = new HomeControl(homeControlDiv, map);

map.controls[google.maps.ControlPosition.TOP_RIGHT].push(
    homeControlDiv);

שכבות-על

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

הוספה והסרה של שכבות-על

סוגי האובייקטים שמיוצגים בשכבת-על זהים בין גרסה 2 לגרסה v3, אבל ההתייחסות אליהם שונה.

שכבות-על ב-V2 API נוספו למפה והוסרו ממנה באמצעות השיטות addOverlay() ו-removeOverlay() של האובייקט GMap2. בגרסה 3, מקצים מפה לשכבת-על דרך הנכס map של מחלקת האפשרויות של שכבת-העל המשויכת. אפשר גם להוסיף או להסיר שכבת-על ישירות על ידי קריאה לשיטה setMap() של אובייקט שכבת-העל וציון המפה הרצויה. הגדרת מאפיין המפה כ-null מסירה את שכבת-העל.

לא קיימת שיטת clearOverlays() בגרסה 3. אם רוצים לנהל קבוצה של שכבות-על, צריך ליצור מערך שיכיל את שכבות-העל. באמצעות המערך הזה, תוכלו להפעיל את setMap() בכל שכבת-על במערך (העברת null אם צריך להסיר אותם).

סמנים ניתנים לגרירה

כברירת מחדל, הסמנים ניתנים ללחיצה אך לא ניתנים לגרירה. שתי הדוגמאות הבאות מוסיפות סמן שניתן לגרירה:

var myLatLng = new GLatLng(-25.363882, 131.044922);
var map = new GMap2(document.getElementById('map'));
map.setCenter(myLatLng, 4);

var marker = new GMarker(latLng, {
  draggable: true
});
map.addOverlay(marker);

var myLatLng = new google.maps.LatLng(-25.363882, 131.044922);
var map = new google.maps.Map(
  document.getElementById('map'), {
  center: myLatLng,
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var marker = new google.maps.Marker({
    position: myLatLng,
    draggable: true,
    map: map
});

סמלים

אפשר להגדיר סמל מותאם אישית שיוצג במקום סמן ברירת המחדל. כדי להשתמש בתמונה מותאמת אישית בגרסה 2, אפשר ליצור מכונת GIcon מה-G_DEFAULT_ICON type ולשנות אותה. אם התמונה גדולה מסמל ברירת המחדל או קטנה ממנה, צריך לציין אותה באמצעות מופע של GSize. ה-API של גרסת v3 מפשט מעט את התהליך. פשוט מגדירים את המאפיין icon של הסמן לכתובת ה-URL של התמונה המותאמת אישית, וה-API יתאים את גודל הסמל באופן אוטומטי.

ה-API ל-JavaScript של מפות Google תומך גם בסמלים מורכבים. סמל מורכב יכול לכלול כמה משבצות או צורות מורכבות, או לציין את 'סדר הערמה' של האופן שבו התמונות יוצגו ביחס לשכבות-על אחרות. כדי להוסיף צורה לסמן ב-v2, צריך לציין את המאפיין הנוסף בכל מופע של GIcon ולהעביר אותו כאפשרות לבנאי של GMarker. בגרסה 3, סמלים שצוינו באופן הזה צריכים להגדיר את מאפייני icon שלהם לאובייקט מסוג Icon. צלליות סמנים אינן נתמכות בגרסה 3.

בדוגמאות הבאות מוצג דגל חוף בחוף בונדי באוסטרליה, והחלק השקוף של הסמל לא ניתן ללחיצה:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

var flagIcon = new GIcon(G_DEFAULT_ICON);
flagIcon.image = '/images/beachflag.png';
flagIcon.imageMap = [1, 1, 1, 20, 18, 20, 18 , 1];
var bbLatLng = new GLatLng(-33.890542, 151.274856);

map.addOverlay(new GMarker(bbLatLng, {
  icon: flagIcon
}));

var map = new google.maps.Map(
  document.getElementById('map'), {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var shape = {
    coord: [1, 1, 1, 20, 18, 20, 18 , 1],
    type: 'poly'
};
var bbLatLng = new google.maps.LatLng(-33.890542, 151.274856);

var bbMarker = new google.maps.Marker({
    icon: '/images/beachflag.png'
    shape: shape,
    position: bbLatLng,
    map: map
});

קווים פוליגוניים

קו פוליגוני מורכב ממערך של LatLng, וגם מסדרה של קטעי קו שמחברים בין המיקומים האלה ברצף סדור. היצירה וההצגה של אובייקט Polyline בגרסה 3 דומות לשימוש באובייקט GPolyline בגרסה 2. הדוגמאות הבאות משרטטות קו גיאודזי שקוף למחצה וברוחב 3 פיקסלים מציריך עד סידני דרך סינגפור:

var polyline = new GPolyline(
  [
    new GLatLng(47.3690239, 8.5380326),
    new GLatLng(1.352083, 103.819836),
    new GLatLng(-33.867139, 151.207114)
  ],
  '#FF0000', 3, 0.5, {
  geodesic: true
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: [
    new google.maps.LatLng(47.3690239, 8.5380326),
    new google.maps.LatLng(1.352083, 103.819836),
    new google.maps.LatLng(-33.867139, 151.207114)
  ],
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
  geodesic: true
});

polyline.setMap(map);

קווים פוליגוניים מקודדים

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

בדוגמאות הבאות מופיע אותו קו פוליגוני מקודד. קוד v3 משתמש בשיטה decodePath() ממרחב השמות google.maps.geometry.encoding.

var polyline = new GPolyline.fromEncoded({
  points: 'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H',
  levels: 'PPP',
  zoomFactor: 2,
  numLevels: 18,
  color: '#ff0000',
  opacity: 0.8,
  weight: 3
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: google.maps.geometry.encoding.decodePath(
    'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H'),
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
});

polyline.setMap(map);

פוליגונים

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

var map = new GMap2(document.getElementById('map'));

map.setCenter(new GLatLng(24.886436, -70.268554), 5);

var bermudaTriangle = new GPolygon(
  [
    new GLatLng(25.774252, -80.190262),
    new GLatLng(18.466465, -66.118292),
    new GLatLng(32.321384, -64.75737),
    new GLatLng(25.774252, -80.190262)
  ],
  '#FF0000', 2, 0.8, '#FF0000', 0.35);

map.addOverlay(bermudaTriangle);

var map = new google.maps.Map(document.getElementById('map'), {
  center: new google.maps.LatLng(24.886436, -70.268554),
  mapTypeId: google.maps.MapTypeId.TERRAIN,
  zoom: 5
});

var bermudaTriangle = new google.maps.Polygon({
  paths: [
    new google.maps.LatLng(25.774252, -80.190262),
    new google.maps.LatLng(18.466465, -66.118292),
    new google.maps.LatLng(32.321384, -64.75737)
  ],
  strokeColor: '#FF0000',
  strokeWeight: 2,
  strokeOpacity: 0.8,
  fillColor: '#FF0000',
  fillOpacity: 0.35
});

bermudaTriangle.setMap(map);

צורות הניתנות לעריכה

ניתן לערוך למשתמש קווים פוליגוניים ופוליגונים. קטעי הקוד הבאים מקבילים:

map.addOverlay(polyline);
polyline.enableEditing();

polyline.setMap(map);
polyline.setEditable(true);

לקבלת יכולות שרטוט מתקדמות יותר, אפשר לעיין בספריית השרטוטים במסמכי התיעוד של גרסה 3.

חלונות מידע

השדה InfoWindow מציג תוכן בחלון צף מעל המפה. יש כמה הבדלים חשובים בין חלונות מידע של v2 ו-v3:

• ה-API של v2 תומך רק ב-GInfoWindow לכל מפה, ואילו v3 API תומך במספר אירועי InfoWindow בו-זמנית בכל מפה.
• גרסה 3 של InfoWindow תישאר פתוחה כשתלחץ על המפה. V2 GInfoWindow נסגרת באופן אוטומטי בלחיצה על המפה. אפשר לחקות את ההתנהגות של גרסה 2 על ידי הוספת האזנה ל-click באובייקט Map.
• ב-v3 API אין תמיכה מובנית ב-InfoWindow עם כרטיסיות.

שכבות-על של קרקע

כדי למקם תמונה במפה, יש להשתמש באובייקט GroundOverlay. ה-constructor של GroundOverlay זהה בעיקרון ב-v2 וב-v3: הוא מציין את כתובת ה-URL של תמונה ואת גבולות התמונה כפרמטרים.

הדוגמה הבאה מציבה מפה עתיקה של ניוארק, ניו ג'רזי במפה כשכבת-על:

var bounds = new GLatLngBounds(
    new GLatLng(40.716216, -74.213393),
    new GLatLng(40.765641, -74.139235));

var overlay = new GGroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

map.addOverlay(overlay);

var bounds = new google.maps.LatLngBounds(
    new google.maps.LatLng(40.716216, -74.213393),
    new google.maps.LatLng(40.765641, -74.139235));

var overlay = new google.maps.GroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

overlay.setMap(map);

סוגי מפות

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

סוגי מפות נפוצים

ארבעת סוגי המפות הבסיסיים זמינים הן ב-v2 והן ב-v3:

• MapTypeId.ROADMAP (מחליף את G_NORMAL_MAP) מציג את תצוגת מפת הדרכים.
• MapTypeId.SATELLITE (מחליף את G_SATELLITE_MAP) הצגת תמונות לוויין של Google Earth.
• MapTypeId.HYBRID (במקום G_HYBRID_MAP) מציג שילוב של תצוגות רגילות ותמונות לוויין.
• MapTypeId.TERRAIN (מחליף את G_PHYSICAL_MAP) מציג מפה פיזית על סמך מידע על פני השטח.

בהמשך מוצגת דוגמה להגדרת המפה לתצוגת פני שטח בגרסאות v2 ו-v3:

map.setMapType(G_PHYSICAL_MAP);
    

map.setMapTypeId(google.maps.MapTypeId.TERRAIN);
    

כמו כן, ב-Maps JavaScript API v3 בוצעו כמה שינויים בסוגי המפות הפחות נפוצים:

• אריחי מפה של גופים שמימיים שאינם כדור הארץ אינם זמינים כסוגי מפות ב-API של v3, אבל ניתן לגשת אליהם כסוגי מפות מותאמים אישית כפי שמוצג בדוגמה הזו.
• אין סוג מפה מיוחד ב-v3 שמחליף את הסוג G_SATELLITE_3D_MAP מ-v2. במקום זאת, אפשר לשלב את הפלאגין של Google Earth במפות v3 באמצעות הספרייה הזו.

מרחק מקסימלי של תמונות

תמונות לוויין לא תמיד זמינות ברמות זום גבוהות. כדאי להשתמש במחלקה google.maps.MaxZoomService כדי לברר מהי רמת הזום הגבוהה ביותר שזמינה לפני שמגדירים אותה. המחלקה הזו מחליפה את השיטה GMapType.getMaxZoomAtLatLng() מגרסה 2.

var point = new GLatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new GMap2(document.getElementById("map"));
map.setUIToDefault();
map.setCenter(point);
map.setMapType(G_HYBRID_MAP);

map.getCurrentMapType().getMaxZoomAtLatLng(point,
  function(response) {
    if (response.status) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

var myLatlng = new google.maps.LatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new google.maps.Map(
  document.getElementById("map"),{
    zoom: 0,
    center: myLatlng,
    mapTypeId: google.maps.MapTypeId.HYBRID
});
var maxZoomService = new google.maps.MaxZoomService();
maxZoomService.getMaxZoomAtLatLng(
  myLatlng,
  function(response) {
    if (response.status == google.maps.MaxZoomStatus.OK) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

צילומי פרספקטיבה אווירית

כשמפעילים תמונות אוויריות בגרסה 3, הפקדים דומים לפקד GLargeZoomControl3D בגרסה 2, עם פקד סיבוב נוסף של מעברון כדי לסובב את התצוגה במסלולים הנתמכים.

אפשר לעקוב אחרי הערים שבהן זמינות כרגע תמונות ב-45° במפה הזו. כשיש תמונות ב-45 מעלות, מתווספת אפשרות של תפריט המשנה ללחצן 'לוויין' ב-API של מפות Google.

שכבות

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

שכבות נתמכות

ממשק ה-API של v3 מספק גישה לכמה שכבות שונות. השכבות האלה חופפות לסיווג GLayer של גרסה 2 באזורים הבאים:

• האובייקט KmlLayer מעבד רכיבי KML ו-GeoRSS לשכבות-על בגרסה 3, ומספקת את התוצאה המקבילה לשכבת GeoXml v2.
• האובייקט TrafficLayer מעבד שכבה שמתארת את מצב התנועה, בדומה לשכבת-העל של גרסה 2 של GTrafficOverlay.

השכבות האלה שונות מגרסה 2. ההבדלים מתוארים בהמשך. כדי להוסיף אותם למפה, קוראים ל-setMap() ומעבירים אליו את האובייקט Map שבו תוצג השכבה.

מידע נוסף על שכבות נתמכות זמין במאמר מסמכי התיעוד של שכבות.

שכבות KML ו-GeoRSS

ה-API ל-JavaScript של מפות Google תומך בתבניות הנתונים של KML ו-GeoRSS להצגת מידע גיאוגרפי. קובצי ה-KML או ה-GeoRSS חייבים להיות נגישים לציבור אם ברצונך לכלול אותם במפה. בגרסה 3, הפורמטים של הנתונים האלה מוצגים באמצעות מופע של KmlLayer, שמחליף את האובייקט GGeoXml מגרסה 2.

ממשק ה-API של v3 גמיש יותר בעיבוד KML, ויאפשר לך להסתיר את InfoWindows ולשנות את תגובת הקליקים. לפרטים נוספים, עיין בתיעוד של שכבות KML ו-GeoRSS בגרסה 3.

כשמתבצע רינדור של KmlLayer, חלות הגבלות על גודל ומורכבות. לפרטים נוספים, אפשר לעיין במסמכי התיעוד של KmlLayer.

הדוגמאות הבאות ממחישות כיצד לטעון קובץ KML.

geoXml = new GGeoXml(
  'https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml');

map.addOverlay(geoXml);

var layer = new google.maps.KmlLayer(
  'https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml', {
    preserveViewport: true
});
layer.setMap(map);

שכבת התנועה

גרסה 3 מאפשרת להשתמש באובייקט TrafficLayer כדי להוסיף למפות מידע על תנועה בזמן אמת (אם הוא נתמך). מידע על התנועה נמסר בזמן שליחת הבקשה. בדוגמאות הבאות אפשר לראות את נתוני התנועה בלוס אנג'לס:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(34.0492459, -118.241043), 13);
map.setUIToDefault();

var trafficOptions = {incidents:false};
trafficInfo = new GTrafficOverlay(trafficOptions);
map.addOverlay(trafficInfo);

var map = new google.maps.Map(
    document.getElementById('map'), {
  center: new google.maps.LatLng(34.0492459, -118.241043),
  mapTypeId: google.maps.MapTypeId.ROADMAP,
  zoom: 13
});

var trafficLayer = new google.maps.TrafficLayer();
trafficLayer.setMap(map);

שלא כמו v2, אין אפשרויות עבור ה-constructor של TrafficLayer ב-v3. אירועים לא זמינים בגרסה 3.

שירותים

קואורדינטות

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

ה-Geocoding API עבר שדרוג ושופר באופן משמעותי, ונוספו תכונות חדשות ומשנה את אופן ייצוג הנתונים.

GClientGeocoder בגרסה 2 של ה-API סיפקה שתי שיטות שונות לקידוד גיאוגרפי קדימה ולהפך, ושיטות נוספות להשפעה על אופן הביצוע של הקידוד הגיאוגרפי. לעומת זאת, האובייקט Geocoder v3 מספק רק שיטת geocode(), שמשתמשת בליטרל של האובייקט שמכיל את תנאי הקלט (בפורמט של אובייקט Geocoding requests) ושיטת קריאה חוזרת. כאשר הבקשה מכילה מאפיין address בטקסט או אובייקט LatLng, ה-Geocoding API יחזיר תגובה של קידוד גיאוגרפי קדימה או הפוך. כדי להשפיע על אופן הביצוע של הקידוד הגיאוגרפי, אפשר להעביר שדות נוספים לבקשת הקידוד הגיאוגרפי:

• השימוש ב-address טקסטואלי מפעיל קידוד גיאוגרפי קדימה, בדומה לקריאה לשיטה getLatLng().
• הכללת אובייקט latLng מפעילה קידוד גיאוגרפי הפוך, בדומה לקריאה לשיטה getLocations().
• הוספה של המאפיין bounds מאפשרת לבצע הטיה של אזור התצוגה, בדומה לקריאה לשיטה setViewport().
• הוספה של המאפיין region מאפשרת לבצע תעדוף לפי קוד אזור, בדומה לקריאה לשיטה setBaseCountryCode().

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

הקוד הבא לוקח כתובת טקסטואלית ומציג את התוצאה הראשונה מהקידוד הגיאוגרפי שלה:

var geocoder = new GClientGeocoder();
var infoPanel;
var map;
var AccuracyDescription = [
  'Unknown accuracy', 'country level accuracy',
  'region level accuracy', 'sub-region level accuracy',
  'town level accuracy', 'post code level accuracy',
  'street level accuracy', 'intersection level accuracy',
  'address level accuracy', 'premise level accuracy',
];

function geocode_result_handler(response) {
  if (!response || response.Status.code != 200) {
    alert('Geocoding failed. ' + response.Status.code);
  } else {
    var bounds = new GLatLngBounds(new GLatLng(
        response.Placemark[0].ExtendedData.LatLonBox.south,
        response.Placemark[0].ExtendedData.LatLonBox.west
    ), new GLatLng(
        response.Placemark[0].ExtendedData.LatLonBox.north,
        response.Placemark[0].ExtendedData.LatLonBox.east
    ));
    map.setCenter(bounds.getCenter(),
        map.getBoundsZoomLevel(bounds));
    var latlng = new GLatLng(
        response.Placemark[0].Point.coordinates[1],
        response.Placemark[0].Point.coordinates[0]);
    infoPanel.innerHTML += '<p>1st result is <em>' +
        // No info about location type
        response.Placemark[0].address +
        '</em> of <em>' +
        AccuracyDescription[response.Placemark[0].
            AddressDetails.Accuracy] +
        '</em> at <tt>' + latlng + '</tt></p>';
    var marker_title = response.Placemark[0].address +
        ' at ' + latlng;
    map.clearOverlays();

    var marker = marker = new GMarker(
        latlng,
        {'title': marker_title}
    );
    map.addOverlay(marker);
  }
}

function geocode_address() {
  var address = document.getElementById('input-text').value;
  infoPanel.innerHTML = '<p>Original address: ' + address + '</p>';
  geocoder.getLocations(address, geocode_result_handler);
}

function initialize() {
  map = new GMap2(document.getElementById('map'));
  map.setCenter(new GLatLng(38, 15), 2);
  map.setUIToDefault();

  infoPanel = document.getElementById('info-panel');
}

var geocoder = new google.maps.Geocoder();
var infoPanel;
var map;
var marker;

function geocode_result_handler(result, status) {
  if (status != google.maps.GeocoderStatus.OK) {
    alert('Geocoding failed. ' + status);
  } else {
    map.fitBounds(result[0].geometry.viewport);
    infoPanel.innerHTML += '<p>1st result for geocoding is <em>' +
        result[0].geometry.location_type.toLowerCase() +
        '</em> to <em>' +
        result[0].formatted_address + '</em> of types <em>' +
        result[0].types.join('</em>, <em>').replace(/_/, ' ') +
        '</em> at <tt>' + result[0].geometry.location +
        '</tt></p>';
    var marker_title = result[0].formatted_address +
        ' at ' + latlng;
    if (marker) {
      marker.setPosition(result[0].geometry.location);
      marker.setTitle(marker_title);
    } else {
      marker = new google.maps.Marker({
        position: result[0].geometry.location,
        title: marker_title,
        map: map
      });
    }
  }
}

function geocode_address() {
  var address = document.getElementById('input-text').value;
  infoPanel.innerHTML = '<p>Original address: ' + address + '</p>';
  geocoder.geocode({'address': address}, geocode_result_handler);
}

function initialize() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: new google.maps.LatLng(38, 15),
    zoom: 2,
    mapTypeId: google.maps.MapTypeId.HYBRID
  });
  infoPanel = document.getElementById('info-panel');
}

מסלול

Maps JavaScript API v3 מחליף את המחלקה GDirections מ-v2 במחלקה DirectionsService לצורך חישוב המסלול.

השיטה route() בגרסה 3 מחליפה גם את השיטות load() וגם את השיטות loadFromWaypoints() מ-v2 API. בשיטה הזו משתמשים בליטרל אחד של אובייקט DirectionsRequest שמכיל את תנאי הקלט ושיטת קריאה חוזרת, כדי להפעיל אותו כשמקבלים את התגובה. ניתן לתת אפשרויות בליטרל האובייקט הזה, בדומה לליטרל האובייקט GDirectionsOptions בגרסה 2.

ב-Maps JavaScript API v3, המשימה של שליחת בקשות לקבלת מסלול לא חלק מהמשימה של בקשות עיבוד. המשימה מטופלת עכשיו עם המחלקה DirectionsRenderer. ניתן לקשור אובייקט DirectionsRenderer לכל מפה או אובייקט DirectionsResult באמצעות השיטות setMap() ו-setDirections() שלו. מאחר שהרינדור הוא MVCObject, הוא יזהה שינויים במאפיינים שלו ויעדכן את המפה כשהמסלול המשויך ישתנה.

הקוד הבא מדגים איך לבקש מסלול הליכה למיקום ספציפי באמצעות שבילים להולכי רגל מכתובת מסוימת. הערה: רק בגרסה 3 אפשר לספק מסלולי הליכה בשביל להולכי רגל בגן החיות של דבלין.

var map;
var directions;
var directionsPanel;

function initialize() {
  var origin = new google.maps.LatLng(53.348172, -6.297285);
  var destination = new google.maps.LatLng(53.355502, -6.30557);
  directionsPanel = document.getElementById("route");

  map = new GMap2(document.getElementById('map'));
  map.setCenter(origin, 10);
  map.setUIToDefault();

  directions = new GDirections(map, directionsPanel);

  directions.loadFromWaypoints(
      [origin, destination], {
        travelMode: 'G_TRAVEL_MODE_WALKING',
  });
}

var map;
var directionsRenderer;
var directionsService = new google.maps.DirectionsService();

function initialize() {
  var origin = new google.maps.LatLng(53.348172, -6.297285);
  var destination = new google.maps.LatLng(53.355502, -6.30557);
  directionsRenderer = new google.maps.DirectionsRenderer();

  map = new google.maps.Map(
      document.getElementById('map'), {
        center: origin,
        zoom: 10,
        mapTypeId: google.maps.MapTypeId.ROADMAP
  });

  directionsRenderer.setPanel(document.getElementById("route"));
  directionsRenderer.setMap(map);
  directionsService.route({
    origin: origin,
    destination: destination,
    travelMode: google.maps.DirectionsTravelMode.WALKING
  }, function(result, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsRenderer.setDirections(result);
    }
  });
}

Street View

Google Street View מספק תצוגות אינטראקטיביות ב-360° ממיקומים ייעודיים בתוך אזור הכיסוי שלו. v3 API תומך ב-Street View באופן מובנה בתוך הדפדפן, בניגוד לגרסה 2 שבה נדרש הפלאגין Flash® כדי להציג תמונות Street View.

תמונות Street View נתמכות באמצעות האובייקט StreetViewPanorama בגרסה 3, או באמצעות האובייקט GStreetviewPanorama בגרסה 2. למחלקות האלה יש ממשקים שונים, אבל יש להן את אותו התפקיד: חיבור הקונטיינר div לתמונות של Street View ומתן אפשרות לציין את המיקום ואת נקודת המבט (POV) של התמונה הפנורמית ב-Street View.

function initialize() {
  var fenwayPark = new GLatLng(42.345573, -71.098326);
  panoramaOptions = {
    latlng: fenwayPark,
    pov: {
      heading: 35,
      pitch: 5,
      zoom: 1
    }
  };

  var panorama = new GStreetviewPanorama(
      document.getElementById('pano'),
      panoramaOptions);

  GEvent.addListener(myPano, "error", handleNoFlash);
}

function handleNoFlash(errorCode) {
  if (errorCode == FLASH_UNAVAILABLE) {
    alert('Error: Your browser does not support Flash');
    return;
  }
}

function initialize() {
  var fenway = new google.maps.LatLng(42.345573, -71.098326);
  var panoramaOptions = {
    position: fenway,
    pov: {
      heading: 35,
      pitch: 5,
      zoom: 1
    }
  };

  var panorama = new google.maps.StreetViewPanorama(
      document.getElementById('pano'),
      panoramaOptions);
}

גישה ישירה לנתוני Street View אפשרית דרך האובייקט StreetViewService בגרסה 3 או אובייקט GStreetviewClient דומה בגרסה 2. שניהם מספקים ממשקים דומים לאחזור או לבדיקת הזמינות של נתוני Street View, ומאפשרים חיפוש לפי מיקום או מזהה פנורמה.

בגרסה 3, Street View מופעל כברירת מחדל. המפה תופיע עם פקד האטב-איש של Street View, וה-API ישתמש שוב ב-div של המפה כדי להציג תמונות פנורמה של StreetView. הקוד הבא מדגים איך לחקות את ההתנהגות v2 על ידי הפרדת הפנורמות של Street View ל-div נפרד.

var marker;
var panoClient = new GStreetviewClient();

function initialize() {
  if (GBrowserIsCompatible()) {
    var myPano = new GStreetviewPanorama(
        document.getElementById('pano'));
    GEvent.addListener(myPano, 'error', handleNoFlash);
    var map = new GMap2(document.getElementById('map'));
    map.setCenter(new GLatLng(42.345573, -71.098326), 16);
    map.setUIToDefault();

    GEvent.addListener(map, 'click', function(overlay, latlng) {
      if (marker) {
        marker.setLatLng(latlng);
      } else {
        marker = new GMarker(latlng);
        map.addOverlay(marker);
      }
      var nearestPano = panoClient.getNearestPanorama(
          latlng, processSVData);
    });

    function processSVData(panoData) {
      if (panoData.code != 200) {
        alert("Panorama data not found for this location.");
      }
      var latlng = marker.getLatLng();
      var dLat = latlng.latRadians()
          - panoData.location.latlng.latRadians();
      var dLon = latlng.lngRadians()
          - panoData.location.latlng.lngRadians();
      var y = Math.sin(dLon) * Math.cos(latlng.latRadians());
      var x = Math.cos(panoData.location.latlng.latRadians()) *
              Math.sin(latlng.latRadians()) -
              Math.sin(panoData.location.latlng.latRadians()) *
              Math.cos(latlng.latRadians()) * Math.cos(dLon);
      var bearing = Math.atan2(y, x) * 180 / Math.PI;

      myPano.setLocationAndPOV(panoData.location.latlng, {
        yaw: bearing
      });
    }

    function handleNoFlash(errorCode) {
      if (errorCode == FLASH_UNAVAILABLE) {
        alert('Error: Your browser does not support Flash');
        return;
      }
    }
  }
}

// Load the API with libraries=geometry
var map;
var marker;
var panorama;
var sv = new google.maps.StreetViewService();

function radians(degrees) { return Math.PI * degrees / 180.0 };

function initialize() {

  panorama = new google.maps.StreetViewPanorama(
      document.getElementById("pano"));

  map = new google.maps.Map(
      document.getElementById('map'), {
    center: new google.maps.LatLng(42.345573, -71.098326),
    mapTypeId: google.maps.MapTypeId.ROADMAP,
    zoom: 16
  });

  google.maps.event.addListener(map, 'click', function(event) {
    if (!marker) {
      marker = new google.maps.Marker({
          position: event.latLng,
          map: map
      });
    } else {
      marker.setPosition(event.latLng);
    }
    sv.getPanoramaByLocation(event.latLng, 50, processSVData);
  });
}

function processSVData(panoData, status) {
  if (status == google.maps.StreetViewStatus.OK) {
    alert("Panorama data not found for this location.");
  }
  var bearing = google.maps.geometry.spherical.computeHeading(
      panoData.location.latLng, marker.getPosition());

  panorama.setPano(panoData.location.pano);

  panorama.setPov({
    heading: bearing,
    pitch: 0,
    zoom: 1
  });

  panorama.setVisible(true);
  marker.setMap(panorama);
}