KmlLayer 遷移路徑

簡介

本指南旨在說明 KmlLayer 最常見的用途，並提供替代實作方式的相應遷移路徑。開發人員請注意，KmlLayer 即將淘汰，因此您必須改用其他替代方案。支援 KmlLayer 的最後一個版本是 3.65，將於 2027 年 5 月停用。

遷移路徑取決於您使用 KmlLayer 的方式：

KML 檔案，用於設定界線/邊界/感興趣區域資訊的樣式：使用界線資料導向樣式 (DDS)，透過 Google 的界線資料設定行政區域。
含有向量資料 (點/折線/邊界/多邊形) 的 KML 檔案：使用資料集 DDS、GeoJSON 或 第三方程式庫，例如 deck.gl 或 geoxml3。
含有互動式元素的 KML 檔案：導入手動事件監聽器和自訂資訊視窗，以進行特徵互動。
含有圖像的 KML 檔案：使用 GroundOverlays 或第三方剖析器疊加圖像。
含有網路連結的 KML 檔案：將每個 KML 上傳為個別的資料集，或合併 KML。如要顯示動態資料，請使用 Datasets API 重新整理資料集。
使用 KML 顯示螢幕疊加層：使用自訂控制項取代標誌、圖例或導覽輔助等固定 UI 元素。

KML 檔案，用於設定邊界/邊框/感興趣區域資訊的樣式

如果開發人員使用 KmlLayer 顯示或設定行政邊界樣式 (例如醒目顯示特定國家/地區、州或地區)，Google 地圖平台建議改用資料導向樣式 (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 地圖項目讀取屬性，以決定其外觀。

範例：樣式函式和可視區域調整

以下範例說明如何載入 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 地圖平台 JavaScript API 上算繪 KML 資料。

1. deck.gl

deck.gl 是採用 WebGL 技術的高效能視覺化架構，透過 GoogleMapsOverlay 和 GeoJsonLayer，這項功能可做為 KML 算繪的近乎直接替代方案。

畫布需求：如要有效使用 deck.gl，請將地圖轉換為使用向量地圖類型 (這會算繪至畫布元素)，並啟用 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 Maps JavaScript API 第 3 版設計的 KML 處理器。這個類別會在瀏覽器中剖析 KML，並將資料算繪為標準的 Google Maps API 物件，例如標記、折線和多邊形。

支援標準地圖：與 WebGL 解決方案不同，geoxml3 可在標準 Google 地圖 JS API v3 地圖上運作，不需要特定算繪模式。
注意事項：
- KMZ 支援有限：程式庫「不完全支援 KMZ 檔案」，通常需要整合其他第三方指令碼 (例如 ZipFile.complete.js)，才能解壓縮 KMZ 封存檔。
- 不支援的元素：系統不支援 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 屬性。由於資料層沒有這些項目的預設 UI，您必須實作自訂 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：將地圖轉換為使用向量地圖類型 (畫布需求)。
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 物件。

原生樣式擷取：程式庫會從 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 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

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 地圖平台資料集不會原生剖析 <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 地圖平台基礎架構中安全無虞地管理，而不必依賴未維護的用戶端剖析器。

使用 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`