เส้นทางการย้ายข้อมูล KmlLayer

บทนำ

จุดประสงค์ของคู่มือนี้คือการครอบคลุมการใช้งาน KmlLayer ที่พบบ่อยที่สุดและ ระบุเส้นทางการย้ายข้อมูลที่สอดคล้องกันไปยังการใช้งานทางเลือก ข้อมูลนี้มีไว้สำหรับนักพัฒนาแอปที่ต้องเปลี่ยนจากการใช้ KmlLayer เนื่องจากมีการกำหนดเลิกใช้งานแล้ว เวอร์ชันสุดท้ายที่รองรับ KmlLayer คือ 3.65 ซึ่งจะหยุดให้บริการในเดือนพฤษภาคม 2027

เส้นทางการย้ายข้อมูลจะขึ้นอยู่กับวิธีที่คุณใช้ KmlLayer ดังนี้

ไฟล์ KML สำหรับจัดรูปแบบข้อมูลขอบเขต/เขตแดน/พื้นที่ที่สนใจ

สำหรับนักพัฒนาที่ใช้ KmlLayer เพื่อแสดงหรือจัดรูปแบบขอบเขตการบริหาร เช่น การไฮไลต์ประเทศ รัฐ หรือย่านที่เฉพาะเจาะจง Google Maps Platform ขอแนะนำให้ย้ายข้อมูลไปยังการจัดรูปแบบตามข้อมูล (DDS) สำหรับขอบเขต

คำแนะนำในการย้ายข้อมูล: การจัดรูปแบบตามข้อมูลสำหรับขอบเขต

การจัดรูปแบบตามข้อมูลสำหรับขอบเขต ช่วยให้คุณเข้าถึง รูปหลายเหลี่ยมของขอบเขตการบริหารของ Google ได้โดยตรง ซึ่งช่วยให้คุณใช้รูปแบบที่กำหนดเอง (การเติมและ การลากเส้น) กับภูมิภาคเหล่านี้ได้โดยไม่ต้องโฮสต์หรือจัดการไฟล์ KML ภายนอก

FeatureType ที่พร้อมใช้งาน

เขตบริหารจะจัดหมวดหมู่ตามฟังก์ชันและจัดเรียงตามระดับ ระบบรองรับฟีเจอร์ประเภทต่อไปนี้สำหรับการจัดรูปแบบ

  • COUNTRY: หน่วยงานทางการเมืองระดับประเทศ
  • ADMINISTRATIVE_AREA_LEVEL_1: เอนทิตีพลเรือนระดับที่ 1 ที่ต่ำกว่าระดับประเทศ (เช่น รัฐในสหรัฐอเมริกา)
  • ADMINISTRATIVE_AREA_LEVEL_2: เอนทิตีพลเรือนระดับที่สองที่ต่ำกว่าระดับประเทศ (เช่น เคาน์ตีในสหรัฐอเมริกา)
  • LOCALITY: เมืองหรือเทศบาลที่จดทะเบียน
  • POSTAL_CODE: รหัสไปรษณีย์ที่ใช้สำหรับการส่งจดหมาย
  • SCHOOL_DISTRICT: เขตการศึกษาแบบรวม ประถมศึกษา หรือ โรงเรียนมัธยมศึกษา

ดูขอบเขต สำหรับภูมิภาคที่พร้อมใช้งานฟีเจอร์ประเภทนี้

วิธีไฮไลต์พื้นที่

หากต้องการจัดรูปแบบภูมิภาคที่เฉพาะเจาะจง คุณต้องกำหนดเป้าหมายโดยใช้รหัสสถานที่

การจำกัดการแพนไปยังพื้นที่

หากต้องการป้องกันไม่ให้ผู้ใช้นำทางออกนอกกรอบล้อมรอบของพื้นที่ที่ไฮไลต์ คุณสามารถใช้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

2. การตั้งค่าวิวพอร์ตเป็นข้อมูล

