Jalur Migrasi KmlLayer

Pengantar

Tujuan panduan ini adalah membahas penggunaan KmlLayer yang paling umum dan menyediakan jalur migrasi yang sesuai ke penerapan alternatif. Informasi ini ditujukan bagi developer yang perlu beralih dari penggunaan KmlLayer karena penghentiannya yang dijadwalkan. Versi terakhir yang mendukung KmlLayer adalah 3.65, yang akan dihentikan pada Mei 2027.

Jalur migrasi Anda bergantung pada cara Anda menggunakan KmlLayer:

File KML untuk menata gaya informasi batas/perbatasan/area yang diminati : Gunakan Gaya visual berbasis data (DDS) untuk batas untuk area administratif menggunakan data batas Google.
File KML dengan data vektor (Titik/Polyline/Batas/Poligon): Gunakan DDS untuk set data, GeoJSON, atau library pihak ketiga seperti deck.gl atau geoxml3.
File KML dengan elemen interaktif: Terapkan pemroses peristiwa manual dan jendela info kustom untuk interaksi fitur.
File KML dengan gambar: Gunakan GroundOverlays atau parser pihak ketiga untuk overlay gambar.
File KML dengan Link Jaringan: Upload setiap KML sebagai set data terpisah, atau gabungkan KML. Jika menampilkan data dinamis, muat ulang set data menggunakan Datasets API.
Menggunakan KML untuk menampilkan Overlay Layar: Gunakan Kontrol Kustom untuk mengganti elemen UI tetap seperti logo, legenda, atau bantuan navigasi.

File KML untuk mengatur gaya visual informasi batas/perbatasan/area yang diminati

Untuk developer yang menggunakan KmlLayer untuk menampilkan atau mengatur gaya visual batas administratif—seperti menandai negara, negara bagian, atau lokalitas tertentu—Google Maps Platform merekomendasikan migrasi ke Gaya visual berbasis data (DDS) untuk batas.

Rekomendasi Migrasi: Gaya Visual Berbasis Data untuk Batas

Gaya visual berbasis data untuk batas memberikan akses langsung ke poligon batas administratif Google, sehingga Anda dapat menerapkan gaya visual kustom (pengisian dan goresan) ke wilayah ini tanpa perlu menghosting atau mengelola file KML eksternal.

Tersedia FeatureType

Wilayah administratif dikategorikan berdasarkan fungsi dan diatur berdasarkan tingkat. Jenis fitur berikut didukung untuk gaya visual:

COUNTRY: Entitas politik nasional.
ADMINISTRATIVE_AREA_LEVEL_1: Entitas sipil urutan pertama di bawah tingkat negara (misalnya, negara bagian di AS).
ADMINISTRATIVE_AREA_LEVEL_2: Entitas sipil urutan kedua di bawah tingkat negara (misalnya, county di AS).
LOCALITY: Gabungan kota besar atau kota kecil.
POSTAL_CODE: Kode pos yang digunakan untuk surat.
SCHOOL_DISTRICT: Distrik sekolah dasar, menengah, atau menengah atas terpadu.

Lihat cakupan batas untuk wilayah tempat jenis fitur ini tersedia.

Cara Menandai Area

Untuk menata gaya wilayah tertentu, Anda harus menargetkannya berdasarkan ID Tempat-nya.

Penyiapan: Anda harus menggunakan ID Peta yang dikonfigurasi untuk jenis peta Vektor JavaScript dan mengaktifkan Lapisan fitur yang tersedia di Konsol Google Cloud.
Penerapan: gunakan kode contoh Menata gaya poligon batas.

Membatasi Penggeseran ke Area

Untuk mencegah pengguna keluar dari kotak pembatas area yang Anda tandai, Anda dapat menggunakan opsi restriction dalam MapOptions.

Objek restriction menentukan latLngBounds yang membatasi area peta yang dapat dilihat. Lihat dokumentasi untuk mengetahui detail selengkapnya tentang cara kerja pembatasan.

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

Ringkasan Penerapan Migrasi

