טעינת Maps JavaScript API

במדריך הזה נסביר איך לטעון את Maps JavaScript API. יש שלוש דרכים לעשות זאת:

שימוש בייבוא דינמי של ספריות

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

כדי לטעון את Maps JavaScript API, מוסיפים את טוען ה-bootstrap בתוך השורה לקוד האפליקציה, כמו שמוצג בקטע הקוד הבא:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

אפשר גם להוסיף את קוד טוען ה-bootstrap ישירות לקוד ה-JavaScript.

כדי לטעון ספריות בזמן ריצה, משתמשים באופרטור await כדי לקרוא ל-importLibrary() מתוך פונקציית async. הצהרה על משתנים עבור המחלקות הנדרשות מאפשרת לכם לדלג על שימוש בנתיב מוסמך (למשל google.maps.Map), כפי שמוצג בדוגמת הקוד הבאה:

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.js

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

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await google.maps.importLibrary("maps");
  await google.maps.importLibrary("marker");

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

אפשרות אחרת היא לטעון את הספריות ישירות ב-HTML, כמו שמוצג כאן:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

איך עוברים ל-Dynamic Library Loading API

פרמטרים נדרשים

  • ‫key: מפתח ה-API שלכם. ממשק Maps JavaScript API לא ייטען אם לא מציינים מפתח API תקין.

פרמטרים אופציונליים

  • ‫v: הגרסה של Maps JavaScript API שנטענת.

  • ‫libraries: מערך של ספריות נוספות של Maps JavaScript API שצריך להתחיל לטעון מראש. בדרך כלל לא מומלץ לציין קבוצה קבועה של ספריות, אבל האפשרות הזו זמינה למפתחים שרוצים לכוונן את התנהגות הקאשינג באתר שלהם. עדיין חשוב להפעיל את הפונקציה google.maps.importLibrary() לכל ספרייה שנבחרה לפני השימוש בה.

  • ‫language: השפה שבה רוצים להשתמש. הדבר משפיע על השמות של אמצעי הבקרה, על הודעות זכויות היוצרים, על הוראות הנסיעה ועל תוויות הבקרה, וגם על התגובות לבקשות שירות. כאן אפשר לעיין ברשימת השפות הנתמכות.

  • ‫region: קוד האזור שבו רוצים להשתמש. השינוי הזה משפיע על התנהגות ה-API בהתאם למדינה או לאזור מסוימים.

  • ‫authReferrerPolicy: לקוחות Maps JavaScript יכולים להגדיר הגבלות של מפנה HTTP במסוף Cloud כדי להגביל את כתובות ה-URL שמורשות להשתמש במפתח API מסוים. כברירת מחדל, אפשר להגדיר את ההגבלות האלה כך שרק נתיבים מסוימים יוכלו להשתמש במפתח API. אם יש סיכוי שמפתח ה-API ישמש כתובות URL כלשהן באותו דומיין או באותו מקור, אפשר להגדיר את authReferrerPolicy: "origin" כדי להגביל את כמות הנתונים שנשלחים כשמאשרים בקשות מ-Maps JavaScript API. כשמציינים את הפרמטר הזה וההגבלות על מפנים HTTP מופעלות ב-Cloud Console, אפשר לטעון את ממשק API של JavaScript במפות Google רק אם יש הגבלה על מפנים HTTP שתואמת לדומיין הנוכחי של האתר בלי שצוין נתיב.

  • ‫mapIds: מערך של מזהי מפות. גורם לטעינה מראש של ההגדרה עבור מזהי המפה שצוינו. אין חובה לציין כאן מזהי מפות כדי להשתמש במזהי מפות, אבל האפשרות הזו זמינה למפתחים שרוצים לשפר את ביצועי הרשת.

  • ‫channel: מידע נוסף זמין במאמר בנושא מעקב אחר השימוש בכל ערוץ.

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

שימוש בתג לטעינה ישירה של סקריפט

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

הוספת תג script

כדי לטעון את Maps JavaScript API בשורה בקובץ HTML, מוסיפים תג script כמו בדוגמה שלמטה.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

פרמטרים של כתובת URL לטעינה ישירה של סקריפט

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

בדוגמה הבאה של כתובת URL יש placeholder לכל הפרמטרים האפשריים:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

כתובת ה-URL בתג script בדוגמה הבאה טוענת את Maps JavaScript API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

פרמטרים נדרשים (ישירים) {:.hide-from-toc}

כשמטעינים את Maps JavaScript API, חובה לציין את הפרמטרים הבאים.

  • ‫key: מפתח ה-API שלכם. ממשק ה-API של JavaScript במפות Google לא ייטען אלא אם מצוין מפתח API תקין.

