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

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

צורות וקווים

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

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

קווים פוליגוניים

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

הוספת קו פוליגוני

ה-constructor של Polyline מקבל קבוצה של PolylineOptions שמציינים את הקואורדינטות של LatLng של הקו, וקבוצה של סגנונות להתאמת ההתנהגות החזותית של הקו הפוליגוני.

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

הערך strokeColor מציין צבע HTML הקסדצימלי בפורמט "#FFFFFF". הכיתה Polyline לא תומכת בצבעים עם שמות.
‫strokeOpacity מציין ערך מספרי בין 0.0 ל-1.0 כדי לקבוע את אטימות הצבע של הקו. ערך ברירת המחדל הוא 1.0.
‫strokeWeight מציין את רוחב הקו בפיקסלים.

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

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

TypeScript

// This example creates a 2-pixel-wide red polyline showing the path of
// the first trans-Pacific flight between Oakland, CA, and Brisbane,
// Australia which was made by Charles Kingsford Smith.
const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;

async function init() {
    const { Polyline } = await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;

    const flightPlanCoordinates = [
        { lat: 37.772, lng: -122.214 },
        { lat: 21.291, lng: -157.821 },
        { lat: -18.142, lng: 178.431 },
        { lat: -27.467, lng: 153.027 },
    ];
    const flightPath = new Polyline({
        path: flightPlanCoordinates,
        geodesic: true,
        strokeColor: '#FF0000',
        strokeOpacity: 1.0,
        strokeWeight: 2,
    });

    flightPath.setMap(innerMap);
}

void init();index.ts

JavaScript

// This example creates a 2-pixel-wide red polyline showing the path of
// the first trans-Pacific flight between Oakland, CA, and Brisbane,
// Australia which was made by Charles Kingsford Smith.
const mapElement = document.querySelector('gmp-map');
let innerMap;

async function init() {
    const { Polyline } = await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;

    const flightPlanCoordinates = [
        { lat: 37.772, lng: -122.214 },
        { lat: 21.291, lng: -157.821 },
        { lat: -18.142, lng: 178.431 },
        { lat: -27.467, lng: 153.027 },
    ];
    const flightPath = new Polyline({
        path: flightPlanCoordinates,
        geodesic: true,
        strokeColor: '#FF0000',
        strokeOpacity: 1.0,
        strokeWeight: 2,
    });

    flightPath.setMap(innerMap);
}

void init();index.js

להצגת דוגמה

הסרת קו פוליגוני

כדי להסיר קו פוליגוני מהמפה, מפעילים את השיטה setMap() ומעבירים את null כארגומנט. בדוגמה הבאה, flightPath הוא אובייקט קו פוליגוני:

flightPath.setMap(null);

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

בדיקת קו פוליגוני

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

הפונקציה getAt() מחזירה את הערך של LatLng באינדקס נתון שמתחיל באפס.
הפונקציה insertAt() מוסיפה את הערך LatLng שהועבר אליה באינדקס נתון שמתחיל מ-0. חשוב לזכור שכל הקואורדינטות הקיימות בערך האינדקס הזה מועברות קדימה.
הפונקציה removeAt() מסירה LatLng בערך אינדקס נתון שמתחיל בספרה אפס.

הערה: אי אפשר לאחזר את הרכיב ה-i של מערך באמצעות התחביר mvcArray[i]. צריך להשתמש ב-mvcArray.getAt(i).

בדוגמה הבאה מוצגת בנייה של קו פוליגוני על סמך קליקים (לוחצים על המפה כדי להוסיף קודקוד).

TypeScript

/**
 * This example creates an interactive map which constructs a polyline based on
 * user clicks. Note that the polyline only appears once its path property
 * contains two LatLng coordinates.
 */

let poly: google.maps.Polyline;
const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;

