เลเยอร์ KML และ GeoRSS

KmlLayer แสดงผลองค์ประกอบ KML และ GeoRSS ในการวางซ้อนชิ้นส่วนแผนที่ JavaScript API

ภาพรวม

Maps JavaScript API รองรับรูปแบบข้อมูล KML และ GeoRSS ในการแสดงข้อมูลทางภูมิศาสตร์ รูปแบบข้อมูลเหล่านี้แสดงบนแผนที่โดยใช้ออบเจ็กต์ KmlLayer ซึ่งผู้สร้างจะรับ URL ของไฟล์ KML หรือ GeoRSS ที่เข้าถึงได้แบบสาธารณะ

หมายเหตุ: คลาส KmlLayer ที่สร้างการวางซ้อน KML ใน Maps JavaScript API ใช้บริการที่ Google โฮสต์เพื่อดึงและแยกวิเคราะห์ไฟล์ KML สำหรับการแสดงผล ดังนั้น คุณจึงจะแสดงไฟล์ KML ได้ก็ต่อเมื่อไฟล์โฮสต์อยู่ใน URL ที่เข้าถึงได้แบบสาธารณะที่ไม่ต้องมีการตรวจสอบสิทธิ์เพื่อเข้าถึงเท่านั้น

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

Maps JavaScript API จะแปลงข้อมูล XML ทางภูมิศาสตร์ที่ระบุเป็นภาพแทน KML ซึ่งแสดงบนแผนที่โดยใช้การวางซ้อนของชิ้นส่วน Maps JavaScript API KML นี้ดู (และจะทำงาน) เหมือนองค์ประกอบการวางซ้อนของ Maps JavaScript API ที่คุ้นเคย องค์ประกอบ KML <Placemark> และ GeoRSS point จะแสดงผลเป็นเครื่องหมาย เช่น องค์ประกอบ <LineString> จะแสดงผลเป็นเส้นประกอบ และองค์ประกอบ <Polygon> จะแสดงผลเป็นรูปหลายเหลี่ยม ในทํานองเดียวกัน องค์ประกอบ <GroundOverlay> จะแสดงผลเป็นรูปภาพสี่เหลี่ยมผืนผ้าบนแผนที่ อย่างไรก็ตาม ที่สำคัญคือออบเจ็กต์เหล่านี้ไม่ใช่ Maps JavaScript API Markers, Polylines, Polygons หรือ GroundOverlays แต่จะแสดงผลเป็นออบเจ็กต์เดียวบนแผนที่

ออบเจ็กต์ KmlLayer รายการจะปรากฏบนแผนที่เมื่อตั้งค่าพร็อพเพอร์ตี้ map แล้ว คุณนำออกจากแผนที่ได้โดยเรียก setMap() ว่าผ่าน null ออบเจ็กต์ KmlLayer จะจัดการการแสดงผลขององค์ประกอบย่อยเหล่านี้โดยการเรียกข้อมูลฟีเจอร์ที่เหมาะสมสำหรับขอบเขตที่กำหนดของแผนที่โดยอัตโนมัติ เมื่อขอบเขตเปลี่ยนแปลง ฟีเจอร์ต่างๆ ในวิวพอร์ตปัจจุบันจะแสดงผลโดยอัตโนมัติ

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

ตัวเลือกเลเยอร์ KML

เครื่องมือสร้าง KmlLayer() เลือกที่จะส่ง KmlLayerOptions จำนวนหนึ่งหรือไม่ก็ได้

• map ระบุ Map ที่จะแสดงผล KmlLayer คุณซ่อน KmlLayer ได้โดยการตั้งค่านี้เป็น null ภายในเมธอด setMap()
• preserveViewport ระบุว่าไม่ควรปรับแผนที่กับขอบเขตของเนื้อหาของ KmlLayer เมื่อแสดงเลเยอร์ โดยค่าเริ่มต้น เมื่อแสดง KmlLayer แผนที่จะซูมและจัดตำแหน่งเพื่อแสดงเนื้อหาทั้งหมดของเลเยอร์
• suppressInfoWindows บ่งชี้ว่าฟีเจอร์ที่คลิกได้ภายใน KmlLayer ไม่ควรเรียกให้แสดงออบเจ็กต์ InfoWindow

