Caminhos de migração do KmlLayer

Introdução

O objetivo deste guia é abordar os usos mais comuns do KmlLayer e fornecer caminhos de migração correspondentes para implementações alternativas. Estas informações são destinadas a desenvolvedores que precisam fazer a transição do uso de KmlLayer devido à descontinuação programada. A última versão compatível com KmlLayer é a 3.65, que será desativada em maio de 2027.

Seu caminho de migração depende de como você está usando o KmlLayer:

Arquivo KML para estilizar informações de limite/borda/área de interesse

Para desenvolvedores que usam KmlLayer para mostrar ou estilizar limites administrativos, como destacar um país, estado ou região administrativa específica, a Plataforma Google Maps recomenda migrar para o estilo baseado em dados (DDS) para limites.

Recomendação de migração: estilo baseado em dados para limites

A estilização baseada em dados para limites oferece acesso direto aos polígonos de limites administrativos do Google, permitindo que você aplique estilos personalizados (preenchimento e traço) a essas regiões sem precisar hospedar ou gerenciar arquivos KML externos.

Disponível FeatureType

As áreas administrativas são categorizadas por função e organizadas por níveis. Os seguintes tipos de recursos são compatíveis com a estilização:

  • COUNTRY: a entidade política nacional.
  • ADMINISTRATIVE_AREA_LEVEL_1: uma entidade civil de primeira ordem abaixo do nível de país (por exemplo, estados nos EUA).
  • ADMINISTRATIVE_AREA_LEVEL_2: uma entidade civil de segunda ordem abaixo do nível de país (por exemplo, condados nos EUA).
  • LOCALITY: uma cidade ou município incorporado.
  • POSTAL_CODE: códigos postais usados para correspondência.
  • SCHOOL_DISTRICT: distritos escolares unificados, de ensino fundamental ou médio.

Consulte a cobertura de limites para saber em quais regiões esses tipos de recursos estão disponíveis.

Como destacar uma área

Para estilizar uma região específica, é necessário segmentá-la pelo ID de lugar.

Restringir o deslocamento a uma área

Para impedir que os usuários naveguem fora da caixa delimitadora da área destacada, use a opção restriction em MapOptions.

O objeto restriction define um latLngBounds que limita a área visível do mapa. Consulte a documentação para mais detalhes sobre como a restrição funciona.

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

Implementação da migração de resumo

Confira um exemplo completo de como usar o estilo baseado em dados para limites e uma restrição de região para centralizar o mapa em uma área específica.

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

Arquivo KML com dados vetoriais (pontos/polilinhas/limites/polígonos)

Recomendação de migração: estilo baseado em dados para conjuntos de dados

O Google recomenda o caminho abaixo para mostrar dados geográficos disponíveis publicamente e ter mais controle sobre o estilo e o desempenho.

Com o estilo baseado em dados para conjuntos de dados, você faz upload dos seus dados geoespaciais (KML, GeoJSON ou CSV), aplica um estilo personalizado com base nos atributos de dados e mostra recursos em mapas de vetor.

1. Configuração e upload

Ao contrário do KmlLayer, que busca um URL no tempo de execução, o DDS exige que você hospede os dados como um conjunto de dados no console do Google Cloud.

2. Definir a janela de visualização para os dados

Por padrão, o KmlLayer faz o movimento panorâmico e o zoom automaticamente para o local dos dados. Com o DDS para conjuntos de dados, esse comportamento não é automático e precisa ser implementado manualmente.

  • Restrições codificadas: se a área de dados for estática, use a opção restriction em MapOptions para bloquear a janela de visualização em limites específicos.
  • Zoom dinâmico: para definir dinamicamente a janela de visualização, use map.fitBounds() com a caixa delimitadora do conjunto de dados.

3. Estilo com base em atributos de recursos

