將 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
    • 移除過時方法的任何參照。已移除許多一般用途的公用程式方法,例如 GDownloadURLGLog。請將這項功能替換為第三方公用程式庫,或是從程式碼中移除這些參照。
    • (選用) 在程式碼中新增程式庫。許多功能已外部化為公用程式庫,因此每個應用程式都只需載入要使用的 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 的支援。
  • 移除許多一般用途輔助類別 (GLogGDownloadUrl)。目前,許多卓越的 JavaScript 程式庫都提供類似的功能,例如 ClosurejQuery
  • 街景服務導入了 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 程式庫都提供類似的功能,例如 ClosurejQuery

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

資料層

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

服務