טעינת ממשק ה-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, כפי שמוצג בדוגמת הקוד הבאה:

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

אם הוספתם מפה באמצעות הרכיב gmp-map, הפונקציה initMap() יכולה לטעון ספריות בלי להצהיר על משתנה עבור המחלקות הנדרשות:

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

initMap();

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

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

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

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

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

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

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

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

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

כדי לטעון את ממשק ה-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>

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

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

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

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

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

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

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

• 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, אפשר לטעון את Maps JavaScript API רק אם יש הגבלת הפניה של HTTP שתואמת לדומיין של האתר הנוכחי ללא נתיב שצוין.

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

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

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

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

שימוש בחבילת 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().

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

מעבר ל-Dynamic Library Import API

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

שלבי ההעברה

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

לפני

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