KmlLayer จะเลื่อนและซูมไปยังตำแหน่งข้อมูลโดยอัตโนมัติโดยค่าเริ่มต้น เมื่อใช้ DDS สำหรับชุดข้อมูล ลักษณะการทำงานนี้จะไม่เป็นไปโดยอัตโนมัติและต้องนำไปใช้ด้วยตนเอง

  • ข้อจำกัดที่ฮาร์ดโค้ด: หากพื้นที่ข้อมูลเป็นแบบคงที่ ให้ใช้ตัวเลือก restriction ใน MapOptions เพื่อล็อกวิวพอร์ตให้อยู่ภายในขอบเขตที่เฉพาะเจาะจง
  • การซูมแบบไดนามิก: หากต้องการตั้งค่า Viewport แบบไดนามิก คุณสามารถใช้ map.fitBounds() กับกรอบล้อมรอบของชุดข้อมูล

3. การจัดรูปแบบจากแอตทริบิวต์ฟีเจอร์

ไฟล์ KML มักจะมีข้อมูลรูปแบบ (เช่น สี) ที่ DDS ไม่ได้ใช้โดยอัตโนมัติ คุณต้องสร้างฟังก์ชันสไตล์ฝั่งไคลเอ็นต์ที่อ่านแอตทริบิวต์จากฟีเจอร์ชุดข้อมูลเพื่อใช้สีและความทึบ โปรดดูรายละเอียดทั้งหมดในเอกสารสำหรับนักพัฒนาซอฟต์แวร์เกี่ยวกับวิธีจัดรูปแบบข้อมูล

ตัวอย่าง: การจัดรูปแบบฟังก์ชันโดยใช้แอตทริบิวต์

ตัวอย่างต่อไปนี้แสดงวิธีสร้างฟังก์ชันรูปแบบที่อ่านแอตทริบิวต์ background_color และ opacity จากชุดข้อมูลที่อัปโหลดโดยตรง

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

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

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

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

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการใช้งานการโต้ตอบและการจัดรูปแบบได้ที่ ภาพรวมการจัดรูปแบบตามข้อมูลสำหรับชุดข้อมูล และ Datasets API สำหรับข้อมูลแบบไดนามิก

คำแนะนำในการย้ายข้อมูล: การแสดงผลฝั่งไคลเอ็นต์ด้วย GeoJSON

สำหรับนักพัฒนาซอฟต์แวร์ที่ย้ายข้อมูลจาก KmlLayer เป็นการแสดงผลฝั่งไคลเอ็นต์ด้วย GeoJSON Google Maps Platform ขอแนะนำเส้นทางการย้ายข้อมูลที่เกี่ยวข้องกับการแปลงรูปแบบข้อมูลและการใช้ชั้นข้อมูล เพื่อแสดงผลและจัดรูปแบบฟีเจอร์ในเบราว์เซอร์โดยตรง

การแสดงผลฝั่งไคลเอ็นต์โดยใช้ชั้นข้อมูลเป็นวิธีที่ยืดหยุ่นสูงในการแสดงข้อมูลทางภูมิศาสตร์ KmlLayer ซึ่งแสดงผลในเซิร์ฟเวอร์ของ Google ต่างจากชั้นข้อมูลที่ช่วยให้คุณโต้ตอบกับฟีเจอร์ต่างๆ ในรูปแบบออบเจ็กต์ JavaScript มาตรฐาน อย่างไรก็ตาม โปรดทราบว่าสำหรับชุดข้อมูลขนาดใหญ่ คุณอาจต้องการการประมวลผลและการแสดงผลข้อมูลฝั่งเซิร์ฟเวอร์ เช่น การใช้การจัดรูปแบบตามข้อมูลสำหรับชุดข้อมูล

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 คำนวณขอบเขตเพื่อตั้งค่า 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
    };
  });
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ชั้นข้อมูลได้ที่เอกสารประกอบการนำเข้า GeoJSON ไปยัง Maps

เส้นทางการย้ายข้อมูล: การแสดงผลฝั่งไคลเอ็นต์ด้วยไลบรารีของบุคคลที่สาม

สำหรับนักพัฒนาซอฟต์แวร์ที่กำลังมองหาทางเลือกอื่นๆ นอกเหนือจาก KmlLayer เรามี ไลบรารีที่ชุมชนดูแลหลายรายการซึ่งแสดงข้อมูล KML ใน Google Maps Platform JavaScript API

1. deck.gl

