טעינת Maps JavaScript API

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

שימוש בייבוא ספרייה דינמי

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

כדי לטעון את Maps JavaScript API, מוסיפים את ה-loader של 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>

אפשר גם להוסיף את קוד ה-loader של 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 שלכם. ממשק API של JavaScript במפות Google לא ייטען אלא אם יצוין מפתח API תקין.

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

  • v: הגרסה של Maps JavaScript API שרוצים לטעון.

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

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

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

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

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

  • channel: מעקב אחר שימוש לכל ערוץ

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

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

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

הוספת תג סקריפט

כדי לטעון את 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 לדוגמה הבאה כוללת placeholders לכל הפרמטרים האפשריים:

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>

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

הפרמטרים הבאים נדרשים בזמן טעינת Maps JavaScript API.

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

פרמטרים אופציונליים (ישיר)

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

  • loading: אסטרטגיית טעינת הקוד שבה יכול להשתמש Maps JavaScript API. מגדירים את הערך async כדי לציין שממשק ה-JavaScript של מפות Google לא נטען באופן סינכרוני ושקוד 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. אם יכול להיות שמפתח ה-API ישמש כתובת URL כלשהי באותו דומיין או מקור, תוכלו להגדיר את auth_referrer_policy=origin כדי להגביל את כמות הנתונים שנשלחים כשנותנים הרשאה לבקשות מ-Maps JavaScript API. האפשרות הזו זמינה החל מגרסה 3.46. כשמציינים את הפרמטר הזה והגבלות על גורמים מפנים מסוג HTTP מופעלות במסוף Cloud, ממשק ה-API של JavaScript במפות Google יוכל לטעון רק אם יש הגבלה על גורם מפנה מסוג 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 { Loader } from "@googlemaps/js-api-loader"

מערך הטעינה חושף ממשק של Promise ושל קריאה חוזרת (callback). בדוגמה הבאה מוצג השימוש בשיטת ברירת המחדל של Promise‏, load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

index.js

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

בדוגמה הבאה מוצג שימוש ב-loader.importLibrary() כדי לטעון ספריות:

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

מעבר ל-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();