این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

مسیرهای مهاجرت KmlLayer

مقدمه

هدف از این راهنما، پوشش رایج‌ترین کاربردهای KmlLayer و ارائه مسیرهای مهاجرت مربوطه به پیاده‌سازی‌های جایگزین است. این اطلاعات برای توسعه‌دهندگانی در نظر گرفته شده است که به دلیل منسوخ شدن برنامه‌ریزی‌شده KmlLayer، نیاز به گذار از استفاده از آن دارند. آخرین نسخه‌ای که از KmlLayer پشتیبانی می‌کند، نسخه ۳.۶۵ است که در ماه مه ۲۰۲۷ از رده خارج خواهد شد.

مسیر مهاجرت شما بستگی به نحوه استفاده شما از KmlLayer دارد:

فایل KML برای استایل‌دهی به اطلاعات مرز/حاشیه/منطقه مورد نظر : از استایل‌دهی داده‌محور (DDS) برای مرزهای مناطق اداری با استفاده از داده‌های مرزی گوگل استفاده کنید.
فایل KML با داده‌های برداری (نقاط/چندخطی‌ها/مرزها/چندضلعی‌ها) : برای مجموعه داده‌ها از DDS ، GeoJSON یا کتابخانه‌های شخص ثالث مانند deck.gl یا geoxml3 استفاده کنید.
فایل KML با عناصر تعاملی : پیاده‌سازی شنونده‌های رویداد دستی و پنجره‌های اطلاعات سفارشی برای تعامل ویژگی‌ها.
فایل KML با تصاویر : برای پوشش تصاویر از GroundOverlays یا تجزیه‌کننده‌های شخص ثالث استفاده کنید.
فایل KML با لینک‌های شبکه : هر KML را به عنوان یک مجموعه داده جداگانه آپلود کنید، یا KMLها را ادغام کنید. در صورت نمایش داده‌های پویا، مجموعه داده را با استفاده از API مجموعه داده‌ها به‌روزرسانی کنید.
استفاده از KML برای نمایش همپوشانی‌های صفحه : از کنترل‌های سفارشی برای جایگزینی عناصر ثابت رابط کاربری مانند لوگوها، راهنماها یا ابزارهای ناوبری استفاده کنید.

فایل KML برای استایل‌دهی به اطلاعات مرز/حاشیه/منطقه مورد نظر

برای توسعه‌دهندگانی که از KmlLayer برای نمایش یا استایل‌دهی به مرزهای مدیریتی - مانند برجسته کردن یک کشور، ایالت یا مکان خاص - استفاده می‌کنند، پلتفرم نقشه‌های گوگل مهاجرت به استایل‌دهی مبتنی بر داده (DDS) را برای مرزها توصیه می‌کند.

توصیه مهاجرت: سبک‌دهی مبتنی بر داده برای مرزها

سبک‌دهی مبتنی بر داده برای مرزها، دسترسی مستقیم به چندضلعی‌های مرزی مدیریتی گوگل را فراهم می‌کند و به شما این امکان را می‌دهد که سبک‌های سفارشی (پر کردن و خط‌کشی) را بدون نیاز به میزبانی یا مدیریت فایل‌های KML خارجی، به این مناطق اعمال کنید.

نوع ویژگی موجود

بخش‌های مدیریتی بر اساس عملکرد دسته‌بندی و بر اساس سطوح مرتب شده‌اند. انواع ویژگی‌های زیر برای استایل‌بندی پشتیبانی می‌شوند:

COUNTRY : نهاد سیاسی ملی.
ADMINISTRATIVE_AREA_LEVEL_1 : یک نهاد مدنی درجه یک پایین‌تر از سطح کشور (مثلاً ایالت‌های ایالات متحده).
ADMINISTRATIVE_AREA_LEVEL_2 : یک نهاد مدنی درجه دو پایین‌تر از سطح کشور (مثلاً شهرستان‌های ایالات متحده).
LOCALITY : یک شهر یا شهرستان ثبت شده.
POSTAL_CODE : کدهای پستی که برای نامه استفاده می‌شوند.
SCHOOL_DISTRICT : مناطق آموزشی یکپارچه، ابتدایی یا متوسطه.