deck.gl เป็นเฟรมเวิร์กการแสดงภาพที่ขับเคลื่อนโดย WebGL ประสิทธิภาพสูง โดยสามารถ ใช้แทนการแสดงผล KML ได้โดยแทบไม่ต้องแก้ไขผ่าน GoogleMapsOverlay และ GeoJsonLayer

  • ข้อกำหนดของ Canvas: หากต้องการใช้ deck.gl อย่างมีประสิทธิภาพ คุณต้องแปลง แผนที่ให้ใช้ประเภทแผนที่เวกเตอร์ (ซึ่งแสดงผลเป็นองค์ประกอบ Canvas) พร้อมความสามารถในการแสดงผล WebGL
  • การรองรับ KML: @loaders.gl/kml จะจัดการการแยกวิเคราะห์เรขาคณิต ซึ่งจะแปลง KML เป็น GeoJSON โปรดทราบว่าฟีเจอร์ KML บางอย่าง เช่น รูปแบบที่ซับซ้อน ไอคอน และ NetworkLink อาจต้องมีการติดตั้งใช้งานด้วยตนเองเพิ่มเติม
  • เอกสารประกอบ: เอกสารประกอบของ deck.gl | โปรแกรมโหลด KML ของ loaders.gl
  • ตัวอย่าง
    • ตัวอย่าง deckgl-kml-updated ในที่เก็บ Google Maps บน GitHub แสดงวิธีใช้ deck.gl เพื่อแสดงข้อมูล KML ที่อัปเดตแบบเรียลไทม์
    • ตัวอย่าง deckgl-kml แสดงวิธีใช้ deck.gl เพื่อแสดงข้อมูล KML

2. geoxml3

geoxml3 เป็นโปรแกรมประมวลผล KML ที่ออกแบบมาโดยเฉพาะสำหรับ Google Maps JavaScript API v3 โดยจะแยกวิเคราะห์ KML ในเบราว์เซอร์แบบโลคัลและแสดงข้อมูลเป็น ออบเจ็กต์ Google Maps API มาตรฐาน เช่น เครื่องหมาย เส้นหลายเส้น และรูปหลายเหลี่ยม

  • การรองรับแผนที่มาตรฐาน: geoxml3 ทำงานบนแผนที่ Google Maps JS API v3 มาตรฐานโดยไม่ต้องใช้โหมดการแสดงผลที่เฉพาะเจาะจง ซึ่งแตกต่างจากโซลูชันที่ใช้ WebGL
  • ข้อควรระวัง:
    • การรองรับ KMZ แบบจำกัด: ไลบรารีไม่รองรับไฟล์ KMZ โดยกำเนิด การแตกไฟล์ KMZ มักจะต้องผสานรวมกับสคริปต์ของบุคคลที่สามเพิ่มเติม เช่น ZipFile.complete.js
    • องค์ประกอบที่ไม่รองรับ: ระบบไม่รองรับฟีเจอร์ต่างๆ เช่น รูปทรงเรขาคณิต 3 มิติ ป้ายกำกับที่ซับซ้อน และองค์ประกอบ KML ใหม่ๆ บางอย่าง
  • เอกสารประกอบ: ที่เก็บ geoxml3 ใน GitHub

ไฟล์ KML ที่มีองค์ประกอบแบบอินเทอร์แอกทีฟ

คำแนะนำในการย้ายข้อมูล: การจัดรูปแบบตามข้อมูลสำหรับชุดข้อมูล

สำหรับนักพัฒนาซอฟต์แวร์ที่ย้ายข้อมูลจาก KmlLayer ไปยังการจัดรูปแบบตามข้อมูล (DDS) สำหรับชุดข้อมูล คู่มือนี้จะอธิบายวิธีเปลี่ยนจากการโต้ตอบ KML อัตโนมัติเป็นการโต้ตอบที่กำหนดเองและมีประสิทธิภาพสูง เช่น การคลิกเมาส์และการวางเมาส์

การตั้งค่าเบื้องต้น

ก่อนที่จะติดตั้งใช้งานการโต้ตอบ โปรดตรวจสอบว่าคุณได้ทำตามขั้นตอนการตั้งค่าจากคู่มือการย้ายข้อมูล KML: ข้อมูลเวกเตอร์แล้ว

  • รหัสแผนที่: กำหนดค่ารหัสแผนที่สำหรับประเภทแผนที่เวกเตอร์
  • อัปโหลด: อัปโหลดข้อมูล KML ไปยังคอนโซล Google Cloud เพื่อรับรหัสชุดข้อมูล
  • การเข้าถึงเลเยอร์: ใช้ map.getDatasetFeatureLayer(datasetId) เพื่อเข้าถึง เลเยอร์แบบอินเทอร์แอกทีฟ

