Lớp KML và GeoRSS

KmlLayer kết xuất các phần tử KML và GeoRSS thành một Lớp phủ ô API Maps JavaScript.

Tổng quan

API JavaScript của Maps hỗ trợ các định dạng dữ liệu KML và GeoRSS để hiển thị thông tin địa lý. Những định dạng dữ liệu này được hiển thị trên ánh xạ bằng cách sử dụng đối tượng KmlLayer, trong đó hàm khởi tạo lấy URL của tệp KML hoặc GeoRSS có thể truy cập công khai.

Lưu ý: Lớp KmlLayer mà tạo lớp phủ KML trong Maps JavaScript API sử dụng dịch vụ được lưu trữ trên Google để truy xuất và phân tích cú pháp các tệp KML để kết xuất. Do đó, chỉ có thể hiển thị các tệp KML nếu chúng được lưu trữ tại URL có thể truy cập công khai mà không yêu cầu xác thực để truy cập.

Nếu bạn cần quyền truy cập vào các tệp riêng tư, quyền kiểm soát chi tiết đối với bộ nhớ đệm, hoặc gửi khung nhìn của trình duyệt đến máy chủ dữ liệu không gian địa lý dưới dạng tham số truy vấn, bạn nên dùng dữ liệu Layer thay vì KmlLayer. Việc này sẽ chuyển hướng người dùng của bạn để trực tiếp yêu cầu tài nguyên từ máy chủ web của bạn.

API JavaScript của Maps chuyển đổi vị trí địa lý được cung cấp Dữ liệu XML vào bản trình bày KML được hiển thị trên bản đồ bằng cách sử dụng Lớp phủ ô API Maps JavaScript. KML này có giao diện (và có phần hoạt động) như API Maps JavaScript quen thuộc phần tử lớp phủ. KML <Placemark> và GeoRSS point các phần tử được kết xuất dưới dạng điểm đánh dấu, ví dụ: các phần tử <LineString> là kết xuất dưới dạng hình nhiều đường và phần tử <Polygon> được kết xuất dưới dạng đa giác. Tương tự, các phần tử <GroundOverlay> được kết xuất dưới dạng hình ảnh hình chữ nhật trên bản đồ. Tuy nhiên, điều quan trọng là các đối tượng này không phải là API Maps JavaScript Markers, Polylines, Polygons hoặc GroundOverlays; thay vào đó, chúng sẽ được kết xuất thành một đối tượng duy nhất trên bản đồ.

KmlLayer đối tượng sẽ xuất hiện trên bản đồ sau map của chúng đã được đặt. Bạn có thể xoá chúng khỏi bản đồ bằng cách gọi setMap() truyền null. KmlLayer đối tượng quản lý quá trình kết xuất các phần tử con này bằng cách tự động truy xuất các đối tượng thích hợp cho ranh giới đã cho của bản đồ. Là giới hạn thay đổi, các tính năng trong khung nhìn hiện tại sẽ tự động kết xuất.

Vì các thành phần trong KmlLayer được kết xuất theo yêu cầu, lớp này cho phép bạn dễ dàng quản lý việc kết xuất hàng nghìn điểm đánh dấu, hình nhiều đường và đa giác. Lưu ý rằng bạn không thể truy cập vào các thành phần này các đối tượng trực tiếp, mặc dù mỗi đối tượng đều cung cấp các sự kiện nhấp chuột trả về dữ liệu các đối tượng riêng lẻ đó.

Tùy chọn lớp KML

Hàm khởi tạo KmlLayer() có thể tuỳ ý truyền một số KmlLayerOptions:

• map chỉ định Map để kết xuất KmlLayer. Bạn có thể ẩn KmlLayer bằng cách đặt tuỳ chọn này thành null trong phương thức setMap().
• preserveViewport chỉ định rằng bản đồ không được được điều chỉnh theo giới hạn nội dung của KmlLayer khi hiển thị lớp. Theo mặc định, khi hiển thị KmlLayer, bản đồ được thu phóng và định vị để hiển thị toàn bộ .
• suppressInfoWindows cho biết rằng các tính năng có thể nhấp trong KmlLayer không được kích hoạt màn hình Đối tượng InfoWindow.

Ngoài ra, sau khi KmlLayer được kết xuất, lớp này sẽ chứa thuộc tính metadata không thể thay đổi có chứa tên của lớp, đoạn mô tả, đoạn trích và tác giả trong đối tượng KmlLayerMetadata chi tiết. Bạn có thể kiểm tra thông tin này bằng cách sử dụng getMetadata() . Vì việc kết xuất đối tượng KmlLayer cần có giao tiếp không đồng bộ với máy chủ bên ngoài, bạn sẽ cần theo dõi sự kiện metadata_changed để cho biết rằng thuộc tính đã được điền sẵn.

