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

נתיבי העברה של KmlLayer

מבוא

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

נתיב ההעברה תלוי באופן השימוש ב-KmlLayer:

קובץ KML לעיצוב מידע על גבולות/אזורים שמעניינים : אפשר להשתמש בסגנון מבוסס-נתונים (DDS) לגבולות של אזורים אדמיניסטרטיביים באמצעות נתוני הגבולות של Google.
קובץ KML עם נתוני וקטור (נקודות, קווים, גבולות, מצולעים): אפשר להשתמש ב-DDS למערכי נתונים, ב-GeoJSON או בספריות של צד שלישי כמו deck.gl או geoxml3.
קובץ KML עם רכיבים אינטראקטיביים: הטמעה של מאזיני אירועים ידניים וחלונות מידע בהתאמה אישית לאינטראקציה עם תכונות.
קובץ KML עם תמונות: משתמשים ב-GroundOverlays או בכלי ניתוח של צד שלישי לשכבות-על של תמונות.
קובץ KML עם קישורי רשת: מעלים כל קובץ KML כקבוצת נתונים נפרדת, או ממזגים קובצי KML. אם מוצגים נתונים דינמיים, צריך לרענן את מערך הנתונים באמצעות Datasets API.
שימוש ב-KML להצגת שכבות-על של מסך: אפשר להשתמש באמצעי בקרה בהתאמה אישית כדי להחליף רכיבי ממשק משתמש קבועים כמו סמלי לוגו, מקראים או עזרים לניווט.

קובץ KML לעיצוב מידע על גבולות, אזורים או אזורי עניין

מפתחים שמשתמשים ב-KmlLayer כדי להציג או לעצב גבולות אדמיניסטרטיביים – למשל, כדי להדגיש מדינה, מדינה או רשות מוניציפאלית ספציפיים – מומלץ להם לעבור אל סגנון מבוסס-נתונים (DDS) לגבולות ב-Google Maps Platform.

המלצה להעברה: סגנון מבוסס-נתונים לגבולות

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

זמין FeatureType

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

‫COUNTRY: הישות הפוליטית הלאומית.
‫ADMINISTRATIVE_AREA_LEVEL_1: חלוקה מנהלית מדרגה ראשונה מתחת לרמה הארצית (לדוגמה, מדינות בארה"ב).
‫ADMINISTRATIVE_AREA_LEVEL_2: חלוקה מנהלית מדרגה שנייה מתחת לרמה הארצית (לדוגמה, מחוזות בארה"ב).
‫LOCALITY: עיר או עיירה מאוגדות.
‫POSTAL_CODE: מיקודים שמשמשים למשלוח דואר.
‫SCHOOL_DISTRICT: מחוזות בתי ספר מאוחדים, יסודיים או על-יסודיים.

כאן אפשר לראות את האזורים שבהם סוגי התכונות האלה זמינים.

איך מסמנים אזור

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

הגדרה: צריך להשתמש במזהה מפה שהוגדר לסוג המפה וקטור של JavaScript ולהפעיל את שכבת התכונות שזמינה ב-Google Cloud Console.
הטמעה: משתמשים בקוד לדוגמה Style a boundary polygon.

הגבלת ההזזה לאזור מסוים

כדי למנוע ממשתמשים לנווט מחוץ לתיבת התוחמת של האזור המודגש, אפשר להשתמש באפשרות restriction בתוך MapOptions.

האובייקט restriction מגדיר את latLngBounds שמגביל את האזור שניתן לראות במפה. פרטים נוספים על אופן הפעולה של ההגבלה מופיעים במאמרי העזרה.

// Restrict panning to a specific bounding box
restriction: {
  latLngBounds: {
    north: 47.8,
    south: 45.8,
    east: 10.5,
    west: 5.9,
  },
  strictBounds: true,
},

סיכום הטמעת ההעברה

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

const myTargetRegion = "ChIJYW1Zb-9kjEcRFXvLDxG1Vlw"; // Place ID for Switzerland

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 46.8, lng: 8.2 },
    zoom: 9,
    mapId: "YOUR_MAP_ID", // Required for DDS
    // Restrict panning to a specific bounding box
    restriction: {
    // Bounding box for Switzerland
      latLngBounds: {
        north: 47.8,
        south: 45.8,
        east: 10.5,
        west: 5.9,
      },
      strictBounds: true,
    },
  });

  // Access the Country layer and style a specific region by Place ID
  const countryLayer = map.getFeatureLayer("COUNTRY");
  countryLayer.style = (options) => {
    if (options.feature.placeId === myTargetRegion) {
      return {
        fillColor: "#FF0000",
        fillOpacity: 0.5,
        strokeColor: "#FF0000",
        strokeWeight: 2,
      };
    } else {
    // Style everything else whited out, to make the area of interest pop out more.
      return {
        fillColor: '#ffffff',
        fillOpacity: 0.8,
      };
    }
  };
}