1. การจัดการเหตุการณ์การโต้ตอบ

ใน KmlLayer API จะจัดการการคลิกฟีเจอร์โดยอัตโนมัติเพื่อแสดงหน้าต่างข้อมูล เมื่อใช้ DDS สำหรับชุดข้อมูล คุณต้องลงทะเบียน Listener สำหรับ เหตุการณ์ของเมาส์ในเลเยอร์ชุดข้อมูลด้วยตนเอง

  • 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 คุณสามารถวนซ้ำแอตทริบิวต์เหล่านี้เพื่อสร้าง โฆษณา Display HTML ที่กำหนดเองได้

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

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

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

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

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

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

ดูเทคนิคการแสดงข้อมูลด้วยภาพขั้นสูงเพิ่มเติมได้ในเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์เกี่ยวกับวิธีจัดรูปแบบฟีเจอร์ข้อมูล

คำแนะนำในการย้ายข้อมูล: การแสดงผลฝั่งไคลเอ็นต์ด้วย GeoJSON

สำหรับนักพัฒนาซอฟต์แวร์ที่ย้ายข้อมูลจาก KmlLayer ไปยังการแสดงผลฝั่งไคลเอ็นต์ด้วย GeoJSON และชั้นข้อมูล คู่มือนี้จะอธิบายวิธีย้ายจากการโต้ตอบ KML อัตโนมัติเป็นการโต้ตอบที่กำหนดเองซึ่งขับเคลื่อนด้วยเหตุการณ์และการจัดรูปแบบแบบไดนามิก

การตั้งค่าเบื้องต้น

ก่อนที่จะใช้การโต้ตอบ คุณต้องแปลงข้อมูล KML เป็น GeoJSON และ โหลดลงในชั้นข้อมูล ดูรายละเอียดเกี่ยวกับการใช้เครื่องมือต่างๆ เช่น ogr2ogr หรือ togeojson และการเริ่มต้นแผนที่ด้วย map.data.loadGeoJson() ได้ในคำแนะนำคำแนะนำในการย้ายข้อมูล: การแสดงผลฝั่งไคลเอ็นต์ด้วย GeoJSON

1. การโต้ตอบอัตโนมัติกับการโต้ตอบด้วยตนเอง

ความแตกต่างที่สำคัญระหว่างชั้นเหล่านี้คือวิธีจัดการข้อมูลจากผู้ใช้ ดังนี้

  • KmlLayer: จัดการการคลิกฟีเจอร์โดยอัตโนมัติ และแสดง InfoWindow ที่มี KML และข้อมูล
  • ชั้นข้อมูล: ไม่แสดงInfoWindow ออบเจ็กต์โดยอัตโนมัติ คุณต้องเพิ่มเครื่องมือฟังเหตุการณ์ด้วยตนเองเพื่อบันทึกการโต้ตอบของผู้ใช้และเขียนโค้ดเพื่อแสดงข้อมูล

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 เนื่องจากชั้นข้อมูลไม่มี UI เริ่มต้นสำหรับข้อมูลเหล่านี้ คุณจึงต้องใช้ 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: การแปลงแผนที่ให้ใช้ประเภทแผนที่เวกเตอร์ (ข้อกำหนดของ Canvas )
  • geoxml3: การแสดงสคริปต์ไลบรารีจากโฮสต์ของคุณเองและการจัดการกลไกการแชร์ทรัพยากรข้ามโดเมน (CORS)

1. ข้อมูลแบบอินเทอร์แอกทีฟด้วย deck.gl

