KmlLayer 迁移途径

简介

本指南旨在介绍 KmlLayer 的最常见用途，并提供相应的迁移途径，以便改用其他实现方式。本文面向的是需要因 KmlLayer 即将弃用而改用其他替代方案的开发者。支持 KmlLayer 的最后一个版本是 3.65，将于 2027 年 5 月停用。

您的迁移路径取决于您使用 KmlLayer 的方式：

用于设置边界/边框/感兴趣区域信息样式的 KML 文件：使用 数据驱动型样式 (DDS) for boundaries 来设置使用 Google 边界数据的行政区域。
包含矢量数据（点/折线/边界/多边形）的 KML 文件：使用 DDS for Datasets、GeoJSON 或 第三方库（例如 deck.gl 或 geoxml3）。
包含互动元素的 KML 文件：实现手动事件监听器和自定义信息窗口，以实现功能互动。
包含影像的 KML 文件：使用 GroundOverlays 或第三方解析器进行影像叠加。
包含网络链接的 KML 文件：将每个 KML 作为单独的数据集上传，或合并 KML。如果显示动态数据，请使用 Datasets API 刷新数据集。
使用 KML 显示屏幕叠加层：使用自定义控件替换固定的界面元素，例如徽标、图例或导航辅助元素。

用于设置边界/边框/感兴趣区域信息样式的 KML 文件

对于使用 KmlLayer 显示或设置行政边界样式（例如突出显示特定国家/地区、州或地区）的开发者，Google Maps Platform 建议迁移到边界的数据驱动型样式 (DDS)。

迁移建议：边界的数据驱动型样式

边界的数据驱动型样式可让您直接访问 Google 的行政边界多边形，从而为这些区域应用自定义样式（填充和描边），而无需托管或管理外部 KML 文件。

可用的 FeatureType

行政区按职能分类，并按级别排列。以下地图项类型支持样式设置：

COUNTRY：国家政治实体。
ADMINISTRATIVE_AREA_LEVEL_1：国家/地区级别以下的一级行政实体（例如美国各州）。
ADMINISTRATIVE_AREA_LEVEL_2：国家/地区级别以下的二级行政实体（例如美国境内的县）。
LOCALITY：有建制的城市或城镇。
POSTAL_CODE：用于邮件的邮政编码。
SCHOOL_DISTRICT：统一学区、小学学区或中学学区。

如需了解在哪些地区可以使用这些地图项类型，请参阅边界覆盖范围。

如何突出显示某个区域

如需设置特定区域的样式，您必须通过其地点 ID 来定位该区域。

设置：您必须使用为 JavaScript 矢量地图类型配置的地图 ID，并在 Google Cloud 控制台中启用地图项图层。
实现：使用设置边界多边形的样式示例代码。

将平移操作限定在指定区域

如需防止用户在突出显示区域的边界框之外进行导航，您可以使用 MapOptions 中的 restriction 选项。

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 不同，DDS 要求您在 Google Cloud 控制台中将数据托管为数据集。

创建地图 ID：使用配置为矢量地图类型的地图 ID。
上传数据集：将 KML 文件上传到 Google Cloud 控制台，以生成唯一的数据集 ID。如需了解详情，请参阅有关如何管理地图数据集的完整文档。
显示数据集：创建数据集 ID 后，您需要将数据集与地图样式和地图 ID 相关联。然后，您将使用数据集 ID 在地图上实际显示数据。如需了解所有详细信息，请参阅有关如何向地图添加数据集的完整文档。
如果您决定以 KML 格式导入数据，请注意数据集的 KML 要求。

2. 将视口设置为数据

KmlLayer 默认情况下会自动平移和缩放至数据位置。对于数据集的 DDS，此行为不是自动的，必须手动实现。

硬编码限制：如果数据区域是静态的，请使用 MapOptions 中的 restriction 选项将视口锁定到特定边界。
动态缩放：如需动态设置视口，您可以将 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 Platform 建议采用一种迁移途径，即转换数据格式并使用数据层直接在浏览器中渲染和设置要素样式。

使用数据层的客户端渲染功能可灵活地显示地理数据。与在 Google 服务器上呈现的 KmlLayer 不同，数据层可让您以标准 JavaScript 对象的形式与功能互动。不过请注意，对于大型数据集，您可能更倾向于对数据进行服务器端处理和渲染，例如使用数据集的数据驱动样式设置。

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 会自动平移和缩放到数据位置，但数据图层不会。如需设置视口以适应 GeoJSON 数据，您必须手动计算边界框并调用 map.fitBounds()。

3. 基于地图项属性设置样式

在数据层中，您可以定义一个 style 函数，该函数可直接从每个 GeoJSON 地图项读取属性（property），以确定其外观。

示例：样式设置功能和视口调整

以下示例演示了如何加载 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 其他替代方案的开发者，有多个社区维护的库可在 Google Maps Platform JavaScript API 上渲染 KML 数据。

1. deck.gl

deck.gl 是一个由 WebGL 提供支持的高性能可视化框架。通过其 GoogleMapsOverlay 和 GeoJsonLayer，它可以作为 KML 渲染的近乎直接替代方案。