קובץ KML עם נתוני וקטור (נקודות, קווים, גבולות, מצולעים)

המלצה להעברה: סגנון מבוסס-נתונים למערכי נתונים

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

האפשרות 'סגנון מבוסס-נתונים' לקבוצות נתונים מאפשרת לכם להעלות נתונים גיאו-מרחביים משלכם (KML,‏ GeoJSON או CSV), להחיל סגנון מותאם אישית על סמך מאפייני הנתונים ולהציג תכונות במפות וקטוריות.

1. הגדרה והעלאה

בניגוד ל-KmlLayer, ששולף כתובת URL בזמן ריצה, ב-DDS צריך לארח את הנתונים כמערך נתונים במסוף Google Cloud.

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

2. הגדרת אזור התצוגה לנתונים

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

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

3. עיצוב ממאפייני תכונה

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

דוגמה: פונקציית סגנון באמצעות מאפיינים

בדוגמה הבאה מוצג אופן היצירה של פונקציית סגנון שקוראת את המאפיינים background_color ו-opacity ישירות ממערך הנתונים שהועלה:

/**
 * Migration example: Styling features from dataset attributes.
 */
function styleDDSLayer(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Set the style function
  datasetLayer.style = (params) => {
    // Access attributes defined in your KML/Dataset
    const featureAttributes = params.feature.datasetAttributes;

    // Read style values from attributes, with fallback defaults
    const fillColor = featureAttributes['background_color'] || '#4285F4';
    const fillOpacity = parseFloat(featureAttributes['opacity']) || 0.5;
    const strokeColor = featureAttributes['border_color'] || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: fillOpacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
    };
  };
}

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

המלצה להעברה: רינדור בצד הלקוח עם GeoJSON

למפתחים שעוברים מ-KmlLayer לרינדור בצד הלקוח באמצעות GeoJSON, Google Maps Platform ממליצה על נתיב העברה שכולל המרה של פורמט הנתונים ושימוש בשכבת הנתונים כדי לרנדר ולעצב תכונות ישירות בדפדפן.

הצגה בצד הלקוח באמצעות שכבת הנתונים מספקת דרך גמישה מאוד להצגת נתונים גיאוגרפיים. שלא כמו KmlLayer, שמוצג בשרתים של Google, שכבת הנתונים מאפשרת לכם לקיים אינטראקציה עם התכונות כאובייקטים רגילים של JavaScript. עם זאת, במערכי נתונים גדולים, יכול להיות שתעדיפו עיבוד והצגה של הנתונים בצד השרת, למשל באמצעות Data-driven Styling for Datasets.

1. המרת KML ל-GeoJSON

השלב הראשון הוא להמיר את קובצי ה-KML ל-GeoJSON. אפשר לעשות את זה באמצעות כמה כלים פופולריים של קוד פתוח:

‫ogr2ogr: כלי שורת פקודה רב-עוצמה, שמהווה חלק מחבילת GDAL, יכול להמיר בין הרבה פורמטים של וקטורים.

ogr2ogr -f GeoJSON output.json input.kml

‫togeojson: כלי קטן שנבדק היטב ומיועד במיוחד להמרה של KML ו-GPX ל-GeoJSON.

togeojson input.kml > output.json

2. הגדרת אזור התצוגה לנתונים

כשמשתמשים ב-KmlLayer, המפה עוברת אוטומטית למיקום הנתונים ומתבצעת התאמה של התצוגה (pan ו-zoom), אבל שכבת הנתונים לא עוברת. כדי להגדיר את אזור התצוגה כך שיתאים לנתוני ה-GeoJSON, צריך לחשב ידנית את התיבה התוחמת ולקרוא ל-map.fitBounds().

3. עיצוב ממאפייני תכונה

בשכבת הנתונים, אפשר להגדיר styleפונקציה שקוראת מאפיינים (properties) ישירות מכל רכיב GeoJSON כדי לקבוע את המראה שלו.

דוגמה: פונקציית סגנון והתאמה של אזור התצוגה

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