deck.gl รองรับ KML เป็นรูปแบบอินพุตโดยตรงและจัดการการโต้ตอบของฟีเจอร์โดยอัตโนมัติ เช่น การคลิกตามข้อมูลที่ระบุในไฟล์ KML

  • การจัดการ KMLLoader: การใช้โมดูล @loaders.gl/kml ระบบจะแยกวิเคราะห์เรขาคณิตและพร็อพเพอร์ตี้เป็นรูปแบบที่ deck.gl ใช้เพื่อทริกเกอร์เหตุการณ์การโต้ตอบโดยตรง
  • การคลิกฟีเจอร์: เมื่อมีการคลิกฟีเจอร์ deck.gl จะบันทึกเหตุการณ์และแสดงข้อมูลเมตาที่เกี่ยวข้อง (เช่น <name> หรือ <description>) ได้
  • ตัวอย่าง: ตัวอย่าง deckgl-kml-updated แสดงการแสดงผล KML แบบเรียลไทม์ ซึ่งการวางเมาส์เหนือเครื่องหมายแผ่นดินไหว จะแสดงข้อมูลเหตุการณ์โดยละเอียด

2. ข้อมูลแบบอินเทอร์แอกทีฟด้วย geoxml3

geoxml3 จะแยกวิเคราะห์ KML ในเครื่องในเบราว์เซอร์ แยกข้อมูลรูปแบบ และ สร้างออบเจ็กต์ Google Maps API มาตรฐานที่ยังคงมีการโต้ตอบ

  • การแยกรูปแบบดั้งเดิม: ไลบรารีจะดึงองค์ประกอบ <Style> และ <StyleMap> จาก KML เพื่อนำไปใช้กับเครื่องหมาย โพลีไลน์ และ รูปหลายเหลี่ยมที่สร้างขึ้น
  • ตัวแฮนเดิลการคลิก: โดยค่าเริ่มต้น 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. การใช้งาน

คุณระบุ URL ของรูปภาพ และออบเจ็กต์ LatLngBounds ที่แสดงสี่เหลี่ยมผืนผ้าบนแผนที่แทนการใช้ไฟล์ KML เพื่อกำหนดขอบเขต

  • เอกสารประกอบ คู่มือการวางซ้อนพื้น
  • การเตรียมรูปภาพ: หากรูปภาพของคุณมีการอ้างอิงทางภูมิศาสตร์แต่ไม่ได้อยู่ใน การฉายภาพที่ถูกต้อง (EPSG:4326) คุณสามารถใช้เครื่องมือโอเพนซอร์ส gdalwarp เพื่อบิดเบือนรูปภาพเพื่อใช้กับ Maps JS API
gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

เส้นทางการย้ายข้อมูล: การใช้ไลบรารีของบุคคลที่สาม

หากเวิร์กโฟลว์กำหนดให้คุณต้องเก็บข้อมูลในรูปแบบ KML คุณสามารถใช้ไลบรารีของบุคคลที่สาม เช่น geoxml3 หรือ deck.gl เพื่อแสดงภาพซ้อนทับได้

ข้อจำกัดความรับผิด: โซลูชันของบุคคลที่สามเหล่านี้ไม่ได้รับการสนับสนุนจาก Google อย่างไรก็ตาม เราได้ทดสอบแล้วและควรใช้งานได้ในกรณีการใช้งานส่วนใหญ่

1. geoxml3

geoxml3 เป็นตัวเลือกที่ดีสำหรับการแยกวิเคราะห์องค์ประกอบ GroundOverlay อย่างง่ายในเครื่อง ในเบราว์เซอร์และแปลงเป็นออบเจ็กต์ Google Maps API

ตัวอย่างการใช้งาน

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

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

2. deck.gl

แม้ว่า deck.gl มาตรฐานของ GeoJsonLayer จะจัดการข้อมูลเวกเตอร์ แต่ก็ยังรองรับ GroundOverlays ผ่านการติดตั้งใช้งานด้วยตนเองโดยใช้ BitmapLayer ได้ด้วย

แนวทางนี้เกี่ยวข้องกับการใช้ KMLLoader เพื่อแยกวิเคราะห์ไฟล์ จากนั้น กำหนด BitmapLayer อย่างชัดเจนด้วย URL รูปภาพและพิกัดที่ดึงออกมา จากข้อมูล KML

  • ข้อกำหนด: การใช้ deck.gl ต้องใช้แผนที่ประเภทเวกเตอร์
  • เอกสารประกอบ: deck.gl Bitmap Layer

กรณีขั้นสูง: พีระมิดไทล์โดยใช้ gdal2tiles