Os arquivos KML geralmente contêm informações de estilo (como cores) que o DDS não aplica automaticamente. Você precisa criar uma função de estilo do lado do cliente que leia atributos dos elementos do conjunto de dados para aplicar cores e opacidade. Consulte a documentação para desenvolvedores sobre como estilizar seus dados para mais detalhes.

Exemplo: função de estilização usando atributos

O exemplo a seguir demonstra como criar uma função de estilo que lê atributos background_color e opacity diretamente do conjunto de dados enviado:

/**
 * 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,
    };
  };
}

Para mais detalhes sobre a implementação de interações e estilos, consulte a Visão geral do estilo baseado em dados para conjuntos de dados e a API Datasets para dados dinâmicos.

Recomendação de migração: renderização do lado do cliente com GeoJSON

Para desenvolvedores que estão migrando de KmlLayer para a renderização do lado do cliente com GeoJSON, a Plataforma Google Maps recomenda um caminho de migração que envolve a conversão do formato de dados e o uso da camada de dados para renderizar e estilizar recursos diretamente no navegador.

A renderização do lado do cliente usando a camada de dados oferece uma maneira altamente flexível de mostrar dados geográficos. Ao contrário de KmlLayer, que é renderizado nos servidores do Google, a camada de dados permite interagir com recursos como objetos JavaScript padrão. No entanto, para conjuntos de dados grandes, talvez seja melhor usar o processamento e a renderização de dados do lado do servidor, como o estilo baseado em dados para conjuntos de dados.

1. Converter KML em GeoJSON

A primeira etapa é converter seus arquivos KML em GeoJSON. Isso pode ser feito usando várias ferramentas de código aberto conhecidas:

  • ogr2ogr: parte do pacote GDAL, esse utilitário de linha de comando avançado pode converter entre vários formatos de vetor.
ogr2ogr -f GeoJSON output.json input.kml
  • togeojson: Uma ferramenta pequena e bem testada projetada especificamente para converter KML e GPX em GeoJSON.
togeojson input.kml > output.json

2. Definir a janela de visualização para os dados

Embora o KmlLayer faça o movimento panorâmico e o zoom automaticamente para o local dos dados, a camada de dados não faz isso. Para definir a janela de visualização de acordo com seus dados GeoJSON, calcule manualmente a caixa delimitadora e chame map.fitBounds().

3. Estilo com base em atributos de recursos

Na camada de dados, é possível definir uma função style que lê atributos (propriedades) diretamente de cada elemento GeoJSON para determinar a aparência dele.

Exemplo: função de estilização e ajuste da janela de visualização

O exemplo a seguir demonstra como carregar dados GeoJSON, calcular os limites para definir a janela de visualização e estilizar elementos com base nos atributos deles:

/**
 * 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
    };
  });
}

Para mais informações sobre como usar a camada de dados, consulte a documentação Importar GeoJSON para o Maps.

Caminho de migração: renderização do lado do cliente com bibliotecas de terceiros

Para desenvolvedores que buscam outras alternativas ao KmlLayer, há várias bibliotecas mantidas pela comunidade que renderizam dados KML na API JavaScript da Plataforma Google Maps.

1. deck.gl

O deck.gl é um framework de visualização de alta performance com tecnologia WebGL. Ele pode ser usado como uma substituição quase direta para a renderização de KML usando GoogleMapsOverlay e GeoJsonLayer.

  • Requisito de tela:para usar deck.gl de maneira eficaz, converta seu mapa para usar o tipo de mapa vetorial (que é renderizado em um elemento de tela) com os recursos de renderização WebGL.
  • Suporte a KML:a análise de geometria é processada por @loaders.gl/kml, que converte KML em GeoJSON. Alguns recursos do KML, como estilos complexos, ícones e NetworkLinks, podem exigir uma implementação manual adicional.
  • Documentação:Documentação do deck.gl | Carregador KML do loaders.gl.
  • Exemplos:
    • O exemplo deckgl-kml-updated no repositório do Google Maps no GitHub demonstra como usar o deck.gl para renderizar dados KML atualizados em tempo real.
    • O exemplo deckgl-kml mostra como usar o deck.gl para renderizar dados KML.

2. geoxml3

O geoxml3 é um processador KML projetado especificamente para a API Google Maps JavaScript v3. Ele analisa o KML localmente no navegador e renderiza os dados como objetos padrão da API Google Maps, como marcadores, polilinhas e polígonos.

  • Suporte a mapas padrão:ao contrário das soluções baseadas em WebGL, o geoxml3 funciona em mapas padrão da API Google Maps JavaScript v3 sem exigir um modo de renderização específico.
  • Ressalvas:
    • Suporte limitado a KMZ:a biblioteca não oferece suporte total a arquivos KMZ de forma nativa. Para descompactar arquivos KMZ, geralmente é necessário integrar com outros scripts de terceiros, como o ZipFile.complete.js.
    • Elementos não compatíveis:recursos como geometrias 3D, rótulos complexos e alguns elementos KML mais recentes não são compatíveis.
  • Documentação:repositório do geoxml3 no GitHub.

Arquivo KML com elementos interativos

Recomendação de migração: estilo baseado em dados para conjuntos de dados

Para desenvolvedores que estão migrando de KmlLayer para Estilo com base em dados (DDS) para conjuntos de dados, este guia explica como fazer a transição de interações automáticas do KML para interações personalizadas de alto desempenho, como cliques do mouse e passar o cursor.

Configuração inicial

Antes de implementar interações, siga as etapas de configuração do guia Migração de KML: dados vetoriais:

  • ID do mapa:configure um ID para o tipo Mapa vetorial.
  • Fazer upload:faça upload dos seus dados KML para o console do Google Cloud e receba um ID do conjunto de dados.
  • Acesso à camada:use map.getDatasetFeatureLayer(datasetId) para acessar a camada interativa.

1. Como processar eventos de interação

No KmlLayer, os cliques em recursos são processados automaticamente pela API para abrir uma janela de informações. Com o DDS para conjuntos de dados, é necessário registrar manualmente listeners para eventos de mouse na camada de conjunto de dados.

  • click:acionado quando um usuário clica em um recurso.
  • mousemove:acionado quando o cursor se move sobre um recurso, útil para efeitos de passar o cursor.

2. Estilo dinâmico (efeito de passar o cursor)

Como os estilos DDS são aplicados globalmente à camada, mantenha uma variável de estado para rastrear com qual recurso está sendo feita a interação e reaplique o estilo.

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. Como mostrar HTML do atributo description

Em KML, a tag <description> geralmente contém HTML para a janela de informações padrão. Quando esses dados são importados como um conjunto de dados, o description se torna um atributo de recurso. Para renderizar, transmita a string diretamente para um google.maps.InfoWindow padrão.

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. InfoWindow personalizada com ExtendedData

Se o KML usar <ExtendedData> para armazenar pares de nome/valor personalizados, eles serão mapeados para datasetAttributes. Você pode iterar esses atributos para criar uma exibição HTML personalizada.

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

Para técnicas de visualização mais avançadas, consulte a documentação para desenvolvedores sobre como estilizar recursos de dados.

Recomendação de migração: renderização do lado do cliente com GeoJSON

Para desenvolvedores que estão migrando do KmlLayer para a renderização do lado do cliente com GeoJSON e a camada de dados, este guia explica como fazer a transição das interações automáticas do KML para interações personalizadas e orientadas por eventos e estilização dinâmica.

Configuração inicial

Antes de implementar interações, é necessário converter os dados KML em GeoJSON e carregá-los na camada de dados. Consulte o guia Recomendação de migração: renderização do lado do cliente com GeoJSON para detalhes sobre o uso de ferramentas como ogr2ogr ou togeojson e a inicialização do mapa com map.data.loadGeoJson().

1. Interações automáticas x manuais

Uma diferença fundamental entre essas camadas é como elas processam a entrada do usuário:

  • KmlLayer: processa automaticamente os cliques em recursos e mostra um InfoWindow com os dados e do KML.
  • Camada de dados: não mostra objetos InfoWindow automaticamente. É necessário adicionar listeners de eventos manualmente para capturar interações do usuário e escrever código para mostrar dados.

2. Como processar eventos de interação

Para tornar os recursos do GeoJSON interativos, use o método addListener() no objeto map.data. Os eventos comuns incluem:

  • click: usado para acionar janelas de informações ou lógica de seleção.
  • mouseover / mouseout: usado para efeitos de passar o cursor e destaque.

3. Mostrar descrições em HTML em uma janela de informações

Quando o KML é convertido em GeoJSON, a tag <description> (que geralmente contém HTML) é mapeada para uma propriedade chamada description. Você pode usar feature.getProperty('description') para extrair essa string e renderizá-la em um google.maps.InfoWindow padrão.

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. Janelas de informações personalizadas e ExtendedData

Se o KML original usou <ExtendedData>, esses pares de nome-valor serão convertidos em propriedades GeoJSON. Como a camada de dados não tem uma interface padrão para isso, é necessário implementar uma InfoWindow personalizada para iterar e mostrar os dados.

É possível acessar esses atributos usando event.feature.getProperty('attribute_name') e criar uma string HTML personalizada ou um elemento DOM para transmitir ao método infoWindow.setContent().

5. Estilo dinâmico (efeitos de passar o cursor)

A camada de dados permite atualizar estilos de recursos de maneira programática em resposta a eventos. Use overrideStyle() para mudar temporariamente a aparência de um recurso (por exemplo, ao passar o cursor) e revertStyle() para retornar ao estilo global.

// 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();
});

Para mais detalhes sobre a implementação, consulte a documentação sobre Data Layer: tratamento de eventos e Data Layer: estilização dinâmica.

Caminho de migração: renderização do lado do cliente com bibliotecas de terceiros

Para desenvolvedores que migram do KmlLayer para soluções de terceiros, este guia se concentra no processamento de dados interativos, como cliques do mouse e eventos dinâmicos, usando deck.gl e geoxml3.

Configuração inicial

Antes de implementar interações, siga as etapas de configuração do guia Caminho de migração: renderização do lado do cliente com bibliotecas de terceiros. Isso inclui:

  • deck.gl: converta seu mapa para usar o tipo de mapa vetorial (requisito de tela).
  • geoxml3: veicule os scripts da biblioteca do seu próprio host e gerencie o compartilhamento de recursos entre origens (CORS).

1. Dados interativos com deck.gl

O deck.gl aceita KML como um formato de entrada direta e processa automaticamente interações de recursos, como cliques, com base nos dados fornecidos no arquivo KML.

  • Processamento do KMLLoader: usando o módulo @loaders.gl/kml, a geometria e as propriedades são analisadas em um formato que o deck.gl usa para acionar eventos de interação de forma nativa.
  • Cliques em recursos: quando um recurso é clicado, o deck.gl pode capturar o evento e mostrar os metadados associados (como <name> ou <description>).
  • Exemplo: o exemplo deckgl-kml-updated demonstra a renderização de KML em tempo real. Ao passar o cursor sobre os marcadores de terremoto, informações detalhadas sobre o evento são exibidas.

2. Dados interativos com geoxml3

O geoxml3 analisa o KML localmente no navegador, extrai informações de estilo e gera objetos padrão da API Google Maps que mantêm a interatividade.

  • Extração de estilo nativo: a biblioteca extrai elementos <Style> e <StyleMap> do KML para aplicá-los aos marcadores, polilinhas e polígonos gerados.
  • Manipuladores de cliques: por padrão, o geoxml3 fornece manipuladores de cliques para esses objetos. Também é possível definir funções de callback personalizadas (createMarker, createOverlay) durante a instanciação do analisador para implementar sua própria lógica de seleção ou atualizações da barra lateral.
  • Exemplo:este exemplo mostra como usar o geoxml3 para renderizar KML, com personalização como marcadores de círculo com interação, como clicar nos marcadores para mostrar informações sobre terremotos.
  • Padrão de uso:
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');

Arquivo KML com imagens

Para desenvolvedores que usam KmlLayer para mostrar imagens, como mapas com dados derivados de satélite, padrões climáticos ou plantas históricas, este guia descreve os caminhos de migração para GroundOverlays ou analisadores de terceiros.

Recomendação de migração: GroundOverlay da API Maps JavaScript

O caminho recomendado para migrar imagens é usar a classe google.maps.GroundOverlay. Isso permite colocar uma imagem no mapa em coordenadas geográficas específicas diretamente no seu código.

1. Implementação

Em vez de usar um arquivo KML para definir os limites, especifique o URL da imagem e um objeto LatLngBounds que representa o retângulo no mapa.

  • Documentação: Guia de sobreposições de solo.
  • Preparação da imagem: se a imagem tiver georreferência, mas não estiver na projeção correta (EPSG:4326), use a ferramenta de código aberto gdalwarp para distorcer a imagem e usar com a API JavaScript do Maps.
gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

Caminho de migração: como usar bibliotecas de terceiros

Se o fluxo de trabalho exigir que você mantenha os dados no formato KML, bibliotecas de terceiros, como geoxml3 ou deck.gl, poderão ser usadas para renderizar sobreposições de imagens.

Exoneração de responsabilidade:essas soluções de terceiros não são compatíveis com o Google. No entanto, eles foram testados e devem funcionar na maioria dos casos de uso.

1. geoxml3

geoxml3 é uma boa opção para analisar elementos GroundOverlay simples localmente no navegador e convertê-los em objetos da API Google Maps.

Exemplo de uso:

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

Embora o GeoJsonLayer padrão do deck.gl processe dados de vetor, ele também pode oferecer suporte a GroundOverlays por uma implementação manual usando o BitmapLayer.

Essa abordagem envolve o uso de KMLLoader para analisar o arquivo e definir explicitamente um BitmapLayer com o URL da imagem e as coordenadas extraídas dos dados KML.

Caso avançado: pirâmides de blocos usando gdal2tiles

Para arquivos KML complexos que contêm pirâmides de blocos de imagens, a migração é mais difícil e exige a extração dos dados de imagens.

  • Ferramenta: o gdal2tiles pode extrair dados de uma pirâmide KMZ e gerar um código padrão da API Maps JavaScript para mostrar os blocos. O resultado final pode exigir modificação manual para ser incorporado a um mapa existente.
gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

O processamento de arquivos KML com links de rede exige uma mudança da busca automática do lado da nuvem de KmlLayer para estratégias de gerenciamento de dados mais explícitas.

Solução compatível: estilo baseado em dados (DDS) para conjuntos de dados

Como os conjuntos de dados da Plataforma Google Maps não analisam elementos <NetworkLink> de forma nativa, escolha uma estratégia de migração com base na estrutura de dados:

  • Estratégia A: conjuntos de dados distintos (ideal para camadas controladas pelo usuário). Faça upload de cada arquivo KML que era um link de rede como um conjunto de dados individual no Console do Google Cloud. Em seguida, use JavaScript para carregar e mostrar essas camadas de forma dinâmica quando necessário chamando map.getDatasetFeatureLayer(datasetId) e ajustando a visibilidade ou o estilo.
  • Estratégia B: arquivo KML simplificado (ideal para exibição de alta performance) Combine todos os recursos dos seus vários arquivos vinculados à rede em um único arquivo KML abrangente antes de fazer upload como um conjunto de dados. Em seguida, use o estilo dinâmico com base nos atributos de recursos para filtrar e mostrar subconjuntos de dados específicos na hora.

Atualização de dados dinâmicos:para imitar o comportamento de "atualização automática" dos links de rede, use a API Datasets para fazer upload programático de uma nova versão do conjunto de dados sempre que os dados de origem mudarem.

Soluções de código aberto: deck.gl e geoxml3

Nem deck.gl nem geoxml3 oferecem suporte robusto para análise e busca automática de elementos <NetworkLink> do KML.

deck.gl

O deck.gl usa o KMLLoader (criado no togeojson), que não oferece suporte a NetworkLinks.

  • Por que não é uma boa solução:o analisador foi projetado para ser um conversor síncrono e "sem complicações" que evita fazer solicitações de rede próprias para garantir confiabilidade e simplicidade. Se o aplicativo depender de arquivos KML que apontam para vários outros URLs, o deck.gl não os resolverá automaticamente.

geoxml3

Embora o geoxml3 tenha sido desenvolvido para analisar KML para a API Maps JavaScript, o suporte a links de rede é experimental e não tem manutenção.

  • Por que não é uma boa solução:a funcionalidade existe apenas em uma ramificação "network_link" específica, que é antiga e não foi bem testada. Não é recomendável usar isso para migração de dados de produção, já que pode não processar estruturas de links complexas ou requisitos de segurança modernos, como CORS.

Recomendação de resumo

Para uma migração confiável, os desenvolvedores precisam evitar analisadores de terceiros para arquivos com links de rede e reconstruir a lógica de busca de dados usando a API Datasets. Isso garante que seus dados sejam gerenciados com segurança na infraestrutura da Plataforma Google Maps, em vez de depender de analisadores do lado do cliente sem manutenção.

Usar KML para mostrar sobreposições de tela

Para desenvolvedores que estão migrando do KmlLayer para alternativas modernas, como o estilo baseado em dados (DDS), é importante observar que as sobreposições de tela são indisponíveis em conjuntos de dados. Para conseguir o mesmo efeito de mostrar imagens, logotipos ou legendas fixas na parte de cima do mapa, crie controles personalizados usando a API Maps JavaScript.

1. O que procurar no seu arquivo KML

Para criar um controle personalizado equivalente, examine o elemento <ScreenOverlay> no arquivo KML para os seguintes atributos principais:

  • <Icon>&lt;href>: o URL da imagem que você quer mostrar.
  • <screenXY>: define onde a sobreposição é posicionada na tela.
    • x=0, y=1 (frações) corresponde a Superior Esquerda.
    • x=1, y=1 corresponde ao Canto superior direito.
    • x=0, y=0 corresponde ao Canto inferior esquerdo.
    • x=1, y=0 corresponde a Canto inferior direito.
  • <size>: define a largura e a altura da sobreposição.
  • <rotation>: indica se a imagem deve ser girada.

2. Implementação: como criar um controle personalizado

Um controle personalizado é essencialmente um elemento HTML padrão (como um <div> ou <img>) que você "envia" para uma das posições predefinidas do mapa.

Mapear posições KML para ControlPosition

A API Maps JavaScript usa a enumeração ControlPosition para ancorar controles. Use a tabela abaixo para mapear seu <screenXY> KML à constante da API JS apropriada:

Posição do KML (screenXY) API JS ControlPosition
Canto superior esquerdo (x:0, y:1) TOP_LEFT (legado) ou BLOCK_START_INLINE_START (lógico)
Canto superior direito (x:1, y:1) TOP_RIGHT ou BLOCK_START_INLINE_END
Canto inferior esquerdo (x:0, y:0) BOTTOM_LEFT ou BLOCK_END_INLINE_START
Canto inferior direito (x:1, y:0) BOTTOM_RIGHT ou BLOCK_END_INLINE_END

3. Exemplo de migração: sobreposição de logotipo fixa

O exemplo a seguir imita um logotipo KML ScreenOverlay posicionado no canto superior direito do mapa.

Estilo de CSS

Use CSS para definir o tamanho e a aparência da sua "sobreposição".

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

Implementação em JavaScript

Adicione o elemento à matriz 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);
}

Mais informações