/**
 * Migration example: Loading GeoJSON, fitting viewport, and styling from attributes.
 */
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -28, lng: 137 },
  });

  // Load the GeoJSON data
  map.data.loadGeoJson('path/to/your/data.json', null, (features) => {
    // Adjust viewport to show all loaded features
    const bounds = new google.maps.LatLngBounds();
    features.forEach((feature) => {
      feature.getGeometry().forEachLatLng((latlng) => {
        bounds.extend(latlng);
      });
    });
    map.fitBounds(bounds);
  });

  // Set the style function to read from GeoJSON properties
  map.data.setStyle((feature) => {
    // Access attributes defined in your GeoJSON properties
    const fillColor = feature.getProperty('background_color') || '#4285F4';
    const opacity = parseFloat(feature.getProperty('opacity')) || 0.5;
    const strokeColor = feature.getProperty('border_color') || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: opacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
      visible: true
    };
  });
}

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

נתיב ההעברה: רינדור בצד הלקוח באמצעות ספריות צד שלישי

למפתחים שמחפשים חלופות אחרות ל-KmlLayer, יש כמה ספריות שמתוחזקות על ידי הקהילה ומעבדות נתוני KML ב-JavaScript API של הפלטפורמה של מפות Google.

‫1. deck.gl

‫deck.gl הוא מסגרת ויזואליזציה עם ביצועים גבוהים שמבוססת על WebGL. אפשר להשתמש בו כמעט במקום עיבוד KML באמצעות GoogleMapsOverlay ו-GeoJsonLayer.

דרישות Canvas: כדי להשתמש ב-deck.gl בצורה יעילה, צריך להמיר את המפה לשימוש בסוג המפה הווקטורית (שמוצגת כרכיב Canvas) עם יכולות העיבוד שלה ב-WebGL.
תמיכה ב-KML: ניתוח הגיאומטריה מתבצע על ידי @loaders.gl/kml, שממיר KML ל-GeoJSON. שימו לב: יכול להיות שיהיה צורך בהטמעה ידנית נוספת של חלק מהתכונות של KML, כמו סגנונות מורכבים, סמלים ו-NetworkLinks.
מסמכים: תיעוד של deck.gl | loaders.gl KML Loader.
דוגמאות:
- הדוגמה deckgl-kml-updated במאגר GitHub של מפות Google מדגימה איך להשתמש ב-deck.gl כדי לעבד נתוני KML שמתעדכנים בזמן אמת.
- בדוגמה deckgl-kml מוצג איך להשתמש ב-deck.gl כדי לעבד נתוני KML.

‫2. geoxml3

‫geoxml3 הוא מעבד KML שתוכנן במיוחד עבור Google Maps JavaScript API v3. הוא מנתח את קובץ ה-KML באופן מקומי בדפדפן ומעבד את הנתונים כאובייקטים רגילים של Google Maps API, כמו סמנים, קווים מצולעים ומצולעים.

תמיכה במפות רגילות: בניגוד לפתרונות שמבוססים על WebGL, ‏ geoxml3 פועל במפות רגילות של Google Maps JS API v3 בלי לדרוש מצב עיבוד ספציפי.
הערות:
- תמיכה מוגבלת ב-KMZ: הספרייה לא תומכת באופן מובנה בקובצי KMZ. בדרך כלל, כדי לבטל את הדחיסה של ארכיוני KMZ צריך לשלב אותה עם סקריפטים נוספים של צד שלישי, כמו ZipFile.complete.js.
- רכיבים שלא נתמכים: תכונות כמו גיאומטריות תלת-ממדיות, תוויות מורכבות ורכיבי KML חדשים מסוימים לא נתמכות.
תיעוד: מאגר geoxml3 ב-GitHub.

קובץ KML עם רכיבים אינטראקטיביים

המלצה להעברה: סגנון מבוסס-נתונים למערכי נתונים

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

הגדרה ראשונית

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

מזהה מפה: מגדירים מזהה מפה לסוג מפה וקטורית.
העלאה: מעלים את נתוני ה-KML למסוף Google Cloud כדי לקבל מזהה של מערך נתונים.
גישה לשכבה: משתמשים ב-map.getDatasetFeatureLayer(datasetId) כדי לגשת לשכבה האינטראקטיבית.

1. טיפול באירועי אינטראקציה

ב-KmlLayer, המערכת מטפלת אוטומטית בלחיצות על תכונות באמצעות ה-API, כדי להציג חלון מידע. כשמשתמשים ב-DDS למערכי נתונים, צריך לרשום ידנית listeners לאירועי עכבר בשכבת מערך הנתונים.

‫click: מופעל כשמשתמש לוחץ על תכונה.
‫mousemove: מופעל כשסמן העכבר עובר מעל תכונה, שימושי ליצירת אפקטים של ריחוף.