Berikut adalah contoh lengkap cara menggunakan Gaya visual berbasis data untuk batas dan pembatasan wilayah guna memfokuskan peta di sekitar area tertentu.

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

File KML dengan data vektor (Titik/Polyline/Batas/Poligon)

Rekomendasi Migrasi: Gaya Visual Berbasis Data untuk Set Data

Google merekomendasikan jalur di bawah ini untuk menampilkan data geografis yang tersedia secara publik sekaligus mendapatkan kontrol yang lebih besar atas gaya dan performa.

Gaya visual berbasis data untuk set data memungkinkan Anda mengupload data geospasial Anda sendiri (KML, GeoJSON, atau CSV), menerapkan gaya visual kustom berdasarkan atribut data, dan menampilkan fitur di peta vektor.

1. Penyiapan dan Upload

Tidak seperti KmlLayer, yang mengambil URL saat runtime, DDS mengharuskan Anda menghosting data sebagai set data di Konsol Google Cloud.

Buat ID Peta: Gunakan ID Peta yang dikonfigurasi untuk jenis Peta vektor.
Mengupload Set Data: Upload file KML Anda ke Konsol Google Cloud untuk membuat ID Set Data yang unik. Baca dokumentasi lengkap tentang cara mengelola Set Data Maps untuk mengetahui detail selengkapnya.
Menampilkan Set Data: Setelah membuat ID Set Data, Anda perlu mengaitkan Set Data dengan Gaya Peta dan ID Peta. Kemudian, Anda akan menggunakan ID Set Data untuk benar-benar menampilkan data di peta. Baca dokumentasi lengkap tentang cara Menambahkan set data ke peta untuk mengetahui semua detailnya.
Perhatikan persyaratan KML untuk Set Data, jika Anda memutuskan untuk mengimpor data dari format KML.

2. Menyetel Area Pandang ke Data

KmlLayer secara otomatis melakukan penyesuaian dan zoom ke lokasi data secara default. Dengan DDS untuk set data, perilaku ini tidak otomatis dan harus diterapkan secara manual.

Batasan yang Dikodekan Langsung: Jika area data bersifat statis, gunakan opsi restriction di MapOptions untuk mengunci area tampilan ke batas tertentu.
Zooming Dinamis: Untuk menetapkan area tampilan secara dinamis, Anda dapat menggunakan map.fitBounds() dengan kotak pembatas set data Anda.

3. Menyesuaikan gaya dari Atribut Fitur

File KML sering kali berisi informasi gaya visual (seperti warna) yang tidak diterapkan secara otomatis oleh DDS. Anda harus membuat fungsi gaya sisi klien yang membaca atribut dari fitur set data untuk menerapkan warna dan opasitas. Lihat dokumentasi developer tentang cara menata gaya data Anda untuk mengetahui detail selengkapnya.

Contoh: Menata Fungsi menggunakan Atribut

Contoh berikut menunjukkan cara membuat fungsi gaya yang membaca atribut background_color dan opacity langsung dari set data yang diupload:

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

Untuk mengetahui detail lebih lanjut tentang penerapan interaksi dan gaya visual, lihat Ringkasan gaya visual berbasis data untuk set data dan Datasets API untuk data dinamis.

Rekomendasi Migrasi: Rendering Sisi Klien dengan GeoJSON

Untuk developer yang bermigrasi dari KmlLayer ke rendering sisi klien dengan GeoJSON, Google Maps Platform merekomendasikan jalur migrasi yang melibatkan konversi format data dan penggunaan Lapisan data untuk merender dan menata gaya fitur secara langsung di browser.

Rendering sisi klien menggunakan Lapisan data memberikan cara yang sangat fleksibel untuk menampilkan data geografis. Tidak seperti KmlLayer, yang dirender di server Google, Lapisan data memungkinkan Anda berinteraksi dengan fitur sebagai objek JavaScript standar. Namun, perhatikan bahwa untuk set data besar, Anda mungkin lebih memilih pemrosesan dan rendering data di sisi server, seperti dengan Gaya yang Didorong Data untuk Set Data.

