將 Maps JavaScript API 應用程式從第 2 版升級至第 3 版

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

總覽

每個應用程式的遷移程序都會略有不同，但有些步驟適用於所有專案：

  1. 取得新的金鑰。Maps JavaScript API 現在使用 Google Cloud 控制台管理金鑰。如果您仍在使用第 2 版金鑰，請務必先取得新的 API 金鑰，再開始遷移作業。
  2. 更新 API 啟動程序。大多數應用程式會使用以下程式碼載入 Maps JavaScript API 3 版：
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. 更新程式碼。所需的變更量很大程度上取決於您的應用程式。常見的變更包括：
    • 請一律參照 google.maps 命名空間。在 v3 中，所有 Maps JavaScript API 程式碼都會儲存在 google.maps.* 命名空間中，而非全域命名空間。在這個程序中，我們也重新命名了大部分的物件。例如，您現在會載入 google.maps.Map，而非 GMap2。
    • 移除所有已淘汰方法的參照。已移除許多通用的實用工具方法，例如 GDownloadURL 和 GLog。請將這項功能替換為第三方公用程式庫，或從程式碼中移除這些參照。
    • (選用) 在程式碼中加入程式庫。許多功能已外部化至公用程式庫，因此每個應用程式只需載入要使用的 API 部分。
    • (選用) 設定專案以使用 v3 外部模組。 您可以使用 v3 外部函式，透過 Closure 編譯器驗證程式碼，或在 IDE 中觸發自動完成功能。進一步瞭解 進階編譯和外部變數。
  4. 測試並重複執行。此時您仍需完成一些工作，但好消息是，您將順利完成新版地圖應用程式 v3 的申請！

Maps JavaScript API 第 3 版的變更

在規劃遷移作業前，請先花時間瞭解 Maps JavaScript API 第 2 版和 Maps JavaScript API 第 3 版的差異。最新版本的 Maps JavaScript API 是從頭開始編寫，著重於新型 JavaScript 程式設計技巧、增加程式庫使用量，以及簡化 API。API 新增了許多新功能，並且有幾項熟悉的功能已變更或移除。本節重點說明這兩個版本之間的一些主要差異。

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

  • 簡化的核心程式庫。許多輔助函式已移至程式庫，有助於縮短 Core API 的載入和剖析時間，讓地圖在任何裝置上都能快速載入。
  • 改善多項功能的效能，例如多邊形算繪和標記放置。
  • 用戶端用量限制的新做法，可更妥善地因應行動裝置 Proxy 和公司防火牆使用的共用位址。
  • 新增對多款新式瀏覽器和行動瀏覽器的支援。已移除對 Internet Explorer 6 的支援。
  • 移除了許多通用輔助類別 ( GLog 或 GDownloadUrl)。目前有許多優異的 JavaScript 程式庫可提供類似功能，例如 Closure 或 jQuery。
  • 街景服務導入了 HTML5 技術，因此在任何行動裝置上都能載入這項服務。
  • 使用自己的相片製作自訂街景服務全景，讓你分享滑雪坡、待售房屋或其他有趣地點的全景。
  • 樣式化地圖自訂功能，可讓您變更基本地圖上的元素顯示方式，以符合您獨特的視覺樣式。
  • 支援多項新服務，例如 ElevationService 和 Distance Matrix。
  • 改良版的路線指引服務提供替代路線、路線最佳化 ( 旅行推銷員問題的近似解決方案)、單車路線 (含 單車路線圖層)、大眾運輸路線和 可拖曳路線。
  • 更新版 Geocoding 格式，可提供比 Geocoding API 2 版 accuracy 值更準確的類型資訊。
  • 支援在單一地圖上顯示多個資訊視窗

為您的應用程式升級

新的金鑰

Maps JavaScript API 第 3 版採用第 2 版的全新金鑰系統。您可能已經在應用程式中使用 v3 金鑰，在這種情況下，您不需要進行任何變更。如要確認，請檢查您用來載入 Maps JavaScript API 的網址是否含有 key 參數。如果鍵值開頭為「ABQIAA」，表示您使用的是 v2 鍵。如果您有 v2 金鑰，則必須在遷移期間升級至 v3 金鑰，這樣才能：

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

請注意，如果您是 Google Maps API for Work 客戶，可能會使用用戶端 ID 搭配 client 參數，而不是使用 key 參數。Maps JavaScript API v3 仍支援用戶端 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 地圖平台付費方案) 請務必按照《 Google 地圖平台付費方案開發人員指南》所述，提供 client 參數。
  5. 移除 v 參數，以便要求最新發布的版本，或根據 v3 版本編號方案變更其值。
  6. (選用) 將 hl 參數替換為 language，並保留其值。
  7. (選用) 新增 libraries 參數，以載入選用資料庫。

在最單純的情況下，第 3 版的 Bootstrap 只會指定 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 會將所有物件放入 Global 命名空間，這可能會導致命名衝突。在 v3 中，所有物件都位於 google.maps 命名空間中。

將應用程式遷移至 v3 時，您必須變更程式碼，才能使用新的命名空間。很抱歉，搜尋「G」並替換為「google.maps」並不會完全生效，但這是檢查程式碼時的好方法。以下列舉幾個 v2 和 v3 中等同的類別範例。

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 版中沒有對應項目：

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 的位址已變更。
  • 在 v3 中，系統不再需要 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 版和第 3 版最受歡迎的功能。參考資料的每個部分均可單獨閱讀。我們建議您不要完整閱讀這份參考資料，而是視情況使用這項資料來協助遷移。

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

活動

Maps JavaScript API 第 3 版的事件模型與第 2 版的類似，但實際上有許多變更。

控制項

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

重疊說明

疊加層會反映您「新增」至地圖的物件，用於指定點、線、面或物件集合。

地圖類型

雖然 v2 和 v3 提供的地圖類型略有不同，但兩個 API 版本都提供所有基本地圖類型。根據預設，v2 會使用標準的「繪製」道路地圖圖塊。不過，v3 需要在建立 google.maps.Map 物件時提供特定地圖類型。

圖層

「圖層」是指地圖上的物件，包含一或多個疊加層。可做為單一單位進行操作，通常會反映物件的集合。

服務