2. עיצוב דינמי (אפקט ריחוף)

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

let currentFeatureId = null;

function initInteraction(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Apply the style function
  datasetLayer.style = (params) => {
    const isHovered = params.feature.datasetAttributes['id'] === currentFeatureId;
    return {
      strokeColor: 'green',
      strokeWeight: isHovered ? 4.0 : 2.0, // Bold border on hover
      fillColor: 'green',
      fillOpacity: isHovered ? 0.5 : 0.3,
    };
  };

  // Add interaction listeners
  datasetLayer.addListener('mousemove', (event) => {
    if (event.features.length > 0) {
      currentFeatureId = event.features[0].datasetAttributes['id'];
      datasetLayer.style = datasetLayer.style; // Re-apply style to reflect changes
    }
  });

  // Clear hover state when the mouse leaves the features
  map.addListener('mousemove', () => {
    if (currentFeatureId !== null) {
      currentFeatureId = null;
      datasetLayer.style = datasetLayer.style;
    }
  });
}

3. הצגת HTML מהמאפיין `description`

ב-KML, התג <description> מכיל לעיתים קרובות HTML לחלון המידע שמוצג כברירת מחדל. כשמייבאים את הנתונים האלה כמערך נתונים, description הופך למאפיין של תכונה. כדי לעבד את המחרוזת, מעבירים אותה ישירות אל google.maps.InfoWindow רגיל.

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

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const feature = event.features[0];
    // Access the HTML description attribute
    const htmlContent = feature.datasetAttributes['description'];

    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. חלון מידע בהתאמה אישית עם `ExtendedData`

אם קובץ ה-KML משתמש ב-<ExtendedData> כדי לאחסן צמדים מותאמים אישית של שם/ערך, הצמדים האלה ממופים ל-datasetAttributes. אפשר לחזור על הפעולות האלה עם מאפיינים אחרים כדי ליצור תצוגת HTML בהתאמה אישית.

function createCustomContent(feature) {
  const attributes = feature.datasetAttributes;
  const container = document.createElement("div");
  container.style.padding = "10px";
  container.innerHTML = "<h3>Feature Details</h3><dl></dl>";

  const dl = container.querySelector("dl");

  // Iterate through all data attributes imported from KML ExtendedData
  for (const key in attributes) {
    const dt = document.createElement("dt");
    dt.style.fontWeight = "bold";
    dt.textContent = key;

    const dd = document.createElement("dd");
    dd.textContent = attributes[key];

    dl.appendChild(dt);
    dl.appendChild(dd);
  }
  return container;
}

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const content = createCustomContent(event.features[0]);
    infoWindow.setContent(content);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

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

המלצה להעברה: רינדור בצד הלקוח עם GeoJSON

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

הגדרה ראשונית

לפני שמטמיעים אינטראקציות, צריך להמיר את נתוני ה-KML ל-GeoJSON ולהעלות אותם לשכבת הנתונים. פרטים על שימוש בכלים כמו ogr2ogr או togeojson ועל הפעלת המפה באמצעות map.data.loadGeoJson() זמינים במדריך המלצה להעברה: עיבוד בצד הלקוח באמצעות GeoJSON.

1. אינטראקציות אוטומטיות לעומת אינטראקציות ידניות

ההבדל העיקרי בין השכבות האלה הוא באופן שבו הן מטפלות בקלט של המשתמש:

‫KmlLayer: המערכת מטפלת אוטומטית בקליקים על תכונות ומציגה InfoWindow שמכיל את נתוני ו- של KML.
שכבת נתונים: לא מוצגים אובייקטים InfoWindow באופן אוטומטי. צריך להוסיף ידנית event listeners כדי לתעד אינטראקציות של משתמשים ולכתוב קוד להצגת נתונים.

2. טיפול באירועי אינטראקציה

כדי להפוך תכונות של GeoJSON לאינטראקטיביות, משתמשים ב-method‏ addListener() באובייקט map.data. דוגמאות לאירועים נפוצים:

‫click: משמש להפעלת חלונות מידע או לוגיקה של בחירה.
‫mouseover / mouseout: משמש להדגשה ולאפקטים של ריחוף.

3. הצגת תיאורים ב-HTML בחלון מידע

כשממירים KML ל-GeoJSON, התג <description> (שבדרך כלל מכיל HTML) ממופה בדרך כלל למאפיין בשם description. אפשר להשתמש ב-feature.getProperty('description') כדי לאחזר את המחרוזת הזו ולהציג אותה בתוך google.maps.InfoWindow רגיל.

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

