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

• position ระบุพิกัดละติจูด/ลองจิจูดที่ ซึ่งจะกำหนด InfoWindow สำหรับคุณลักษณะ KML นี้ ช่วงเวลานี้ คือตำแหน่งที่มีการคลิกสำหรับรูปหลายเหลี่ยม เส้นประกอบ และ GroundOverlays แต่เป็นจุดกำเนิดที่แท้จริงของเครื่องหมาย
• pixelOffset แสดงค่าชดเชยจากค่าข้างต้น position เพื่อตรึง InfoWindow "tail" สำหรับวัตถุหลายเหลี่ยม ระยะห่างนี้มักจะ 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> และ &lt;text&gt;
• KMZ (KML ที่มีการบีบอัด รวมถึงรูปภาพที่แนบมา)
• โพลีไลน์และรูปหลายเหลี่ยม
• ลักษณะของโพลีไลน์และรูปหลายเหลี่ยม รวมถึง สี สีเติม และความโปร่งแสง
• ลิงก์ของเครือข่ายเพื่อนำเข้าข้อมูลแบบไดนามิก
• Ground Overlay และ Screen Overlay

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