טעינת ממשק ה-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>

אפשר גם להוסיף את קוד ה-loader של Bootstrap ישירות לקוד ה-JavaScript.

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

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:

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: הגרסה של ממשק JavaScript API של מפות Google לטעינה.

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

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

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

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

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

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

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

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

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

הערה: אפשר לקרוא ל-importLibrary לאחר שהתג של הטעינה הישירה של הסקריפט כולל הטעינה הסתיימה.

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

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

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

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

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

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

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

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

• solution_channel: הפלטפורמה של מפות 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
});

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