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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

npm install @googlemaps/js-api-loader

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

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

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

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

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

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

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

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

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

הקטע הזה עוסק בכל הפרמטרים שאפשר לציין במחרוזת השאילתה של כתובת ה-URL שטוענת את הסקריפט, במהלך טעינת ה-API של JavaScript של מפות Google. חלק מהפרמטרים הם אופציונליים ואחרים הם אופציונליים. כמקובל בכתובות URL, כל הפרמטרים מופרדים באמצעות תו האמפרסנד (&).

כתובת ה-URL לדוגמה הבאה כוללת placeholders לכל הפרמטרים האפשריים:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&solution_channel="SOLUTION_IDENTIFIER"
&auth_referrer_policy="AUTH_REFERRER_POLICY"

כתובת ה-URL בדוגמה הבאה של התג script טוענת את Maps JavaScript API:

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

הפרמטרים הנדרשים (קודמים)

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

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

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

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

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

• v: הגרסה של API JavaScript של מפות Google.

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

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

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

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

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

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

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

בקטע הזה מוסברים השלבים הדרושים להעברת השילוב לצורך שימוש ב-Dynamic Library Import API.

שלבי ההעברה

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

לפני

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