Canvas 要求：如需有效使用 deck.gl，您必须将地图转换为使用矢量地图类型（该类型会渲染到 canvas 元素）及其 WebGL 渲染功能。
KML 支持：几何图形解析由 @loaders.gl/kml 处理，该库可将 KML 转换为 GeoJSON。请注意，某些 KML 功能（例如复杂样式、图标和 NetworkLink）可能需要额外的手动实现。
文档： deck.gl 文档 | loaders.gl KML 加载器。
示例：
- Google 地图 GitHub 代码库中的 deckgl-kml-updated 示例演示了如何使用 deck.gl 渲染实时更新的 KML 数据。
- deckgl-kml 示例演示了如何使用 deck.gl 渲染 KML 数据。

2. geoxml3

geoxml3 是一款专门为 Google 地图 JavaScript API v3 设计的 KML 处理器。它会在浏览器中本地解析 KML，并将数据渲染为标准 Google 地图 API 对象，例如标记、多段线和多边形。

标准地图支持：与基于 WebGL 的解决方案不同，geoxml3 可在标准 Google 地图 JS API v3 地图上运行，而无需特定的渲染模式。
注意事项：
- 有限的 KMZ 支持：该库不支持 KMZ 文件。解压缩 KMZ 归档文件通常需要与 ZipFile.complete.js 等其他第三方脚本集成。
- 不支持的元素：不支持 3D 几何图形、复杂标签和某些较新的 KML 元素等功能。
文档： geoxml3 GitHub 代码库。

包含互动元素的 KML 文件

迁移建议：数据集的数据驱动型样式

对于从 KmlLayer 迁移到数据集的数据驱动型样式 (DDS) 的开发者，本指南介绍了如何从自动 KML 互动过渡到自定义的高性能互动（例如鼠标点击和悬停）。

初始设置

在实现互动之前，请确保您已按照 KML 迁移：矢量数据指南中的设置步骤进行操作：

地图 ID：为矢量地图类型配置地图 ID。
上传：将 KML 数据上传到 Google Cloud 控制台，以获取数据集 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. 显示来自 `description` 属性的 HTML

在 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：自动处理地图项点击，并显示包含 KML 和数据的 InfoWindow。
数据层：不会自动显示 InfoWindow 对象。您必须手动添加事件监听器来捕获用户互动，并编写代码来显示数据。

2. 处理互动事件

如需使 GeoJSON 地图项具有互动性，请对 map.data 对象使用 addListener() 方法。常见活动包括：

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 属性。由于数据层没有针对这些内容的默认界面，因此您必须实现自定义 InfoWindow 以遍历并显示它们。

您可以使用 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：将地图转换为使用矢量地图类型（需要 canvas）。
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 地图 API 对象。

原生样式提取：该库会从 KML 中提取 <Style> 和 <StyleMap> 元素，以将其应用于生成的标记、多段线和多边形。
点击处理程序：默认情况下，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 文件来定义边界，而是指定图片网址和表示地图上矩形的 LatLngBounds 对象。

文档：地面叠加层指南。
图片准备：如果您的图片已进行地理配准，但投影不正确 (EPSG:4326)，您可以使用开源工具 gdalwarp 对图片进行变形，以便与 Maps JavaScript API 搭配使用。

gdalwarp -t_srs EPSG:4326 image.jp2 image.jpg

迁移途径：使用第三方库

如果您的工作流程要求您以 KML 格式保留数据，则可以使用 geoxml3 或 deck.gl 等第三方库来渲染影像叠加层。

免责声明：Google 不支持这些第三方解决方案。不过，这些功能已经过测试，应该适用于大多数用例。

1. geoxml3

geoxml3 非常适合在浏览器中本地解析简单的 GroundOverlay 元素，并将其转换为 Google 地图 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

虽然 deck.gl 的标准 GeoJsonLayer 可以处理矢量数据，但它也可以通过使用 BitmapLayer 的手动实现来支持 GroundOverlays。

此方法涉及利用 KMLLoader 解析文件，然后使用从 KML 数据中提取的图片网址和坐标显式定义 BitmapLayer。

要求：使用 deck.gl 需要矢量地图类型。
文档： deck.gl 位图层

高级示例：使用 gdal2tiles 创建图块金字塔

对于包含影像图块金字塔的复杂 KML 文件，迁移难度更大，需要提取影像数据。

工具：gdal2tiles 可以从 KMZ 金字塔中提取数据，并生成标准的 Maps JavaScript API 代码来显示图块。请注意，最终结果可能需要手动修改才能纳入现有地图中。

gdal2tiles -z 10- -n -u https://yourhost.com/tiles/ -w google input.kmz

包含网络链接的 KML 文件

处理包含网络链接的 KML 文件需要从自动云端提取 KmlLayer 转向更明确的数据管理策略。

支持的解决方案：数据集的数据驱动型样式 (DDS)

由于 Google Maps Platform 数据集无法原生解析 <NetworkLink> 元素，因此您必须根据数据结构选择迁移策略：