นอกจากนี้ เมื่อแสดงผล KmlLayer แล้ว จะมีพร็อพเพอร์ตี้ metadata ที่เปลี่ยนแปลงไม่ได้ ซึ่งประกอบด้วยชื่อ คำอธิบาย ตัวอย่างข้อมูล และผู้เขียนของเลเยอร์ภายใน KmlLayerMetadata Object Literal คุณตรวจสอบข้อมูลนี้ได้โดยใช้เมธอด getMetadata() เนื่องจากการแสดงผลออบเจ็กต์ KmlLayer ต้องใช้การสื่อสารแบบไม่พร้อมกันกับเซิร์ฟเวอร์ภายนอก คุณจึงต้องรอเหตุการณ์ metadata_changed ซึ่งจะระบุว่ามีการเติมข้อมูลพร็อพเพอร์ตี้แล้ว

ตัวอย่างต่อไปนี้สร้าง KmlLayer จากฟีด GeoRSS ที่ระบุ

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: 49.496675, lng: -102.65625 },
    }
  );

  const georssLayer = new google.maps.KmlLayer({
    url:
      "http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss",
  });
  georssLayer.setMap(map);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: 49.496675, lng: -102.65625 },
  });
  const georssLayer = new google.maps.KmlLayer({
    url: "http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss",
  });

  georssLayer.setMap(map);
}

window.initMap = initMap;
index.js

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
style.css

<html>
  <head>
    <title>GeoRSS Layers</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

ตัวอย่างต่อไปนี้สร้าง KmlLayer จากฟีด KML ที่ระบุ

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 11,
      center: { lat: 41.876, lng: -87.624 },
    }
  );

  const ctaLayer = new google.maps.KmlLayer({
    url: "https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml",
    map: map,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 11,
    center: { lat: 41.876, lng: -87.624 },
  });
  const ctaLayer = new google.maps.KmlLayer({
    url: "https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml",
    map: map,
  });
}

window.initMap = initMap;
index.js

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
style.css

<html>
  <head>
    <title>KML Layers</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

รายละเอียดฟีเจอร์ KML

เนื่องจาก KML อาจมีฟีเจอร์จำนวนมาก คุณจึงไม่สามารถเข้าถึงข้อมูลฟีเจอร์จากออบเจ็กต์ KmlLayer โดยตรง แต่เมื่อมีการแสดงฟีเจอร์ ฟีเจอร์เหล่านั้นจะแสดงผลให้ดูเหมือนการวางซ้อน Maps JavaScript API ที่คลิกได้ การคลิกที่แต่ละฟีเจอร์จะเป็นการแสดงข้อมูล InfoWindow ที่มี KML <title> และ <description> ของฟีเจอร์ดังกล่าวโดยค่าเริ่มต้น นอกจากนี้ การคลิกฟีเจอร์ KML จะสร้าง KmlMouseEvent ซึ่งส่งผ่านข้อมูลต่อไปนี้

• position ระบุพิกัดละติจูด/ลองจิจูดที่จะยึด InfoWindow สำหรับฟีเจอร์ KML นี้ โดยทั่วไปตำแหน่งนี้เป็นตำแหน่งที่มีการคลิกสำหรับรูปหลายเหลี่ยม เส้นประกอบ และ GroundOverlays แต่เป็นต้นทางที่แท้จริงของเครื่องหมาย
• pixelOffset ระบุออฟเซ็ตจาก position ด้านบนเพื่อยึด InfoWindow "หาง" สำหรับวัตถุที่เป็นรูปหลายเหลี่ยม ออฟเซ็ตนี้โดยทั่วไปจะเป็น 0,0 แต่สำหรับเครื่องหมายจะมีความสูงของเครื่องหมาย
• featureData มีโครงสร้าง JSON ของ KmlFeatureData

ตัวอย่างออบเจ็กต์ KmlFeatureData แสดงอยู่ด้านล่าง

{
  author: {
    email: "nobody@google.com",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

ตัวอย่างต่อไปนี้แสดงข้อความของฟีเจอร์ KML <Description> ภายในด้าน <div> เมื่อมีการคลิกองค์ประกอบดังกล่าว

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 12,
      center: { lat: 37.06, lng: -95.68 },
    }
  );

  const kmlLayer = new google.maps.KmlLayer({
    url: "https://raw.githubusercontent.com/googlearchive/kml-samples/gh-pages/kml/Placemark/placemark.kml",
    suppressInfoWindows: true,
    map: map,
  });

  kmlLayer.addListener("click", (kmlEvent) => {
    const text = kmlEvent.featureData.description;

    showInContentWindow(text);
  });

  function showInContentWindow(text: string) {
    const sidebar = document.getElementById("sidebar") as HTMLElement;

    sidebar.innerHTML = text;
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 37.06, lng: -95.68 },
  });
  const kmlLayer = new google.maps.KmlLayer({
    url: "https://raw.githubusercontent.com/googlearchive/kml-samples/gh-pages/kml/Placemark/placemark.kml",
    suppressInfoWindows: true,
    map: map,
  });

  kmlLayer.addListener("click", (kmlEvent) => {
    const text = kmlEvent.featureData.description;

    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    const sidebar = document.getElementById("sidebar");

    sidebar.innerHTML = text;
  }
}

