סקירה כללית

בחירת פלטפורמה: Android iOS JavaScript

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

קהל

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

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

שלום עולם

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

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

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

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
להצגת דוגמה

רוצה לנסות דוגמה?

גם בדוגמה הפשוטה הזו, יש כמה דברים שחשוב לשים לב אליהם:

  1. אנחנו מצהירים על האפליקציה כ-HTML5 באמצעות ההצהרה <!DOCTYPE html>.
  2. אנחנו יוצרים רכיב div בשם 'מפה' כדי להחזיק את המפה.
  3. אנחנו מגדירים פונקציית JavaScript שיוצרת מפה באמצעות div.
  4. אנו טוענים את Maps JavaScript API באמצעות טוען האתחול.

שלבים אלה מוסברים להלן.

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

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

מידע נוסף זמין במאמר טעינת ה-API של JavaScript של מפות Google.

טוען אתחול

צריך לטעון את 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>

כדי לטעון ספריות בזמן ריצה, צריך להשתמש באופרטור await כדי להפעיל את importLibrary() מתוך פונקציה אסינכרונית:

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

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

חבילת NPM js-api-loader

השתמשו ב-@googlemaps/js-api-loader כדי להשתמש ב-NPM כדי לטעון את ה-API של JavaScript במפות. מתקינים אותו דרך 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,
  });
});

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

הצהירו על האפליקציה שלכם כ-HTML5

מומלץ להצהיר על DOCTYPE אמיתי באפליקציית האינטרנט שלך. בדוגמאות שכאן, הצהרתנו על האפליקציות שלנו כ-HTML5, באמצעות שימוש ב-DOCTYPEHTML5 פשוט של HTML5, כמוצג למטה:

<!DOCTYPE html>

רוב הדפדפנים הנוכחיים יעבדו תוכן שהוצהר באמצעות DOCTYPE הזה ב'מצב סטנדרטי', כלומר, האפליקציה צריכה לעמוד בדרישות מסוימות יותר של דפדפנים. הפונקציה DOCTYPE גם תוכננה כך שהיא תיפגע בצורה חיננית. דפדפנים שלא מבינים אותו יתעלמו ממנו וישתמשו ב'מצב תאימות (quirks mode)' כדי להציג את התוכן.

שימו לב שחלק משירות ה-CSS שפועל במצב תאימות (quirks) לא פועל במצב רגיל. באופן ספציפי, כל הגדלים שמבוססים על אחוזים חייבים לרשת מרכיבי בלוק הורה. אם אחד מאבות האב לא מצליח לציין גודל, ההנחה היא שהגודל הוא 0 x 0 פיקסלים. לכן כללנו כאן את הצהרת <style> הבאה:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

הצהרת ה-CSS הזו מציינת שמאגר המפה <div> (עם המזהה map) צריך לתפוס 100% מהגובה של גוף ה-HTML. לתשומת ליבך, עלינו להצהיר במפורש גם על האחוזים האלה עבור <body> ו-<html>.

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

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

טעינה מוטבעת

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

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

טעינה דינמית

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

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);
      

טעינה דינמית

החבילה @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,
  });
});

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

מאפיינים של תג סקריפט

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

  • src: כתובת ה-URL שממנה נטען API JavaScript של מפות Google, כולל כל הסמלים וההגדרות שנדרשים כדי להשתמש ב-API של JavaScript במפות Google. כתובת ה-URL בדוגמה הזו כוללת שני פרמטרים: key, שבו מציינים את מפתח ה-API, ו-callback, שבו מציינים את השם של פונקציה גלובלית שנקראת לאחר טעינה מלאה של ה-API של JavaScript במפות. מידע נוסף על פרמטרים של כתובות אתרים.
  • async: בקשה לדפדפן להוריד ולהפעיל את הסקריפט באופן אסינכרוני. כשהסקריפט מופעל, הוא יפעיל את הפונקציה שצוינה באמצעות הפרמטר callback.

ספריות

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

מיפוי רכיבי DOM

<div id="map"></div>

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