// Handle clicks to show the HTML description
map.data.addListener('click', (event) => {
  // Access the 'description' property from the GeoJSON feature
  const htmlContent = event.feature.getProperty('description');

  if (htmlContent) {
    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. חלונות מידע מותאמים אישית ו-`ExtendedData`

אם קובץ ה-KML המקורי השתמש ב-<ExtendedData>, צמדי השם-ערך האלה מומרים למאפייני GeoJSON. מכיוון שבשכבת הנתונים אין ממשק משתמש שמוגדר כברירת מחדל להצגת הנתונים האלה, צריך להטמיע חלון מידע מותאם אישית כדי לחזור על הנתונים ולהציג אותם.

אפשר לגשת למאפיינים האלה באמצעות event.feature.getProperty('attribute_name') וליצור מחרוזת HTML מותאמת אישית או רכיב DOM כדי להעביר לשיטה infoWindow.setContent().

5. עיצוב דינמי (אפקטים של מעבר ריחוף)

שכבת הנתונים מאפשרת לעדכן את סגנונות התכונות באופן פרוגרמטי בתגובה לאירועים. משתמשים ב-overrideStyle() כדי לשנות באופן זמני את המראה של תכונה (למשל, כשמעבירים מעל התכונה את העכבר) וב-revertStyle() כדי לחזור לסגנון הגלובלי.

// Set a base style for all features
map.data.setStyle({
  fillColor: 'blue',
  strokeWeight: 1
});

// Highlight feature on mouseover
map.data.addListener('mouseover', (event) => {
  map.data.revertStyle(); // Clear previous highlights
  map.data.overrideStyle(event.feature, {strokeWeight: 8});
});

// Revert style on mouseout
map.data.addListener('mouseout', (event) => {
  map.data.revertStyle();
});

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

נתיב ההעברה: רינדור בצד הלקוח באמצעות ספריות צד שלישי

למפתחים שעוברים מ-KmlLayer לפתרונות של צד שלישי, המדריך הזה מתמקד בטיפול בנתונים אינטראקטיביים כמו קליקים בעכבר ואירועים דינמיים באמצעות deck.gl ו-geoxml3.

הגדרה ראשונית

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

‫deck.gl: המרה של המפה לשימוש בסוג המפה הווקטורית (נדרש canvas).
‫geoxml3: הצגת סקריפטים של הספריות מהמארח שלכם וניהול של שיתוף משאבים בין מקורות (CORS).

1. נתונים אינטראקטיביים עם deck.gl

‫deck.gl תומך ב-KML כפורמט קלט ישיר ומטפל אוטומטית באינטראקציות של תכונות כמו קליקים על סמך הנתונים שסופקו בקובץ ה-KML.

טיפול ב-KMLLoader: באמצעות המודול @loaders.gl/kml, המערכת מנתחת את הגיאומטריה והמאפיינים לפורמט שמשמש את deck.gl להפעלת אירועי אינטראקציה באופן מקורי.
קליקים על תכונות: כשלוחצים על תכונה, deck.gl יכול לתעד את האירוע ולהציג מטא-נתונים שמשויכים אליו (כמו <name> או <description>).
דוגמה: בדוגמה deckgl-kml-updated מוצג עיבוד KML בזמן אמת, שבו כשמעבירים את העכבר מעל סמני רעידות אדמה מוצג מידע מפורט על האירוע.

2. נתונים אינטראקטיביים באמצעות geoxml3

האפליקציה geoxml3 מנתחת את קובץ ה-KML באופן מקומי בדפדפן, מחלצת פרטי סגנון ויוצרת אובייקטים רגילים של Google Maps API ששומרים על האינטראקטיביות שלהם.

שליפת סגנון מקורי: הספרייה שולפת רכיבי <Style> ו-<StyleMap> מ-KML כדי להחיל אותם על סמנים, קווים ופוליגונים שנוצרו.
Click Handlers: כברירת מחדל, geoxml3 מספק Click Handlers לאובייקטים האלה. אפשר גם להגדיר פונקציות קריאה חוזרת מותאמות אישית (createMarker,‏ createOverlay) במהלך יצירת מופע של מנתח התוכן כדי להטמיע לוגיקה משלכם לבחירה או לעדכונים בסרגל הצד.
דוגמה: בדוגמה הזו מוצג אופן השימוש ב-geoxml3 לעיבוד KML, עם התאמה אישית כמו סמנים מעגליים עם אינטראקציה, למשל קליק על הסמנים כדי להציג מידע על רעידות אדמה.
דפוס שימוש:

var myParser = new geoXML3.parser({
  map: map,
  processStyles: true, // Automatically handle KML styles
  afterParse: function(doc) {
    // Code to run after the KML is fully parsed
  }
});
myParser.parse('interactive_data.kml');

קובץ KML עם תמונות

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

המלצה להעברה: Maps JavaScript API GroundOverlay

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

1. הטמעה

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

מסמכי תיעוד: מדריך לשכבות-על של תמונות על הקרקע
הכנת תמונה: אם התמונה שלך היא בעלת הפניה גיאוגרפית אבל לא בהטלה הנכונה (EPSG:4326), אפשר להשתמש בכלי הקוד הפתוח gdalwarp כדי לעוות את התמונה לשימוש עם Maps JavaScript API.

gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

נתיב ההעברה: שימוש בספריות של צד שלישי

אם אתם צריכים לשמור את הנתונים בפורמט KML בתהליך העבודה שלכם, אתם יכולים להשתמש בספריות של צד שלישי כמו geoxml3 או deck.gl כדי להציג שכבות-על של תמונות.

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

‫1. geoxml3

‫geoxml3 היא אפשרות טובה לניתוח רכיבי GroundOverlay פשוטים באופן מקומי בדפדפן ולהמרה שלהם לאובייקטים של Google Maps API.

דוגמה לשימוש:

const geoXmlParser = new geoXML3.parser({
    map: map,
    afterParse: function(doc) {
        console.log("Parsing complete. Number of documents: " + doc.length);
        const bounds = doc[0].gbounds;
        if (bounds && !bounds.isEmpty()) {
           map.fitBounds(bounds);
        }
    },
    createOverlay: function(groundOverlayData) {
        // Extract bounds and URL from parsed KML data
        const imageUrl = groundOverlayData.icon.href;
        const imageBounds = {
            north: parseFloat(groundOverlayData.latLonBox.north),
            south: parseFloat(groundOverlayData.latLonBox.south),
            east: parseFloat(groundOverlayData.latLonBox.east),
            west: parseFloat(groundOverlayData.latLonBox.west)
        };

        // Create the Google Maps GroundOverlay
        const nativeOverlay = new google.maps.GroundOverlay(imageUrl, imageBounds);
        nativeOverlay.setMap(map);
    }
});
geoXmlParser.parse('your_file.kml');

‫2. deck.gl

הגרסה הרגילה של deck.gl,‏ GeoJsonLayer, מטפלת בנתוני וקטור, אבל היא יכולה גם לתמוך ב-GroundOverlays באמצעות הטמעה ידנית עם BitmapLayer.

הגישה הזו כוללת שימוש ב-KMLLoader כדי לנתח את הקובץ, ואז הגדרה מפורשת של BitmapLayer עם כתובת ה-URL של התמונה והקואורדינטות שחולצו מנתוני ה-KML.

דרישה: כדי להשתמש ב-deck.gl, צריך להגדיר את סוג המפה כמפת וקטור.
מסמכים: deck.gl Bitmap Layer

תרחיש מתקדם: יצירת פירמידות של משבצות באמצעות gdal2tiles

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

כלי: gdal2tiles יכול לחלץ נתונים מפירמידת KMZ ולהפיק קוד סטנדרטי של Maps JavaScript API כדי להציג את המשבצות. שימו לב: יכול להיות שיהיה צורך לבצע שינויים ידניים בתוצאה הסופית כדי לשלב אותה במפה קיימת.

gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

קובץ KML עם קישורי רשת

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

פתרון נתמך: סגנון מבוסס-נתונים (DDS) למערכי נתונים

מערכי נתונים של Google Maps Platform לא מנתחים באופן טבעי רכיבי <NetworkLink>, ולכן צריך לבחור אסטרטגיית העברה על סמך מבנה הנתונים:

אסטרטגיה א': מערכי נתונים נפרדים (הכי מתאים לשכבות שהמשתמש שולט בהן) מעלים כל קובץ KML שהיה בעבר קישור לרשת כמערך נתונים נפרד במסוף Google Cloud. אחר כך אפשר להשתמש ב-JavaScript כדי לטעון ולהציג את השכבות האלה באופן דינמי כשצריך, על ידי קריאה ל-map.getDatasetFeatureLayer(datasetId) ושינוי החשיפה או הסגנון שלו.
אסטרטגיה ב': קובץ KML שטוח (הכי טוב לתצוגה עם ביצועים גבוהים) משלבים את כל התכונות מקובצי הרשת השונים לקובץ KML מקיף אחד, לפני שמעלים אותו כקבוצת נתונים. אחר כך תוכלו להשתמש בסגנון דינמי על סמך מאפייני התכונה כדי לסנן ולהציג קבוצות משנה ספציפיות של נתונים תוך כדי תנועה.

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

פתרונות קוד פתוח: deck.gl ו-geoxml3

אף אחד מהם, deck.gl או geoxml3, לא מספק תמיכה חזקה בניתוח ובהבאה אוטומטית של רכיבי KML‏ <NetworkLink>.

deck.gl

deck.gl משתמש ב-KMLLoader (שמבוסס על togeojson), שלא תומך באופן מפורש ב-NetworkLinks.

למה זה לא פתרון טוב: המנתח נועד להיות ממיר סינכרוני ופשוט, שלא יוצר בקשות משלו לרשת כדי להבטיח אמינות ופשטות. אם האפליקציה שלכם מסתמכת על קובצי KML שמפנים לכמה כתובות URL אחרות, מערכת deck.gl לא תפתור אותן באופן אוטומטי.

geoxml3

‫geoxml3 פותח כדי לנתח KML עבור Maps JS API, אבל התמיכה שלו בקישורי רשת היא ניסיונית ולא מתוחזקת.

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

סיכום המלצות

כדי לבצע העברה מהימנה, מפתחים צריכים להימנע משימוש בכלי ניתוח של צד שלישי לקבצים עם קישורים לרשת, ובמקום זאת לבנות מחדש את הלוגיקה של אחזור הנתונים באמצעות Datasets API. כך אפשר לוודא שהנתונים מנוהלים בצורה מאובטחת בתשתית של Google Maps Platform, במקום להסתמך על מנתחים (parsers) בצד הלקוח שלא מתחזקים.

שימוש ב-KML להצגת שכבות-על של מסך

מפתחים שעוברים מ-KmlLayer לחלופות מודרניות כמו סגנון מבוסס-נתונים (DDS), חשוב שידעו ששכבות-על במסך אינן נתמכות במערכי נתונים. כדי להשיג את אותו אפקט של הצגת תמונות, סמלי לוגו או מקרא קבועים מעל המפה, צריך ליצור אמצעי בקרה בהתאמה אישית באמצעות Maps JavaScript API.

1. מה צריך לחפש בקובץ ה-KML

כדי ליצור רכיב Custom Control מקביל, בודקים את הרכיב <ScreenOverlay> בקובץ ה-KML ומחפשים את מאפייני המפתח הבאים:

‫<Icon><href>: כתובת ה-URL של התמונה שרוצים להציג.
‫<screenXY>: כאן מגדירים את המיקום של שכבת-העל במסך.
- ‫x=0, y=1 (שברים) מתאים לפינה הימנית העליונה.
- ‫x=1, y=1 מתאים לפינה השמאלית העליונה.
- ‫x=0, y=0 תואם לפינה השמאלית התחתונה.
- ‫x=1, y=0 תואם לפינה הימנית התחתונה.
‫<size>: הגדרת הרוחב והגובה של שכבת העל.
‫<rotation>: מציין אם צריך לסובב את התמונה.

2. הטמעה: יצירת אמצעי בקרה מותאם אישית

רכיב בקרה מותאם אישית הוא בעצם רכיב HTML רגיל (כמו <div> או <img>) שמוסיפים לאחד מהמיקומים המוגדרים מראש במפה.

מיפוי מיקומי KML אל `ControlPosition`

‫Maps JavaScript API משתמש ב-enum‏ ControlPosition כדי להגדיר את מיקום אמצעי הבקרה. אתם יכולים להיעזר בטבלה הבאה כדי למפות את ה-KML <screenXY> לקבוע המתאים ב-JS API:

מיקום ב-KML‏ (`screenXY`)	‫JS API `ControlPosition`
שמאל למעלה (`x:0, y:1`)	‫`TOP_LEFT` (Legacy) או `BLOCK_START_INLINE_START` (Logical)
פינה ימנית עליונה (`x:1, y:1`)	`TOP_RIGHT` או `BLOCK_START_INLINE_END`
שמאל למטה (`x:0, y:0`)	`BOTTOM_LEFT` או `BLOCK_END_INLINE_START`
ימין למטה (`x:1, y:0`)	`BOTTOM_RIGHT` או `BLOCK_END_INLINE_END`

3. דוגמה להעברה: שכבת-על קבועה של לוגו

בדוגמה הבאה מוצג לוגו של KML ScreenOverlay שממוקם בפינה השמאלית העליונה של המפה.

סגנון CSS

משתמשים ב-CSS כדי להגדיר את הגודל והמראה של ה'שכבת על'.

#logo-control {
  padding: 10px;
  background-color: rgba(255, 255, 255, 0.8);
  margin: 10px;
  border-radius: 2px;
  box-shadow: 0 1px 4px rgba(0,0,0,0.3);
}

#logo-control img {
  width: 150px; /* Equivalent to KML <size> */
  display: block;
}

הטמעה של JavaScript

מוסיפים את הרכיב למערך map.controls.

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 41.85, lng: -87.65 },
  });

  // 1. Create the container for the overlay
  const logoControlDiv = document.createElement("div");
  logoControlDiv.id = "logo-control";

  // 2. Create the image (KML <Icon>)
  const logoImage = document.createElement("img");
  logoImage.src = "https://example.com/logo.png";
  logoImage.alt = "Company Logo";

  logoControlDiv.appendChild(logoImage);

  // 3. Position the control (KML <screenXY>)
  // In this case, we use TOP_RIGHT
  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(logoControlDiv);
}

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

