將 Maps JavaScript API 應用程式從 V2 升級至 V3

Maps JavaScript API 2 版已於 2021 年 5 月 26 日停止提供。因此，您網站的 2 版地圖會停止運作，並傳回 JavaScript 錯誤。如要繼續在您的網站上使用地圖，請遷移至 Maps JavaScript API 3 版。本指南將引導您完成相關程序。

總覽

每個應用程式的遷移程序略有不同，但所有專案都應採取下列步驟：

  1. 取得新的金鑰。Maps JavaScript API 現在會使用 Google Cloud Console 管理金鑰。如果您仍在使用 v2 金鑰，請務必先取得新的 API 金鑰，再開始遷移。
  2. 更新 API 開機磁碟。大多數應用程式會使用以下程式碼載入 Maps JavaScript API 3 版：
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. 更新程式碼。您需要進行的變更數量取決於應用程式。常見的變更包括：
    • 一律參照 google.maps 命名空間。在第 3 版中，所有 Maps JavaScript API 程式碼都會儲存在 google.maps.* 命名空間，而非全域命名空間。在這項程序中，大部分物件也已重新命名。舉例來說，您現在可以載入 google.maps.Map，而不是 GMap2。
    • 移除過時方法的任何參照。已移除許多一般用途的公用程式方法，例如 GDownloadURL 和 GLog。請將這項功能替換為第三方公用程式庫，或是從程式碼中移除這些參照。
    • (選用) 在程式碼中新增程式庫。許多功能已外部化為公用程式庫，因此每個應用程式都只需載入要使用的 API 部分。
    • (選用) 將專案設為使用 v3 外部。 v3 外部可用於使用 Closure Compiler 驗證程式碼，或是在 IDE 中觸發自動完成功能。進一步瞭解進階編譯和外部服務。
  4. 測試並反覆修正。到目前為止，你還有一些工作要做，但好消息是，你現在已準備好改用全新的第 3 版地圖應用程式！

Maps JavaScript API 3 版的變更

規劃遷移作業前，請先花點時間瞭解 Maps JavaScript API 第 2 版與 Maps JavaScript API 3 版之間的差異。最新版本的 Maps JavaScript API 完全是以零開始編寫而成，但著重於著重於新型 JavaScript 程式設計技術、增加程式庫使用量和簡化的 API。 API 中新增了許多新功能，另有多項您熟悉的功能甚至有所變更。本節將重點介紹這兩個版本的主要差異。

第 3 版 API 中的部分變更包括：

  • 簡化的核心程式庫。許多補充函式已移至程式庫，因此可縮短 Core API 的載入和剖析時間，讓地圖在任何裝置上都能快速載入。
  • 改善幾種功能 (例如多邊形轉譯和標記位置) 的效能。
  • 針對用戶端用戶端用量限制及公司防火牆使用的共用位址，提供用戶端使用限制這項新方法。
  • 新增對多個新式瀏覽器和行動瀏覽器的支援。移除對 Internet Explorer 6 的支援。
  • 移除許多一般用途輔助類別 (GLog 或 GDownloadUrl)。目前，許多卓越的 JavaScript 程式庫都提供類似的功能，例如 Closure 或 jQuery。
  • 街景服務導入了 HTML5 技術，因此在任何行動裝置上都能載入這項服務。
  • 自行標示「自訂街景服務」全景圖，方便您分享滑雪坡道、待售房屋或其他有趣的地點全景。
  • 樣式化地圖自訂功能可讓您變更基本地圖上元素的顯示方式，以符合自己的獨特視覺樣式。
  • 支援多種新服務，例如 ElevationService 和 距離矩陣。
  • 更完善的路線規劃服務包括替代路線、路線最佳化 (旅客銷售問題概略的解決方案)、單車路線 (包含單車圖層)、大眾運輸路線和可拖曳的路線。
  • 更新的 Geocoding 格式，能夠提供比 Geocoding API v2 所提供的 accuracy 值更準確的類型資訊。
  • 在單一地圖上支援多個資訊視窗

為您的應用程式升級

新的金鑰

Maps JavaScript API 3 版使用第 2 版的全新金鑰系統。您的應用程式可能已採用第 3 版金鑰，因此無須變更。如要進行驗證，請查看您載入 Maps JavaScript API 的網址，並查看其 key 參數。如果鍵/值開頭為 'ABQIAA'，代表您使用的是 v2 金鑰。如果您有 v2 金鑰，就必須在遷移過程中升級至 v3 金鑰，這麼做會：

載入 Maps JavaScript API 第 3 版時，系統會傳送金鑰。進一步瞭解如何產生 API 金鑰。

請注意，如果您是 Google Maps API for Work 客戶，使用的用戶端 ID 可能是 client 參數，而不是 key 參數。Maps JavaScript API 3.0 版仍支援用戶端 ID，不需要執行金鑰升級程序。

