Lớp KML và GeoRSS

KmlLayer hiển thị các phần tử KML và GeoRSS thành một lớp phủ thẻ thông tin API Maps JavaScript.

Tổng quan

API Maps JavaScript hỗ trợ các định dạng dữ liệu KML và GeoRSS để hiển thị thông tin địa lý. Các định dạng dữ liệu này được hiển thị trên bản đồ bằ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 tạo lớp phủ KML trong API Maps JavaScript sử dụng dịch vụ do Google lưu trữ để truy xuất và phân tích cú pháp các tệp KML nhằm hiển thị. Do đó, bạn chỉ có thể hiển thị tệp KML nếu tệp đó được lưu trữ tại một URL có thể truy cập công khai và 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ư, kiểm soát chi tiết đối với bộ nhớ đệm hoặc gửi khung nhìn 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 sử dụng lớp dữ liệu thay vì KmlLayer. Thao tác này sẽ hướng trình duyệt của người dùng 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 dữ liệu XML địa lý được cung cấp thành một bản trình bày KML hiển thị trên bản đồ bằng cách sử dụng lớp phủ thẻ thông tin API JavaScript của Maps. KML này trông giống (và hoạt động tương tự) như các phần tử lớp phủ quen thuộc của API Maps JavaScript. Các phần tử KML <Placemark> và GeoRSS point được hiển thị dưới dạng điểm đánh dấu, ví dụ: các phần tử <LineString> được hiển thị dưới dạng đa tuyến và các phần tử <Polygon> được hiển thị 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à Markers, Polylines, Polygons hoặc GroundOverlays của API JavaScript của Maps; thay vào đó, các đối tượng này được kết xuất thành một đối tượng duy nhất trên bản đồ.

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

Vì các thành phần trong KmlLayer được kết xuất theo yêu cầu, nên 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, đa tuyến và đa giác. Xin lưu ý rằng bạn không thể truy cập trực tiếp vào các đối tượng thành phần này, mặc dù mỗi đối tượng đều cung cấp các sự kiện nhấp trả về dữ liệu trên các đối tượng riêng lẻ đó.

Tuỳ chọn lớp KML

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

• map chỉ định Map để hiển thị KmlLayer. Bạn có thể ẩn KmlLayer bằng cách đặt giá trị này thành null trong phương thức setMap().
• preserveViewport chỉ định rằng không được điều chỉnh bản đồ theo giới hạn của nội dung KmlLayer khi hiển thị lớp. Theo mặc định, khi hiển thị KmlLayer, bản đồ sẽ được thu phóng và định vị để hiển thị toàn bộ nội dung của lớp.
• 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 việc hiển thị các đối tượng InfoWindow.

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

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

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 một KmlLayer từ nguồn cấp dữ liệu KML nhất định:

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

Chi tiết về tính năng KML

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

• position cho biết toạ độ vĩ độ/kinh độ để neo InfoWindow cho tính năng KML này. Vị trí này thường là vị trí được nhấp cho đa giác, đa tuyến và GroundOverlay, nhưng là nguồn gốc thực sự cho điểm đánh dấu.
• pixelOffset cho biết độ dời từ position ở trên để neo "đuôi" InfoWindow. Đối với các đối tượng đa giác, độ dời này thường là 0,0, nhưng đối với các điểm đánh dấu, độ dời này bao gồm cả 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à một đố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 hiển thị văn bản <Description> của đối tượng KML trong một <div> bên khi người dùng nhấp vào đối tượng đó:

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

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

Lưu ý: Các giới hạn này có thể thay đổi 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ệp hình ảnh chưa nén tối đa trong tệp KMZ

500 KB 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ể hiển thị trên một Google Maps. Nếu bạn vượt quá giới hạn này, thì không có lớp nào sẽ xuất hiện trên bản đồ và một lỗi sẽ được báo cáo trong bảng điều khiển JavaScript của trình duyệt web. Giới hạn này dựa trên tổ hợp số lượng lớp KmlLayer được tạo và tổng chiều dài của tất cả URL dùng để tạo các lớp đó. Mỗi KmlLayer mới mà bạn tạo sẽ chiếm một phần giới hạn cho lớp và một phần giới hạn khác tuỳ thuộc vào độ dài của URL nơi tải tệp KML. Do đó, số lượng lớp mà bạn có thể thêm sẽ khác nhau tuỳ theo ứng dụng; trung bình, bạn có thể tải từ 10 đến 20 lớp mà không gặp phải giới hạn. Nếu bạn vẫn gặp phải giới hạn này, hãy sử dụng trình rút gọn URL để rút gọn URL KML. Ngoài ra, hãy tạo một tệp KML bao gồm NetworkLinks đến từng URL KML.

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

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 máy chủ của bạn. Đ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 một bản trình bày tiết kiệm không gian của các phân đoạn thích hợp trong tệp KML khi người dùng nhấp vào, kéo và thu phóng bản đồ.

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

• Sử dụng thẻ <expires> thích hợp trong KML.
  
  KmlLayer sẽ không sử dụng tiêu đề HTTP khi quyết định cách lưu tệp KML vào bộ nhớ đệm.
• Khô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 và phân phát các tệp đó một cách 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 cố gắng bỏ qua bộ nhớ đệm trừ phi bạn biết chắc chắn rằng tệp của mình đã được cập nhật.
  
  Việc 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 máy chủ 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 đang phân phát các tệp KML lớn.
  
  Điều này cũng có thể khiến bộ nhớ đệm phân phát dữ liệu cũ cho người dùng, nếu đồng hồ của người dùng không chính xác và thẻ <expires> chưa được đặt chính xác.
  
  Thay vào đó, hãy phát hành các tệp tĩnh đã 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 truyền đến KmlLayer bằng phiên bản hiện tại.
• Giới hạn số lần thay đổi đối với tệp KML ở mức một lần mỗi phút.
  
  Nếu tổng kích thước của tất cả tệp lớn hơn 1 MB (không nén), giới hạn sẽ thay đổi thành một lần mỗi 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 các 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 khung nhìn 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 máy chủ dữ liệu không gian địa lý của bạn có một lượng lớn dữ liệu, hãy cân nhắc sử dụng lớp dữ liệu.
• Khi sử dụng máy chủ dữ liệu không gian địa lý, hãy sử dụng nhiều KmlLayer cho mỗi nhóm đối tượng mà bạn muốn cho phép người dùng bật/tắt, thay vì một KmlLayer duy nhất với các tham số truy vấn khác nhau.
• Sử dụng tệp KMZ 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 lưu trữ trên đám mây khác, hãy 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. Các hành vi 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 thích 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à đường đa tuyến.
• Xoá mọi thành phần 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 cần truy cập vào dữ liệu riêng tư, ngăn lưu vào bộ nhớ đệm hoặc gửi khung nhìn 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 sử dụng lớp dữ liệu thay vì KmlLayer. Thao tác này sẽ hướng trình duyệt của người dùng trực tiếp yêu cầu tài nguyên từ máy chủ web của bạn.

Các phần tử KML được hỗ trợ

Maps JavaScript API hỗ trợ các phần tử KML sau. 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ể thông qua <BalloonStyle> và <text>
• 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 thông tin chi tiết đầy đủ về các phần tử KML được hỗ trợ.