Ví dụ sau đây tạo KmlLayer từ phương thức đã cho Nguồn cấp dữ liệu 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

Ví dụ sau đây tạo KmlLayer từ KML đã cho nguồn cấp dữ liệu:

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

Thông tin chi tiết về tính năng KML

Do KML có thể bao gồm một số lượng lớn các đối tượng, bạn có thể không truy cập được dữ liệu tính năng trực tiếp từ đối tượng KmlLayer. Thay vào đó, dưới dạng các tính năng được hiển thị, chúng được kết xuất để trông giống như có thể nhấp vào Lớp phủ API JavaScript cho Maps. Khi bạn nhấp vào từng tính năng riêng lẻ, theo mặc định, bạn sẽ thấy một InfoWindow chứa KML <title> và <description> thông tin về đối tượng được cung cấp. Ngoài ra, một lượt nhấp vào một đối tượng KML cũng tạo ra một KmlMouseEvent, truyền những thông tin sau:

• position cho biết vĩ độ/kinh độ tại để neo InfoWindow cho đối tượng KML này. Chiến dịch này vị trí thường là vị trí được nhấp vào cho đa giác, hình nhiều đường và GroundOverlays, nhưng là nguồn gốc thực sự của các điểm đánh dấu.
• pixelOffset cho biết giá trị chênh lệch so với giá trị trên position để cố định InfoWindow “đuôi”. Đối với đối tượng đa giác, độ lệch này thường là 0,0 nhưng đối với điểm đánh dấu, sẽ bao gồm chiều cao của điểm đánh dấu.
• featureData chứa cấu trúc JSON của KmlFeatureData.

Dưới đây là đối tượng KmlFeatureData mẫu:

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

Ví dụ sau đây minh hoạ đối tượng KML <Description> văn bản trong một bên <div> khi đối tượng được nhấp vào:

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

Hạn chế về kích thước và độ phức tạp khi kết xuất KML

API JavaScript của Maps có những giới hạn về kích thước và độ phức tạp của các tệp KML được tải. Dưới đây là thông tin tóm tắt về các hạn mức hiện tại.

Lưu ý: Các giới hạn này có thể thay đổi bất kỳ lúc nào bất cứ lúc nào.

Kích thước tối đa của tệp đã tìm nạp (KML thô, GeoRSS thô hoặc KMZ đã nén)

3MB

Kích thước tối đa của tệp KML đã giải nén

10MB

Kích thước tối đa của tệp hình ảnh không nén trong tệp KMZ

500KB mỗi tệp

Số lượng đường liên kết mạng tối đa

10

Tổng số lượng đối tượng địa lý tối đa trong toàn tài liệu

1.000

Số lớp KML

Có giới hạn về số lượng Lớp KML có thể được hiển thị trên một Bản đồ Google. Nếu bạn vượt quá giới hạn này, không có các lớp trên sẽ xuất hiện trên bản đồ và lỗi sẽ được báo cáo trong trang web của bạn bảng điều khiển JavaScript của trình duyệt. Hạn mức này được tính dựa trên sự kết hợp giữa số lượng lớp KmlLayer đã tạo và tổng thời lượng của tất cả URL được sử dụng để tạo các lớp đó. Mỗi KmlLayer mới bạn tạo sẽ chiếm một phần giới hạn cho lớp và là phần giới hạn bổ sung tùy thuộc vào độ dài của URL mà trong đó Tệp KML đã được tải từ. Do đó, số lượng lớp bạn có thể thêm sẽ khác nhau tuỳ theo ứng dụng; trung bình, bạn sẽ có thể tải giữa 10 và 20 lớp mà không đạt đến giới hạn. Nếu vẫn đạt tới giới hạn, sử dụng công cụ rút ngắn URL để rút ngắn URL KML. Ngoài ra, hãy tạo một một tệp KML chứa NetworkLinks cho các URL KML riêng lẻ.

Những điều cần cân nhắc về hiệu suất và việc lưu vào bộ nhớ đệm

Các máy chủ của Google sẽ tạm thời lưu các tệp KML vào bộ nhớ đệm để giảm tải cho bạn máy chủ. Điều này cũng sẽ cải thiện hiệu suất cho người dùng bằng cách phân phát biểu thị các phân đoạn thích hợp trong tệp KML theo cách tiết kiệm không gian, dưới dạng người dùng nhấp vào, xoay và thu phóng bản đồ.

Để đạt được hiệu suất tốt nhất, bạn nên:

