將 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
    • 移除所有已淘汰方法的參照。已移除許多通用的實用工具方法,例如 GDownloadURLGLog。請將這項功能替換為第三方公用程式庫,或從程式碼中移除這些參照。
    • (選用) 在程式碼中加入程式庫。許多功能已外部化至公用程式庫,因此每個應用程式只需載入要使用的 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 程式庫可提供類似功能,例如 ClosurejQuery
  • 街景服務導入了 HTML5 技術,因此在任何行動裝置上都能載入這項服務。
  • 使用自己的相片製作自訂街景服務全景,方便您分享滑雪坡、待售房屋或其他有趣地點的全景。
  • 樣式化地圖自訂功能,可讓您變更基本地圖上的元素顯示方式,以符合您獨特的視覺樣式。
  • 支援多項新服務,例如 ElevationServiceDistance 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 程式庫都提供類似的功能,例如 ClosurejQuery

下列類別在 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 物件,設定載入地圖所需的三個屬性:centerzoommapTypeId
  • 根據預設,第 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 物件時,必須提供特定地圖類型。

圖層

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

服務