1. Mengonversi KML ke GeoJSON

Langkah pertama adalah mengonversi file KML Anda menjadi GeoJSON. Hal ini dapat dilakukan menggunakan beberapa alat open source populer:

ogr2ogr: Bagian dari rangkaian GDAL, utilitas command line yang canggih ini dapat mengonversi antara banyak format vektor.

ogr2ogr -f GeoJSON output.json input.kml

togeojson: Alat kecil yang telah diuji dengan baik dan dirancang khusus untuk mengonversi KML dan GPX ke GeoJSON.

togeojson input.kml > output.json

2. Menyetel Area Pandang ke Data

Meskipun KmlLayer otomatis menggeser dan melakukan zoom ke lokasi data, lapisan Data tidak melakukannya. Untuk menyetel area tampilan agar sesuai dengan data GeoJSON, Anda harus menghitung kotak pembatas secara manual dan memanggil map.fitBounds().

3. Menyesuaikan gaya dari Atribut Fitur

Di Lapisan data, Anda dapat menentukan fungsi style yang membaca atribut (properti) langsung dari setiap fitur GeoJSON untuk menentukan penampilannya.

Contoh: Penyesuaian Fungsi dan Area Lihat

Contoh berikut menunjukkan cara memuat data GeoJSON, menghitung batasnya untuk menetapkan area tampilan, dan menata gaya fitur berdasarkan atributnya:

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

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Lapisan data, lihat dokumentasi Mengimpor GeoJSON ke Maps.

Jalur Migrasi: Rendering Sisi Klien dengan library pihak ketiga

Untuk developer yang mencari alternatif lain selain KmlLayer, ada beberapa library yang dikelola komunitas yang merender data KML di Google Maps Platform JavaScript API.

1. deck.gl

deck.gl adalah framework visualisasi berperforma tinggi yang didukung WebGL. Library ini dapat digunakan sebagai pengganti hampir langsung untuk rendering KML melalui GoogleMapsOverlay dan GeoJsonLayer.

Persyaratan Canvas: Untuk menggunakan deck.gl secara efektif, Anda harus mengonversi peta Anda agar menggunakan jenis peta Vektor (yang dirender ke elemen canvas) dengan kemampuan rendering WebGL-nya.
Dukungan KML: Penguraian geometri ditangani oleh @loaders.gl/kml, yang mengonversi KML menjadi GeoJSON. Perhatikan bahwa beberapa fitur KML seperti gaya kompleks, ikon, dan NetworkLink mungkin memerlukan penerapan manual tambahan.
Dokumentasi: Dokumentasi deck.gl | Pemuat KML loaders.gl.
Contoh:
- Contoh deckgl-kml-updated di repositori GitHub Google Maps menunjukkan cara menggunakan deck.gl untuk merender data KML yang diupdate secara real-time.
- Contoh deckgl-kml menunjukkan cara menggunakan deck.gl untuk merender data KML.

2. geoxml3

geoxml3 adalah pemroses KML yang dirancang khusus untuk Google Maps JavaScript API v3. Aplikasi ini mem-parsing KML secara lokal di browser dan merender data sebagai objek Google Maps API standar seperti Penanda, Polyline, dan Poligon.

Dukungan Peta Standar: Tidak seperti solusi berbasis WebGL, geoxml3 berfungsi di peta Google Maps JS API v3 standar tanpa memerlukan mode rendering tertentu.
Peringatan:
- Dukungan KMZ Terbatas: Library tidak sepenuhnya mendukung file KMZ secara native; membuka arsip KMZ biasanya memerlukan integrasi dengan skrip pihak ketiga tambahan seperti ZipFile.complete.js.
- Elemen yang Tidak Didukung: Fitur seperti geometri 3D, label kompleks, dan elemen KML baru tertentu tidak didukung.
Dokumentasi: Repositori GitHub geoxml3.

File KML dengan elemen interaktif

Rekomendasi Migrasi: Gaya Visual Berbasis Data untuk Set Data

