Пути миграции KmlLayer

Введение

Цель данного руководства — описать наиболее распространенные способы использования KmlLayer и предоставить соответствующие пути миграции к альтернативным реализациям. Эта информация предназначена для разработчиков, которым необходимо перейти от использования KmlLayer в связи с его запланированным прекращением поддержки. Последняя версия , поддерживающая KmlLayer, — 3.65, которая будет выведена из эксплуатации в мае 2027 года.

Путь миграции зависит от того, как вы используете KmlLayer:

KML-файл для оформления границ/областей интереса.

Разработчикам, использующим KmlLayer для отображения или оформления административных границ — например, для выделения конкретной страны, штата или населенного пункта — платформа Google Maps рекомендует перейти на стиль оформления границ, управляемый данными (DDS) .

Рекомендация по миграции: стилизация границ на основе данных.

Управление стилями границ на основе данных обеспечивает прямой доступ к полигонам административных границ Google, позволяя применять пользовательские стили (заливку и обводку) к этим областям без необходимости размещения или управления внешними KML-файлами.

Доступный тип объекта

Административные области классифицируются по функциям и располагаются по уровням. Для оформления поддерживаются следующие типы объектов:

  • COUNTRY : Национальное политическое образование.
  • ADMINISTRATIVE_AREA_LEVEL_1 : Гражданское образование первого порядка ниже уровня страны (например, штаты в США).
  • ADMINISTRATIVE_AREA_LEVEL_2 : Гражданское образование второго порядка, находящееся ниже уровня страны (например, округа в США).
  • LOCALITY : Город или поселок, имеющий статус муниципалитета.
  • POSTAL_CODE : Почтовые индексы, используемые для почтовой переписки.
  • SCHOOL_DISTRICT : Объединенные, начальные или средние школьные округа.

См. информацию о покрытии границ для регионов, где доступны эти типы объектов.

Как выделить область

Для оформления определенного региона необходимо указать его идентификатор места (Place ID) .

Ограничение панорамирования определенной областью

Чтобы запретить пользователям выходить за пределы выделенной области, вы можете использовать параметр restriction в MapOptions .

Объект restriction определяет latLngBounds , который ограничивает видимую область карты. Более подробную информацию о том, как работает ограничение, см. в документации .

// Restrict panning to a specific bounding box
restriction: {
  latLngBounds: {
    north: 47.8,
    south: 45.8,
    east: 10.5,
    west: 5.9,
  },
  strictBounds: true,
},

Краткое описание внедрения миграции

Вот полный пример того, как использовать стилизацию на основе данных для обозначения границ и ограничения области, чтобы сфокусировать карту вокруг определенной территории.

const myTargetRegion = "ChIJYW1Zb-9kjEcRFXvLDxG1Vlw"; // Place ID for Switzerland

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 46.8, lng: 8.2 },
    zoom: 9,
    mapId: "YOUR_MAP_ID", // Required for DDS
    // Restrict panning to a specific bounding box
    restriction: {
    // Bounding box for Switzerland
      latLngBounds: {
        north: 47.8,
        south: 45.8,
        east: 10.5,
        west: 5.9,
      },
      strictBounds: true,
    },
  });

  // Access the Country layer and style a specific region by Place ID
  const countryLayer = map.getFeatureLayer("COUNTRY");
  countryLayer.style = (options) => {
    if (options.feature.placeId === myTargetRegion) {
      return {
        fillColor: "#FF0000",
        fillOpacity: 0.5,
        strokeColor: "#FF0000",
        strokeWeight: 2,
      };
    } else {
    // Style everything else whited out, to make the area of interest pop out more.
      return {
        fillColor: '#ffffff',
        fillOpacity: 0.8,
      };
    }
  };
}

KML-файл с векторными данными (точки/полилинии/границы/полигоны)

Рекомендации по миграции: стилизация наборов данных на основе данных.

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

Возможность стилизации наборов данных на основе данных позволяет загружать собственные геопространственные данные (KML, GeoJSON или CSV), применять пользовательские стили на основе атрибутов данных и отображать объекты на векторных картах.