async function init() {
    // Import the needed libraries.
    const [{ Polyline }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    innerMap = mapElement.innerMap;

    poly = new Polyline({
        strokeColor: '#000000',
        strokeOpacity: 1.0,
        strokeWeight: 3,
    });
    poly.setMap(innerMap);

    // Handles click events on a map, and adds a new point to the Polyline.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        const latLng = event.latLng;
        if (!latLng) return;

        const path = poly.getPath();

        // Because path is an MVCArray, we can simply append a new coordinate
        // and it will automatically appear.
        path.push(latLng);

        // Add a new marker at the new plotted point on the polyline.
        new AdvancedMarkerElement({
            position: latLng,
            title: '#' + path.getLength(),
            map: innerMap,
        });
    });
}

void init();index.ts

JavaScript

/**
 * This example creates an interactive map which constructs a polyline based on
 * user clicks. Note that the polyline only appears once its path property
 * contains two LatLng coordinates.
 */

let poly;
const mapElement = document.querySelector('gmp-map');
let innerMap;

async function init() {
    // Import the needed libraries.
    const [{ Polyline }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    innerMap = mapElement.innerMap;

    poly = new Polyline({
        strokeColor: '#000000',
        strokeOpacity: 1.0,
        strokeWeight: 3,
    });
    poly.setMap(innerMap);

    // Handles click events on a map, and adds a new point to the Polyline.
    innerMap.addListener('click', (event) => {
        const latLng = event.latLng;
        if (!latLng) return;

        const path = poly.getPath();

        // Because path is an MVCArray, we can simply append a new coordinate
        // and it will automatically appear.
        path.push(latLng);

        // Add a new marker at the new plotted point on the polyline.
        new AdvancedMarkerElement({
            position: latLng,
            title: '#' + path.getLength(),
            map: innerMap,
        });
    });
}

void init();index.js

להצגת דוגמה

התאמה אישית של קו פוליגוני

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

פוליגונים

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

אובייקטים מסוג Polygon יכולים לתאר צורות מורכבות, כולל:

כמה אזורים לא רציפים שמוגדרים על ידי פוליגון אחד.
אזורים עם חורים.
חיתוכים של אזור אחד או יותר.

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

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

הוספת מצולע

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

במצולעים פשוטים שמורכבים מנתיב אחד בלבד, אפשר ליצור Polygon באמצעות מערך אחד של קואורדינטות LatLng. ‫Maps JavaScript API ימיר את המערך הפשוט למערך של מערכים בזמן הבנייה, כשהוא יאחסן אותו במאפיין paths. ה-API מספק שיטת getPath() פשוטה למצולעים שמורכבים ממסלול אחד.

הערה: אם יוצרים פוליגון פשוט בדרך הזו, עדיין צריך לאחזר ערכים מהפוליגון על ידי שינוי הנתיב כ-MVCArray.

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

TypeScript

// This example creates a simple polygon representing the Bermuda Triangle.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 5,
      center: { lat: 24.886, lng: -70.268 },
      mapTypeId: "terrain",
    }
  );

  // Define the LatLng coordinates for the polygon's path.
  const triangleCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
    { lat: 25.774, lng: -80.19 },
  ];

  // Construct the polygon.
  const bermudaTriangle = new google.maps.Polygon({
    paths: triangleCoords,
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

// This example creates a simple polygon representing the Bermuda Triangle.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 5,
    center: { lat: 24.886, lng: -70.268 },
    mapTypeId: "terrain",
  });
  // Define the LatLng coordinates for the polygon's path.
  const triangleCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
    { lat: 25.774, lng: -80.19 },
  ];
  // Construct the polygon.
  const bermudaTriangle = new google.maps.Polygon({
    paths: triangleCoords,
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
}

window.initMap = initMap;index.js

להצגת דוגמה

השלמה אוטומטית של פוליגונים

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

הדוגמה הבאה זהה לדוגמה הקודמת, אבל ה-LatLng האחרון הושמט: לצפייה בדוגמה.

איך מסירים פוליגון

כדי להסיר פוליגון מהמפה, מפעילים את ה-method‏ setMap() ומעבירים את null כארגומנט. בדוגמה הבאה, bermudaTriangle הוא אובייקט פוליגון:

bermudaTriangle.setMap(null);

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

בדיקת פוליגון

בפוליגון, סדרת הקואורדינטות מצוינת כמערך של מערכים, שבהם כל מערך הוא מסוג MVCArray. כל מערך "עלה" הוא מערך של קואורדינטות LatLng שמציינות נתיב אחד. כדי לאחזר את הקואורדינטות האלה, צריך להפעיל את ה-method‏ getPaths() של האובייקט Polygon. מכיוון שהמערך הוא MVCArray, צריך לשנות אותו ולבדוק אותו באמצעות הפעולות הבאות:

הפונקציה getAt() מחזירה את הערך של LatLng באינדקס נתון שמתחיל באפס.
הפונקציה insertAt() מוסיפה את הערך LatLng שהועבר אליה באינדקס נתון שמתחיל מ-0. חשוב לזכור שכל הקואורדינטות הקיימות בערך האינדקס הזה מועברות קדימה.
הפונקציה removeAt() מסירה LatLng בערך אינדקס נתון שמתחיל בספרה אפס.

הערה: אי אפשר לאחזר את הרכיב ה-i של מערך באמצעות התחביר mvcArray[i]. צריך להשתמש ב-mvcArray.getAt(i).

TypeScript

// This example creates a simple polygon representing the Bermuda Triangle.
// When the user clicks on the polygon an info window opens, showing
// information about the polygon's coordinates.

let map: google.maps.Map;

let infoWindow: google.maps.InfoWindow;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    zoom: 5,
    center: { lat: 24.886, lng: -70.268 },
    mapTypeId: "terrain",
  });

  // Define the LatLng coordinates for the polygon.
  const triangleCoords: google.maps.LatLngLiteral[] = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
  ];

  // Construct the polygon.
  const bermudaTriangle = new google.maps.Polygon({
    paths: triangleCoords,
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 3,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);

  // Add a listener for the click event.
  bermudaTriangle.addListener("click", showArrays);

  infoWindow = new google.maps.InfoWindow();
}