載入 API

您必須對程式碼進行的第一個修改涉及載入 API 的方式。在第 2 版中，您是透過對 http://maps.google.com/maps 的要求載入 Maps JavaScript API，如要載入 Maps JavaScript API 3 版，您必須執行下列變更：

  1. 從 //maps.googleapis.com/maps/api/js 載入 API
  2. 移除 file 參數。
  3. 使用新的 v3 金鑰更新 key 參數。Google Maps API for Work 客戶應使用 client 參數。
  4. (僅限 Google 地圖平台付費方案) 確認提供 client 參數，如《Google 地圖平台付費方案開發人員指南》所述。
  5. 移除 v 參數以要求最新的發布版本，並根據 v3 版本管理配置，變更這個值。
  6. (選用) 將 hl 參數替換為 language，並保留其值。
  7. (選用) 新增 libraries 參數以載入選用程式庫。

在最簡單的情況下，v3 啟動條件只會指定 API 金鑰參數：

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

以下範例說明如何使用德文版最新版 Maps JavaScript API 2 版：

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

下方範例針對第 3 版提出相同要求。

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

導入 google.maps 命名空間

在 Maps JavaScript API 第 3 版中，最明顯的改變就是 google.maps 命名空間的推出。v2 API 預設會將所有物件放置在全域命名空間中，這可能會導致命名衝突。在 v3 中，所有物件都位於 google.maps 命名空間中。

將應用程式遷移至 v3 時，您必須變更程式碼才能使用新命名空間。但很遺憾地，在搜尋「G」時，會用「google.maps."win'」做為完整的程式碼執行方式，但查看程式碼時也適合採用這項規則。以下列舉第 2 版和第 3 版中同等類別的範例。

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

移除過時的程式碼

Maps JavaScript API 3 版在第 2 版中大部分功能都有平行功能，但部分類別已不再支援。在遷移過程中，您應將這些類別替換為第三方公用程式庫，或是從程式碼中移除這些參照。許多優質 JavaScript 程式庫都提供類似的功能，例如 Closure 或 jQuery。

下列類別在 Maps JavaScript API 3.0 版中沒有平行功能：

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

比較程式碼

我們來比較兩個使用 v2 和 v3 API 編寫的應用程式。

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

如您所見，這兩個應用程式之間有一些差異。明顯的改變包括：

  • 載入 API 的位址已變更。
  • 第 3 版不再需要使用 GBrowserIsCompatible() 和 GUnload() 方法，且已從 API 中移除。
  • GMap2 物件已由 google.maps.Map 取代為 API 中的中央物件。
  • 屬性現在是透過 Options 類別載入。在上述範例中，我們透過內嵌的 MapOptions 物件，設定載入地圖所需的三個屬性 (center、zoom 和 mapTypeId)。
  • 根據預設，第 3 版會啟用預設使用者介面。如要停用這項設定，請在 MapOptions 物件中將 disableDefaultUI 屬性設為 true。

摘要

在這個階段，您將會略微熟悉在 Maps JavaScript API 第 2 版到第 3 版中遷移時的重點。 你可能還需要知道更多相關資訊，但這取決於你的應用程式。下列各節針對您可能遇到的特定情況提供了遷移操作說明。此外，在您升級期間，有許多資源可能會對升級作業有幫助。

如果您對本文有任何疑問或問題，請使用本頁最上方的 [傳送意見回饋] 連結。

詳細參考資料

本節將詳細介紹 Maps JavaScript API 2.0 版和第 3 版中最熱門的功能。參考資料的各個部分都是個別讀取。建議您不要完整閱讀這份參考資料，而是按照個案內容逐步進行遷移作業。

  • 事件 - 註冊及處理事件。
  • 控制項 - 操控地圖上的導覽控制項。
  • 疊加層 - 在地圖上新增和編輯物件。
  • 地圖類型 - 構成基本地圖的圖塊。
  • 圖層 - 以群組的形式新增和編輯內容，例如 KML 或路況圖層。
  • 服務 - 使用 Google 的地理編碼、路線或街景服務服務。

事件

Maps JavaScript API 第 3 版的事件模型與第 2 版的事件模型十分相似，但經過大幅變更之後。

控制項

Maps JavaScript API 顯示 UI 控制項，方便使用者與地圖互動。您可以使用 API 自訂這些控制項的顯示方式。

重疊說明

疊加層會反映您在「新增」至地圖中的物件，以標示物件的點、線、區域或集合。

地圖類型

第 2 版和第 3 版提供的地圖類型略有不同，但所有基本地圖類型都可用於這兩種 API 版本。根據預設，v2 會使用標準「繪製」藍圖。不過，v3 需要在建立 google.maps.Map 物件時指定特定地圖類型。

資料層

圖層是地圖上由一或多個疊加層組成的物件。可以將其視為單一單位，且通常可反映物件的集合。

服務