1. Настройка и загрузка

В отличие от KmlLayer , который получает URL-адрес во время выполнения, DDS требует размещения данных в виде набора данных в консоли Google Cloud.

  • Создайте идентификатор карты : используйте идентификатор карты, настроенный для типа карты «Векторная» .
  • Загрузка набора данных : Загрузите свой KML-файл в консоль Google Cloud, чтобы сгенерировать уникальный идентификатор набора данных . Для получения более подробной информации ознакомьтесь с полной документацией по управлению наборами данных карт .
  • Отображение набора данных: После создания идентификатора набора данных необходимо связать его со стилем карты и идентификатором карты. Затем вы будете использовать идентификатор набора данных для фактического отображения данных на карте. Подробную информацию о том, как добавить набор данных на карту, см. в полной документации .
  • Обратите внимание на требования к KML- файлам для наборов данных, если вы решите импортировать данные из формата KML.

2. Настройка области просмотра на данные.

В KmlLayer по умолчанию происходит автоматическое перемещение и масштабирование до местоположения данных. В DDS для наборов данных это поведение не является автоматическим и должно быть реализовано вручную.

  • Жестко заданные ограничения : Если область данных статична, используйте параметр restriction в MapOptions , чтобы зафиксировать область просмотра в определенных пределах.
  • Динамическое масштабирование : Для динамической установки области просмотра можно использовать map.fitBounds() с ограничивающим прямоугольником вашего набора данных.

3. Стилизация на основе атрибутов объекта

KML-файлы часто содержат информацию о стиле (например, о цветах), которую DDS не применяет автоматически. Вам необходимо создать функцию стиля на стороне клиента, которая считывает атрибуты из объектов набора данных для применения цветов и прозрачности. Для получения полной информации обратитесь к документации разработчика по вопросам оформления данных .

Пример: стилизация функции с использованием атрибутов.

В следующем примере показано, как создать функцию стиля, которая считывает атрибуты background_color и opacity непосредственно из загруженного набора данных:

/**
 * Migration example: Styling features from dataset attributes.
 */
function styleDDSLayer(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Set the style function
  datasetLayer.style = (params) => {
    // Access attributes defined in your KML/Dataset
    const featureAttributes = params.feature.datasetAttributes;

    // Read style values from attributes, with fallback defaults
    const fillColor = featureAttributes['background_color'] || '#4285F4';
    const fillOpacity = parseFloat(featureAttributes['opacity']) || 0.5;
    const strokeColor = featureAttributes['border_color'] || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: fillOpacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
    };
  };
}

Для получения более подробной информации о реализации интерактивных элементов и стилей см. обзор стилей, управляемых данными, для наборов данных и API наборов данных для динамических данных.

Рекомендация по миграции: Отображение на стороне клиента с использованием GeoJSON.

Разработчикам, переходящим с KmlLayer на клиентскую отрисовку с использованием GeoJSON, платформа Google Maps рекомендует путь миграции, включающий преобразование формата данных и использование слоя данных для отрисовки и стилизации объектов непосредственно в браузере.

Рендеринг на стороне клиента с использованием слоя данных обеспечивает очень гибкий способ отображения географических данных. В отличие от KmlLayer , который рендерится на серверах Google, слой данных позволяет взаимодействовать с объектами как со стандартными объектами JavaScript. Однако следует отметить, что для больших наборов данных вы можете предпочесть обработку и рендеринг данных на стороне сервера, например, с помощью Data-driven Styling for Datasets.

1. Преобразовать KML в GeoJSON

Первый шаг — преобразование KML-файлов в GeoJSON. Это можно сделать с помощью нескольких популярных инструментов с открытым исходным кодом:

  • ogr2ogr : Эта мощная утилита командной строки, входящая в состав пакета GDAL, позволяет конвертировать файлы между множеством векторных форматов. 
ogr2ogr -f GeoJSON output.json input.kml
  • togeojson : Небольшой, хорошо протестированный инструмент, разработанный специально для преобразования файлов KML и GPX в GeoJSON. 
togeojson input.kml > output.json

