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

הצהרת האפליקציה כ-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: מוסיפים מפה עם סמן

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

  • 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." 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

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

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

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

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

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

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

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