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

KmlLayer แสดงผลองค์ประกอบ KML และ GeoRSS เป็นการวางซ้อนของชิ้นส่วนแผนที่ของ Maps 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 จะจัดการการแสดงผลขององค์ประกอบย่อยเหล่านี้โดยการดึงข้อมูล ฟีเจอร์ที่เหมาะสมสำหรับขอบเขตที่กำหนดของแผนที่โดยอัตโนมัติ เมื่อขอบเขตเปลี่ยนไป ระบบจะแสดงผลฟีเจอร์ใน Viewport ปัจจุบันโดยอัตโนมัติ

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

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

เครื่องมือสร้าง KmlLayer() จะส่งผ่านจำนวน KmlLayerOptions (ไม่บังคับ) ดังนี้

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

นอกจากนี้ เมื่อแสดงผล KmlLayer แล้ว KmlLayer จะมีพร็อพเพอร์ตี้ metadata ที่เปลี่ยนแปลงไม่ได้ซึ่งมีชื่อ คำอธิบาย ข้อมูลตัวอย่าง และผู้เขียนของเลเยอร์ภายในออบเจ็กต์ KmlLayerMetadata ลิเทอรัล คุณตรวจสอบข้อมูลนี้ได้โดยใช้เมธอด 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 นี้ โดยทั่วไปแล้ว ตำแหน่งนี้คือตำแหน่งที่คลิกสำหรับรูปหลายเหลี่ยม เส้นหลายเส้น และ GroundOverlay แต่เป็นต้นทางจริงสำหรับเครื่องหมาย
• 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 ที่รองรับ