Слои KML и GeoRSS

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.
Выберите платформу: Android iOS JavaScript

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. point элементы KML <Placemark> и GeoRSS отображаются как маркеры, например, элементы <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 объекта 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;

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;

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;
}

HTML

<html>
  <head>
    <title>GeoRSS Layers</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</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;

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;

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;
}

HTML

<html>
  <head>
    <title>KML Layers</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</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"
}

В следующем примере отображается текст элемента 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;

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;

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%;
}

HTML

<html>
  <head>
    <title>KML Feature Details</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>

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

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

Maps JavaScript API имеет ограничения на размер и сложность загружаемых файлов 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

Maps JavaScript API поддерживает следующие элементы KML. Синтаксический анализатор KML обычно молча игнорирует теги XML, которые он не понимает.

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

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

KML-элемент Поддерживается в API? Комментарий
<адрес> нет
<Сведения об адресе> нет
<Псевдоним> Н/Д <Модель> не поддерживается
<высота> нет
<режим высоты> нет
<атом:автор> да
<атом:ссылка> да
<атом:имя> да
<Воздушный стиль> частично поддерживается только <текст>
<начало> Н/Д <TimeSpan> не поддерживается
<bgColor> нет
<bottomFov> Н/Д <PhotoOverlay> не поддерживается
<Камера> нет
<Изменить> частично поддерживаются только изменения стиля
<цвет> частично включает #AABBGGRR и #BBGGRR; не поддерживается в <IconStyle>, <ScreenOverlay> и <GroundOverlay>
<режим цвета> нет
<куки> нет
<координаты> да
<Создать> нет
<Данные> да
<Удалить> нет
<описание> да HTML-контент разрешен, но очищен для защиты от кросс-браузерных атак. Замена сущностей в форме $[ dataName ] не поддерживается.
<режим отображения> нет
<отображаемое имя> нет
<Документ> частично косвенно дети поддерживаются; не влияет как дочерний элемент других функций
<drawOrder> нет
<восток> да
<конец> Н/Д <TimeSpan> не поддерживается
<истекает> да подробности см. в разделе «Сводка».
<Расширенные данные> частично только нетипизированные <Data>, без <SimpleData> или <Schema>, а также замены сущностей в форме $[ dataName ] не поддерживаются.
<выдавливание> нет
<заполнить> да
<flyToView> нет
<Папка> да
<geomColor> нет устарел
<Коллекция геометрии> нет устарел
<геоммасштаб> нет устарел
<происхождение сетки> Н/Д <PhotoOverlay> не поддерживается
<Наложение земли> да нельзя вращать
<ч> да устарел
<заголовок> да
намекать да target=... поддерживается
<горячая точка> да
<ссылка> да
<httpQuery> нет
<Значок> да нельзя вращать
<Стиль значка> да
<ImagePyramid> Н/Д <PhotoOverlay> не поддерживается
<иннерграундариес> да неявно из порядка <LinearRing>
<ItemIcon> Н/Д <ListStyle> не поддерживается
<ключ> Н/Д <StyleMap> не поддерживается
<кмл> да
<меткаЦвет> нет устарел
<Стиль метки> нет
<широта> да
<LatLonAltBox> да
<LatLonBox> да
<левое поле> Н/Д <PhotoOverlay> не поддерживается
<Линейное кольцо> да
<LineString> да
<Стиль линии> да
<Ссылка> да
<ссылкаОписание> нет
<имя_ссылки> нет
<фрагмент ссылки> нет
<списокItemType> Н/Д <ListStyle> не поддерживается
<Стиль списка> нет
<Местоположение> Н/Д <Модель> не поддерживается
<Лод> да
<долгота> да
<Посмотреть> нет
<максимальная высота> да
<maxFadeExtent> да
<максимальная высота> Н/Д <PhotoOverlay> не поддерживается
<maxLodPixels> да
<maxSessionLength> нет
<максширина> Н/Д <PhotoOverlay> не поддерживается
<сообщение> нет
<Метаданные> нет устарел
<минимальная высота> да
<minFadeExtent> да
<minLodPixels> да
<minRefreshPeriod> нет <Сетевая ссылка>
<Модель> нет
<Мультигеометрия> частично визуализируются, но отображаются как отдельные функции на левой боковой панели
<имя> да
<рядом> Н/Д <PhotoOverlay> не поддерживается
<Сетевая ссылка> да
<NetworkLinkControl> частично <Update> и <expires> частично поддерживаются. API игнорирует параметры срока действия в заголовках HTTP, но использует параметры срока действия, указанные в KML. При отсутствии настроек срока действия или в течение интервала действия Карты Google могут кэшировать данные, полученные из Интернета, на неопределенное время. Повторную загрузку данных из Интернета можно принудительно вызвать, переименовав документ и загрузив его по другому URL-адресу, или убедившись, что документ содержит соответствующие параметры истечения срока действия.
<север> да
<открыть> да
<Ориентация> Н/Д <Модель> не поддерживается
<внешняя граница> да неявно из порядка <LinearRing>
<схема> да
<наложениеXY> нет
<Пара> Н/Д <StyleMap> не поддерживается
<номер телефона> нет
<Фотооверлей> нет
<Метка> да
<Точка> да
<Многоугольник> да
<Полистиль> да
<диапазон> да
<интервал обновления> частично только <ссылка>; нет в <Значок>
<режим обновления> да Заголовки HTTP не поддерживаются для режима onExpire. См. примечания к <Update> и <expires> выше.
<обновить видимость> нет
<Регион> да
<Карта ресурсов> Н/Д <Модель> не поддерживается
<правый угол> Н/Д <PhotoOverlay> не поддерживается
<рулон> Н/Д <Камера> и <Модель> не поддерживаются
<поворот> нет
<вращениеXY> нет
<Масштаб> Н/Д <Модель> не поддерживается
<масштаб> нет
<Схема> нет
<Данные схемы> нет
<Наложение экрана> да нельзя вращать
<экранXY> нет
<форма> Н/Д <PhotoOverlay> не поддерживается
<ПростыеДанные> Н/Д <SchemaData> не поддерживаются
<Простое поле> Н/Д <Схема> не поддерживаются
<размер> да
<фрагмент> да
<юг> да
<состояние> Н/Д <ListStyle> не поддерживается
<Стиль> да
<Карта стиля> нет эффекты опрокидывания (выделения) не поддерживаются
<ссылка на стиль> Н/Д <StyleMap> не поддерживается
<targetHref> частично поддерживается в <Update>, но не в <Alias>
<тесселяция> нет
<текст> да замена $[geDirections] не поддерживается
<цвет текста> нет
<размер плитки> Н/Д <PhotoOverlay> не поддерживается
<наклон> нет
<TimeSpan> нет
<Отметка времени> нет
<topFov> Н/Д <PhotoOverlay> не поддерживается
<Обновить> частично изменяется только стиль, а не <Создать> или <Удалить>
<URL> да устарел
<значение> да
<viewBoundScale> нет
<формат просмотра> нет
<viewRefreshMode> частично "Остановить" поддерживается
<viewRefreshTime> да
<ViewVolume> Н/Д <PhotoOverlay> не поддерживается
<видимость> частично yes на <Folder> — дочерние метки наследуют свою видимость
<ш> да устарел
<запад> да
<когда> Н/Д <TimeStamp> не поддерживается
<ширина> да
<х> да устарел
<у> да устарел