function showArrays(event: any) {
  // Since this polygon has only one path, we can call getPath() to return the
  // MVCArray of LatLngs.
  // @ts-ignore
  const polygon = this as google.maps.Polygon;
  const vertices = polygon.getPath();

  let contentString =
    "<b>Bermuda Triangle polygon</b><br>" +
    "Clicked location: <br>" +
    event.latLng.lat() +
    "," +
    event.latLng.lng() +
    "<br>";

  // Iterate over the vertices.
  for (let i = 0; i < vertices.getLength(); i++) {
    const xy = vertices.getAt(i);

    contentString +=
      "<br>" + "Coordinate " + i + ":<br>" + xy.lat() + "," + xy.lng();
  }

  // Replace the info window's content and position.
  infoWindow.setContent(contentString);
  infoWindow.setPosition(event.latLng);

  infoWindow.open(map);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

// This example creates a simple polygon representing the Bermuda Triangle.
// When the user clicks on the polygon an info window opens, showing
// information about the polygon's coordinates.
let map;
let infoWindow;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    zoom: 5,
    center: { lat: 24.886, lng: -70.268 },
    mapTypeId: "terrain",
  });

  // Define the LatLng coordinates for the polygon.
  const triangleCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
  ];
  // Construct the polygon.
  const bermudaTriangle = new google.maps.Polygon({
    paths: triangleCoords,
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 3,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
  // Add a listener for the click event.
  bermudaTriangle.addListener("click", showArrays);
  infoWindow = new google.maps.InfoWindow();
}

function showArrays(event) {
  // Since this polygon has only one path, we can call getPath() to return the
  // MVCArray of LatLngs.
  // @ts-ignore
  const polygon = this;
  const vertices = polygon.getPath();
  let contentString =
    "<b>Bermuda Triangle polygon</b><br>" +
    "Clicked location: <br>" +
    event.latLng.lat() +
    "," +
    event.latLng.lng() +
    "<br>";

  // Iterate over the vertices.
  for (let i = 0; i < vertices.getLength(); i++) {
    const xy = vertices.getAt(i);

    contentString +=
      "<br>" + "Coordinate " + i + ":<br>" + xy.lat() + "," + xy.lng();
  }

  // Replace the info window's content and position.
  infoWindow.setContent(contentString);
  infoWindow.setPosition(event.latLng);
  infoWindow.open(map);
}

window.initMap = initMap;index.js

להצגת דוגמה

איך יוצרים חור בפוליגון

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

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

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

TypeScript

// This example creates a triangular polygon with a hole in it.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 5,
      center: { lat: 24.886, lng: -70.268 },
    }
  );

  // Define the LatLng coordinates for the polygon's  outer path.
  const outerCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
  ];

  // Define the LatLng coordinates for the polygon's inner path.
  // Note that the points forming the inner path are wound in the
  // opposite direction to those in the outer path, to form the hole.
  const innerCoords = [
    { lat: 28.745, lng: -70.579 },
    { lat: 29.57, lng: -67.514 },
    { lat: 27.339, lng: -66.668 },
  ];

  // Construct the polygon, including both paths.
  const bermudaTriangle = new google.maps.Polygon({
    paths: [outerCoords, innerCoords],
    strokeColor: "#FFC107",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FFC107",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

// This example creates a triangular polygon with a hole in it.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 5,
    center: { lat: 24.886, lng: -70.268 },
  });
  // Define the LatLng coordinates for the polygon's  outer path.
  const outerCoords = [
    { lat: 25.774, lng: -80.19 },
    { lat: 18.466, lng: -66.118 },
    { lat: 32.321, lng: -64.757 },
  ];
  // Define the LatLng coordinates for the polygon's inner path.
  // Note that the points forming the inner path are wound in the
  // opposite direction to those in the outer path, to form the hole.
  const innerCoords = [
    { lat: 28.745, lng: -70.579 },
    { lat: 29.57, lng: -67.514 },
    { lat: 27.339, lng: -66.668 },
  ];
  // Construct the polygon, including both paths.
  const bermudaTriangle = new google.maps.Polygon({
    paths: [outerCoords, innerCoords],
    strokeColor: "#FFC107",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FFC107",
    fillOpacity: 0.35,
  });

  bermudaTriangle.setMap(map);
}