מבוא

קובץ KML לעיצוב מידע על גבולות, אזורים או אזורי עניין

המלצה להעברה: סגנון מבוסס-נתונים לגבולות

זמין FeatureType

איך מסמנים אזור

הגבלת ההזזה לאזור מסוים

סיכום הטמעת ההעברה

קובץ KML עם נתוני וקטור (נקודות, קווים, גבולות, מצולעים)

המלצה להעברה: סגנון מבוסס-נתונים למערכי נתונים

1. הגדרה והעלאה

2. הגדרת אזור התצוגה לנתונים

3. עיצוב ממאפייני תכונה

דוגמה: פונקציית סגנון באמצעות מאפיינים

המלצה להעברה: רינדור בצד הלקוח עם GeoJSON

1. המרת KML ל-GeoJSON

2. הגדרת אזור התצוגה לנתונים

3. עיצוב ממאפייני תכונה

דוגמה: פונקציית סגנון והתאמה של אזור התצוגה

נתיב ההעברה: רינדור בצד הלקוח באמצעות ספריות צד שלישי

‫1. deck.gl

‫2. geoxml3

קובץ KML עם רכיבים אינטראקטיביים

המלצה להעברה: סגנון מבוסס-נתונים למערכי נתונים

הגדרה ראשונית

1. טיפול באירועי אינטראקציה

