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

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

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

เครื่องมือสร้าง KmlLayer() สามารถส่ง KmlLayerOptions หลายรายการได้ ดังนี้

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

นอกจากนี้ เมื่อแสดงผล 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 นี้ โดยทั่วไปแล้ว ตำแหน่งนี้จะเป็นตำแหน่งที่คลิกสำหรับรูปหลายเหลี่ยม เส้นประกอบ และพื้นวาง แต่จะเป็นจุดเริ่มต้นจริงสำหรับเครื่องหมาย
• 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"
}

ตัวอย่างต่อไปนี้แสดงข้อความองค์ประกอบ <Description> ของ KML ภายใน <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

500KB ต่อไฟล์

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

10

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

1,000

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

จำนวนเลเยอร์ KML ที่แสดงใน Google Map รายการเดียวมีขีดจำกัด หากเกินขีดจํากัดนี้ เลเยอร์ทั้งหมดจะไม่ปรากฏบนแผนที่ และระบบจะรายงานข้อผิดพลาดในคอนโซล JavaScript ของเบราว์เซอร์ ขีดจํากัดจะอิงตามจํานวนชั้น KmlLayer ที่สร้างขึ้นและความยาวรวมของ URL ทั้งหมดที่ใช้สร้างเลเยอร์เหล่านั้น KmlLayer ใหม่แต่ละรายการที่คุณสร้างจะใช้พื้นที่บางส่วนของขีดจํากัดสําหรับเลเยอร์ และอีกส่วนหนึ่งของขีดจํากัดจะขึ้นอยู่กับความยาวของ URL ที่โหลดไฟล์ KML ดังนั้น จำนวนเลเยอร์ที่คุณเพิ่มได้จะแตกต่างกันไปตามแอปพลิเคชัน โดยเฉลี่ยแล้ว คุณควรโหลดเลเยอร์ได้ 10-20 เลเยอร์โดยไม่ถึงขีดจำกัด หากยังใช้ URL เกินขีดจํากัดอยู่ ให้ใช้ตัวย่อ 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 ที่รองรับ