window.initMap = initMap;index.js

להצגת דוגמה

מלבנים

בנוסף למחלקה הגנרית Polygon, ‏Google Maps JavaScript API כולל מחלקה ספציפית לאובייקטים מסוג Rectangle, כדי לפשט את הבנייה שלהם.

הוספת מלבן

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

בניגוד ל-Polygon, לא מגדירים paths ל-Rectangle. במקום זאת, למלבן יש מאפיין bounds שמגדיר את הצורה שלו על ידי ציון google.maps.LatLngBounds למלבן.

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

TypeScript

// This example adds a red rectangle to a map.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 11,
      center: { lat: 33.678, lng: -116.243 },
      mapTypeId: "terrain",
    }
  );

  const rectangle = new google.maps.Rectangle({
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
    map,
    bounds: {
      north: 33.685,
      south: 33.671,
      east: -116.234,
      west: -116.251,
    },
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

// This example adds a red rectangle to a map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 11,
    center: { lat: 33.678, lng: -116.243 },
    mapTypeId: "terrain",
  });
  const rectangle = new google.maps.Rectangle({
    strokeColor: "#FF0000",
    strokeOpacity: 0.8,
    strokeWeight: 2,
    fillColor: "#FF0000",
    fillOpacity: 0.35,
    map,
    bounds: {
      north: 33.685,
      south: 33.671,
      east: -116.234,
      west: -116.251,
    },
  });
}