Bagi developer yang bermigrasi dari KmlLayer ke Penataan gaya berbasis data (DDS) untuk kumpulan data, panduan ini menjelaskan cara bertransisi dari interaksi KML otomatis ke interaksi kustom berperforma tinggi seperti klik dan pengarahan kursor.

Penyiapan Awal

Sebelum menerapkan interaksi, pastikan Anda telah mengikuti langkah-langkah penyiapan dari panduan Migrasi KML: Data Vektor:

ID Peta: Konfigurasi ID Peta untuk jenis Peta vektor.
Upload: Upload data KML Anda ke Konsol Google Cloud untuk mendapatkan ID Set Data.
Akses Lapisan: Gunakan map.getDatasetFeatureLayer(datasetId) untuk mengakses lapisan interaktif.

1. Menangani Peristiwa Interaksi

Di KmlLayer, klik fitur ditangani secara otomatis oleh API untuk memunculkan jendela info. Dengan DDS untuk set data, Anda harus mendaftarkan pemroses untuk peristiwa mouse di lapisan set data secara manual.

click: Dipicu saat pengguna mengklik fitur.
mousemove: Dipicu saat kursor bergerak di atas fitur, berguna untuk efek pengarahan kursor.

2. Gaya Dinamis (Efek Saat Kursor Diarahkan)

Karena gaya DDS diterapkan secara global ke lapisan, Anda harus mempertahankan variabel status untuk melacak fitur mana yang berinteraksi dan menerapkan kembali gaya.

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. Menampilkan HTML dari Atribut `description`

Dalam KML, tag <description> sering kali berisi HTML untuk jendela info default. Saat data ini diimpor sebagai set data, description akan menjadi atribut fitur. Untuk merendernya, teruskan string langsung ke google.maps.InfoWindow standar.

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. InfoWindow Kustom dengan `ExtendedData`

Jika KML Anda menggunakan <ExtendedData> untuk menyimpan pasangan nama/nilai kustom, pasangan ini dipetakan ke datasetAttributes. Anda dapat melakukan iterasi pada atribut ini untuk membuat tampilan HTML kustom.

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

Untuk teknik visualisasi yang lebih canggih, lihat dokumentasi developer tentang cara menata fitur data.

Rekomendasi Migrasi: Rendering Sisi Klien dengan GeoJSON

Untuk developer yang melakukan migrasi dari KmlLayer ke rendering sisi klien dengan GeoJSON dan Lapisan data, panduan ini menjelaskan cara bertransisi dari interaksi KML otomatis ke interaksi kustom berbasis peristiwa dan gaya dinamis.

Penyiapan Awal

Sebelum menerapkan interaksi, Anda harus mengonversi data KML ke GeoJSON dan memuatnya ke Lapisan data. Lihat panduan Rekomendasi Migrasi: Rendering Sisi Klien dengan GeoJSON untuk mengetahui detail tentang penggunaan alat seperti ogr2ogr atau togeojson dan menginisialisasi peta dengan map.data.loadGeoJson().

1. Interaksi Otomatis versus Manual

Perbedaan utama antara lapisan ini adalah cara mereka menangani input pengguna:

KmlLayer: Menangani klik fitur secara otomatis dan menampilkan InfoWindow yang berisi data dan KML.
Lapisan Data: Tidak menampilkan objek InfoWindow secara otomatis. Anda harus menambahkan pemroses peristiwa secara manual untuk merekam interaksi pengguna dan menulis kode untuk menampilkan data.

2. Menangani Peristiwa Interaksi

Untuk membuat fitur GeoJSON interaktif, gunakan metode addListener() pada objek map.data. Peristiwa umum meliputi:

click: Digunakan untuk memicu jendela info atau logika pemilihan.
mouseover / mouseout: Digunakan untuk efek pengarahan kursor dan penyorotan.

3. Menampilkan Deskripsi HTML di InfoWindow

