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

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

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

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

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

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

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

תוכלו גם להוסיף את הקוד של אתחול האתחול ישירות לקוד ה-JavaScript.

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

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

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:

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

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: קוד האזור שבו צריך להשתמש. זה משנה את אופן הפעולה של המפה בהתאם למדינה או לאזור מסוימים.

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

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

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

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

• 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: קוד האזור שבו רוצים להשתמש. כך אפשר לשנות את התנהגות המפה בהתאם למדינה או לאזור מסוימים.

• auth_referrer_policy: הלקוחות יכולים להגדיר במסוף Cloud הגבלות על הגורמים המפנים מסוג HTTP, וכך להגביל את כתובות ה-URL שמורשות להשתמש במפתח API מסוים. כברירת מחדל, אפשר להגדיר את ההגבלות האלה כך שיאפשרו רק לנתיב מסוימים להשתמש במפתח API. אם כתובת URL כלשהי באותו דומיין או מקור יכולה להשתמש במפתח ה-API, אפשר להגדיר את auth_referrer_policy=origin כך שיגביל את כמות הנתונים שנשלחים בעת הרשאת בקשות מה-JavaScript API של מפות Google. התכונה הזו זמינה החל מגרסה 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"

ה-Loader חושף ממשק Promise ו-callback. בדוגמה הבאה תוכלו לראות את השימוש בשיטת ברירת המחדל Promise load().

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

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

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

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

שלבי ההעברה

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

לפני

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