window.initMap = initMap;
index.js

/* Optional: Makes the sample page fill the window. */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#container {
  height: 100%;
  display: flex;
}

#sidebar {
  flex-basis: 15rem;
  flex-grow: 1;
  padding: 1rem;
  max-width: 30rem;
  height: 100%;
  box-sizing: border-box;
  overflow: auto;
}

#map {
  flex-basis: 0;
  flex-grow: 4;
  height: 100%;
}
style.css

<html>
  <head>
    <title>KML Feature Details</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="container">
      <div id="map"></div>
      <div id="sidebar"></div>
    </div>

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

ข้อจำกัดด้านขนาดและความซับซ้อนสำหรับการแสดงผล KML

Maps JavaScript API มีการจำกัดขนาดและความซับซ้อนของไฟล์ KML ที่โหลด ด้านล่างนี้เป็นข้อมูลสรุปของขีดจำกัดในปัจจุบัน

หมายเหตุ: ขีดจำกัดเหล่านี้อาจเปลี่ยนแปลงได้ทุกเมื่อ

ขนาดไฟล์ใหญ่ที่สุดที่โหลดเข้ามาได้ (KML ดิบ, GeoRSS ดิบหรือ KMZ ที่มีการบีดอัด)

3MB

ขนาดไฟล์ KML สูงสุดที่ไม่มีการบีบอัด

10MB

ขนาดไฟล์ภาพสูงสุดที่ไม่มีการบีบอัดในไฟล์ KMZ

500 KB ต่อไฟล์

จำนวนลิงก์เครือข่ายสูงสุด

10

จำนวนสูงสุดของจุดสนใจทั้งหมดที่มีอยู่ในทั้งเอกสาร

1,000 คน

จำนวนเลเยอร์ KML

เลเยอร์ KML แสดงใน Google Maps เดียวได้อย่างจำกัด หากคุณเกินขีดจำกัดนี้ เลเยอร์จะไม่ปรากฏขึ้นบนแผนที่และจะรายงานข้อผิดพลาดในคอนโซล JavaScript ของเว็บเบราว์เซอร์ ขีดจำกัดนี้ขึ้นอยู่กับจำนวนคลาส KmlLayer ที่สร้างขึ้นร่วมกับความยาวรวมของ URL ทั้งหมดที่ใช้ในการสร้างเลเยอร์เหล่านั้น KmlLayer ใหม่แต่ละรายการที่คุณสร้างจะใช้ส่วนหนึ่งของขีดจำกัดสำหรับเลเยอร์และส่วนอื่นๆ ของขีดจำกัด ทั้งนี้ขึ้นอยู่กับความยาวของ URL ที่ใช้โหลดไฟล์ KML ดังนั้น จำนวนเลเยอร์ที่คุณเพิ่มได้จึงแตกต่างกันไปตามแอปพลิเคชัน โดยเฉลี่ยแล้วคุณควรโหลดได้ 10 ถึง 20 เลเยอร์โดยไม่ถึงขีดจำกัด หากยังถึงขีดจำกัดแล้ว ให้ใช้เครื่องมือย่อ URL เพื่อย่อ URL ของ KML ให้สั้นลง หรือสร้างไฟล์ KML เดียวที่ประกอบด้วย NetworkLinks ไปยัง URL ของ KML แต่ละรายการ

ข้อควรพิจารณาเกี่ยวกับประสิทธิภาพและการแคช

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

เพื่อประสิทธิภาพที่ดีที่สุด เราขอแนะนำให้คุณทำดังนี้

• ใช้แท็ก <expires> ที่เหมาะสมใน KML
  
  KmlLayer จะไม่ใช้ส่วนหัว HTTP เมื่อเลือกวิธีแคชไฟล์ KML
• อย่าสร้างไฟล์แบบไดนามิกตามเวลาที่ขอ
  
  แต่ให้สร้างไฟล์ก่อนที่จะจำเป็นต้องใช้ และแสดงไฟล์แบบคงที่แทน หากเซิร์ฟเวอร์ใช้เวลานานในการส่งไฟล์ KML KmlLayer อาจไม่แสดง