สำหรับไฟล์ KML ที่ซับซ้อนซึ่งมีพีระมิดไทล์ของภาพ การย้ายข้อมูลจะยากขึ้นและต้องแยกข้อมูลภาพ

  • เครื่องมือ: gdal2tiles สามารถดึงข้อมูลจาก พีระมิด KMZ และสร้างโค้ด Maps JavaScript API มาตรฐานเพื่อแสดง ไทล์ โปรดทราบว่าผลลัพธ์สุดท้ายอาจต้องมีการแก้ไขด้วยตนเองเพื่อรวมเข้ากับแผนที่ที่มีอยู่
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

การจัดการไฟล์ KML ที่มีลิงก์เครือข่ายต้องเปลี่ยนจากการดึงข้อมูล KmlLayer โดยอัตโนมัติทางฝั่งคลาวด์ไปเป็นกลยุทธ์การจัดการข้อมูลที่ชัดเจนยิ่งขึ้น

โซลูชันที่รองรับ: การจัดรูปแบบตามข้อมูล (DDS) สำหรับชุดข้อมูล

เนื่องจากชุดข้อมูล Google Maps Platform ไม่ได้แยกวิเคราะห์องค์ประกอบ <NetworkLink> โดยค่าเริ่มต้น คุณจึงต้องเลือกกลยุทธ์การย้ายข้อมูลตามโครงสร้างข้อมูล

  • กลยุทธ์ ก: ชุดข้อมูลที่แตกต่างกัน (เหมาะที่สุดสำหรับเลเยอร์ที่ผู้ใช้ควบคุม) อัปโหลด ไฟล์ KML แต่ละไฟล์ที่ก่อนหน้านี้เป็นลิงก์เครือข่ายเป็นชุดข้อมูลแต่ละชุดของตัวเอง ในคอนโซล Google Cloud จากนั้นคุณจะใช้ JavaScript เพื่อ โหลดและแสดงเลเยอร์เหล่านี้แบบไดนามิกได้เมื่อจำเป็นโดยการเรียก map.getDatasetFeatureLayer(datasetId) และปรับระดับการแสดงผลหรือ รูปแบบ
  • กลยุทธ์ B: ไฟล์ KML ที่รวมกัน (เหมาะที่สุดสำหรับการแสดงผลที่มีประสิทธิภาพสูง) รวมฟีเจอร์ทั้งหมดจากไฟล์ที่ลิงก์กับเครือข่ายต่างๆ เป็นไฟล์ KML ไฟล์เดียวที่ครอบคลุม ก่อนที่จะอัปโหลดเป็นชุดข้อมูล จากนั้นคุณสามารถใช้การจัดรูปแบบแบบไดนามิกตามแอตทริบิวต์ของฟีเจอร์เพื่อกรองและแสดง ชุดข้อมูลย่อยที่เฉพาะเจาะจงได้ทันที

การอัปเดตข้อมูลแบบไดนามิก: หากต้องการเลียนแบบลักษณะการทำงาน "รีเฟรชอัตโนมัติ" ของ NetworkLink ให้ใช้ Datasets API เพื่ออัปโหลดชุดข้อมูลเวอร์ชันใหม่โดยอัตโนมัติ เมื่อใดก็ตามที่ข้อมูลแหล่งที่มามีการเปลี่ยนแปลง

โซลูชันโอเพนซอร์ส: deck.gl และ geoxml3

ทั้ง deck.gl และ geoxml3 ไม่รองรับการแยกวิเคราะห์และ การดึงข้อมูลองค์ประกอบ KML <NetworkLink> โดยอัตโนมัติ

deck.gl

deck.gl ใช้ KMLLoader (สร้างขึ้นบน togeojson) ซึ่งไม่รองรับ NetworkLink อย่างชัดเจน

  • เหตุผลที่วิธีนี้ไม่ใช่โซลูชันที่ดี: ตัวแยกวิเคราะห์ได้รับการออกแบบมาให้เป็นตัวแปลงแบบซิงโครนัสที่ "ใช้งานง่าย" ซึ่งหลีกเลี่ยงการส่งคำขอเครือข่ายของตัวเองเพื่อให้มั่นใจถึงความน่าเชื่อถือและความเรียบง่าย หากแอปพลิเคชันของคุณใช้ ไฟล์ KML ที่ชี้ไปยัง URL อื่นๆ หลายรายการ deck.gl จะไม่ แก้ไข URL เหล่านั้นโดยอัตโนมัติ