window.initMap = initMap;index.js

להצגת דוגמה

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

TypeScript

// This example creates a rectangle based on the viewport
// on any 'zoom-changed' event.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 11,
      center: { lat: 40.74852, lng: -73.981687 },
      mapTypeId: "terrain",
    }
  );

  const rectangle = new google.maps.Rectangle();

  map.addListener("zoom_changed", () => {
    // Get the current bounds, which reflect the bounds before the zoom.
    rectangle.setOptions({
      strokeColor: "#FF0000",
      strokeOpacity: 0.8,
      strokeWeight: 2,
      fillColor: "#FF0000",
      fillOpacity: 0.35,
      map,
      bounds: map.getBounds() as google.maps.LatLngBounds,
    });
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;index.ts

JavaScript

// This example creates a rectangle based on the viewport
// on any 'zoom-changed' event.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 11,
    center: { lat: 40.74852, lng: -73.981687 },
    mapTypeId: "terrain",
  });
  const rectangle = new google.maps.Rectangle();

  map.addListener("zoom_changed", () => {
    // Get the current bounds, which reflect the bounds before the zoom.
    rectangle.setOptions({
      strokeColor: "#FF0000",
      strokeOpacity: 0.8,
      strokeWeight: 2,
      fillColor: "#FF0000",
      fillOpacity: 0.35,
      map,
      bounds: map.getBounds(),
    });
  });
}

window.initMap = initMap;index.js

להצגת דוגמה

הסרת מלבן

כדי להסיר מלבן מהמפה, מפעילים את השיטה setMap() ומעבירים את null כארגומנט.

rectangle.setMap(null);

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

מעגלים

בנוסף למחלקה הגנרית Polygon, ‏Google Maps JavaScript API כולל מחלקה ספציפית לאובייקטים מסוג Circle, כדי לפשט את הבנייה שלהם.

הוספת מעגל

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

בניגוד ל-Polygon, לא מגדירים paths ל-Circle. במקום זאת, לעיגול יש שני מאפיינים נוספים שמגדירים את הצורה שלו:

‫center מציין את google.maps.LatLng של מרכז המעגל.
‫radius מציין את רדיוס המעגל במטרים.

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

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

TypeScript

const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;