• อย่าพยายามข้ามแคชเว้นแต่จะทราบแน่ชัดว่าไฟล์ได้รับการอัปเดตแล้ว
  
  การหลบเลี่ยงแคชเสมอ (เช่น การใส่ตัวเลขสุ่มหรือเวลานาฬิกาของผู้ใช้เป็นพารามิเตอร์การค้นหา) อาจทำให้เซิร์ฟเวอร์ของคุณทำงานหนักเกินไปหากเว็บไซต์ได้รับความนิยมอย่างกะทันหันและคุณกำลังแสดงไฟล์ KML ขนาดใหญ่
  
  นอกจากนี้ยังอาจทำให้แคชแสดงข้อมูลเก่าแก่ผู้ใช้ หากนาฬิกาของผู้ใช้ไม่ถูกต้อง และแท็ก <expires> ไม่ได้ตั้งค่าอย่างถูกต้อง
  
  แต่ให้เผยแพร่ไฟล์แบบคงที่ที่อัปเดตซึ่งมีหมายเลขการแก้ไขใหม่แยกกัน และใช้รหัสฝั่งเซิร์ฟเวอร์เพื่ออัปเดต URL ที่ส่งไปยัง KmlLayer แบบไดนามิกด้วยเวอร์ชันปัจจุบันแทน
• จำกัดการเปลี่ยนแปลงในไฟล์ KML เป็น 1 ครั้งต่อนาที
  
  หากไฟล์ทั้งหมดมีขนาดรวมมากกว่า 1 MB (ไม่บีบอัด) ให้จำกัดการเปลี่ยนแปลงเป็น 1 ครั้งต่อ 5 นาที
• เมื่อใช้เซิร์ฟเวอร์ข้อมูลเชิงพื้นที่ โปรดหลีกเลี่ยงการใช้พารามิเตอร์การค้นหาเพื่อจำกัดวิวพอร์ตของเลเยอร์
  
  แต่คุณสามารถจำกัดวิวพอร์ตของแผนที่โดยใช้เหตุการณ์ bounds_changed แทนได้ ผู้ใช้จะได้รับเฉพาะฟีเจอร์ที่ แสดงได้โดยอัตโนมัติเท่านั้น
  
  หากมีข้อมูลจำนวนมากในเซิร์ฟเวอร์ข้อมูลเชิงพื้นที่ ให้พิจารณาใช้ชั้นข้อมูลแทน
• เมื่อใช้เซิร์ฟเวอร์ข้อมูลเชิงพื้นที่ ให้ใช้ KmlLayer หลายรายการสำหรับฟีเจอร์แต่ละกลุ่มที่ต้องการอนุญาตให้ผู้ใช้สลับ แทนการใช้ KmlLayer เดียวที่มีพารามิเตอร์การค้นหาต่างกัน
• ใช้ไฟล์ KMZ ที่บีบอัดเพื่อลดขนาดไฟล์
• หากคุณใช้ Google Cloud Storage หรือโซลูชันพื้นที่เก็บข้อมูลระบบคลาวด์อื่น โปรดหลีกเลี่ยงการใช้ฟีเจอร์ต่างๆ เช่น URL ที่ลงนามหรือโทเค็นชั่วคราวเพื่อบังคับใช้การควบคุมการเข้าถึง เนื่องจากอาจทำให้ไม่มีการแคชโดยไม่ได้ตั้งใจ
• ลดความแม่นยำของจุดทั้งหมดเป็นความแม่นยำที่เหมาะสม
• ผสานและปรับรูปเรขาคณิตของฟีเจอร์ที่คล้ายกันให้ง่ายขึ้น เช่น รูปหลายเหลี่ยมและเส้นประกอบ
• นำองค์ประกอบหรือทรัพยากรรูปภาพที่ไม่ได้ใช้ออก
• นำองค์ประกอบที่ไม่รองรับออก

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

องค์ประกอบ KML ที่สนับสนุน

Maps JavaScript API สนับสนุนองค์ประกอบ KML ต่อไปนี้ ปกติแล้ว โปรแกรมแยกวิเคราะห์ KML จะละเลยแท็กที่โปรแกรมไม่เข้าใจโดยไม่มีผลอะไร

• หมุด
• ไอคอน
• โฟลเดอร์
• HTML ที่สื่อความหมาย—การแทนที่เอนทิตีผ่าน <BalloonStyle> และ <text>
• KMZ (KML ที่มีการบีบอัด รวมถึงรูปภาพที่แนบมา)
• โพลีไลน์และรูปหลายเหลี่ยม
• ลักษณะของโพลีไลน์และรูปหลายเหลี่ยม รวมถึง สี สีเติม และความโปร่งแสง
• ลิงก์ของเครือข่ายเพื่อนำเข้าข้อมูลแบบไดนามิก
• Ground Overlay และ Screen Overlay

ตารางต่อไปนี้แสดงรายละเอียดทั้งหมดขององค์ประกอบ KML ที่สนับสนุน