Saat KML dikonversi menjadi GeoJSON, tag <description> (yang sering kali berisi HTML) biasanya dipetakan ke properti bernama description. Anda dapat menggunakan feature.getProperty('description') untuk mengambil string ini dan merendernya di dalam google.maps.InfoWindow standar.

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. InfoWindows Kustom dan `ExtendedData`

Jika KML asli Anda menggunakan <ExtendedData>, pasangan nama-nilai ini akan dikonversi menjadi properti GeoJSON. Karena Lapisan data tidak memiliki UI default untuk hal ini, Anda harus menerapkan InfoWindow kustom untuk melakukan iterasi dan menampilkannya.

Anda dapat mengakses atribut ini menggunakan event.feature.getProperty('attribute_name') dan membuat string HTML kustom atau elemen DOM untuk diteruskan ke metode infoWindow.setContent().

5. Gaya Visual Dinamis (Efek Saat Kursor Diarahkan)

Lapisan Data memungkinkan Anda memperbarui gaya fitur secara terprogram sebagai respons terhadap peristiwa. Gunakan overrideStyle() untuk mengubah sementara tampilan fitur (misalnya, saat kursor diarahkan) dan revertStyle() untuk kembali ke gaya global.

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

Untuk detail penerapan yang lebih mendetail, lihat dokumentasi tentang Lapisan Data: Penanganan Peristiwa dan Lapisan Data: Gaya Visual Dinamis.

Jalur Migrasi: Rendering Sisi Klien dengan library pihak ketiga

Untuk developer yang bermigrasi dari KmlLayer ke solusi pihak ketiga, panduan ini berfokus pada penanganan data interaktif seperti klik mouse dan peristiwa dinamis menggunakan deck.gl dan geoxml3.

Penyiapan Awal

Sebelum menerapkan interaksi, pastikan Anda telah mengikuti langkah-langkah penyiapan dari panduan Jalur Migrasi: Rendering Sisi Klien dengan library pihak ke-3. Hal ini mencakup:

deck.gl: Mengonversi peta Anda untuk menggunakan Jenis peta vektor (persyaratan kanvas).
geoxml3: Menayangkan skrip pustaka dari host Anda sendiri dan mengelola Cross-Origin Resource Sharing (CORS).

1. Data Interaktif dengan deck.gl

deck.gl mendukung KML sebagai format input langsung dan secara otomatis menangani interaksi fitur seperti klik berdasarkan data yang diberikan dalam file KML.

Penanganan KMLLoader: Menggunakan modul @loaders.gl/kml, geometri dan properti diuraikan ke dalam format yang digunakan deck.gl untuk memicu peristiwa interaksi secara native.
Klik Fitur: Saat fitur diklik, deck.gl dapat merekam peristiwa dan menampilkan metadata terkait (seperti <name> atau <description>).
Contoh: Contoh deckgl-kml-updated menunjukkan rendering KML real-time di mana mengarahkan kursor ke penanda gempa bumi akan menampilkan informasi peristiwa yang mendetail.

2. Data Interaktif dengan geoxml3

geoxml3 mengurai KML secara lokal di browser, mengekstrak informasi gaya, dan membuat objek Google Maps API standar yang mempertahankan interaktivitasnya.

Ekstraksi Gaya Native: Library mengambil elemen <Style> dan <StyleMap> dari KML untuk menerapkannya ke Penanda, Polyline, dan Poligon yang dihasilkan.
Click Handler: Secara default, geoxml3 menyediakan click handler untuk objek ini. Anda juga dapat menentukan fungsi callback kustom (createMarker, createOverlay) selama instansiasi parser untuk menerapkan logika pemilihan atau pembaruan sidebar Anda sendiri.
Contoh: Contoh ini menunjukkan cara menggunakan geoxml3 untuk merender KML, dengan penyesuaian seperti penanda lingkaran dengan interaksi, seperti mengklik penanda untuk menampilkan informasi gempa bumi.
Pola Penggunaan:

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

File KML dengan gambar

