مسارات نقل البيانات في KmlLayer

مقدمة

يهدف هذا الدليل إلى تغطية الاستخدامات الأكثر شيوعًا لفئة KmlLayer وتقديم مسارات نقل بيانات مقابلة إلى عمليات تنفيذ بديلة. هذه المعلومات موجَّهة للمطوّرين الذين يحتاجون إلى التوقّف عن استخدام KmlLayer بسبب إيقافها نهائيًا في الموعد المحدّد. آخر إصدار متوافق مع KmlLayer هو 3.65، وسيتم إيقافه نهائيًا في أيار (مايو) 2027.

يعتمد مسار نقل البيانات على طريقة استخدامك لـ KmlLayer:

ملف KML لتصميم معلومات الحدود/المنطقة/نقطة الاهتمام

بالنسبة إلى المطوّرين الذين يستخدمون KmlLayer لعرض الحدود الإدارية أو تصميمها، مثل تمييز بلد أو ولاية أو منطقة معيّنة، تنصح منصة خرائط Google بالانتقال إلى التصميم المستند إلى البيانات (DDS) للحدود.

اقتراح بشأن عملية النقل: تصميم مستند إلى البيانات للحدود

توفّر ميزة تصميم مستند إلى البيانات للحدود إمكانية الوصول المباشر إلى مضلّعات الحدود الإدارية من Google، ما يتيح لك تطبيق أنماط مخصّصة (التعبئة والحدود) على هذه المناطق بدون الحاجة إلى استضافة ملفات KML خارجية أو إدارتها.

FeatureType المتاحة

يتم تصنيف المناطق الإدارية حسب الوظيفة وترتيبها حسب المستويات. تتوفّر أنواع الميزات التالية للتصميم:

  • ‫COUNTRY: الكيان السياسي الوطني.
  • ADMINISTRATIVE_AREA_LEVEL_1: منطقة إدارية من الدرجة الأولى تندرج تحت مستوى البلد (مثل الولايات في الولايات المتحدة).
  • ADMINISTRATIVE_AREA_LEVEL_2: منطقة إدارية من الدرجة الثانية تندرج تحت مستوى البلد (مثل المقاطعات في الولايات المتحدة).
  • LOCALITY: مدينة أو بلدة مدمجة
  • POSTAL_CODE: الرموز البريدية المستخدَمة في البريد
  • SCHOOL_DISTRICT: دوائر المدارس الموحّدة أو الابتدائية أو الثانوية

اطّلِع على تغطية الحدود للمناطق التي تتوفّر فيها أنواع الميزات هذه.

كيفية تمييز منطقة

لتنسيق منطقة معيّنة، يجب استهدافها من خلال رقم تعريف المكان.

  • الإعداد: يجب استخدام معرّف خريطة تم إعداده لنوع خريطة اتجاهية في JavaScript وتفعيل طبقة عناصر المتاحة في Google Cloud Console.
  • التنفيذ: استخدِم نموذج الرمز تحديد نمط مضلّع حدودي.

حصر التحريك في منطقة معيّنة

لمنع المستخدمين من التنقّل خارج المربّع المحيط بالمنطقة المميّزة، يمكنك استخدام الخيار 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 Console.

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" باتّباع مسار نقل يتضمّن تحويل تنسيق البيانات واستخدام طبقة البيانات لعرض الميزات وتنسيقها مباشرةً في المتصفّح.

يتيح العرض من جهة العميل باستخدام "طبقة البيانات" طريقة مرنة للغاية لعرض البيانات الجغرافية. على عكس KmlLayer، التي يتم عرضها على خوادم Google، تتيح لك طبقة البيانات التفاعل مع الميزات كعناصر JavaScript عادية. يُرجى العِلم أنّه بالنسبة إلى مجموعات البيانات الكبيرة، قد تفضّل معالجة البيانات وعرضها من جهة الخادم، مثلاً باستخدام "الأنماط المستندة إلى البيانات" لمجموعات البيانات.

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 تحرّك الكاميرا وتكبّرها تلقائيًا إلى موقع البيانات، لا تفعل "طبقة البيانات" ذلك. لضبط إطار العرض ليناسب بيانات GeoJSON، عليك احتساب المربّع المحيط يدويًا واستدعاء map.fitBounds().

3- تحديد الأنماط من سمات العناصر

في "طبقة البيانات"، يمكنك تحديد دالة style تقرأ السمات (الخصائص) مباشرةً من كل عنصر 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 إلى "خرائط Google".

مسار نقل البيانات: العرض من جهة العميل باستخدام مكتبات تابعة لجهات خارجية

بالنسبة إلى المطوّرين الذين يبحثون عن بدائل أخرى KmlLayer، تتوفّر عدة مكتبات يديرها المنتدى وتعرض بيانات KML على Google Maps Platform JavaScript API.

‫1. deck.gl