برای اطلاع از مناطقی که این نوع ویژگی‌ها در آنها موجود است ، به پوشش مرزی مراجعه کنید.

چگونه یک منطقه را برجسته کنیم

برای استایل‌دهی به یک منطقه خاص، باید آن را با Place ID هدف قرار دهید.

راه‌اندازی : شما باید از یک شناسه نقشه پیکربندی‌شده برای نوع نقشه برداری جاوا اسکریپت استفاده کنید و لایه ویژگی موجود در کنسول ابری گوگل را فعال کنید.
پیاده‌سازی : از کد نمونه‌ی 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 با داده‌های برداری (نقاط/چندخطی‌ها/مرزها/چندضلعی‌ها)

توصیه مهاجرت: سبک‌دهی داده‌محور برای مجموعه داده‌ها

گوگل مسیر زیر را برای نمایش داده‌های جغرافیایی در دسترس عموم و در عین حال کنترل بیشتر بر ظاهر و عملکرد، توصیه می‌کند.

استایل‌دهی داده‌محور برای مجموعه داده‌ها به شما امکان می‌دهد داده‌های جغرافیایی خود (KML، GeoJSON یا CSV) را آپلود کنید، استایل‌دهی سفارشی را بر اساس ویژگی‌های داده اعمال کنید و عوارض را روی نقشه‌های برداری نمایش دهید.

۱. راه‌اندازی و آپلود

برخلاف KmlLayer که در زمان اجرا یک URL را دریافت می‌کند، DDS از شما می‌خواهد که داده‌ها را به عنوان یک مجموعه داده در کنسول Google Cloud میزبانی کنید.

ایجاد شناسه نقشه : از یک شناسه نقشه پیکربندی شده برای نوع نقشه برداری استفاده کنید.
آپلود مجموعه داده : فایل KML خود را در کنسول ابری گوگل آپلود کنید تا یک شناسه مجموعه داده منحصر به فرد ایجاد شود. برای جزئیات بیشتر ، مستندات کامل در مورد نحوه مدیریت مجموعه داده‌های نقشه‌ها را مطالعه کنید.
نمایش مجموعه داده‌ها: پس از ایجاد شناسه مجموعه داده‌ها، باید مجموعه داده‌ها را با یک سبک نقشه و یک شناسه نقشه مرتبط کنید. سپس از شناسه مجموعه داده‌ها برای نمایش داده‌ها روی نقشه استفاده خواهید کرد. برای جزئیات بیشتر ، مستندات کامل در مورد نحوه افزودن مجموعه داده‌ها به نقشه را مطالعه کنید.
اگر تصمیم دارید داده‌های خود را از قالب KML وارد کنید، به الزامات KML برای مجموعه داده‌ها توجه کنید .

۲. تنظیم Viewport برای داده‌ها

KmlLayer به طور خودکار و به طور پیش‌فرض به محل داده‌ها حرکت افقی و عمودی (pan) و بزرگنمایی (zoom) می‌کند. با DDS برای مجموعه داده‌ها، این رفتار خودکار نیست و باید به صورت دستی پیاده‌سازی شود.

محدودیت‌های کدگذاری‌شده : اگر ناحیه داده ثابت است، از گزینه restriction در MapOptions برای قفل کردن نمای دید به مرزهای خاص استفاده کنید.
بزرگنمایی پویا : برای تنظیم پویای نمای دید، می‌توانید map.fitBounds() به همراه کادر محصورکننده مجموعه داده خود استفاده کنید.

۳. استایل‌دهی از ویژگی‌های ویژگی

فایل‌های KML اغلب حاوی اطلاعات سبک (مانند رنگ‌ها) هستند که DDS به طور خودکار اعمال نمی‌کند. شما باید یک تابع سبک سمت کلاینت ایجاد کنید که ویژگی‌های ویژگی‌های مجموعه داده‌ها را برای اعمال رنگ‌ها و شفافیت بخواند. برای جزئیات کامل، به مستندات توسعه‌دهنده در مورد نحوه سبک‌بندی داده‌های خود مراجعه کنید.

مثال: استایل‌دهی به تابع با استفاده از ویژگی‌ها