2. Настройка области просмотра на данные.

В то время как KmlLayer автоматически перемещается и масштабируется в соответствии с местоположением данных, слой Data этого не делает. Чтобы установить область просмотра в соответствии с вашими данными GeoJSON, необходимо вручную рассчитать ограничивающий прямоугольник и вызвать метод map.fitBounds() .

3. Стилизация на основе атрибутов объекта

В слое данных можно определить функцию style , которая считывает атрибуты (свойства) непосредственно из каждого объекта GeoJSON для определения его внешнего вида.

Пример: Функция стилизации и настройка области просмотра.

В следующем примере показано, как загрузить данные GeoJSON, рассчитать их границы для установки области просмотра и стилизовать объекты на основе их атрибутов:

/**
 * Migration example: Loading GeoJSON, fitting viewport, and styling from attributes.
 */
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -28, lng: 137 },
  });

  // Load the GeoJSON data
  map.data.loadGeoJson('path/to/your/data.json', null, (features) => {
    // Adjust viewport to show all loaded features
    const bounds = new google.maps.LatLngBounds();
    features.forEach((feature) => {
      feature.getGeometry().forEachLatLng((latlng) => {
        bounds.extend(latlng);
      });
    });
    map.fitBounds(bounds);
  });

  // Set the style function to read from GeoJSON properties
  map.data.setStyle((feature) => {
    // Access attributes defined in your GeoJSON properties
    const fillColor = feature.getProperty('background_color') || '#4285F4';
    const opacity = parseFloat(feature.getProperty('opacity')) || 0.5;
    const strokeColor = feature.getProperty('border_color') || '#34A853';

    return {
      fillColor: fillColor,
      fillOpacity: opacity,
      strokeColor: strokeColor,
      strokeWeight: 2,
      visible: true
    };
  });
}

Для получения дополнительной информации об использовании слоя данных см. документацию по импорту GeoJSON в карты .

Вариант миграции: рендеринг на стороне клиента с использованием сторонних библиотек.

Для разработчиков, ищущих альтернативы KmlLayer , существует несколько поддерживаемых сообществом библиотек, которые отображают KML-данные в JavaScript API платформы Google Maps.

1. deck.gl

deck.gl — это высокопроизводительная платформа визуализации на основе WebGL. Она может использоваться практически в качестве замены рендеринга KML благодаря встроенным модулям GoogleMapsOverlay и GeoJsonLayer .

  • Требование к элементу Canvas: Для эффективного использования deck.gl необходимо преобразовать карту в векторный тип (который отображается в элементе canvas) с возможностями рендеринга WebGL.
  • Поддержка KML: Парсинг геометрии осуществляется с помощью @loaders.gl/kml , который преобразует KML в GeoJSON. Обратите внимание, что для некоторых функций KML, таких как сложные стили, значки и сетевые ссылки, может потребоваться дополнительная ручная реализация.
  • Документация: deck.gl Documentation | loaders.gl KML Loader .
  • Примеры:
    • Пример deckgl-kml-updated из репозитория Google Maps на GitHub демонстрирует, как использовать deck.gl для отображения KML-данных, обновляемых в режиме реального времени.
    • Пример deckgl-kml демонстрирует, как использовать deck.gl для отображения данных KML.

2. geoxml3

geoxml3 — это обработчик KML, специально разработанный для JavaScript API Google Maps версии 3. Он анализирует KML локально в браузере и отображает данные в виде стандартных объектов API Google Maps, таких как маркеры, полилинии и полигоны.

  • Поддержка стандартных карт: В отличие от решений на основе WebGL, geoxml3 работает со стандартными картами Google Maps JS API v3 без необходимости выбора определенного режима рендеринга.
  • Предостережения:
    • Ограниченная поддержка KMZ: библиотека не поддерживает файлы KMZ в полном объеме ; для распаковки архивов KMZ обычно требуется интеграция с дополнительными сторонними скриптами, такими как ZipFile.complete.js .
    • Неподдерживаемые элементы: такие элементы, как 3D-геометрии, сложные метки и некоторые новые элементы KML, не поддерживаются.
  • Документация: репозиторий geoxml3 на GitHub .