• Sử dụng một thẻ <expires> thích hợp trong KML.
  
  KmlLayer sẽ không sử dụng tiêu đề HTTP khi quyết định cách thức để lưu các tệp KML vào bộ nhớ đệm.
• Đừng tạo tệp một cách linh động tại thời điểm yêu cầu.
  
  Thay vào đó, hãy tạo các tệp trước khi cần đến rồi phân phát chúng theo phương thức tĩnh. Nếu máy chủ của bạn mất nhiều thời gian để truyền tệp KML thì KmlLayer có thể không hiển thị.
• Đừng tìm cách bỏ qua bộ nhớ đệm trừ phi bạn biết rõ ràng rằng tệp đã được cập nhật.
  
  Luôn bỏ qua bộ nhớ đệm (ví dụ: bằng cách thêm một số ngẫu nhiên hoặc thời gian đồng hồ của người dùng làm tham số truy vấn) có thể dễ dàng khiến ứng dụng của bạn bị quá tải nếu trang web của bạn đột nhiên trở nên phổ biến và bạn phân phối các tệp KML lớn.
  
  Điều này cũng có thể khiến bộ nhớ đệm phân phối dữ liệu cũ cho người dùng, nếu có đồng hồ không chính xác và thẻ <expires> chưa được đặt chính xác.
  
  Thay vào đó, hãy xuất bản các tệp tĩnh được cập nhật bằng số bản sửa đổi mới, riêng biệt, và sử dụng mã phía máy chủ để cập nhật động URL được chuyển đến KmlLayer cho phiên bản hiện tại.
• Giới hạn các thay đổi đối với tệp KML thành một lần mỗi phút.
  
  Nếu tất cả các tệp có tổng kích thước lớn hơn 1MB (không nén), hãy giới hạn thay đổi thành một lần/5 phút.
• Khi sử dụng máy chủ dữ liệu không gian địa lý, hãy tránh sử dụng tham số truy vấn để giới hạn khung nhìn của các lớp.
  
  Thay vào đó, bạn có thể giới hạn chế độ xem bản đồ bằng Sự kiện bounds_changed. Người dùng sẽ chỉ nhận được các tính năng có thể tự động hiển thị.
  
  Nếu có một lượng lớn dữ liệu trong máy chủ dữ liệu không gian địa lý, hãy xem xét bằng lớp dữ liệu thay thế.
• Khi sử dụng máy chủ dữ liệu không gian địa lý, hãy dùng nhiều KmlLayer cho từng nhóm tính năng mà bạn muốn cho phép người dùng bật/tắt, thay vì so với một KmlLayer với các tham số truy vấn khác nhau.
• Sử dụng tệp KMZ được nén để giảm kích thước tệp.
• Nếu bạn đang sử dụng Google Cloud Storage hoặc một giải pháp bộ nhớ trên đám mây khác, tránh sử dụng các tính năng như URL đã ký hoặc mã thông báo tạm thời để thực thi các biện pháp kiểm soát quyền truy cập. Những URL này có thể vô tình ngăn việc lưu vào bộ nhớ đệm.
• Giảm độ chính xác của tất cả các điểm xuống một độ chính xác phù hợp.
• Hợp nhất và đơn giản hoá hình học của các đối tượng tương tự, chẳng hạn như đa giác và hình nhiều đường.
• Xoá mọi phần tử hoặc tài nguyên hình ảnh không dùng đến.
• Xoá mọi thành phần không được hỗ trợ.

Nếu bạn cần truy cập dữ liệu cá nhân, ngăn việc lưu vào bộ nhớ đệm hoặc gửi trình duyệt khung nhìn đến máy chủ dữ liệu không gian địa lý làm tham số truy vấn, nên sử dụng lớp dữ liệu thay vì KmlLayer. Việc này sẽ chuyển hướng người dùng của bạn để trực tiếp truy cập vào yêu cầu tài nguyên từ máy chủ web của bạn.

Phần tử KML được hỗ trợ

API JavaScript của Maps hỗ trợ những phần tử KML sau đây. Trình phân tích cú pháp KML thường bỏ qua trong im lặng những thẻ XML mà trình này không hiểu.

• Dấu vị trí
• Biểu tượng
• Thư mục
• HTML mô tả—Thay thế thực thể qua <BalloonStyle> và &lt;text&gt;
• KMZ (KML đã nén, bao gồm cả hình ảnh đính kèm)
• Hình nhiều đường và đa giác
• Kiểu hình nhiều đường và đa giác, bao gồm màu, phủ màu và độ mờ
• Liên kết mạng để nhập dữ liệu động
• Lớp phủ mặt đất và lớp phủ màn hình

Bảng sau đây cung cấp đầy đủ thông tin chi tiết về các phần tử KML được hỗ trợ.