פרמטרים אופציונליים (ישירים) {:.hide-from-toc}

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

  • ‫loading: אסטרטגיית טעינת הקוד ש-Maps JavaScript API יכול להשתמש בה. הערך שמוגדר הוא async כדי לציין שממשק Maps JavaScript API לא נטען באופן סינכרוני ושלא מופעל קוד JavaScript על ידי האירוע load של הסקריפט. מומלץ מאוד להגדיר את האפשרות הזו ל-async כשאפשר, כדי לשפר את הביצועים. (במקום זאת, אפשר להשתמש בפרמטר callback כדי לבצע פעולות כש-Maps JavaScript API זמין). זמין החל מגרסה 3.55.

  • ‫callback: השם של פונקציה גלובלית שתיקרא אחרי ש-Maps JavaScript API ייטען באופן מלא.

  • ‫v: הגרסה של Maps JavaScript API שבה רוצים להשתמש.

  • ‫libraries: רשימה מופרדת בפסיקים של ספריות נוספות של Maps JavaScript API לטעינה.

  • ‫language: השפה שבה רוצים להשתמש. ההגדרה הזו משפיעה על השמות של אמצעי הבקרה, על הודעות זכויות היוצרים, על הוראות הנסיעה ועל תוויות אמצעי הבקרה, וגם על התשובות לבקשות שירות. כאן אפשר לעיין ברשימת השפות הנתמכות.

  • ‫region: קוד האזור שבו רוצים להשתמש. השינוי הזה משפיע על התנהגות ה-API בהתאם למדינה או לאזור מסוימים.

  • ‫auth_referrer_policy: לקוחות יכולים להגדיר הגבלות על גורמים מפנים מסוג HTTP במסוף Cloud כדי להגביל את כתובות ה-URL שיכולות להשתמש במפתח API מסוים. כברירת מחדל, אפשר להגדיר את ההגבלות האלה כך שרק נתיבים מסוימים יוכלו להשתמש במפתח API. אם יש כתובות URL בדומיין או במקור מסוים שעשויות להשתמש במפתח ה-API, אפשר להגדיר את auth_referrer_policy=origin כדי להגביל את כמות הנתונים שנשלחים כשמאשרים בקשות מ-Maps JavaScript API. האפשרות הזו זמינה החל מגרסה 3.46. כשמציינים את הפרמטר הזה וההגבלות על מפנה HTTP מופעלות ב-Cloud Console, אפשר לטעון את Maps JavaScript API רק אם יש הגבלה על מפנה HTTP שתואמת לדומיין הנוכחי של האתר בלי שצוינה נתיב.

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

  • channel: מידע נוסף זמין במאמר בנושא מעקב אחר השימוש בכל ערוץ.

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

שימוש בחבילה js-api-loader של NPM

חבילת ‎@googlemaps/js-api-loader זמינה לטעינה באמצעות מנהל החבילות NPM. מתקינים אותו באמצעות הפקודה הבאה:

npm install @googlemaps/js-api-loader

אפשר לייבא את החבילה הזו לאפליקציה באמצעות:

import { setOptions, importLibrary } from "@googlemaps/js-api-loader"

הטוען משתמש ב-Promises כדי להפוך ספריות לזמינות. ספריות נטענות באמצעות ה-method‏ importLibrary(). בדוגמה הבאה מוצגת טעינה של המחלקה Map:

import { setOptions, importLibrary } from "@googlemaps/js-api-loader";

setOptions({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
});

importLibrary("maps").then(({ Map }) => {
  new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}).catch(e => {
  // do something
});

אפשר גם להשתמש ב-async/await בפונקציה אסינכרונית. בדוגמה הזו נטענות ספריות נוספות:

import { setOptions, importLibrary } from "@googlemaps/js-api-loader";

setOptions({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
});

const { Map } = await importLibrary("maps");
const { AdvancedMarkerElement } = await importLibrary("marker");
const map = new Map(document.getElementById("map"), {
  center: { lat: -34.397, lng: 150.644 },
  zoom: 8,
});
const marker = new AdvancedMarkerElement({
  map,
  position: { lat: -34.397, lng: 150.644 },
});
const { PlaceAutocompleteElement } = await importLibrary("places");
await google.maps.importLibrary("places");
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
document.body.append(placeAutocomplete);

דוגמה עם js-api-loader

מעבר ל-Dynamic Library Import API

בקטע הזה מפורטים השלבים הנדרשים להעברת השילוב לשימוש ב-Dynamic Library Import API.

שלבים בהעברה

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

לפני

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

אחרי

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

לאחר מכן, מעדכנים את קוד האפליקציה:

  • משנים את הפונקציה initMap() לאסינכרונית.
  • מתקשרים אל importLibrary() כדי לטעון את הספריות שצריך ולגשת אליהן.

לפני

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

אחרי

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();