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

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

總覽

每個應用程式的遷移程序略有不同,但以下幾個步驟適用於所有專案:

  1. 取得新的金鑰。Maps JavaScript API 現在會使用 Google Cloud 控制台管理金鑰。如果您仍在使用第 2 版的金鑰,請務必取得新的 API 金鑰再開始遷移。
  2. 更新 API Bootstrap。大多數應用程式會使用下列程式碼載入 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 部分。
    • (選用) 將專案設為使用第 3 版的外部值。第 3 版外部程式庫可用來透過 Closure Compiler 來驗證程式碼,或在 IDE 中觸發自動完成功能。進一步瞭解 進階編譯與 Externs
  4. 反覆測試。此時您還需完成一些工作,但好消息是,您已經能順利使用新的第 3 版地圖應用程式了!

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 技術,因此在任何行動裝置上都能載入這項服務。
  • 自訂街景服務全景圖,可讓您分享滑雪坡道、待售房屋或其他有趣地點的全景。
  • 樣式化地圖自訂項目可讓您變更基本地圖元素的顯示方式,以配合您的獨特視覺風格。
  • 支援多種新服務,例如 ElevationService距離矩陣
  • 改良版路線規劃服務提供了替代路線、路線最佳化服務 (有關 旅行銷售員問題的概略解決方案)、單車路線 (包含 單車圖層)、大眾運輸路線和 可拖曳的路線
  • 更新地理編碼格式,提供比 Geocoding API 第 2 版 accuracy 值更準確的類型資訊。
  • 支援單一地圖上的多個資訊視窗

為您的應用程式升級

新的金鑰

Maps JavaScript API 第 3 版採用第 2 版的新金鑰系統。您可能已在應用程式中使用 v3 金鑰,因此不必進行任何變更。如要確認,請查看您載入 Maps JavaScript API 的網址,確認是否包含 key 參數。如果鍵/值的開頭是「ABQIAA」,表示使用的是第 2 版金鑰。如果您有第 2 版的金鑰,必須在遷移期間升級至 v3 金鑰,這項操作會:

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

請注意,如果您是 Google Maps API for Work 客戶,那麼您也許會將用戶端 ID 與 client 參數搭配使用,而非使用 key 參數。Maps JavaScript API 第 3 版仍支援用戶端 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 命名空間的簡介。根據預設,第 2 版 API 會將所有物件放在全域命名空間中,因此可能導致命名衝突。在 v3 中,所有物件都位於 google.maps 命名空間中。

將應用程式遷移至第 3 版時,您必須變更程式碼才能使用新的命名空間。很抱歉,搜尋「G」並取代為「google.maps.」並無法完全正常運作。不過,在檢查程式碼時,請務必以經驗法則為準。以下是第 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 版中,下列類別沒有平行:

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

比較程式碼

接著來比較使用第 2 版和第 3 版 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  >
    <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 版和第 3 版最常用的功能。參考資料中的每個區段都設計為可供單獨閱讀。建議您不要完整閱讀本參考資料,而是視情況使用這些內容來協助您完成遷移作業。

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

活動

Maps JavaScript API 第 3 版的事件模型與第 2 版相似,但實際上已有部分變更。

控制項

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

重疊說明

疊加層會反映您在地圖中加入的物件,用以指派點線、區域或物件集合。

地圖類型

第 2 版和第 3 版提供的地圖類型略有不同,但這兩種 API 版本都提供所有基本地圖類型。根據預設,第 2 版會使用標準「繪製」道路地圖圖塊。不過,第 3 版規定建立 google.maps.Map 物件時必須指定特定的地圖類型。

圖層

「圖層」是指地圖上由一或多個疊加層組成的物件。這可以視為單一單元加以操作,通常會反映多個物件集合。

服務