مثال زیر نحوه ایجاد یک تابع style را نشان می‌دهد که ویژگی‌های 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,
    };
  };
}

برای جزئیات بیشتر در مورد پیاده‌سازی تعاملات و سبک‌بندی، به سبک‌بندی مبتنی بر داده برای مجموعه داده‌ها و API مجموعه داده‌ها برای داده‌های پویا مراجعه کنید.

توصیه مهاجرت: رندر سمت کلاینت با GeoJSON

برای توسعه‌دهندگانی که از KmlLayer به رندر سمت کلاینت با GeoJSON مهاجرت می‌کنند، پلتفرم نقشه‌های گوگل مسیر مهاجرتی را پیشنهاد می‌کند که شامل تبدیل فرمت داده‌های شما و استفاده از لایه داده برای رندر و استایل‌دهی مستقیم ویژگی‌ها در مرورگر است.

رندر سمت کلاینت با استفاده از لایه داده، روشی بسیار انعطاف‌پذیر برای نمایش داده‌های جغرافیایی فراهم می‌کند. برخلاف KmlLayer که روی سرورهای گوگل رندر می‌شود، لایه داده به شما امکان می‌دهد با ویژگی‌ها مانند اشیاء استاندارد جاوا اسکریپت تعامل داشته باشید. با این حال، توجه داشته باشید که برای مجموعه داده‌های بزرگ، ممکن است پردازش و رندر سمت سرور داده‌های خود را ترجیح دهید، مانند Data-driven Styling for Datasets.

۱. تبدیل KML به GeoJSON

اولین قدم تبدیل فایل‌های KML به GeoJSON است. این کار را می‌توان با استفاده از چندین ابزار متن‌باز محبوب انجام داد:

ogr2ogr : بخشی از مجموعه GDAL، این ابزار قدرتمند خط فرمان می‌تواند فرمت‌های برداری زیادی را به هم تبدیل کند.

ogr2ogr -f GeoJSON output.json input.kml

togeojson : ابزاری کوچک و آزمایش‌شده که به‌طور خاص برای تبدیل KML و GPX به GeoJSON طراحی شده است.

togeojson input.kml > output.json

۲. تنظیم Viewport برای داده‌ها

در حالی که KmlLayer به طور خودکار به محل داده حرکت و بزرگنمایی می‌کند، لایه Data این کار را انجام نمی‌دهد. برای تنظیم viewport برای تطبیق با داده‌های GeoJSON، باید کادر مرزی را به صورت دستی محاسبه کرده و تابع map.fitBounds() را فراخوانی کنید.

۳. استایل‌دهی از ویژگی‌های ویژگی

در لایه داده، می‌توانید یک تابع style تعریف کنید که ویژگی‌ها (خصوصیات) را مستقیماً از هر ویژگی GeoJSON می‌خواند تا ظاهر آن را تعیین کند.

مثال: تابع استایل‌دهی و تنظیم نمای دید

مثال زیر نحوه بارگذاری داده‌های GeoJSON، محاسبه محدوده‌های آن برای تنظیم viewport و استایل‌دهی به ویژگی‌ها بر اساس ویژگی‌هایشان را نشان می‌دهد:

