טעינת ממשק ה-API של JavaScript במפות Google

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

• שימוש בייבוא ספרייה דינמית (מומלץ)
• שימוש בחבילת NPM js-api-loader
• להשתמש בתג לטעינת סקריפט ישיר.

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

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

<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>

אתם יכולים גם להוסיף את קוד הטעינה של Botstrap ישירות לקוד ה-JavaScript.

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

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  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,
  });
}

initMap();
index.ts

הערה: מומלץ לקרוא את המדריך בנושא השימוש ב-TypeScript ובמפות Google.

JavaScript

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

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

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

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

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

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

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

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

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

• mapIds: מערך של מזהי המפה. גורם לטעינה מראש של מזהי המפה שצוינו.

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

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

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

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

npm install @googlemaps/js-api-loader

ניתן לייבא את החבילה הזו לאפליקציה באמצעות:

import { Loader } from "@googlemaps/js-api-loader"

הטוען חושף ממשק של הבטחה וקריאה חוזרת (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

הערה: מומלץ לקרוא את המדריך בנושא השימוש ב-TypeScript ובמפות Google.

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
});

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

בקטע הזה מוסבר איך משתמשים בתג הטעינה של הסקריפט הישיר. Google ממליצה לעבור ל-Dynamic Library Browser API.

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

כדי לטעון את ה-API ל-JavaScript של מפות Google בצורה מוטבעת בקובץ HTML, צריך להוסיף תג script כמו שמתואר בהמשך.

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

סקריפט ישיר טוען פרמטרים של כתובת אתר

הקטע הזה עוסק בכל הפרמטרים שאפשר לציין במחרוזת השאילתה של כתובת ה-URL לטעינת הסקריפט במהלך טעינת ה-API ל-JavaScript של מפות Google. יש פרמטרים מסוימים שנדרשים, והפרמטרים האחרים הם אופציונליים. כמו שקורה בכתובות 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 טוענת את ה-API ל-JavaScript של מפות Google:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  הערה: פרמטר השאילתה הזה מיועד לשימוש של Google. למידע נוסף, ראו פרמטר הפתרונות של הפלטפורמה של מפות Google.

מעבר לממשק ה-API לייבוא ספריות דינמיות

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

שלבי ההעברה

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

לפני

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&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();