async function init() {
    // Request needed libraries.
    const [{ Circle }, { AdvancedMarkerElement }, { event }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
            google.maps.importLibrary('core'),
        ]);

    // Set the initial map center point.
    const initialCenter = { lat: 34.98956821576194, lng: 135.74239981260283 }; // Hotel Emion, Kyoto, Japan

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

    // Get the buttons.
    const buttons = document.querySelectorAll('input[name="radius"]');

    // Create the circle.
    const walkingCircle = new Circle({
        strokeColor: '#ffdd00ff',
        strokeOpacity: 0.8,
        strokeWeight: 2,
        fillColor: '#ffdd00ff',
        fillOpacity: 0.35,
        map: innerMap,
        center: initialCenter,
        radius: 400,
        draggable: true,
        editable: false,
    });

    // Define a "Crosshair" vector icon
    const parser = new DOMParser();
    const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="-6 -6 12 12"><path d="M -6,0 L 6,0 M 0,-6 L 0,6" stroke="black" stroke-width="1"/></svg>`;

    const pinSvg = parser.parseFromString(
        svgString,
        'image/svg+xml'
    ).documentElement;

    const centerMarker = new AdvancedMarkerElement({
        position: initialCenter,
        title: 'A marker using a custom SVG image.',
        anchorLeft: '-50%',
        anchorTop: '-50%',
    });
    centerMarker.append(pinSvg);
    mapElement.append(centerMarker);

    // Wait for the map to finish drawing its tiles.
    event.addListenerOnce(innerMap, 'tilesloaded', () => {
        // Get the controls div
        const controls = document.getElementById('control-panel');

        // Display controls once map is loaded.
        if (controls) {
            controls.style.display = 'block';
        }
    });

    // Add event listener to update the radius based on user selection.
    buttons.forEach((button) => {
        button.addEventListener('change', (changeEvent) => {
            const target = changeEvent.target as HTMLInputElement;
            walkingCircle.setRadius(Number(target.value));
        });
    });

    // Handle user click, reset the map center and position the circle.
    innerMap.addListener(
        'click',
        (
            mapsMouseEvent:
                google.maps.MapMouseEvent | google.maps.IconMouseEvent
        ) => {
            const newCenter = mapsMouseEvent.latLng;
            if (!newCenter) return;
            walkingCircle.setCenter(newCenter);
            centerMarker.position = newCenter;
            innerMap.panTo(newCenter);
        }
    );

    // Handle user dragging the circle, update the center marker position.
    walkingCircle.addListener('center_changed', () => {
        centerMarker.position = walkingCircle.getCenter();
    });
}

void init();index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;

async function init() {
    // Request needed libraries.
    const [{ Circle }, { AdvancedMarkerElement }, { event }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
            google.maps.importLibrary('core'),
        ]);

    // Set the initial map center point.
    const initialCenter = { lat: 34.98956821576194, lng: 135.74239981260283 }; // Hotel Emion, Kyoto, Japan

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

    // Get the buttons.
    const buttons = document.querySelectorAll('input[name="radius"]');

    // Create the circle.
    const walkingCircle = new Circle({
        strokeColor: '#ffdd00ff',
        strokeOpacity: 0.8,
        strokeWeight: 2,
        fillColor: '#ffdd00ff',
        fillOpacity: 0.35,
        map: innerMap,
        center: initialCenter,
        radius: 400,
        draggable: true,
        editable: false,
    });

    // Define a "Crosshair" vector icon
    const parser = new DOMParser();
    const svgString = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="-6 -6 12 12"><path d="M -6,0 L 6,0 M 0,-6 L 0,6" stroke="black" stroke-width="1"/></svg>`;

    const pinSvg = parser.parseFromString(
        svgString,
        'image/svg+xml'
    ).documentElement;

    const centerMarker = new AdvancedMarkerElement({
        position: initialCenter,
        title: 'A marker using a custom SVG image.',
        anchorLeft: '-50%',
        anchorTop: '-50%',
    });
    centerMarker.append(pinSvg);
    mapElement.append(centerMarker);

    // Wait for the map to finish drawing its tiles.
    event.addListenerOnce(innerMap, 'tilesloaded', () => {
        // Get the controls div
        const controls = document.getElementById('control-panel');

        // Display controls once map is loaded.
        if (controls) {
            controls.style.display = 'block';
        }
    });

    // Add event listener to update the radius based on user selection.
    buttons.forEach((button) => {
        button.addEventListener('change', (changeEvent) => {
            const target = changeEvent.target;
            walkingCircle.setRadius(Number(target.value));
        });
    });

    // Handle user click, reset the map center and position the circle.
    innerMap.addListener('click', (mapsMouseEvent) => {
        const newCenter = mapsMouseEvent.latLng;
        if (!newCenter) return;
        walkingCircle.setCenter(newCenter);
        centerMarker.position = newCenter;
        innerMap.panTo(newCenter);
    });

    // Handle user dragging the circle, update the center marker position.
    walkingCircle.addListener('center_changed', () => {
        centerMarker.position = walkingCircle.getCenter();
    });
}

void init();index.js

CSS

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

#control-panel {
    display: none; /* Set to 'display: block' after the map loads. */
    background-color: #fff;
    border: 2px solid #fff;
    border-radius: 3px;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
    font-family: 'Roboto', sans-serif;
    font-size: medium;
    margin: 10px;
    padding: 10px;
}style.css

HTML