KML-файл с интерактивными элементами

Рекомендации по миграции: стилизация наборов данных на основе данных.

Для разработчиков, переходящих с KmlLayer на стилизацию на основе данных (DDS) для наборов данных , это руководство объясняет, как перейти от автоматического взаимодействия с KML к пользовательским высокопроизводительным взаимодействиям, таким как щелчки мыши и наведение курсора.

Первоначальная настройка

Перед внедрением взаимодействий убедитесь, что вы выполнили шаги настройки, описанные в руководстве по миграции KML: векторные данные :

  • Идентификатор карты: Настройте идентификатор карты для типа карты «Векторная» .
  • Загрузка: Загрузите ваши KML-данные в консоль Google Cloud, чтобы получить идентификатор набора данных (Dataset ID) .
  • Доступ к слою: Используйте map.getDatasetFeatureLayer(datasetId) для доступа к интерактивному слою.

1. Обработка событий взаимодействия

В KmlLayer щелчки по объектам обрабатываются автоматически API, вызывая всплывающее информационное окно. В случае с DDS для наборов данных необходимо вручную регистрировать обработчики событий мыши на слое набора данных.

  • click : Срабатывает, когда пользователь нажимает на какой-либо элемент.
  • mousemove : Срабатывает при наведении курсора на объект, полезно для создания эффектов при наведении курсора.

2. Динамическое оформление (эффект при наведении курсора)

Поскольку стили DDS применяются ко всему слою глобально, следует поддерживать переменную состояния для отслеживания того, с каким объектом осуществляется взаимодействие, и повторного применения стиля. 

let currentFeatureId = null;

function initInteraction(map, datasetId) {
  const datasetLayer = map.getDatasetFeatureLayer(datasetId);

  // Apply the style function
  datasetLayer.style = (params) => {
    const isHovered = params.feature.datasetAttributes['id'] === currentFeatureId;
    return {
      strokeColor: 'green',
      strokeWeight: isHovered ? 4.0 : 2.0, // Bold border on hover
      fillColor: 'green',
      fillOpacity: isHovered ? 0.5 : 0.3,
    };
  };

  // Add interaction listeners
  datasetLayer.addListener('mousemove', (event) => {
    if (event.features.length > 0) {
      currentFeatureId = event.features[0].datasetAttributes['id'];
      datasetLayer.style = datasetLayer.style; // Re-apply style to reflect changes
    }
  });

  // Clear hover state when the mouse leaves the features
  map.addListener('mousemove', () => {
    if (currentFeatureId !== null) {
      currentFeatureId = null;
      datasetLayer.style = datasetLayer.style;
    }
  });
}

3. Отображение HTML-кода из атрибута description .

В KML тег <description> часто содержит HTML-код для окна информации по умолчанию. При импорте этих данных в качестве набора данных description становится атрибутом объекта. Для его отображения передайте строку непосредственно в стандартный объект google.maps.InfoWindow .

const infoWindow = new google.maps.InfoWindow();

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const feature = event.features[0];
    // Access the HTML description attribute
    const htmlContent = feature.datasetAttributes['description'];

    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. Пользовательское информационное окно с ExtendedData

Если в вашем KML-файле используется <ExtendedData> для хранения пользовательских пар "имя/значение", они сопоставляются с datasetAttributes ). Вы можете перебирать эти атрибуты для создания пользовательского HTML-отображения.

function createCustomContent(feature) {
  const attributes = feature.datasetAttributes;
  const container = document.createElement("div");
  container.style.padding = "10px";
  container.innerHTML = "<h3>Feature Details</h3><dl></dl>";

  const dl = container.querySelector("dl");

  // Iterate through all data attributes imported from KML ExtendedData
  for (const key in attributes) {
    const dt = document.createElement("dt");
    dt.style.fontWeight = "bold";
    dt.textContent = key;

    const dd = document.createElement("dd");
    dd.textContent = attributes[key];

    dl.appendChild(dt);
    dl.appendChild(dd);
  }
  return container;
}

