הוספת מפה של Google עם סמן באמצעות JavaScript

מבוא

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

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

תחילת העבודה

יש שלושה שלבים ליצירת מפה של Google עם סמן בדף האינטרנט:

  1. קבלת מפתח API
  2. יצירת דף HTML
  3. הוספת מפה עם סמן

צריך דפדפן אינטרנט. בוחרים דפדפן ידוע כמו Google Chrome (מומלץ),‏ Firefox,‏ Safari או Edge, בהתאם לפלטפורמה שלכם, מתוך רשימת הדפדפנים הנתמכים.

שלב 1: קבלת מפתח API

בקטע הזה מוסבר איך לאמת את האפליקציה שלכם ב-Maps JavaScript API באמצעות מפתח API משלכם.

כדי לקבל מפתח API:

  1. נכנסים ל מסוף Google Cloud.

  2. יוצרים או בוחרים פרויקט.

  3. לוחצים על Continue כדי להפעיל את ה-API ואת כל השירותים הקשורים.

  4. בדף Credentials, מקבלים מפתח API (ומגדירים את ההגבלות על מפתח ה-API). הערה: אם יש לכם מפתח API קיים ללא הגבלות, או מפתח עם הגבלות בדפדפן, תוכלו להשתמש במפתח הזה.

  5. במאמר שימוש במפתחות API מוסבר איך למנוע גניבת מכסות ולאבטח את מפתח ה-API.

  6. מפעילים את החיוב. למידע נוסף, ראו שימוש וחיובים.

  7. אחרי שתקבלו מפתח API, תוכלו להוסיף אותו לקטע הקוד הבא בלחיצה על 'YOUR_API_KEY'. מעתיקים ומדביקים את תג הסקריפט של מנהל האתחול כדי להשתמש בו בדף האינטרנט שלכם.

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

שלב 2: יוצרים דף HTML

זהו הקוד של דף אינטרנט בסיסי ב-HTML:

<!doctype html>
<!--
 @license
 Copyright 2019 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->
<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <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>

index.html

שימו לב שזהו דף בסיסי מאוד עם כותרת ברמה שלוש (h3) ורכיב div יחיד. אתם יכולים להוסיף לדף האינטרנט כל תוכן שתרצו.

הבנת הקוד

בשלב הזה בדוגמה, יש לנו:

  • הצהרת על האפליקציה כ-HTML5 באמצעות ההצהרה !DOCTYPE html.
  • יצרנו רכיב div בשם 'map' כדי לאכלס את המפה.
  • הטעינה של ממשק ה-API של JavaScript במפות Google התבצעה באמצעות מטעין ה-bootstrap.

הצהרת האפליקציה כ-HTML5

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

<!DOCTYPE html>

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

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

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

יצירת רכיב div

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

הקוד הבא מגדיר אזור בדף למפת Google.

<!--The div element for the map -->
<div id="map"></div>

בשלב הזה במדריך, הסמל div מופיע כבלוק אפור כי עדיין לא הוספתם מפה. הקוד הבא מתאר את ה-CSS שמגדיר את הגודל והצבע של div.

/* Set the size of the div element that contains the map */
#map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

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

טעינת Maps JavaScript API

מערך האתחול מכין את ממשק ה-JavaScript API של מפות Google לטעינת (לא נטענות ספריות עד שמופיעה הקריאה ל-importLibrary()).

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

הוראות לקבלת מפתח API מפורטות בקטע שלב 3: קבלת מפתח API.

שלב 3: מוסיפים מפה עם סמן

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

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();
index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();
index.js

בקוד שלמעלה, הספריות Map ו-AdvancedMarkerElement נטענות כשקוראים לפונקציה initMap().

הבנת הקוד

בשלב הזה במדריך, יש לנו:

  • הגדרת פונקציית JavaScript שיוצרת מפה ב-div.
  • יצרתם AdvancedMarkerElement כדי להוסיף סמן למפה.

הוספת מפה

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

TypeScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };

// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

// The map, centered at Uluru
map = new Map(
  document.getElementById('map') as HTMLElement,
  {
    zoom: 4,
    center: position,
    mapId: 'DEMO_MAP_ID',
  }
);
index.ts

JavaScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };
// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

// The map, centered at Uluru
map = new Map(document.getElementById("map"), {
  zoom: 4,
  center: position,
  mapId: "DEMO_MAP_ID",
});

index.js

יש שתי אפשרויות חובה לכל מפה: center ו-zoom. בקוד שלמעלה, הפונקציה new Map() יוצרת אובייקט חדש של מפות Google. המאפיין center מציין לממשק ה-API איפה למרכז את המפה.

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

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

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

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

הוסף סמן

הקוד הבא מציב סמן במפה. המאפיין position מגדיר את המיקום של הסמן.

TypeScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: 'Uluru'
});
index.ts

JavaScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: "Uluru",
});
index.js

קוד לדוגמה מלא

הקוד המלא לדוגמה זמין כאן:

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();
index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();
index.js

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

style.css

HTML

<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <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>
index.html

ניסיון של דוגמה

מידע נוסף על סמנים:

טיפים ופתרון בעיות

  • מידע נוסף על הצגת קואורדינטות קו הרוחב/קו האורך או על המרת כתובת לקווי אורך ורוחב
  • אפשר לשנות את האפשרויות כמו סגנון ומאפיינים כדי להתאים אישית את המפה. למידע נוסף על התאמה אישית של מפות, אפשר לעיין במדריכים בנושא עיצוב וציור במפה.
  • אתם יכולים להשתמש במסוף של Developer Tools בדפדפן האינטרנט כדי לבדוק ולהריץ את הקוד, לקרוא דוחות שגיאות ולפתור בעיות בקוד.
  • כדי לפתוח את המסוף ב-Chrome, משתמשים במקשי הקיצור הבאים:
    Command+Option+J (ב-Mac) או Control+Shift+J (ב-Windows).

  • כדי לקבל את קואורדינטות קווי הרוחב והאורך של מיקום מסוים במפות Google, פועלים לפי השלבים הבאים.

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

  • אפשר להמיר כתובת לקווי אורך ורוחב באמצעות שירות הגיאוקוד. במדריכים למפתחים מפורט מידע על תחילת השימוש בשירות הקידוד הגיאוגרפי.