Слои KML и GeoRSS

Выберите платформу: Android iOS JavaScript

KmlLayer отображает элементы KML и GeoRSS в наложение плиток Maps JavaScript API.

Обзор

API JavaScript Карт поддерживает форматы данных 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. point элементы KML <Placemark> и GeoRSS отображаются как маркеры, например, элементы <LineString> отображаются как полилинии, а элементы <Polygon> отображаются как многоугольники. Аналогично, элементы <GroundOverlay> отображаются на карте как прямоугольные изображения. Однако важно отметить, что эти объекты не являются Markers Maps JavaScript API, 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

Примечание. Прочтите руководство по использованию TypeScript и Google Maps.

JavaScript

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

Примечание. JavaScript скомпилирован из фрагмента TypeScript.

CSS

/* 
 * 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

<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

Попробуйте образец

JSFiddle.net Google Cloud Shell

В следующем примере создается 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

Примечание. Прочтите руководство по использованию TypeScript и Google Maps.

JavaScript

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

Примечание. JavaScript скомпилирован из фрагмента TypeScript.

CSS

/* 
 * 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

<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

Попробуйте образец

JSFiddle.net Google Cloud Shell

Подробности о функциях KML

Поскольку KML может включать в себя большое количество объектов, вы не можете напрямую получить доступ к данным объекта из объекта KmlLayer . Вместо этого при отображении функций они отображаются в виде кликабельных наложений Maps JavaScript API. При нажатии на отдельные объекты по умолчанию открывается InfoWindow содержащее информацию KML <title> и <description> для данного объекта. Кроме того, щелчок по объекту KML создает KmlMouseEvent , который передает следующую информацию:

• position указывает координаты широты и долготы, к которым можно привязать InfoWindow для этой функции KML. Эта позиция обычно является местом щелчка для полигонов, полилиний и GroundOverlays, но истинным началом координат для маркеров.
• pixelOffset указывает смещение от указанной выше position для привязки «хвоста» InfoWindow . Для полигональных объектов это смещение обычно равно 0,0 , но для маркеров включает высоту маркера.
• featureData содержит JSON-структуру KmlFeatureData .

Пример объекта KmlFeatureData показан ниже:

{
  author: {
    email: "[e-mail]",
    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

Примечание. Прочтите руководство по использованию TypeScript и Google Maps.

JavaScript

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

Примечание. JavaScript скомпилирован из фрагмента TypeScript.

CSS

/* 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

<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

Попробуйте образец

JSFiddle.net Google Cloud Shell

Ограничения по размеру и сложности для рендеринга KML

API JavaScript Карт имеет ограничения на размер и сложность загружаемых файлов KML. Ниже приведен краткий обзор текущих ограничений.

Примечание. Эти ограничения могут быть изменены в любое время.

Максимальный размер извлекаемого файла (необработанный KML, необработанный GeoRSS или сжатый KMZ)

3 МБ

Максимальный размер несжатого файла KML

10 МБ

Максимальный размер файла несжатого изображения в файлах KMZ

500 КБ на файл

Максимальное количество сетевых ссылок

10

Максимальное количество общих функций документа

1000

Количество слоев KML

Существует ограничение на количество слоев KML, которые могут отображаться на одной карте Google. Если вы превысите этот предел, ни один из ваших слоев не появится на карте, и в консоли JavaScript вашего веб-браузера будет сообщено об ошибке. Ограничение основано на сочетании количества созданных классов KmlLayer и общей длины всех URL-адресов, используемых для создания этих слоев. Каждый новый создаваемый вами KmlLayer будет занимать часть лимита слоя и дополнительную часть лимита в зависимости от длины URL-адреса, с которого был загружен файл KML. Следовательно, количество слоев, которые вы можете добавить, будет зависеть от приложения; в среднем вы сможете загрузить от 10 до 20 слоев, не достигая предела. Если вы все еще достигли предела, используйте средство сокращения URL-адресов, чтобы сократить URL-адреса KML. Альтернативно можно создать один файл KML, состоящий из сетевых ссылок на отдельные URL-адреса KML.

Вопросы производительности и кэширования

Серверы Google временно кэшируют файлы KML, чтобы снизить нагрузку на ваши серверы. Это также повысит производительность ваших пользователей за счет эффективного представления соответствующих сегментов вашего файла KML, когда ваши пользователи нажимают, перемещают и масштабируют карту.

Для достижения наилучшей производительности мы рекомендуем вам:

• Используйте соответствующий тег <expires> в KML.
  
  KmlLayer не будет использовать заголовки HTTP при принятии решения о том, как кэшировать файлы KML.
• Не создавайте файлы динамически во время запроса.
  
  Вместо этого создавайте файлы до того, как они понадобятся, и обслуживайте их статически. Если вашему серверу требуется много времени для передачи файла KML, KmlLayer может не отображаться.
• Не пытайтесь обойти кеши, если вы точно не уверены, что ваш файл был обновлен.
  
  Постоянный обход кешей (например, путем добавления случайного числа или времени на часах пользователя в качестве параметра запроса) может легко привести к перегрузке ваших серверов, если ваш сайт внезапно станет популярным и вы обслуживаете большие файлы KML.
  
  Это также может привести к тому, что кеш будет предоставлять пользователям устаревшие данные, если часы какого-либо пользователя неверны и тег <expires> установлен неправильно.
  
  Вместо этого публикуйте обновленные статические файлы с новым дискретным номером версии и используйте серверный код для динамического обновления URL-адреса, переданного в KmlLayer до текущей версии.
• Ограничьте внесение изменений в файлы KML до одного раза в минуту.
  
  Если общий размер всех файлов превышает 1 МБ (в несжатом виде), ограничьте изменения раз в 5 минут.
• При использовании сервера геопространственных данных избегайте использования параметров запроса, чтобы ограничить область просмотра слоев.
  
  Вместо этого вы можете ограничить область просмотра карты с помощью bounds_changed . Пользователям будут отправлены только те функции, которые могут отображаться автоматически.
  
  Если на вашем сервере геопространственных данных хранится большой объем данных, рассмотрите возможность использования вместо этого слоев данных .
• При использовании сервера геопространственных данных используйте несколько KmlLayer для каждой группы функций, которые вы хотите разрешить пользователям переключать, а не один KmlLayer с разными параметрами запроса.
• Используйте сжатые файлы KMZ, чтобы уменьшить размер файла.
• Если вы используете Google Cloud Storage или другое облачное хранилище, избегайте использования таких функций, как подписанные URL-адреса или временные токены, для обеспечения контроля доступа. Это может непреднамеренно помешать кэшированию.
• Уменьшите точность всех точек до соответствующей точности .
• Объединяйте и упрощайте геометрию похожих объектов, таких как полигоны и полилинии.
• Удалите все неиспользуемые элементы или ресурсы изображений.
• Удалите все неподдерживаемые элементы .

Если вам необходимо получить доступ к личным данным, предотвратить кеширование или отправить область просмотра браузера на сервер геопространственных данных в качестве параметра запроса, мы рекомендуем использовать слои данных вместо KmlLayer . Это заставит браузеры ваших пользователей напрямую запрашивать ресурсы с вашего веб-сервера.

Поддерживаемые элементы KML

API JavaScript Карт поддерживает следующие элементы KML. Анализатор KML обычно игнорирует непонятные ему теги XML.

• Метки
• Иконки
• Папки
• Описательный HTML — замена объекта с помощью <BalloonStyle> и <text>.
• KMZ (сжатый KML, включая прикрепленные изображения)
• Полилинии и многоугольники
• Стили полилиний и многоугольников, включая цвет, заливку и непрозрачность.
• Сетевые ссылки для динамического импорта данных
• Наземные наложения и наложения экрана

В следующей таблице приведены подробные сведения о поддерживаемых элементах KML.

KML-элемент	Поддерживается в API?	Комментарий
<адрес>	нет
<Детали адреса>	нет
<Псевдоним>	Н/Д	<Модель> не поддерживается
<высота>	нет
<режим высоты>	нет
<атом:автор>	да
<атом: ссылка>	да
<атом:имя>	да
<BalloonStyle>	частично	поддерживается только <текст>
<начало>	Н/Д	<TimeSpan> не поддерживается
<bgColor>	нет
<bottomFov>	Н/Д	<PhotoOverlay> не поддерживается.
<Камера>	нет
<Изменить>	частично	поддерживаются только изменения стиля
<цвет>	частично	включает #AABBGGRR и #BBGGRR; не поддерживается в <IconStyle>, <ScreenOverlay> и <GroundOverlay>
<colorMode>	нет
<cookie>	нет
<координаты>	да
<Создать>	нет
<Данные>	да
<Удалить>	нет
<описание>	да	Содержимое HTML разрешено, но оно обрабатывается для защиты от кросс-браузерных атак. Замены сущностей в форме $[ dataName ] не поддерживаются.
<режим отображения>	нет
<имя_дисплея>	нет
<Документ>	частично	косвенно дети получают поддержку; не влияет как дочерний элемент других функций
<drawOrder>	нет
<восток>	да
<конец>	Н/Д	<TimeSpan> не поддерживается
<срок действия истекает>	да	подробности см. в разделе «Сводка».
<Расширенные данные>	частично	Только нетипизированные <Data>, никакие <SimpleData> или <Schema>, а также замены сущностей в форме $[ dataName ] не поддерживаются.
<выдавливание>	нет
<заполнить>	да
<flyToView>	нет
<Папка>	да
<геомколор>	нет	устарел
<КоллекцияГеометрии>	нет	устарел
<геомскале>	нет	устарел
<gridOrigin>	Н/Д	<PhotoOverlay> не поддерживается.
<GroundOverlay>	да	невозможно повернуть
<ч>	да	устарел
<заголовок>	да
намекать	да	target=... поддерживается
<горячая точка>	да
<href>	да
<httpQuery>	нет
<Значок>	да	невозможно повернуть
<Иконостиль>	да
<Пирамида изображения>	Н/Д	<PhotoOverlay> не поддерживается.
<innerBoundaryIs>	да	неявно из порядка <LinearRing>
<ItemIcon>	Н/Д	<ListStyle> не поддерживается.
<ключ>	Н/Д	<StyleMap> не поддерживается.
<кмл>	да
<цвет метки>	нет	устарел
<Стиль метки>	нет
<широта>	да
<ЛатЛонАльтБокс>	да
<ЛатЛонБокс>	да
<leftFov>	Н/Д	<PhotoOverlay> не поддерживается.
<Линейное Кольцо>	да
<СтрокаЛинии>	да
<Стиль линии>	да
<Ссылка>	да
<ссылкаОписание>	нет
<имя ссылки>	нет
<linkSnippet>	нет
<листитемтипе>	Н/Д	<ListStyle> не поддерживается.
<СтильСписка>	нет
<Местоположение>	Н/Д	<Модель> не поддерживается
<Лод>	да
<долгота>	да
<Смотри>	нет
<максвысота>	да
<максфадеекстент>	да
<максВысота>	Н/Д	<PhotoOverlay> не поддерживается.
<maxLodPixels>	да
<макссессиондлина>	нет
<максширина>	Н/Д	<PhotoOverlay> не поддерживается.
<сообщение>	нет
<Метаданные>	нет	устарел
<минвысота>	да
<минфадеекстент>	да
<минЛодПикселс>	да
<минрефрешпериод>	нет	<СетьСсылка>
<Модель>	нет
<Мультигеометрия>	частично	визуализируется, но отображается как отдельные элементы на левой боковой панели
<имя>	да
<рядом>	Н/Д	<PhotoOverlay> не поддерживается.
<СетьСсылка>	да
<NetworkLinkControl>	частично	<Update> и <expires> поддерживаются частично. API игнорирует настройки срока действия в заголовках HTTP, но использует настройки срока действия, указанные в KML. При отсутствии настроек срока действия или в течение срока действия Карты Google могут кэшировать данные, полученные из Интернета, на неопределенный период времени. Повторное получение данных из Интернета можно вызвать, переименовав документ и получив его по другому URL-адресу, или убедившись, что документ содержит соответствующие настройки срока действия.
<север>	да
<открыть>	да
<Ориентация>	Н/Д	<Модель> не поддерживается
<outerBoundaryIs>	да	неявно из порядка <LinearRing>
<контур>	да
<оверлейXY>	нет
<Пара>	Н/Д	<StyleMap> не поддерживается.
<номер телефона>	нет
<Фотооверлей>	нет
<Метка>	да
<Точка>	да
<Многоугольник>	да
<ПолиСтиль>	да
<диапазон>	да
<интервал обновления>	частично	только <Ссылка>; нет в <Значок>
<режим обновления>	да	Заголовки HTTP не поддерживаются в режиме «onExpire». См. примечания к <Update> и <expires> выше.
<обновитьвидимость>	нет
<Регион>	да
<КартаРесурса>	Н/Д	<Модель> не поддерживается
<rightFov>	Н/Д	<PhotoOverlay> не поддерживается.
<ролл>	Н/Д	<Камера> и <Модель> не поддерживаются.
<вращение>	нет
<вращениеXY>	нет
<Масштаб>	Н/Д	<Модель> не поддерживается
<масштаб>	нет
<Схема>	нет
<ДанныеСхемы>	нет
<ScreenOverlay>	да	невозможно повернуть
<экранXY>	нет
<форма>	Н/Д	<PhotoOverlay> не поддерживается.
<ПростыеДанные>	Н/Д	<SchemaData> не поддерживаются.
<SimpleField>	Н/Д	<Схема> не поддерживаются
<размер>	да
<Фрагмент>	да
<юг>	да
<состояние>	Н/Д	<ListStyle> не поддерживается.
<Стиль>	да
<Карта стилей>	нет	эффекты ролловера (выделения) не поддерживаются
<styleUrl>	Н/Д	<StyleMap> не поддерживается.
<targetHref>	частично	поддерживается в <Обновление>, а не в <Псевдоним>
<тесселяция>	нет
<текст>	да	замена $[geDirections] не поддерживается
<текстовый цвет>	нет
<размер плитки>	Н/Д	<PhotoOverlay> не поддерживается.
<наклон>	нет
<TimeSpan>	нет
<метка времени>	нет
<topFov>	Н/Д	<PhotoOverlay> не поддерживается.
<Обновление>	частично	меняется только стиль, а не <Создать> или <Удалить>
<URL-адрес>	да	устарел
<значение>	да
<viewBoundScale>	нет
<формат просмотра>	нет
<виеврефрешмоде>	частично	«onStop» поддерживается
<виеврефрештиме>	да
<Просмотробъема>	Н/Д	<PhotoOverlay> не поддерживается.
<видимость>	частично	да в <Folder> — дочерние метки наследуют их видимость
<ш>	да	устарел
<запад>	да
<когда>	Н/Д	<TimeStamp> не поддерживается.
<ширина>	да
<х>	да	устарел
<у>	да	устарел