2. עיצוב דינמי (אפקט ריחוף)

3. הצגת HTML מהמאפיין description

4. חלון מידע בהתאמה אישית עם ExtendedData

המלצה להעברה: רינדור בצד הלקוח עם GeoJSON

הגדרה ראשונית

1. אינטראקציות אוטומטיות לעומת אינטראקציות ידניות

2. טיפול באירועי אינטראקציה

3. הצגת תיאורים ב-HTML בחלון מידע

4. חלונות מידע מותאמים אישית ו-ExtendedData

5. עיצוב דינמי (אפקטים של מעבר ריחוף)

נתיב ההעברה: רינדור בצד הלקוח באמצעות ספריות צד שלישי

הגדרה ראשונית

1. נתונים אינטראקטיביים עם deck.gl

2. נתונים אינטראקטיביים באמצעות geoxml3

קובץ KML עם תמונות

המלצה להעברה: Maps JavaScript API GroundOverlay

1. הטמעה

נתיב ההעברה: שימוש בספריות של צד שלישי

‫1. geoxml3

‫2. deck.gl

תרחיש מתקדם: יצירת פירמידות של משבצות באמצעות gdal2tiles

קובץ KML עם קישורי רשת

פתרון נתמך: סגנון מבוסס-נתונים (DDS) למערכי נתונים

פתרונות קוד פתוח: deck.gl ו-geoxml3

deck.gl

geoxml3

סיכום המלצות

שימוש ב-KML להצגת שכבות-על של מסך

1. מה צריך לחפש בקובץ ה-KML

2. הטמעה: יצירת אמצעי בקרה מותאם אישית

מיפוי מיקומי KML אל ControlPosition

3. דוגמה להעברה: שכבת-על קבועה של לוגו

סגנון CSS

הטמעה של JavaScript

מידע נוסף

נתיבי העברה של KmlLayer

3. הצגת HTML מהמאפיין `description`

4. חלון מידע בהתאמה אישית עם `ExtendedData`

4. חלונות מידע מותאמים אישית ו-`ExtendedData`

מיפוי מיקומי KML אל `ControlPosition`