‫ Places UI Kit: ספרייה מוכנה לשימוש שמאפשרת למפתחים להתאים אישית ולשלוט. כדאי לנסות ולשתף את המשוב שלך על חוויית השימוש בערכת ממשק המשתמש.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

מבוא

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

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

תחילת העבודה

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

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

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

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

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

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

נכנסים ל מסוף Google Cloud.
יוצרים או בוחרים פרויקט.
לוחצים על Continue כדי להפעיל את ה-API ואת כל השירותים שקשורים אליו.
בדף Credentials, מקבלים מפתח API (ומגדירים את ההגבלות על מפתח ה-API). הערה: אם יש לכם מפתח API קיים ללא הגבלות, או מפתח עם הגבלות על דפדפנים, אתם יכולים להשתמש בו.
כדי למנוע גניבת מכסות ולאבטח את מפתח ה-API, קראו את המאמר שימוש במפתחות API.
מפעילים את החיוב. למידע נוסף, קראו את המאמר שימוש וחיוב.

אחרי שמקבלים מפתח 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 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

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

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

זהו דף HTML בסיסי מאוד שמשתמש ברכיב gmp-map כדי להציג מפה בדף. המפה תהיה ריקה כי עדיין לא הוספנו קוד JavaScript.

הבנת הקוד

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

הצהרתם על האפליקציה כ-HTML5 באמצעות ההצהרה !DOCTYPE html.
טעינה של Maps JavaScript API באמצעות רכיב טעינה להפעלת API.
יצרנו רכיב gmp-map שיכיל את המפה.

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

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

<!DOCTYPE html>

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

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

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

טעינת Maps JavaScript API

רכיב הטעינה להפעלת ה-API מכין את Maps JavaScript API לטעינה (לא נטענות ספריות עד שמתבצעת קריאה ל-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>

בשלב 3: קבלת מפתח API מוסבר איך לקבל מפתח API משלכם.

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

יצירת רכיב `gmp-map`

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

הקוד הבא מגדיר את הרכיב gmp-map ומגדיר את הפרמטרים center,‏ zoom ו-map-id.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

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

רמות זום

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

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

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

הקוד הבא מתאר את ה-CSS שמגדיר את הגודל של הרכיב gmp-map.

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

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

שיבוץ רכיבים אינטראקטיביים

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

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

‫שלב 3: מוסיפים קוד JavaScript

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

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();index.ts

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();index.js

הקוד שלמעלה מבצע את הפעולות הבאות כשמתבצעת קריאה ל-initMap():

טוען את הספריות maps ו-marker.
מקבלת את רכיב המפה מה-DOM.
מגדירה אפשרויות מפה נוספות במפה הפנימית.
הוספת סמן למפה.

קבלת אובייקט המפה והגדרת האפשרויות

המשתנה innerMap מייצג מופע של המחלקה Map. כדי להגדיר את אפשרויות המפה, מקבלים את המכונה innerMap מרכיב המפה וקוראים ל-setOptions. בקטע הקוד הבא אפשר לראות איך מקבלים את המופע של innerMap מה-DOM, ואז קוראים ל-setOptions:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

מחכים שהמפה תיטען.

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

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

כך הקוד יופעל רק אחרי שהמפה תיטען. ה-handler מופעל רק פעם אחת במהלך מחזור החיים של האפליקציה.

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

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

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();index.ts

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-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 a Map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <!-- The map, centered at Uluru, Australia. -->
        <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
            <div id="controls" slot="control-inline-start-block-start">
                <h3>My Google Maps Demo</h3>
            </div>
        </gmp-map>
    </body>
</html>index.html

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

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

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

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

מבוא

תחילת העבודה

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

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

הבנת הקוד

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

טעינת Maps JavaScript API

יצירת רכיב gmp-map

רמות זום

שיבוץ רכיבים אינטראקטיביים

‫שלב 3: מוסיפים קוד JavaScript

TypeScript

JavaScript

קבלת אובייקט המפה והגדרת האפשרויות

מחכים שהמפה תיטען.

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

TypeScript

JavaScript

CSS

HTML

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

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

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

יצירת רכיב `gmp-map`