<html>
    <head>
        <title>Circles</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>
        <gmp-map
            center="34.98956821576194, 135.74239981260283"
            zoom="15"
            map-id="DEMO_MAP_ID">
            <div id="control-panel" slot="control-inline-start-block-start">
                <input
                    id="short-walk"
                    type="radio"
                    name="radius"
                    value="400"
                    checked />
                <label for="short-walk">Short Walk (~5 minutes)</label><br />
                <input
                    id="medium-walk"
                    type="radio"
                    name="radius"
                    value="800" />
                <label for="medium-walk">Medium Walk (~15 minutes)</label><br />
                <input id="long-walk" type="radio" name="radius" value="1600" />
                <label for="long-walk">Long Walk (~30 minutes) </label>
            </div>
        </gmp-map>
    </body>
</html>index.html

להצגת דוגמה

הסרת מעגל

כדי להסיר עיגול מהמפה, מפעילים את ה-method‏ setMap() ומעבירים את null כארגומנט.

circle.setMap(null);

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

צורות שהמשתמשים יכולים לערוך ולגרור

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

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

איך הופכים צורה לניתנת לעריכה

אפשר להגדיר כל צורה (קווים פוליגוניים, פוליגונים, עיגולים ומלבנים) כניתנת לעריכה על ידי המשתמש, על ידי הגדרת editable ל-true באפשרויות של הצורה.

var bounds = {
  north: 44.599,
  south: 44.490,
  east: -78.443,
  west: -78.649
};

// Define a rectangle and set its editable property to true.
var rectangle = new google.maps.Rectangle({
  bounds: bounds,
  editable: true
});

להצגת דוגמה

איך הופכים צורה לניתנת לגרירה

כברירת מחדל, צורה שמצוירת במפה תהיה קבועה במיקום שלה. כדי לאפשר למשתמשים לגרור צורה למיקום אחר במפה, מגדירים את draggable ל-true באפשרויות הצורה.

var redCoords = [
  {lat: 25.774, lng: -80.190},
  {lat: 18.466, lng: -66.118},
  {lat: 32.321, lng: -64.757}
];

// Construct a draggable red triangle with geodesic set to true.
new google.maps.Polygon({
  map: map,
  paths: redCoords,
  strokeColor: '#FF0000',
  strokeOpacity: 0.8,
  strokeWeight: 2,
  fillColor: '#FF0000',
  fillOpacity: 0.35,
  draggable: true,
  geodesic: true
});

כשמפעילים גרירה בפוליגון או בקו פוליגוני, כדאי גם להגדיר את המאפיין geodesic של הפוליגון או הקו הפוליגוני כ-true כדי להפוך אותם לגאודזיים.

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

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

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

במפה הבאה מוצגים שני משולשים בגודל ובמידות דומים. המאפיין geodesic של המשולש האדום מוגדר לערך true. שימו לב איך הצורה שלו משתנה כשהוא נע צפונה.

להצגת דוגמה

האזנה לאירועי עריכה

כשעורכים צורה, מופעל אירוע בסיום העריכה. האירועים האלה מפורטים בהמשך.

צורה	אירועים
מעגל	`radius_changed` `center_changed`
פוליגון	`insert_at` `remove_at` `set_at` צריך להגדיר את המאזין בנתיב של המצולע. אם לפוליגון יש כמה נתיבים, צריך להגדיר מאזין לכל נתיב.
מצולע פתוח	`insert_at` `remove_at` `set_at` צריך להגדיר את המאזין בנתיב של הקו הפוליגוני.
מלבן	`bounds_changed`

כמה קטעי קוד שימושיים:

google.maps.event.addListener(circle, 'radius_changed', function() {
  console.log(circle.getRadius());
});

google.maps.event.addListener(outerPath, 'set_at', function() {
  console.log('Vertex moved on outer path.');
});

google.maps.event.addListener(innerPath, 'insert_at', function() {
  console.log('Vertex removed from inner path.');
});

google.maps.event.addListener(rectangle, 'bounds_changed', function() {
  console.log('Bounds changed.');
});

דוגמה לטיפול באירוע עריכה במלבן