Untuk developer yang menggunakan KmlLayer untuk menampilkan gambar—seperti peta dengan data yang berasal dari satelit, pola cuaca, atau cetak biru historis—panduan ini menguraikan jalur migrasi ke GroundOverlays atau parser pihak ketiga.

Rekomendasi Migrasi: GroundOverlay Maps JavaScript API

Jalur yang direkomendasikan untuk memigrasikan gambar adalah dengan menggunakan class google.maps.GroundOverlay. Dengan begitu, Anda dapat menempatkan gambar di peta pada koordinat geografis tertentu langsung dalam kode.

1. Penerapan

Daripada mengandalkan file KML untuk menentukan batas, Anda menentukan URL gambar dan objek LatLngBounds yang merepresentasikan persegi panjang pada peta.

Dokumentasi: Panduan Overlay Bumi.
Penyiapan Gambar: Jika gambar Anda memiliki georeferensi, tetapi tidak dalam proyeksi yang benar (EPSG:4326), Anda dapat menggunakan alat open source gdalwarp untuk memodifikasi gambar agar dapat digunakan dengan Maps JS API.

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

Jalur Migrasi: Menggunakan Library Pihak Ketiga

Jika alur kerja Anda mengharuskan Anda menyimpan data dalam format KML, library pihak ketiga seperti geoxml3 atau deck.gl dapat digunakan untuk merender overlay gambar.

Pernyataan penyangkalan: Solusi pihak ketiga ini tidak didukung oleh Google. Namun, fitur ini telah diuji dan akan berfungsi untuk sebagian besar kasus penggunaan.

1. geoxml3

geoxml3 adalah opsi yang baik untuk mengurai elemen GroundOverlay sederhana secara lokal di browser dan mengonversinya menjadi objek Google Maps API.

Contoh Penggunaan:

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

Meskipun GeoJsonLayer standar deck.gl menangani data vektor, GeoJsonLayer ini juga dapat mendukung GroundOverlays melalui penerapan manual menggunakan BitmapLayer.

Pendekatan ini melibatkan pemanfaatan KMLLoader untuk mengurai file, lalu secara eksplisit menentukan BitmapLayer dengan URL gambar dan koordinat yang diekstrak dari data KML.

Persyaratan: Penggunaan deck.gl memerlukan jenis Peta vektor.
Dokumentasi: Lapisan Bitmap deck.gl

Kasus Lanjutan: Petak Piramida menggunakan gdal2tiles

Untuk file KML kompleks yang berisi piramida petak gambar, migrasi lebih sulit dan memerlukan ekstraksi data gambar.

Alat: gdal2tiles dapat mengekstrak data dari piramida KMZ dan menghasilkan kode Maps JavaScript API standar untuk menampilkan petak. Perhatikan bahwa hasil akhir mungkin memerlukan modifikasi manual agar dapat dimasukkan ke dalam peta yang ada.

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

File KML dengan Link Jaringan

Penanganan file KML dengan link jaringan memerlukan peralihan dari pengambilan KmlLayer otomatis di sisi cloud ke strategi pengelolaan data yang lebih eksplisit.

Solusi yang Didukung: Gaya Visual Berbasis Data (DDS) untuk Set Data

Karena set data Google Maps Platform tidak secara native mengurai elemen <NetworkLink>, Anda harus memilih strategi migrasi berdasarkan struktur data Anda:

Strategi A: Kumpulan Data Terpisah (Terbaik untuk Lapisan yang Dikontrol Pengguna) Upload setiap file KML yang sebelumnya merupakan link jaringan sebagai kumpulan data terpisah di Konsol Google Cloud. Kemudian, Anda dapat menggunakan JavaScript untuk memuat dan menampilkan lapisan ini secara dinamis saat diperlukan dengan memanggil map.getDatasetFeatureLayer(datasetId) dan menyesuaikan visibilitas atau gayanya.
Strategi B: File KML yang Diratakan (Terbaik untuk Tampilan Performa Tinggi) Gabungkan semua fitur dari berbagai file yang ditautkan ke jaringan menjadi satu file KML yang komprehensif sebelum menguploadnya sebagai set data. Kemudian, Anda dapat menggunakan gaya dinamis berdasarkan atribut fitur untuk memfilter dan menampilkan subkumpulan data tertentu secara langsung.