geoxml3

แม้ว่าเราจะพัฒนา geoxml3 ขึ้นมาเพื่อแยกวิเคราะห์ KML สำหรับ Maps JS API แต่การรองรับ NetworkLink นั้นยังอยู่ในขั้นทดลองและไม่มีการบำรุงรักษา

  • เหตุใดจึงไม่ใช่โซลูชันที่ดี: ฟังก์ชันการทำงานมีเฉพาะในสาขา "network_link" ที่เฉพาะเจาะจงซึ่งเก่าและไม่ได้ทดสอบอย่างดี เราไม่แนะนำให้ใช้เครื่องมือนี้ ในการย้ายข้อมูลการผลิต เนื่องจากอาจจัดการโครงสร้างลิงก์ที่ซับซ้อนหรือข้อกำหนดด้านความปลอดภัยที่ทันสมัย เช่น CORS ไม่ได้

คำแนะนำสรุป

นักพัฒนาแอปควรหลีกเลี่ยงการใช้ตัวแยกวิเคราะห์ของบุคคลที่สามสำหรับไฟล์ที่มีลิงก์เครือข่าย และสร้างตรรกะการดึงข้อมูลใหม่โดยใช้ Datasets API เพื่อให้การย้ายข้อมูลเป็นไปอย่างราบรื่น ซึ่งจะช่วยให้มั่นใจได้ว่าข้อมูลของคุณจะได้รับการจัดการอย่างปลอดภัยภายในโครงสร้างพื้นฐานของ Google Maps Platform แทนที่จะต้องพึ่งพาโปรแกรมแยกวิเคราะห์ฝั่งไคลเอ็นต์ที่ไม่มีการบำรุงรักษา

ใช้ KML เพื่อแสดงภาพซ้อนทับบนหน้าจอ

สำหรับนักพัฒนาซอฟต์แวร์ที่ย้ายข้อมูลจาก KmlLayer ไปยังทางเลือกที่ทันสมัยกว่า เช่น การจัดรูปแบบที่อิงตามข้อมูล (DDS) โปรดทราบว่าชุดข้อมูลไม่รองรับการซ้อนทับหน้าจอ หากต้องการให้แสดงรูปภาพ โลโก้ หรือ คำอธิบายที่ตรึงไว้บนแผนที่ คุณต้องสร้าง การควบคุมที่กำหนดเอง โดยใช้ Maps JavaScript API

1. สิ่งที่ควรมองหาในไฟล์ KML

หากต้องการสร้างการควบคุมที่กำหนดเองที่เทียบเท่า ให้ตรวจสอบองค์ประกอบ <ScreenOverlay> ในไฟล์ KML เพื่อดูแอตทริบิวต์หลักต่อไปนี้

  • <Icon>&lt;href>: URL ของรูปภาพที่ต้องการ แสดง
  • <screenXY>: กำหนดตำแหน่งที่วางซ้อนบนหน้าจอ
    • x=0, y=1 (เศษส่วน) สอดคล้องกับบน ซ้าย
    • x=1, y=1 สอดคล้องกับ Top Right
    • x=0, y=0 สอดคล้องกับด้านซ้ายล่าง
    • x=1, y=0 สอดคล้องกับขวาล่าง
  • <size>: กำหนดความกว้างและความสูงของ ภาพซ้อนทับ
  • <rotation>: ระบุว่าควรหมุนรูปภาพหรือไม่

2. การใช้งาน: การสร้างตัวควบคุมที่กำหนดเอง

โดยพื้นฐานแล้วตัวควบคุมที่กำหนดเองคือองค์ประกอบ HTML มาตรฐาน (เช่น <div> หรือ <img>) ที่คุณ "พุช" ไปยังตำแหน่งที่กำหนดไว้ล่วงหน้าตำแหน่งใดตำแหน่งหนึ่งของแผนที่

การแมปตำแหน่ง KML กับ ControlPosition

Maps JavaScript API ใช้ ControlPosition enum เพื่อยึดตัวควบคุม ใช้ตารางด้านล่างเพื่อแมป KML <screenXY> กับค่าคงที่ 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);
}

ข้อมูลเพิ่มเติม