בדוגמה שלמעלה, השתמשנו ב-CSS כדי להגדיר את הגובה של div המפה כ-"100%". התמונה הזו תורחב להתאמה לגודל במכשירים ניידים. ייתכן שיהיה צורך להתאים את ערכי הרוחב והגובה בהתאם לגודל המסך ולמרווח הפנימי של הדפדפן. חשוב לשים לב שתגי div בדרך כלל לוקחים את הרוחב שלהם מהאלמנט שמכיל אותם, ותגי div ריקים בדרך כלל מקבלים גובה 0. מסיבה זו, יש להגדיר תמיד גובה ב-<div> באופן מפורש.

אפשרויות מפה

יש שתי אפשרויות נדרשות לכל מפה: center ו-zoom.

map = new Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

רמות מרחק התצוגה

הרזולוציה הראשונית שבה ניתן להציג את המפה מוגדרת על ידי המאפיין zoom, שבו מרחק התצוגה 0 תואם למפה של כדור הארץ שהתרחקה לחלוטין, ורמות זום גדולות יותר התקרבות ברזולוציה גבוהה יותר.

zoom: 8

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

  • 1: עולם
  • 5: ארץ/יבשת
  • 10: עיר
  • 15: רחובות
  • 20: בניינים

שלוש התמונות הבאות משקפות את אותו המיקום של טוקיו ברמות הזום של 0, 7 ו-18.

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

אובייקט המפה

map = new Map(document.getElementById("map"), {...});

המחלקה של JavaScript שמייצגת מפה היא המחלקה Map. אובייקטים במחלקה הזו מגדירים מפה אחת בדף. (אפשר ליצור יותר ממופע אחד של המחלקה – כל אובייקט יגדיר מפה נפרדת בדף). אנחנו יוצרים מכונה חדשה של המחלקה הזו באמצעות האופרטור new של JavaScript.

כשיוצרים מופע חדש של מפה, צריך לציין רכיב HTML מסוג <div> בדף כמאגר של המפה. צומתי HTML הם צאצאים של האובייקט document של JavaScript, ואנחנו מקבלים הפניה לרכיב הזה באמצעות ה-method document.getElementById().

הקוד הזה מגדיר משתנה (בשם map) ומקצה אותו לאובייקט Map חדש. הפונקציה Map() נקראת בונה וההגדרה שלה מוצגת כאן:

יצרן התיאור
Map(mapDiv:Node, opts?:MapOptions ) יצירת מפה חדשה בתוך מאגר ה-HTML הנתון — שהוא בדרך כלל רכיב DIV — באמצעות כל אחד מהפרמטרים (אופציונלי) שמועברים.

פתרון בעיות

שגיאות במפתח API ובחיוב

בנסיבות מסוימות, ניתן להציג מפה כהה או תמונת Street View 'שלילית', שמסומנת כסימן מים עם הטקסט 'למטרות פיתוח בלבד'. ההתנהגות הזו בדרך כלל מצביעה על בעיות במפתח API או בחיוב. כדי להשתמש במוצרי הפלטפורמה של מפות Google צריך להפעיל את החיוב בחשבון, ובכל הבקשות לכלול מפתח API תקין. התהליך הבא יעזור לפתור את הבעיה:

אם הקוד לא עובד:

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

  • מחפשים שגיאות הקלדה. חשוב לזכור ש-JavaScript היא שפה תלוית אותיות רישיות.
  • בודקים את היסודות – חלק מהבעיות הנפוצות ביותר מתרחשות במהלך יצירת המפה הראשונית. למשל:
    • עליך לוודא שציינת את המאפיינים zoom ו-center באפשרויות המפה.
    • מוודאים שהצהרתם על רכיב div שבו המפה תופיע במסך.
    • יש לוודא שלרכיב ה-div של המפה יש גובה. כברירת מחדל, רכיבי div נוצרים בגובה 0 ולכן הם בלתי נראים.
    אפשר להיעזר בדוגמאות שלנו להטמעה של קובצי עזר.
  • אפשר להשתמש בכלי לניפוי באגים של JavaScript כדי לזהות בעיות, כמו הבעיה שזמינה בכלים למפתחים ב-Chrome. קודם כל צריך לחפש שגיאות בלוח JavaScript.
  • אפשר לפרסם שאלות באתר Stack Overflow. הנחיות לפרסום שאלות מוצלחות זמינות בדף Support.