שכבת שרטוט (ספרייה)

1. סקירה כללית
2. שימוש בספרייה
3. אפשרויות של DrawingManager
4. עדכון של אמצעי הבקרה של כלי השרטוט
5. אירועי שרטוט

סקירה כללית

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

שימוש בספרייה

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

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

אחרי שמוסיפים את הפרמטר libraries, אפשר ליצור אובייקט DrawingManager באופן הבא:

var drawingManager = new google.maps.drawing.DrawingManager();
drawingManager.setMap(map);

אפשרויות של DrawingManager

ה-constructor של DrawingManager מקבל קבוצת אפשרויות שמגדירות את קבוצת אמצעי הבקרה שיוצגו, את המיקום של אמצעי הבקרה ואת מצב הציור הראשוני.

• המאפיין drawingMode של DrawingManager מגדיר את מצב הציור הראשוני של DrawingManager. אפשר להזין בו את הקבוע google.maps.drawing.OverlayType. ברירת המחדל היא null, ובמקרה כזה הסמן נמצא במצב ללא ציור כש-DrawingManager מופעל.
• המאפיין drawingControl של DrawingManager מגדיר את ההצגה של ממשק הבחירה של כלי הציור במפה. אפשר להזין בו ערך בוליאני.
• אפשר גם להגדיר את המיקום של הפקדים ואת סוגי שכבות-העל שצריך לייצג בפקדים באמצעות המאפיין drawingControlOptions של DrawingManager.
  • position מגדיר את המיקום של פקדי הציור במפה, ומקבל קבוע של google.maps.ControlPosition.
  • drawingModes הוא מערך של קבועים מסוג google.maps.drawing.OverlayType, והוא מגדיר את סוגי שכבות-העל שרוצים לכלול בבורר הצורות של פקדי השרטוט. סמל היד תמיד יופיע, ויאפשר למשתמש לבצע פעולות במפה בלי לצייר. הסדר של הכלים בפקטור יהיה זהה לסדר שבו הם הוגדרו במערך.
• לכל סוג שכבת-על אפשר להקצות קבוצה של מאפייני ברירת מחדל, שמגדירים את המראה של שכבת-העל בזמן היצירה הראשונה שלה. הם מוגדרים במאפיין {overlay}Options של שכבת-העל הזו (כאשר {overlay} מייצג את סוג שכבת-העל). לדוגמה, אפשר להגדיר את מאפייני המילוי, מאפייני הקו, הערך של zIndex והיכולת ללחוץ על עיגול באמצעות המאפיין circleOptions. אם מועברים ערכים של גודל, מיקום או מפה, המערכת מתעלמת מהם. פרטים מלאים על המאפיינים שאפשר להגדיר מופיעים בחומר העזר בנושא ממשק ה-API.

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

// This example requires the Drawing library. Include the libraries=drawing
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=drawing">

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

  const drawingManager = new google.maps.drawing.DrawingManager({
    drawingMode: google.maps.drawing.OverlayType.MARKER,
    drawingControl: true,
    drawingControlOptions: {
      position: google.maps.ControlPosition.TOP_CENTER,
      drawingModes: [
        google.maps.drawing.OverlayType.MARKER,
        google.maps.drawing.OverlayType.CIRCLE,
        google.maps.drawing.OverlayType.POLYGON,
        google.maps.drawing.OverlayType.POLYLINE,
        google.maps.drawing.OverlayType.RECTANGLE,
      ],
    },
    markerOptions: {
      icon: "https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png",
    },
    circleOptions: {
      fillColor: "#ffff00",
      fillOpacity: 1,
      strokeWeight: 5,
      clickable: false,
      editable: true,
      zIndex: 1,
    },
  });

  drawingManager.setMap(map);
}

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

// This example requires the Drawing library. Include the libraries=drawing
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=drawing">
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
  const drawingManager = new google.maps.drawing.DrawingManager({
    drawingMode: google.maps.drawing.OverlayType.MARKER,
    drawingControl: true,
    drawingControlOptions: {
      position: google.maps.ControlPosition.TOP_CENTER,
      drawingModes: [
        google.maps.drawing.OverlayType.MARKER,
        google.maps.drawing.OverlayType.CIRCLE,
        google.maps.drawing.OverlayType.POLYGON,
        google.maps.drawing.OverlayType.POLYLINE,
        google.maps.drawing.OverlayType.RECTANGLE,
      ],
    },
    markerOptions: {
      icon: "https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png",
    },
    circleOptions: {
      fillColor: "#ffff00",
      fillOpacity: 1,
      strokeWeight: 5,
      clickable: false,
      editable: true,
      zIndex: 1,
    },
  });

  drawingManager.setMap(map);
}

window.initMap = initMap;
index.js

עדכון הפקדים של כלי השרטוט

אחרי שיוצרים את האובייקט DrawingManager, אפשר לעדכן אותו על ידי קריאה ל-setOptions() והעברת ערכים חדשים.

drawingManager.setOptions({
  drawingControlOptions: {
    position: google.maps.ControlPosition.BOTTOM_LEFT,
    drawingModes: ['marker']
  }
});

כדי להסתיר או להציג את הלחצן של כלי הציור:

// To hide:
drawingManager.setOptions({
  drawingControl: false
});

// To show:
drawingManager.setOptions({
  drawingControl: true
});

כדי להסיר את הלחצן של כלי הציור מהאובייקט map:

drawingManager.setMap(null);

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

אירועי שרטוט

כשיוצרים שכבת-על של צורה, מופעלים שני אירועים:

• אירוע {overlay}complete (כאשר {overlay} מייצג את סוג שכבת-העל, למשל circlecomplete,‏ polygoncomplete וכו'). הפניה לשכבת-העל מועברת כארגומנט.
• אירוע overlaycomplete. אובייקט לטיטרל, שמכיל את הערך OverlayType והפניה לשכבת-העל, מועבר כארגומנטים.

google.maps.event.addListener(drawingManager, 'circlecomplete', function(circle) {
  var radius = circle.getRadius();
});

google.maps.event.addListener(drawingManager, 'overlaycomplete', function(event) {
  if (event.type == 'circle') {
    var radius = event.overlay.getRadius();
  }
});

חשוב לדעת שאירועי google.maps.Map, כמו click ו-mousemove, מושבתים בזמן שמשרטטים במפה.