策略 A：不同的数据集（最适合用户控制的图层）在 Google Cloud 控制台中，将之前作为网络链接的每个 KML 文件上传为各自独立的数据集。然后，您可以使用 JavaScript 在需要时通过调用 map.getDatasetFeatureLayer(datasetId) 并调整其可见性或样式来动态加载和显示这些图层。
策略 B：扁平化 KML 文件（最适合高性能显示） 将各种网络链接文件中的所有要素合并到一个全面的 KML 文件中，然后再将其作为数据集上传。然后，您可以根据要素属性使用动态样式来过滤和显示特定的数据子集。

更新动态数据：如需模拟网络链接的“自动刷新”行为，请使用 Datasets API 在源数据发生更改时以编程方式上传数据集的新版本。

开源解决方案：deck.gl 和 geoxml3

deck.gl 和 geoxml3 均未提供对解析和自动提取 KML <NetworkLink> 元素的强大支持。

deck.gl

deck.gl 使用 KMLLoader（基于 togeojson 构建），明确不支持 NetworkLink。

为什么这不是一个好的解决方案：解析器旨在成为一个同步的“无忧”转换器，避免自行发出网络请求，以确保可靠性和简单性。如果您的应用依赖于指向多个其他网址的 KML 文件，deck.gl 将不会自动解析这些网址。

geoxml3

虽然 geoxml3 是为 Maps JS API 开发的，用于解析 KML，但它对网络链接的支持仍处于实验阶段，且未维护。

为什么说这不是一个好的解决方案：该功能仅存在于一个旧的且未经充分测试的特定“network_link”分支中。不建议使用此方法迁移生产数据，因为它可能无法处理复杂的链接结构或 CORS 等现代安全要求。

总结建议

为了实现可靠的迁移，开发者应避免使用第三方解析器来解析包含网络链接的文件，而应使用 Datasets API 重建数据提取逻辑。这样可以确保在 Google Maps Platform 基础架构中安全地管理数据，而无需依赖未维护的客户端解析器。

使用 KML 显示屏幕叠加层

对于从 KmlLayer 迁移到数据驱动型样式 (DDS) 等现代替代方案的开发者，请务必注意，数据集不支持屏幕叠加层。如需实现与在地图顶部显示固定图片、徽标或图例相同的效果，您必须使用 Maps JavaScript API 创建自定义控件。

1. KML 文件中应注意的事项

如需构建等效的自定义控件，请检查 KML 文件中的 <ScreenOverlay> 元素，查看以下关键属性：

<Icon><href>：要显示的图片的网址。
<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`

Maps JavaScript API 使用 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);
}

KmlLayer 迁移途径 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

简介

用于设置边界/边框/感兴趣区域信息样式的 KML 文件

迁移建议：边界的数据驱动型样式

可用的 FeatureType

如何突出显示某个区域

将平移操作限定在指定区域

迁移实施摘要

包含矢量数据（点/折线/边界/多边形）的 KML 文件

迁移建议：数据集的数据驱动型样式

1. 设置和上传

2. 将视口设置为数据

3. 基于地图项属性设置样式

示例：使用属性设置函数样式

迁移建议：使用 GeoJSON 进行客户端渲染

1. 将 KML 转换为 GeoJSON

2. 将视口设置为数据

3. 基于地图项属性设置样式

示例：样式设置功能和视口调整

迁移途径：使用第三方库进行客户端渲染

1. deck.gl

2. geoxml3

包含互动元素的 KML 文件

迁移建议：数据集的数据驱动型样式

初始设置

1. 处理互动事件

2. 动态样式（悬停效果）

3. 显示来自 description 属性的 HTML

4. 使用 ExtendedData 的自定义信息窗口

迁移建议：使用 GeoJSON 进行客户端渲染

初始设置

1. 自动交互与手动交互

2. 处理互动事件

3. 在信息窗口中显示 HTML 说明

4. 自定义信息窗口和 ExtendedData

5. 动态样式设置（悬停效果）

迁移途径：使用第三方库进行客户端渲染

初始设置

1. 利用 deck.gl 实现交互式数据

2. 使用 geoxml3 实现交互式数据

包含影像的 KML 文件

迁移建议：Maps JavaScript API GroundOverlay

1. 实现

迁移途径：使用第三方库

1. geoxml3

2. deck.gl

高级示例：使用 gdal2tiles 创建图块金字塔

包含网络链接的 KML 文件

支持的解决方案：数据集的数据驱动型样式 (DDS)

开源解决方案：deck.gl 和 geoxml3

deck.gl

geoxml3

总结建议

使用 KML 显示屏幕叠加层

1. KML 文件中应注意的事项

2. 实现：创建自定义控件

将 KML 位置信息映射到 ControlPosition

3. 迁移示例：固定徽标叠加层

CSS 样式

JavaScript 实现

更多信息

KmlLayer 迁移途径

3. 显示来自 `description` 属性的 HTML

4. 使用 `ExtendedData` 的自定义信息窗口

4. 自定义信息窗口和 `ExtendedData`

将 KML 位置信息映射到 `ControlPosition`