‫deck.gl هو إطار عمل عالي الأداء للعرض المرئي يستند إلى WebGL. ويمكن استخدامه كبديل شبه جاهز لعرض KML من خلال GoogleMapsOverlay وGeoJsonLayer.

  • متطلبات لوحة الرسم: لاستخدام deck.gl بفعالية، يجب تحويل الخريطة لاستخدام نوع "الخريطة المتجهة" (الذي يتم عرضه في عنصر لوحة الرسم) مع إمكانات العرض باستخدام WebGL.
  • دعم KML: تتولّى @loaders.gl/kml عملية تحليل الأشكال الهندسية، وهي تحوّل KML إلى GeoJSON. يُرجى العِلم أنّ بعض ميزات KML، مثل الأنماط المعقّدة والرموز وNetworkLinks، قد تتطلّب تنفيذًا يدويًا إضافيًا.
  • المستندات: مستندات deck.gl | أداة تحميل KML في loaders.gl
  • أمثلة:
    • يوضّح نموذج deckgl-kml-updated في مستودع Google Maps على GitHub كيفية استخدام deck.gl لعرض بيانات KML يتم تعديلها في الوقت الفعلي.
    • يوضّح نموذج deckgl-kml كيفية استخدام deck.gl لعرض بيانات KML.

‫2. geoxml3

‫geoxml3 هو معالج KML مصمّم خصيصًا للإصدار 3 من Google Maps JavaScript API. تعمل هذه الأداة على تحليل ملفات KML محليًا في المتصفح وعرض البيانات كعناصر عادية في Google Maps API، مثل العلامات والخطوط المتعددة والمضلعات.

  • التوافق مع الخرائط العادية: على عكس الحلول المستندة إلى WebGL، تعمل geoxml3 على خرائط عادية من الإصدار 3 من Google Maps JS API بدون الحاجة إلى وضع عرض محدّد.
  • المحاذير:
    • توافق محدود مع ملفات KMZ: لا تتوافق المكتبة بشكل كامل مع ملفات KMZ بشكل أصلي، وعادةً ما يتطلّب فك ضغط أرشيفات KMZ دمجها مع نصوص برمجية إضافية تابعة لجهات خارجية، مثل ZipFile.complete.js.
    • العناصر غير المتوافقة: لا تتوافق الميزات مثل الأشكال الهندسية الثلاثية الأبعاد والتصنيفات المعقّدة وبعض عناصر KML الأحدث.
  • المستندات: مستودع geoxml3 على GitHub

ملف KML يتضمّن عناصر تفاعلية

اقتراح بشأن عملية النقل: تصميم مستند إلى البيانات لمجموعات البيانات

بالنسبة إلى المطوّرين الذين سينتقلون من KmlLayer إلى تصميم مستند إلى البيانات (DDS) لمجموعات البيانات، يوضّح هذا الدليل كيفية الانتقال من التفاعلات التلقائية مع ملفات KML إلى التفاعلات المخصّصة العالية الأداء، مثل النقر بالماوس والتمرير.

عملية الإعداد الأوّلية

قبل تنفيذ التفاعلات، تأكَّد من اتّباع خطوات الإعداد الواردة في دليل نقل بيانات KML: البيانات المتجهة:

  • معرّف الخريطة: اضبط معرّف خريطة لنوع الخريطة الاتجاهية.
  • التحميل: حمِّل بيانات KML إلى Google Cloud Console للحصول على معرّف مجموعة البيانات.
  • الوصول إلى الطبقة: استخدِم map.getDatasetFeatureLayer(datasetId) للوصول إلى الطبقة التفاعلية.

1. التعامل مع أحداث التفاعل

في KmlLayer، تعالج واجهة برمجة التطبيقات تلقائيًا النقرات على الميزات لعرض نافذة معلومات. باستخدام خدمة DDS لمجموعات البيانات، عليك تسجيل أدوات معالجة أحداث الماوس يدويًا في طبقة مجموعة البيانات.

  • ‫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 وتحميلها إلى &quot;طبقة البيانات&quot;. راجِع دليل اقتراح الترحيل: العرض من جهة العميل باستخدام GeoJSON للحصول على تفاصيل حول استخدام أدوات مثل ogr2ogr أو togeojson وتهيئة الخريطة باستخدام map.data.loadGeoJson().

1. التفاعلات التلقائية مقابل التفاعلات اليدوية

يتمثّل الاختلاف الرئيسي بين هذه الطبقات في طريقة تعاملها مع بيانات أدخلها المستخدم:

  • KmlLayer: يتعامل تلقائيًا مع النقرات على العناصر ويعرض InfoWindow يحتوي على بيانات KML و.
  • طبقة البيانات: لا تعرض عناصر InfoWindow تلقائيًا. يجب إضافة أدوات معالجة الأحداث يدويًا لتسجيل تفاعلات المستخدمين وكتابة رمز لعرض البيانات.

2. التعامل مع أحداث التفاعل

لجعل عناصر GeoJSON تفاعلية، استخدِم طريقة 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. بما أنّ "طبقة البيانات" لا تتضمّن واجهة مستخدم تلقائية لهذه العناصر، عليك تنفيذ InfoWindow مخصّصة لتكرارها وعرضها.