Memperbarui Data Dinamis: Untuk meniru perilaku "muat ulang otomatis" link jaringan, gunakan Datasets API untuk mengupload versi baru set data Anda secara terprogram setiap kali data sumber berubah.

Solusi Open Source: deck.gl dan geoxml3

deck.gl maupun geoxml3 tidak memberikan dukungan yang kuat untuk mengurai dan mengambil elemen <NetworkLink> KML secara otomatis.

deck.gl

deck.gl menggunakan KMLLoader (dibuat di togeojson), yang secara eksplisit tidak mendukung NetworkLink.

Alasan mengapa ini bukan solusi yang baik: Parser dirancang sebagai konverter sinkron "tanpa repot" yang menghindari pembuatan permintaan jaringannya sendiri untuk memastikan keandalan dan kesederhanaan. Jika aplikasi Anda mengandalkan file KML yang mengarah ke beberapa URL lain, deck.gl tidak akan menyelesaikannya secara otomatis.

geoxml3

Meskipun geoxml3 dikembangkan untuk mengurai KML untuk Maps JS API, dukungan untuk link jaringan bersifat eksperimental dan tidak dikelola.

Mengapa ini bukan solusi yang baik: Fungsi hanya ada di cabang "network_link" tertentu yang sudah lama dan tidak diuji dengan baik. Penggunaan alat ini untuk migrasi data produksi tidak disarankan karena alat ini mungkin gagal menangani struktur link yang kompleks atau persyaratan keamanan modern seperti CORS.

Rekomendasi Ringkasan

Untuk migrasi yang andal, developer harus menghindari parser pihak ketiga untuk file dengan link jaringan dan membangun kembali logika pengambilan data menggunakan Datasets API. Hal ini memastikan data Anda dikelola dengan aman dalam infrastruktur Google Maps Platform, bukan mengandalkan parser sisi klien yang tidak dikelola.

Menggunakan KML untuk menampilkan Overlay Layar

Untuk developer yang bermigrasi dari KmlLayer ke alternatif modern seperti Gaya visual berbasis data (DDS), penting untuk diperhatikan bahwa Overlay Layar tidak didukung di Kumpulan Data. Untuk mendapatkan efek yang sama dalam menampilkan gambar, logo, atau legenda tetap di atas peta, Anda harus membuat Kontrol Kustom menggunakan Maps JavaScript API.

1. Yang Harus Dicari dalam File KML Anda

Untuk membuat Kontrol Kustom yang setara, periksa elemen <ScreenOverlay> dalam file KML Anda untuk mengetahui atribut utama berikut:

<Icon><href>: URL gambar yang ingin Anda tampilkan.
<screenXY>: Ini menentukan posisi overlay di layar.
- x=0, y=1 (pecahan) sesuai dengan Kiri Atas.
- x=1, y=1 sesuai dengan Kanan Atas.
- x=0, y=0 sesuai dengan Kiri Bawah.
- x=1, y=0 sesuai dengan Kanan Bawah.
<size>: Menentukan lebar dan tinggi overlay.
<rotation>: Menunjukkan apakah gambar harus diputar.

2. Implementasi: Membuat Kontrol Kustom

Kontrol Kustom pada dasarnya adalah elemen HTML standar (seperti <div> atau <img>) yang Anda "dorong" ke salah satu posisi standar peta.

Memetakan Posisi KML ke `ControlPosition`

Maps JavaScript API menggunakan enum ControlPosition untuk menyematkan kontrol. Gunakan tabel di bawah untuk memetakan <screenXY> KML ke konstanta JS API yang sesuai:

