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

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

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

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

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

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

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

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

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

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

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

• v: הגרסה של ממשק JavaScript API של מפות Google לטעינה.

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

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

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

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

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