يمكنك الوصول إلى هذه السمات باستخدام 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: لتحويل خريطتك إلى نوع الخريطة المتّجهة (متطلبات لوحة الرسم).
  • 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 لتطبيقهما على العلامات المتولّدة والخطوط المتعددة والمضلّعات.
  • معالجات النقرات: يوفّر geoxml3 تلقائيًا معالجات النقرات لهذه العناصر. يمكنك أيضًا تحديد دوال ردّ اتصال مخصّصة (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 أو أدوات تحليل تابعة لجهات خارجية.

اقتراح النقل: GroundOverlay في Maps JavaScript API

المسار المقترَح لنقل الصور هو استخدام الفئة 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

في حين أنّ GeoJsonLayer العادي في deck.gl يتعامل مع بيانات المتجهات، يمكنه أيضًا توفير GroundOverlays من خلال عملية تنفيذ يدوية باستخدام BitmapLayer.

يتضمّن هذا الأسلوب استخدام KMLLoader لتحليل الملف ثم تحديد BitmapLayer بشكل صريح مع عنوان URL للصورة والإحداثيات المستخرجة من بيانات KML.

حالة متقدّمة: إنشاء أهرامات مربّعات باستخدام gdal2tiles

بالنسبة إلى ملفات KML المعقّدة التي تحتوي على هرميات مربّعات الصور، يكون نقل البيانات أكثر صعوبة ويتطلّب استخراج بيانات الصور.

  • الأداة: يمكن لأداة gdal2tiles استخراج البيانات من هرم KMZ وإنشاء رمز Maps JavaScript API عادي لعرض المربّعات. يُرجى العِلم أنّ النتيجة النهائية قد تتطلّب تعديلاً يدويًا ليتم دمجها في خريطة حالية.
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

تتطلّب معالجة ملفات KML التي تتضمّن روابط شبكة الانتقال من عملية الجلب التلقائي لـ KmlLayer من جهة السحابة الإلكترونية إلى استراتيجيات أكثر وضوحًا لإدارة البيانات.

الحلّ المتاح: تصميم مستند إلى البيانات (DDS) لمجموعات البيانات

بما أنّ مجموعات بيانات منصة خرائط Google لا تحلّل عناصر <NetworkLink> بشكلٍ تلقائي، عليك اختيار استراتيجية نقل بيانات استنادًا إلى بنية بياناتك:

  • الاستراتيجية (أ): مجموعات البيانات المنفصلة (الأفضل للطبقات التي يتحكّم بها المستخدم): حمِّل كل ملف KML كان في السابق رابطًا لشبكة كملف مجموعة بيانات منفصل في Google Cloud Console. يمكنك بعد ذلك استخدام 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 JavaScript API، فإنّ توافقه مع روابط الشبكة تجريبي وغير مُدار.

  • سبب عدم ملاءمة هذا الحلّ: لا تتوفّر هذه الوظيفة إلا في فرع "network_link" القديم الذي لم يتم اختباره بشكل جيد. لا ننصح باستخدام هذه الطريقة لنقل بيانات الإنتاج، لأنّها قد لا تتمكّن من التعامل مع بنى الروابط المعقّدة أو متطلبات الأمان الحديثة، مثل سياسة مشاركة الموارد متعددة المصادر (CORS).

اقتراح الملخّص

لضمان عملية نقل موثوقة، على المطوّرين تجنُّب استخدام أدوات تحليل تابعة لجهات خارجية للملفات التي تتضمّن روابط شبكة، وعليهم بدلاً من ذلك إعادة إنشاء منطق استرجاع البيانات باستخدام Datasets API. يضمن ذلك إدارة بياناتك بأمان ضمن البنية الأساسية لمنصة Google Maps بدلاً من الاعتماد على أدوات تحليل غير مُصانة من جهة العميل.

استخدام KML لعرض "تراكبات الشاشة"

بالنسبة إلى المطوّرين الذين سينتقلون من KmlLayer إلى بدائل حديثة مثل "التصميم المستند إلى البيانات" (DDS)، من المهم ملاحظة أنّ تراكبات الشاشة غير متاحة في مجموعات البيانات. لتحقيق التأثير نفسه المتمثل في عرض صور أو شعارات أو وسائط إيضاحية ثابتة فوق الخريطة، عليك إنشاء عناصر تحكّم مخصّصة باستخدام Maps JavaScript API.

1. المحتوى الذي يجب التنبه إليه في ملف KML

لإنشاء عنصر تحكّم مخصّص مكافئ، افحص العنصر <ScreenOverlay> في ملف KML بحثًا عن السمات الرئيسية التالية:

  • <Icon>&lt;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 التعداد ControlPosition لتثبيت عناصر التحكّم. استخدِم الجدول أدناه لربط <screenXY> KML بثابت JS API المناسب:

موضع ملف KML (screenXY) JS API ControlPosition
أعلى اليمين (x:0, y:1) ‫TOP_LEFT (قديم) أو BLOCK_START_INLINE_START (منطقي)
أعلى اليمين (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- مثال على عملية نقل البيانات: تراكب الشعار الثابت

يحاكي المثال التالي شعار ScreenOverlay بتنسيق KML موضوعًا في أعلى يسار الخريطة.

نمط 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);
}

مزيد من المعلومات