datasetLayer.addListener('click', (event) => {
  if (event.features.length > 0) {
    const content = createCustomContent(event.features[0]);
    infoWindow.setContent(content);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

Для получения более сложных методов визуализации см. документацию для разработчиков о том, как оформлять элементы данных .

Рекомендация по миграции: Отображение на стороне клиента с использованием GeoJSON.

Для разработчиков, переходящих с KmlLayer на клиентскую отрисовку с использованием GeoJSON и слоя данных , это руководство объясняет, как перейти от автоматического взаимодействия с KML к пользовательскому взаимодействию, управляемому событиями, и динамическому стилизации.

Первоначальная настройка

Перед реализацией интерактивных элементов необходимо преобразовать данные KML в GeoJSON и загрузить их в слой данных. Подробную информацию об использовании таких инструментов, как ogr2ogr или togeojson , и инициализации карты с помощью map.data.loadGeoJson() см. в руководстве «Рекомендации по миграции: рендеринг на стороне клиента с использованием GeoJSON» .

1. Автоматическое и ручное взаимодействие

Ключевое различие между этими уровнями заключается в способе обработки пользовательского ввода:

  • KmlLayer : Автоматически обрабатывает клики по элементам и отображает InfoWindow содержащее KML-файл. и данные.
  • Слой данных : Автоматическое отображение объектов InfoWindow не происходит. Необходимо вручную добавить обработчики событий для отслеживания действий пользователя и написать код для отображения данных.

2. Обработка событий взаимодействия

Для обеспечения интерактивности объектов GeoJSON используйте метод addListener() объекта map.data . К распространенным событиям относятся:

  • click : Используется для запуска информационных окон или логики выбора.
  • mouseover / mouseout : Используется для эффектов наведения курсора и выделения.

3. Отображение HTML-описаний в информационном окне.

При преобразовании KML в GeoJSON тег <description> (который часто содержит HTML-код) обычно сопоставляется со свойством с именем description . Вы можете использовать feature.getProperty('description') , чтобы получить эту строку и отобразить её в стандартном google.maps.InfoWindow . 

const infoWindow = new google.maps.InfoWindow();

// Handle clicks to show the HTML description
map.data.addListener('click', (event) => {
  // Access the 'description' property from the GeoJSON feature
  const htmlContent = event.feature.getProperty('description');

  if (htmlContent) {
    infoWindow.setContent(htmlContent);
    infoWindow.setPosition(event.latLng);
    infoWindow.open(map);
  }
});

4. Пользовательские информационные окна и ExtendedData

Если в исходном KML-файле использовался <ExtendedData> , эти пары "имя-значение" преобразуются в свойства GeoJSON. Поскольку слой данных не имеет стандартного пользовательского интерфейса для этих свойств, вам необходимо реализовать собственное информационное окно для перебора и отображения этих данных.

Вы можете получить доступ к этим атрибутам, используя event.feature.getProperty('attribute_name') , и создать пользовательскую HTML-строку или DOM-элемент для передачи в метод infoWindow.setContent() .

5. Динамическое оформление (эффекты при наведении курсора)

Слой данных позволяет программно обновлять стили объектов в ответ на события. Используйте overrideStyle() для временного изменения внешнего вида объекта (например, при наведении курсора), а revertStyle() — для возврата к глобальному стилю. 

// Set a base style for all features
map.data.setStyle({
  fillColor: 'blue',
  strokeWeight: 1
});

// Highlight feature on mouseover
map.data.addListener('mouseover', (event) => {
  map.data.revertStyle(); // Clear previous highlights
  map.data.overrideStyle(event.feature, {strokeWeight: 8});
});

// Revert style on mouseout
map.data.addListener('mouseout', (event) => {
  map.data.revertStyle();
});

Более подробную информацию о реализации см. в документации по уровням данных: обработка событий и динамическое стилирование .

Вариант миграции: рендеринг на стороне клиента с использованием сторонних библиотек.

Для разработчиков, переходящих с KmlLayer на сторонние решения, это руководство посвящено обработке интерактивных данных, таких как щелчки мыши и динамические события, с использованием deck.gl и geoxml3 .

Первоначальная настройка

Перед внедрением интерактивных элементов убедитесь, что вы выполнили шаги по настройке, описанные в руководстве « Путь миграции: рендеринг на стороне клиента с использованием сторонних библиотек» . Это включает в себя:

  • deck.gl : Преобразование вашей карты в векторный тип (требование к холсту).
  • geoxml3 : Обслуживание скриптов библиотеки с вашего собственного хоста и управление междоменным доступом к ресурсам (CORS).

1. Интерактивные данные с помощью deck.gl

deck.gl поддерживает KML в качестве прямого входного формата и автоматически обрабатывает взаимодействия с объектами, такие как клики, на основе данных, предоставленных в KML-файле.

  • Обработка KMLLoader : с помощью модуля @loaders.gl/kml геометрия и свойства преобразуются в формат, который deck.gl использует для запуска событий взаимодействия нативно.
  • Клики по функциям : При щелчке по функции deck.gl может перехватить событие и отобразить связанные метаданные (например <name> или <description> ).
  • Пример : В примере deckgl-kml-updated демонстрируется отрисовка KML-файлов в реальном времени, где при наведении курсора на маркеры землетрясений отображается подробная информация о событии.

2. Интерактивные данные с использованием geoxml3

geoxml3 анализирует KML-файл локально в браузере, извлекает информацию о стиле и генерирует стандартные объекты Google Maps API, сохраняющие свою интерактивность.

  • Извлечение собственных стилей : Библиотека извлекает элементы <Style> и <StyleMap> из KML-файла, чтобы применить их к сгенерированным маркерам, полилиниям и полигонам.
  • Обработчики кликов : По умолчанию geoxml3 предоставляет обработчики кликов для этих объектов. Вы также можете определить пользовательские функции обратного вызова ( createMarker , createOverlay ) во время создания экземпляра парсера, чтобы реализовать собственную логику выбора или обновления боковой панели.
  • Пример: В этом примере показано, как использовать geoxml3 для отображения KML-файлов с возможностью настройки, например, интерактивных маркеров в виде кругов, таких как нажатие на маркеры для отображения информации о землетрясениях.
  • Шаблон использования : 
var myParser = new geoXML3.parser({
  map: map,
  processStyles: true, // Automatically handle KML styles
  afterParse: function(doc) {
    // Code to run after the KML is fully parsed
  }
});
myParser.parse('interactive_data.kml');

KML-файл с изображениями

Для разработчиков, использующих KmlLayer для отображения изображений, таких как карты со спутниковыми данными, погодными условиями или историческими чертежами, в этом руководстве описаны пути миграции на GroundOverlays или сторонние парсеры.

Рекомендация по миграции: Maps JavaScript API GroundOverlay

Рекомендуемый способ миграции изображений — использование класса google.maps.GroundOverlay . Это позволяет размещать изображение на карте в определенных географических координатах непосредственно в коде.

1. Реализация

Вместо того чтобы полагаться на KML-файл для определения границ, вы указываете URL-адрес изображения и объект LatLngBounds , представляющий прямоугольник на карте.

  • Документация : Руководство по грунтовым покрытиям .
  • Подготовка изображения : Если ваше изображение имеет географическую привязку, но не в правильной проекции (EPSG:4326), вы можете использовать инструмент с открытым исходным кодом gdalwarp для деформации изображения для использования с API Maps JS. 
gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

Путь миграции: использование сторонних библиотек.

Если в вашем рабочем процессе требуется хранить данные в формате KML, для наложения изображений можно использовать сторонние библиотеки, такие как geoxml3 или deck.gl

Примечание: Данные сторонние решения не поддерживаются Google . Однако они были протестированы и должны работать в большинстве случаев.

1. geoxml3

geoxml3 — хороший вариант для локального анализа простых элементов GroundOverlay в браузере и преобразования их в объекты Google Maps API.

Пример использования: 

const geoXmlParser = new geoXML3.parser({
    map: map,
    afterParse: function(doc) {
        console.log("Parsing complete. Number of documents: " + doc.length);
        const bounds = doc[0].gbounds;
        if (bounds && !bounds.isEmpty()) {
           map.fitBounds(bounds);
        }
    },
    createOverlay: function(groundOverlayData) {
        // Extract bounds and URL from parsed KML data
        const imageUrl = groundOverlayData.icon.href;
        const imageBounds = {
            north: parseFloat(groundOverlayData.latLonBox.north),
            south: parseFloat(groundOverlayData.latLonBox.south),
            east: parseFloat(groundOverlayData.latLonBox.east),
            west: parseFloat(groundOverlayData.latLonBox.west)
        };

        // Create the Google Maps GroundOverlay
        const nativeOverlay = new google.maps.GroundOverlay(imageUrl, imageBounds);
        nativeOverlay.setMap(map);
    }
});
geoXmlParser.parse('your_file.kml');

2. deck.gl

Хотя стандартный GeoJsonLayer в deck.gl обрабатывает векторные данные, он также может поддерживать GroundOverlays посредством ручной реализации с использованием BitmapLayer .

Этот подход предполагает использование KMLLoader для анализа файла, а затем явное определение BitmapLayer с URL-адресом изображения и координатами, извлеченными из данных KML.

Сложный пример: пирамиды из плиток с использованием gdal2tiles

Для сложных KML-файлов, содержащих пирамиды из фрагментов изображений, миграция представляет собой более сложную задачу и требует извлечения данных изображений.

  • Инструмент gdal2tiles может извлекать данные из пирамиды KMZ и генерировать стандартный код JavaScript API для отображения тайлов. Обратите внимание, что для интеграции в существующую карту может потребоваться ручная доработка конечного результата. 
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

Для работы с KML-файлами, содержащими сетевые ссылки, требуется переход от автоматического получения данных из KmlLayer на стороне облака к более явным стратегиям управления данными.

Поддерживаемое решение: Стилизация на основе данных (DDS) для наборов данных

Поскольку наборы данных Google Maps Platform изначально не обрабатывают элементы <NetworkLink> , вам необходимо выбрать стратегию миграции, исходя из структуры ваших данных:

  • Стратегия А: Отдельные наборы данных (лучше всего подходит для слоев, управляемых пользователем). Загрузите каждый KML-файл, который ранее был сетевой ссылкой, как отдельный набор данных в консоль Google Cloud. Затем вы можете использовать JavaScript для динамической загрузки и отображения этих слоев по мере необходимости, вызывая метод map.getDatasetFeatureLayer(datasetId) и регулируя его видимость или стиль.
  • Стратегия B: Сглаженный KML-файл (оптимальный вариант для высокопроизводительного отображения). Объедините все данные из различных файлов, связанных по сети, в один всеобъемлющий KML-файл, прежде чем загружать его в качестве набора данных. Затем вы можете использовать динамическое оформление на основе атрибутов данных для фильтрации и отображения определенных подмножеств данных в режиме реального времени.

Обновление динамических данных: Чтобы имитировать поведение «автоматического обновления» сетевых ссылок, используйте API наборов данных для программной загрузки новой версии вашего набора данных всякий раз, когда изменяются исходные данные.

Решения с открытым исходным кодом: deck.gl и geoxml3

Ни deck.gl , ни geoxml3 не обеспечивают надежной поддержки для анализа и автоматической загрузки элементов KML <NetworkLink> .

deck.gl

deck.gl использует KMLLoader (построенный на основе togeojson ), который явно не поддерживает NetworkLinks .

  • Почему это не лучшее решение: Парсер разработан как синхронный, "простой" конвертер, который избегает собственных сетевых запросов для обеспечения надежности и простоты. Если ваше приложение использует KML-файлы, указывающие на несколько других URL-адресов, deck.gl не сможет автоматически их разрешить.

geoxml3

Хотя geoxml3 был разработан для анализа KML-файлов для API MapsJS, его поддержка сетевых ссылок является экспериментальной и не поддерживается .

  • Почему это не лучшее решение: Функциональность существует только в конкретной ветке "network_link", которая устарела и плохо протестирована. Использование этого решения для миграции данных в рабочую среду не рекомендуется, поскольку оно может не справиться со сложными структурами каналов связи или современными требованиями безопасности, такими как CORS.

Краткое изложение рекомендаций

Для надежной миграции разработчикам следует избегать использования сторонних парсеров для файлов с сетевыми ссылками и вместо этого перестроить логику получения данных, используя API наборов данных . Это гарантирует безопасное управление данными в рамках инфраструктуры платформы Google Maps, а не зависимость от неподдерживаемых клиентских парсеров.

Используйте KML для отображения экранных наложений.

Разработчикам, переходящим с KmlLayer на современные альтернативы, такие как стилизация на основе данных (DDS), важно отметить, что наложения на экран не поддерживаются в наборах данных . Для достижения того же эффекта отображения фиксированных изображений, логотипов или легенд поверх карты необходимо создать пользовательские элементы управления с помощью JavaScript API карт.

1. Что искать в вашем KML-файле

Для создания аналогичного пользовательского элемента управления изучите элемент <ScreenOverlay> в вашем KML-файле на наличие следующих ключевых атрибутов:

  • <Icon>&lt;href> : URL изображения, которое вы хотите отобразить.
  • <screenXY> : Этот параметр определяет положение наложения на экране.
    • x=0, y=1 (дробные значения) соответствует верхнему левому углу .
    • x=1, y=1 соответствует верхнему правому углу .
    • x=0, y=0 соответствует нижнему левому углу .
    • x=1, y=0 соответствует нижнему правому углу .
  • <size> : Определяет ширину и высоту наложения.
  • <rotation> : Указывает, следует ли повернуть изображение.

2. Реализация: Создание пользовательского элемента управления

Пользовательский элемент управления — это, по сути, стандартный HTML-элемент (например, <div> или <img> ), который вы "добавляете" в одну из предопределенных позиций карты.

Сопоставление позиций KML с ControlPosition

API JavaScript для работы с картами использует перечисление ControlPosition для привязки элементов управления. Используйте таблицу ниже, чтобы сопоставить ваш KML-файл <screenXY> с соответствующей константой JS API:

Позиция KML ( screenXY ) JS API ControlPosition
Вверху слева ( x:0, y:1 ) TOP_LEFT (устаревшая версия) или BLOCK_START_INLINE_START (логическая версия)
Вверху справа ( x:1, y:1 ) TOP_RIGHT или BLOCK_START_INLINE_END
Нижний левый угол ( x:0, y:0 ) BOTTOM_LEFT или BLOCK_END_INLINE_START
Нижний правый угол ( x:1, y:0 ) BOTTOM_RIGHT или BLOCK_END_INLINE_END

3. Пример миграции: наложение фиксированного логотипа.

В следующем примере имитируется логотип KML ScreenOverlay, расположенный в правом верхнем углу карты.

CSS-стили

Используйте CSS для определения размера и внешнего вида вашего "наложения". 

#logo-control {
  padding: 10px;
  background-color: rgba(255, 255, 255, 0.8);
  margin: 10px;
  border-radius: 2px;
  box-shadow: 0 1px 4px rgba(0,0,0,0.3);
}

#logo-control img {
  width: 150px; /* Equivalent to KML <size> */
  display: block;
}

Реализация на JavaScript

Добавьте элемент в массив map.controls . 

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 12,
    center: { lat: 41.85, lng: -87.65 },
  });

  // 1. Create the container for the overlay
  const logoControlDiv = document.createElement("div");
  logoControlDiv.id = "logo-control";

  // 2. Create the image (KML <Icon>)
  const logoImage = document.createElement("img");
  logoImage.src = "https://example.com/logo.png";
  logoImage.alt = "Company Logo";

  logoControlDiv.appendChild(logoImage);

  // 3. Position the control (KML <screenXY>)
  // In this case, we use TOP_RIGHT
  map.controls[google.maps.ControlPosition.TOP_RIGHT].push(logoControlDiv);
}

Дополнительная информация