Posisi KML (`screenXY`)	JS API `ControlPosition`
Kiri Atas (`x:0, y:1`)	`TOP_LEFT` (Legacy) atau `BLOCK_START_INLINE_START` (Logical)
Kanan Atas (`x:1, y:1`)	`TOP_RIGHT` atau `BLOCK_START_INLINE_END`
Kiri Bawah (`x:0, y:0`)	`BOTTOM_LEFT` atau `BLOCK_END_INLINE_START`
Kanan Bawah (`x:1, y:0`)	`BOTTOM_RIGHT` atau `BLOCK_END_INLINE_END`

3. Contoh Migrasi: Overlay Logo Tetap

Contoh berikut meniru logo ScreenOverlay KML yang diposisikan di Kanan Atas peta.

Gaya CSS

Gunakan CSS untuk menentukan ukuran dan tampilan "overlay" Anda.

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

Penerapan JavaScript

Tambahkan elemen ke array 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);
}

Jalur Migrasi KmlLayer Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Pengantar

File KML untuk mengatur gaya visual informasi batas/perbatasan/area yang diminati

Rekomendasi Migrasi: Gaya Visual Berbasis Data untuk Batas

Tersedia FeatureType

Cara Menandai Area

Membatasi Penggeseran ke Area

Ringkasan Penerapan Migrasi

File KML dengan data vektor (Titik/Polyline/Batas/Poligon)

Rekomendasi Migrasi: Gaya Visual Berbasis Data untuk Set Data

1. Penyiapan dan Upload

2. Menyetel Area Pandang ke Data

3. Menyesuaikan gaya dari Atribut Fitur

Contoh: Menata Fungsi menggunakan Atribut

Rekomendasi Migrasi: Rendering Sisi Klien dengan GeoJSON

1. Mengonversi KML ke GeoJSON

2. Menyetel Area Pandang ke Data

3. Menyesuaikan gaya dari Atribut Fitur

Contoh: Penyesuaian Fungsi dan Area Lihat

Jalur Migrasi: Rendering Sisi Klien dengan library pihak ketiga

1. deck.gl

2. geoxml3

File KML dengan elemen interaktif

Rekomendasi Migrasi: Gaya Visual Berbasis Data untuk Set Data

Penyiapan Awal

1. Menangani Peristiwa Interaksi

2. Gaya Dinamis (Efek Saat Kursor Diarahkan)

3. Menampilkan HTML dari Atribut description

4. InfoWindow Kustom dengan ExtendedData

Rekomendasi Migrasi: Rendering Sisi Klien dengan GeoJSON

Penyiapan Awal

1. Interaksi Otomatis versus Manual

2. Menangani Peristiwa Interaksi

3. Menampilkan Deskripsi HTML di InfoWindow

4. InfoWindows Kustom dan ExtendedData

5. Gaya Visual Dinamis (Efek Saat Kursor Diarahkan)

Jalur Migrasi: Rendering Sisi Klien dengan library pihak ketiga

Penyiapan Awal

1. Data Interaktif dengan deck.gl

2. Data Interaktif dengan geoxml3

File KML dengan gambar

Rekomendasi Migrasi: GroundOverlay Maps JavaScript API

1. Penerapan

Jalur Migrasi: Menggunakan Library Pihak Ketiga

1. geoxml3

2. deck.gl

Kasus Lanjutan: Petak Piramida menggunakan gdal2tiles

File KML dengan Link Jaringan

Solusi yang Didukung: Gaya Visual Berbasis Data (DDS) untuk Set Data

Solusi Open Source: deck.gl dan geoxml3

deck.gl

geoxml3

Rekomendasi Ringkasan

Menggunakan KML untuk menampilkan Overlay Layar

1. Yang Harus Dicari dalam File KML Anda

2. Implementasi: Membuat Kontrol Kustom

Memetakan Posisi KML ke ControlPosition

3. Contoh Migrasi: Overlay Logo Tetap

Gaya CSS

Penerapan JavaScript

Informasi Selengkapnya

Jalur Migrasi KmlLayer

3. Menampilkan HTML dari Atribut `description`

4. InfoWindow Kustom dengan `ExtendedData`

4. InfoWindows Kustom dan `ExtendedData`

Memetakan Posisi KML ke `ControlPosition`