/**
 * 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
    };
  });
}

برای اطلاعات بیشتر در مورد استفاده از لایه داده، به مستندات Importing GeoJSON into Maps مراجعه کنید.

مسیر مهاجرت: رندر سمت کلاینت با کتابخانه‌های شخص ثالث

برای توسعه‌دهندگانی که به دنبال جایگزین‌های دیگری برای KmlLayer هستند، چندین کتابخانه تحت مدیریت جامعه وجود دارد که داده‌های KML را در API جاوا اسکریپت پلتفرم نقشه‌های گوگل رندر می‌کنند.

۱. عرشه.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 .
مثال‌ها:
- نمونه‌ی به‌روزرسانی‌شده با deckgl-kml در مخزن گیت‌هاب گوگل مپس، نحوه‌ی استفاده از deck.gl برای رندر کردن داده‌های KML که به‌صورت بلادرنگ به‌روزرسانی می‌شوند را نشان می‌دهد.
- نمونه deckgl-kml نحوه استفاده از deck.gl برای رندر کردن داده‌های KML را نشان می‌دهد.

۲. ژئوکس‌میل۳

geoxml3 یک پردازنده KML است که به طور خاص برای Google Maps JavaScript API v3 طراحی شده است. این پردازنده KML را به صورت محلی در مرورگر تجزیه می‌کند و داده‌ها را به عنوان اشیاء استاندارد API Google Maps مانند نشانگرها، چندخطی‌ها و چندضلعی‌ها رندر می‌کند.

پشتیبانی از نقشه‌های استاندارد: برخلاف راهکارهای مبتنی بر WebGL، geoxml3 بدون نیاز به حالت رندرینگ خاص، روی نقشه‌های استاندارد Google Maps JS API v3 کار می‌کند.
هشدارها:
- پشتیبانی محدود از KMZ: این کتابخانه به طور کامل از فایل‌های KMZ پشتیبانی نمی‌کند ؛ خارج کردن فایل‌های KMZ از حالت فشرده معمولاً نیاز به ادغام با اسکریپت‌های شخص ثالث اضافی مانند ZipFile.complete.js دارد.
- عناصر پشتیبانی نشده: ویژگی‌هایی مانند هندسه‌های سه‌بعدی، برچسب‌های پیچیده و برخی عناصر جدیدتر KML پشتیبانی نمی‌شوند.
مستندات: geoxml3 مخزن گیت‌هاب .

فایل KML با عناصر تعاملی

توصیه مهاجرت: سبک‌دهی داده‌محور برای مجموعه داده‌ها

برای توسعه‌دهندگانی که از KmlLayer به سبک‌بندی مبتنی بر داده (DDS) برای مجموعه داده‌ها مهاجرت می‌کنند، این راهنما نحوه انتقال از تعاملات خودکار KML به تعاملات سفارشی و با کارایی بالا مانند کلیک ماوس و حرکت موس روی صفحه (hover) را توضیح می‌دهد.

راه‌اندازی اولیه

قبل از پیاده‌سازی تعاملات، مطمئن شوید که مراحل راه‌اندازی را از راهنمای KML Migration: Vector Data دنبال کرده‌اید:

شناسه نقشه: یک شناسه نقشه برای نوع نقشه برداری پیکربندی کنید.
آپلود: داده‌های KML خود را در کنسول ابری گوگل آپلود کنید تا یک شناسه مجموعه داده (Dataset ID) دریافت کنید.
دسترسی به لایه: برای دسترسی به لایه تعاملی map.getDatasetFeatureLayer(datasetId) استفاده کنید.

۱. مدیریت رویدادهای تعاملی

در KmlLayer ، کلیک‌های ویژگی به طور خودکار توسط API مدیریت می‌شوند تا یک پنجره اطلاعات ظاهر شود. با DDS برای مجموعه داده‌ها، باید به صورت دستی شنونده‌هایی را برای رویدادهای ماوس در لایه مجموعه داده‌ها ثبت کنید.

click : زمانی فعال می‌شود که کاربر روی یک ویژگی کلیک کند.
mousemove : هنگامی که مکان‌نما روی یک ویژگی حرکت می‌کند، فعال می‌شود و برای جلوه‌های شناور مفید است.

۲. استایل پویا (افکت شناور)

از آنجا که سبک‌های DDS به صورت سراسری به لایه اعمال می‌شوند، باید یک متغیر حالت (state variable) داشته باشید تا بتوانید ردیابی کنید که با کدام ویژگی تعامل برقرار می‌شود و سبک را دوباره اعمال کنید.

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;
    }
  });
}

۳. نمایش 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);
  }
});

۴. پنجره اطلاعات سفارشی با `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() به راهنمای Migration Recommendation: Client-Side Rendering with GeoJSON مراجعه کنید.

۱. تعاملات خودکار در مقابل تعاملات دستی

تفاوت کلیدی بین این لایه‌ها نحوه مدیریت ورودی کاربر است:

KmlLayer : به طور خودکار کلیک‌های ویژگی را مدیریت می‌کند و یک InfoWindow حاوی KML نمایش می‌دهد. و داده‌ها
لایه داده : اشیاء InfoWindow به طور خودکار نمایش نمی‌دهد. شما باید به صورت دستی شنونده‌های رویداد را برای ثبت تعاملات کاربر اضافه کنید و کدی برای نمایش داده‌ها بنویسید.

۲. مدیریت رویدادهای تعاملی

برای تعاملی کردن ویژگی‌های GeoJSON، از متد addListener() در شیء map.data استفاده کنید. رویدادهای رایج عبارتند از:

click : برای فعال کردن پنجره‌های اطلاعات یا منطق انتخاب استفاده می‌شود.
mouseover / mouseout : برای جلوه‌های شناور و برجسته‌سازی استفاده می‌شود.

۳. نمایش توضیحات HTML در یک InfoWindow

وقتی 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);
  }
});

۴. سفارشی‌سازی InfoWindows و `ExtendedData`

اگر KML اصلی شما از <ExtendedData> استفاده می‌کرد، این جفت‌های نام-مقدار به ویژگی‌های GeoJSON تبدیل می‌شوند. از آنجا که لایه داده رابط کاربری پیش‌فرضی برای این موارد ندارد، باید یک InfoWindow سفارشی پیاده‌سازی کنید تا در آن پیمایش کرده و آنها را نمایش دهد.

شما می‌توانید با استفاده از event.feature.getProperty('attribute_name') به این ویژگی‌ها دسترسی پیدا کنید و یک رشته HTML یا عنصر DOM سفارشی برای ارسال به متد infoWindow.setContent() بسازید.

۵. استایل پویا (افکت‌های شناور)

لایه داده به شما امکان می‌دهد سبک‌های ویژگی را به صورت برنامه‌نویسی شده در پاسخ به رویدادها به‌روزرسانی کنید. 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).

۱. داده‌های تعاملی با deck.gl

deck.gl از KML به عنوان یک فرمت ورودی مستقیم پشتیبانی می‌کند و به طور خودکار تعاملات مربوط به ویژگی‌ها مانند کلیک‌ها را بر اساس داده‌های ارائه شده در فایل KML مدیریت می‌کند.

مدیریت KMLLoader : با استفاده از ماژول @loaders.gl/kml ، هندسه و ویژگی‌ها به فرمتی تجزیه می‌شوند که deck.gl از آن برای فعال‌سازی رویدادهای تعاملی به صورت بومی استفاده می‌کند.
کلیک روی ویژگی‌ها : وقتی روی یک ویژگی کلیک می‌شود، deck.gl می‌تواند این رویداد را ثبت کرده و فراداده‌های مرتبط (مانند <name> یا <description> ) را نمایش دهد.
مثال : نمونه به‌روزرسانی‌شده با deckgl-kml، رندر KML را به‌صورت بلادرنگ نشان می‌دهد که در آن با نگه‌داشتن ماوس روی نشانگرهای زلزله، اطلاعات دقیقی از رویداد نمایش داده می‌شود.

۲. داده‌های تعاملی با geoxml3

geoxml3 کد KML را به صورت محلی در مرورگر تجزیه می‌کند، اطلاعات استایل را استخراج می‌کند و اشیاء استاندارد 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 یا تجزیه‌کننده‌های شخص ثالث را تشریح می‌کند.

توصیه مهاجرت: API جاوا اسکریپت نقشه‌ها GroundOverlay

مسیر پیشنهادی برای انتقال تصاویر، استفاده از کلاس google.maps.GroundOverlay است. این به شما امکان می‌دهد تصویری را مستقیماً در کد خود، در مختصات جغرافیایی خاص، روی نقشه قرار دهید.

۱. پیاده‌سازی

به جای تکیه بر یک فایل KML برای تعریف مرزها، شما URL تصویر و یک شیء LatLngBounds را که نمایانگر مستطیل روی نقشه است، مشخص می‌کنید.

مستندات : راهنمای پوشش‌های زمینی .
آماده‌سازی تصویر : اگر تصویر شما ژئورفرنس شده است اما در تصویر صحیح (EPSG:4326) نیست، می‌توانید از ابزار متن‌باز gdalwarp برای تغییر شکل تصویر جهت استفاده با Maps JS API استفاده کنید.

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

مسیر مهاجرت: استفاده از کتابخانه‌های شخص ثالث

اگر گردش کار شما ایجاب می‌کند که داده‌های خود را با فرمت KML نگه دارید، می‌توانید از کتابخانه‌های شخص ثالث مانند geoxml3 یا deck.gl برای رندر کردن پوشش‌های تصویری استفاده کنید.

سلب مسئولیت: این راه‌حل‌های شخص ثالث توسط گوگل پشتیبانی نمی‌شوند . با این حال، آزمایش شده‌اند و باید برای اکثر موارد استفاده کار کنند.

۱. ژئوکس‌ام‌ال۳

geoxml3 گزینه خوبی برای تجزیه عناصر ساده GroundOverlay به صورت محلی در مرورگر و تبدیل آنها به اشیاء 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');

۲. عرشه.gl

در حالی که GeoJsonLayer استاندارد deck.gl داده‌های برداری را مدیریت می‌کند، می‌تواند GroundOverlays نیز از طریق پیاده‌سازی دستی با استفاده از BitmapLayer پشتیبانی کند.

این رویکرد شامل استفاده از KMLLoader برای تجزیه فایل و سپس تعریف صریح یک BitmapLayer با URL تصویر و مختصات استخراج شده از داده‌های KML است.

الزامات: استفاده از deck.gl به یک نوع نقشه برداری (Vector map) نیاز دارد.
مستندات: deck.gl لایه بیت‌مپ

حالت پیشرفته: هرم‌های کاشی با استفاده از gdal2tiles

برای فایل‌های پیچیده KML حاوی هرم‌های کاشی تصویری، انتقال دشوارتر است و نیاز به استخراج داده‌های تصویری دارد.

ابزار : gdal2tiles می‌تواند داده‌ها را از هرم KMZ استخراج کرده و کد API جاوا اسکریپت استاندارد Maps را برای نمایش کاشی‌ها تولید کند. توجه داشته باشید که نتیجه نهایی ممکن است نیاز به اصلاح دستی برای گنجاندن در نقشه موجود داشته باشد.

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

فایل KML با لینک‌های شبکه

مدیریت فایل‌های KML با لینک‌های شبکه نیازمند تغییر از واکشی خودکار و سمت ابر KmlLayer به استراتژی‌های مدیریت داده‌های صریح‌تر است.

راهکار پشتیبانی‌شده: استایل‌دهی داده‌محور (DDS) برای مجموعه داده‌ها

از آنجا که مجموعه داده‌های پلتفرم نقشه‌های گوگل عناصر <NetworkLink> را به صورت بومی تجزیه نمی‌کنند، شما باید بر اساس ساختار داده‌های خود، یک استراتژی مهاجرت انتخاب کنید:

استراتژی الف: مجموعه داده‌های متمایز (بهترین گزینه برای لایه‌های تحت کنترل کاربر) هر فایل KML که قبلاً یک لینک شبکه بود را به عنوان مجموعه داده جداگانه خود در کنسول Google Cloud بارگذاری کنید. سپس می‌توانید با فراخوانی map.getDatasetFeatureLayer(datasetId) و تنظیم میزان نمایش یا سبک آن، از جاوا اسکریپت برای بارگذاری پویا و نمایش این لایه‌ها در صورت نیاز استفاده کنید.
استراتژی ب: فایل KML مسطح (بهترین گزینه برای نمایش با کارایی بالا) تمام ویژگی‌های فایل‌های مختلف متصل به شبکه خود را قبل از آپلود به عنوان یک مجموعه داده، در یک فایل KML جامع و واحد ترکیب کنید. سپس می‌توانید از سبک‌دهی پویا بر اساس ویژگی‌های ویژگی‌ها برای فیلتر کردن و نمایش زیرمجموعه‌های خاص داده‌ها درجا استفاده کنید.

به‌روزرسانی داده‌های پویا: برای تقلید از رفتار «تازه‌سازی خودکار» لینک‌های شبکه، از API مجموعه داده‌ها استفاده کنید تا هر زمان که داده‌های منبع تغییر می‌کنند، نسخه جدیدی از مجموعه داده‌های خود را از طریق برنامه‌نویسی بارگذاری کنید.

راهکارهای متن‌باز: deck.gl و geoxml3

نه deck.gl و نه geoxml3 پشتیبانی قوی برای تجزیه و دریافت خودکار عناصر KML <NetworkLink> ارائه نمی‌دهند.

deck.gl

deck.gl از KMLLoader (ساخته شده بر روی togeojson ) استفاده می‌کند که صراحتاً از NetworkLinks پشتیبانی نمی‌کند .

چرا این راه حل خوبی نیست: این تجزیه‌گر به گونه‌ای طراحی شده است که یک مبدل همزمان و "بدون دردسر" باشد و از ایجاد درخواست‌های شبکه خود برای اطمینان از قابلیت اطمینان و سادگی جلوگیری کند. اگر برنامه شما به فایل‌های KML متکی است که به چندین URL دیگر اشاره می‌کنند، deck.gl به طور خودکار آنها را حل نمی‌کند.

geoxml3

اگرچه geoxml3 برای تجزیه KML برای API Maps JS توسعه داده شده است، پشتیبانی آن از لینک‌های شبکه آزمایشی و بدون پشتیبانی است.

چرا این راه حل خوبی نیست: این قابلیت فقط در یک شاخه خاص "network_link" وجود دارد که قدیمی است و به خوبی آزمایش نشده است. استفاده از این برای مهاجرت داده‌های عملیاتی توصیه نمی‌شود، زیرا ممکن است نتواند ساختارهای پیوند پیچیده یا الزامات امنیتی مدرن مانند CORS را مدیریت کند.

خلاصه توصیه

برای یک مهاجرت مطمئن، توسعه‌دهندگان باید از تجزیه‌کننده‌های شخص ثالث برای فایل‌هایی با لینک‌های شبکه اجتناب کنند و در عوض منطق واکشی داده‌ها را با استفاده از API مجموعه داده‌ها (Datasets API) بازسازی کنند . این امر تضمین می‌کند که داده‌های شما به طور ایمن در زیرساخت پلتفرم نقشه‌های گوگل مدیریت می‌شوند، نه اینکه به تجزیه‌کننده‌های سمت کلاینتِ بدون پشتیبانی تکیه کنند.

استفاده از KML برای نمایش همپوشانی‌های صفحه نمایش

برای توسعه‌دهندگانی که از KmlLayer به جایگزین‌های مدرن مانند استایل‌دهی مبتنی بر داده (DDS) مهاجرت می‌کنند، توجه به این نکته ضروری است که Screen Overlays در Datasets پشتیبانی نمی‌شود . برای دستیابی به همان اثر نمایش تصاویر ثابت، لوگوها یا راهنماها در بالای نقشه، باید با استفاده از Maps JavaScript API، کنترل‌های سفارشی ایجاد کنید.

۱. در فایل KML خود به دنبال چه چیزی باشید

برای ساخت یک کنترل سفارشی معادل، عنصر <ScreenOverlay> را در فایل KML خود برای یافتن ویژگی‌های کلیدی زیر بررسی کنید:

<Icon><href> : آدرس اینترنتی تصویری که می‌خواهید نمایش دهید.
<screenXY> : این پارامتر محل قرارگیری لایه پوششی روی صفحه را مشخص می‌کند.
- x=0, y=1 (کسری) مربوط به بالا سمت چپ است.
- x=1, y=1 مربوط به بالا سمت راست هستند.
- x=0, y=0 مربوط به پایین سمت چپ است.
- x=1, y=0 مربوط به پایین سمت راست است.
<size> : عرض و ارتفاع لایه پوششی را تعریف می‌کند.
<rotation> : مشخص می‌کند که آیا تصویر باید چرخانده شود یا خیر.

۲. پیاده‌سازی: ایجاد یک کنترل سفارشی

یک کنترل سفارشی اساساً یک عنصر HTML استاندارد (مانند <div> یا <img> ) است که شما آن را به یکی از موقعیت‌های از پیش تعریف شده نقشه "فشار" می‌دهید.

نگاشت موقعیت‌های KML به `ControlPosition`

API جاوااسکریپت Maps از enum ControlPosition برای اتصال کنترل‌ها استفاده می‌کند. از جدول زیر برای نگاشت <screenXY> در KML به ثابت JS API مناسب استفاده کنید:

موقعیت KML ( `screenXY` )	`ControlPosition` API در JS
بالا سمت چپ ( `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`

۳. مثال مهاجرت: روکش لوگوی ثابت

مثال زیر از لوگوی 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;
}

پیاده‌سازی جاوا اسکریپت

عنصر را به آرایه 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 برای استایل‌دهی به اطلاعات مرز/حاشیه/منطقه مورد نظر

توصیه مهاجرت: سبک‌دهی مبتنی بر داده برای مرزها

نوع ویژگی موجود

چگونه یک منطقه را برجسته کنیم

محدود کردن حرکت افقی به یک ناحیه

خلاصه پیاده‌سازی مهاجرت

فایل KML با داده‌های برداری (نقاط/چندخطی‌ها/مرزها/چندضلعی‌ها)

توصیه مهاجرت: سبک‌دهی داده‌محور برای مجموعه داده‌ها

۱. راه‌اندازی و آپلود

۲. تنظیم Viewport برای داده‌ها

۳. استایل‌دهی از ویژگی‌های ویژگی

مثال: استایل‌دهی به تابع با استفاده از ویژگی‌ها

توصیه مهاجرت: رندر سمت کلاینت با GeoJSON

۱. تبدیل KML به GeoJSON

۲. تنظیم Viewport برای داده‌ها

۳. استایل‌دهی از ویژگی‌های ویژگی

مثال: تابع استایل‌دهی و تنظیم نمای دید

مسیر مهاجرت: رندر سمت کلاینت با کتابخانه‌های شخص ثالث

۱. عرشه.gl

۲. ژئوکس‌میل۳

فایل KML با عناصر تعاملی

توصیه مهاجرت: سبک‌دهی داده‌محور برای مجموعه داده‌ها

راه‌اندازی اولیه

۱. مدیریت رویدادهای تعاملی

۲. استایل پویا (افکت شناور)

۳. نمایش HTML از ویژگی description

۴. پنجره اطلاعات سفارشی با ExtendedData

توصیه مهاجرت: رندر سمت کلاینت با GeoJSON

راه‌اندازی اولیه

۱. تعاملات خودکار در مقابل تعاملات دستی

۲. مدیریت رویدادهای تعاملی

۳. نمایش توضیحات HTML در یک InfoWindow

۴. سفارشی‌سازی InfoWindows و ExtendedData

۵. استایل پویا (افکت‌های شناور)

مسیر مهاجرت: رندر سمت کلاینت با کتابخانه‌های شخص ثالث

راه‌اندازی اولیه

۱. داده‌های تعاملی با deck.gl

۲. داده‌های تعاملی با geoxml3

فایل KML با تصاویر

توصیه مهاجرت: API جاوا اسکریپت نقشه‌ها GroundOverlay

۱. پیاده‌سازی

مسیر مهاجرت: استفاده از کتابخانه‌های شخص ثالث

۱. ژئوکس‌ام‌ال۳

۲. عرشه.gl

حالت پیشرفته: هرم‌های کاشی با استفاده از gdal2tiles

فایل KML با لینک‌های شبکه

راهکار پشتیبانی‌شده: استایل‌دهی داده‌محور (DDS) برای مجموعه داده‌ها

راهکارهای متن‌باز: deck.gl و geoxml3

deck.gl

geoxml3

خلاصه توصیه

استفاده از KML برای نمایش همپوشانی‌های صفحه نمایش

۱. در فایل KML خود به دنبال چه چیزی باشید

۲. پیاده‌سازی: ایجاد یک کنترل سفارشی

نگاشت موقعیت‌های KML به ControlPosition

۳. مثال مهاجرت: روکش لوگوی ثابت

استایل‌دهی CSS

پیاده‌سازی جاوا اسکریپت

اطلاعات بیشتر

مسیرهای مهاجرت KmlLayer

۳. نمایش HTML از ویژگی `description`

۴. پنجره اطلاعات سفارشی با `ExtendedData`

۴. سفارشی‌سازی InfoWindows و `ExtendedData`

نگاشت موقعیت‌های KML به `ControlPosition`