האזנה לאירועי גרירה

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

אירוע	תיאור
`dragstart`	מופעל כשהמשתמש מתחיל לגרור את הצורה.
`drag`	מופעל שוב ושוב בזמן שהמשתמש גורר את הצורה.
`dragend`	מופעל כשהמשתמש מפסיק לגרור את הצורה.

מידע נוסף על טיפול באירועים זמין במסמכי התיעוד בנושא אירועים.

גבולות וירטואליים וגבולות של אזורים בטוחים

ב-Google Maps Platform אין Geofencing API נפרד. כדי להציג רדיוס של גבול וירטואלי או אזור בטוח במפה באינטרנט ולבדוק אם קואורדינטה בזמן אמת נמצאת בתוך הגבול הזה, משלבים צורות עם ספריית הגיאומטריה (google.maps.GeometryLibrary) שנטענת דרך google.maps.importLibrary("geometry"):

גבול וירטואלי מעגלי: משרטטים google.maps.Circle (או מעבירים google.maps.CircleLiteral) ובודקים אם הקואורדינטה נמצאת בתוך המעגל באמצעות google.maps.geometry.poly.containsLocation(). אם אתם צריכים גם את המרחק במטרים מ-Circle.getCenter(), אתם יכולים להפעיל את google.maps.geometry.spherical.computeDistanceBetween().
גבולות וירטואליים מצולעים: מציירים google.maps.Polygon ובודקים אם הקואורדינטה נמצאת בתוך המצולע באמצעות google.maps.geometry.poly.containsLocation().
פוליגון במפה תלת-ממדית: במפה תלת-ממדית (צורות וקווים), משרטטים google.maps.maps3d.Polygon3DElement ומעבירים את הקואורדינטות של Polygon3DElement.path אל google.maps.Polygon כשמפעילים את google.maps.geometry.poly.containsLocation().

בדוגמה הבאה מצויר אזור בטוח מעגלי וגבול וירטואלי מצולע, ואז נבדק אם קואורדינטה בזמן אמת נמצאת בתוך כל גבול:

const {Circle, Polygon} = await google.maps.importLibrary("maps");
const {poly} = await google.maps.importLibrary("geometry");

const livePosition = {lat: 37.424, lng: -122.085};

// 1. Circular geofence (500-meter radius)
const circularGeofence = new Circle({
  map,
  center: {lat: 37.422, lng: -122.084},
  radius: 500,
});
const isInsideCircle = poly.containsLocation(livePosition, circularGeofence);

// 2. Polygonal geofence
const polygonGeofence = new Polygon({
  map,
  paths: [
    {lat: 37.420, lng: -122.088},
    {lat: 37.420, lng: -122.080},
    {lat: 37.426, lng: -122.080},
    {lat: 37.426, lng: -122.088},
  ],
});
const isInsidePolygon = poly.containsLocation(livePosition, polygonGeofence);

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

קווים פוליגוניים

הוספת קו פוליגוני

TypeScript

JavaScript

הסרת קו פוליגוני

בדיקת קו פוליגוני

TypeScript

JavaScript

התאמה אישית של קו פוליגוני

פוליגונים

הוספת מצולע

TypeScript

JavaScript

השלמה אוטומטית של פוליגונים

איך מסירים פוליגון

בדיקת פוליגון

TypeScript

JavaScript

איך יוצרים חור בפוליגון

TypeScript

JavaScript

מלבנים

הוספת מלבן

TypeScript

JavaScript

TypeScript

JavaScript

הסרת מלבן

מעגלים

הוספת מעגל

TypeScript

JavaScript

CSS

HTML

הסרת מעגל

צורות שהמשתמשים יכולים לערוך ולגרור

איך הופכים צורה לניתנת לעריכה

איך הופכים צורה לניתנת לגרירה

האזנה לאירועי עריכה

האזנה לאירועי גרירה

גבולות וירטואליים וגבולות של אזורים בטוחים

צורות וקווים