您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps JavaScript API

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps JavaScript API 與相關服務
  3. 建立適當的金鑰
繼續

將您的 Google Maps JavaScript API 應用程式從 v2 升級至 v3

我們已不再提供 Google Maps JavaScript API 版本 2。本指南的主要目的是協助已使用 Google Maps JavaScript API v2 的開發人員將程式碼遷移至版本 3

Google Maps JavaScript API v2 與 v3 之間差異頗大。當您開始使用新的 API 後,您會很快地發現這並非僅是一次累加式升級。好消息是,我們站在開發人員的角度,新增了許多很棒的新功能,並改進了 API 整體的可用性。若您計畫要從 Google Maps JavaScript API v2 升級至 Google Maps JavaScript API v3,本指南將協助您完成遷移程序,並指出幾項對 v2 API 使用者來說最常見的變更。

總覽

每個應用程式的遷移程序有些許不同,但仍有些步驟是所有專案通用的:

  1. 取得新的金鑰。Google Maps JavaScript API 現在使用 Google API Console 來管理金鑰。開始遷移之前,請務必取得新的 API 金鑰
  2. 更新 API 啟動程序。大部分應用程式會使用下列程式碼來載入 Google Maps JavaScript API v3:
    <script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=true_OR_false"></script>
    
  3. 更新程式碼。所需的變更多寡取決於應用程式。常見的變更包括:
    • 總是參照 google.maps 命名空間。在 v3 中,所有 Google Maps JavaScript API 程式碼均儲存於 google.maps.* 命名空間中(而非全域命名空間)。在此過程中,大多數的物件也已被重新命名。例如,從現在起您載入的是 google.maps.Map 而非 GMap2
    • 移除對過時方法的參照。我們已移除數個一般用途的公用程式方法,例如 GDownloadURLGLog。請使用第三方公用程式庫取代此功能,或將這些參照從您的程式碼中移除。
    • (選擇性)新增程式庫至您的程式碼。許多功能已外部化為公用程式庫,因此應用程式僅需載入 API 中將要使用的部分。
    • (選擇性)設定專案使用 v3 extern。v3 extern 可用來協助您使用 Closure Compiler 驗證程式碼,或在 IDE 中觸發自動完成。深入了解進階編譯與 extern
  4. 測試並逐一查看。此時,您仍會有一些工作要做,但好消息是您就快要完成新的 v3 地圖應用程式了!

Google Maps JavaScript API 版本 3 中的變更

策劃遷移前,請先花點時間了解 Google Maps JavaScript API v2 與 Google Maps JavaScript API v3 之間的差異。全新打造的最新版 Google Maps JavaScript API 著重於現代 JavaScript 程式設計技術、增加了程式庫的使用,並簡化了 API。API 中新增了許多新功能,對一些熟悉的功能做了更改或甚至直接移除。本節著重說明兩個版本之間的一些主要差異。

v3 API 中的變更包括:

  • 簡化的核心程式庫。許多補充功能已移至程式庫,幫助縮短載入,剖析核心 API 的時間,使您的地圖在任何裝置上都能快速載入。
  • 數個功能的效能已提升,例如多邊形轉譯與標記放置。
  • 新的用戶端使用限制處理方法,能更充分地顧及行動裝置 Proxy 及企業防火牆採用的共用位址。
  • 新增數種最新瀏覽器與行動裝置瀏覽器的支援。移除對 Internet Explorer 6 的支援。
  • 移除多個一般用途的協助程式類別 ( GLog GDownloadUrl)。現今有許多絕佳的 JavaScript 程式庫可提供類似功能,例如 ClosurejQuery
  • 可在任何行動裝置上載入的 HTML5 街景服務實作。
  • 使用您的相片來自訂街景服務全景,分享滑雪場、準備出售的房屋或其他有趣地點的全景圖。
  • 樣式化地圖自訂項目可讓您變更基本地圖上的元素顯示方式,配合您的獨特視覺風格。
  • 支援多種新服務,例如 ElevationServiceDistance Matrix
  • 更佳的路線規劃服務,提供替代路線、路線最佳化(旅行推銷員問題的近似解)、單車路線規劃(搭配單車圖層)、大眾運輸路線規劃,以及可拖曳路線規劃
  • 已更新地理編碼格式,提供比 Google Maps Geocoding API v2 中的 accuracy 值更準確的類型資訊。
  • 支援單一地圖上出現多個資訊視窗

升級您的應用程式

您的新金鑰

Google Maps JavaScript API v3 使用新的金鑰系統。這表示您的 v2 金鑰將不適用於 v3 應用程式。在將應用程式部署到生產環境前,先新增 v3 金鑰,便能:

金鑰在載入 Google Maps JavaScript API v3 時傳遞。若要產生金鑰:

  1. 造訪 Google API Console,並使用您的 Google 帳戶登入。
  2. 從左方功能表中按一下 服務 連結,然後啟用 Google Maps JavaScript API v3 服務。
  3. 啟用服務後,您可以從 API Access 頁面的 Simple API Access 區段找到您的 API 金鑰。Maps API 應用程式使用 Key for browser apps

Maps APIs for Work 授權的用戶端編號

如果您擁有 Google Maps APIs for Work 授權,則您需使用用戶端編號,而非金鑰。請注意,這兩者無法同時使用。用戶端編號和金鑰相似,但具有下列差異:

  • 使用用戶端編號的 Google Maps APIs 應用程式可能得以存取額外功能或限制,例如 Maps Analytics
  • Google Cloud Support 會為您建立用戶端編號,並提供在 Maps APIs for Work 歡迎函中。您不必使用 Google API Console 來建立或尋找用戶端編號。
  • 載入 Google Maps JavaScript API 時,您應該使用 client 參數,而非 key 參數。例如:
    <script src="//maps.googleapis.com/maps/api/js?v=3&client=gme-yourclientid&sensor=true_or_false" type="text/javascript"></script>
  • 用戶端編號前面一律加上 gme-

載入 API

您對程式碼進行的初步修改涉及 API 載入的方式。在 v2 中,您對 http://maps.google.com/maps 提出要求來載入 Google Maps JavaScript API。如果您要載入 Google Maps JavaScript API v3,則需進行下列變更:

  1. //maps.googleapis.com/maps/api/js 載入 API
  2. 移除 file 參數。
  3. 請確認您已包含必要的 sensor 參數
  4. 使用新的 v3 金鑰更新 key 參數。Google Maps APIs for Work 客戶則須使用 client 參數。
  5. (僅適用 Google Maps APIs Premium Plan)確認您已提供 client 參數,如 Google Maps APIs Premium Plan 開發人員指南中所述。
  6. 移除 v 參數來要求最新版本,或根據 v3 版本控制配置來變更其值。
  7. (選擇性)hl 參數取代為 language 並保留其值。
  8. (選擇性) 新增 libraries 參數來載入 選用程式庫

在最單純的情況下,v3 啟動程序僅會指定您的 API 金鑰與 sensor 參數:

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=false"></script>

下列範例要求最新(實驗功能)德文版本的 Maps JavaScript API v2:

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

下列範例是 v3 中相對應的要求。

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&key=YOUR_API_KEY&language=de"></script>

版本控制

v3 不要求您載入特定版本。如果您省略版本參數,會得到最新實驗功能版本的 API。您也可以指定特定版本號碼、最新(實驗功能)版本,或最穩定的凍結版本。

下列表格將 v2 的版本配置對應至 v3。

v2 v3 使用案例
2.s 3.0 凍結版本。可用的最舊版本。
2 3 發行版本。最新的穩定版本。
2.x 3.exp 實驗功能版本。

重要:Google Maps APIs Premium Plan SLA 不適用於實驗功能版本。Google Maps APIs Premium Plan 應用程式必須使用目前的發行凍結版本,才能涵蓋在 SLA 中。

導入 google.maps 命名空間

Google Maps JavaScript API v3 中最明顯的變更應屬 google.maps 命名空間的導入。v2 API 預設會將所有物件放在全域命名空間中,但這可能造成命名衝突。在 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
或 google.maps.PolylineOptions

移除過時程式碼

Google Maps JavaScript API v3 具備大部分 v2 功能的對等功能;然而,有部分類別現已不再支援。遷移時,您應使用第三方公用程式庫取代這些類別,或將這些參照從您的程式碼中移除。有許多絕佳的 JavaScript 程式庫可提供類似功能,例如 ClosurejQuery

下列類別在 Google Maps JavaScript API v3 中沒有對等類別:

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&sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    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?sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    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
  • 根據預設,v3 會開啟預設 UI。您可以在 MapOptions 物件中,將 disableDefaultUI 屬性設定為 true 來停用預設 UI。

摘要

此時,您應已初步了解幾項從 Google Maps JavaScript API v2 遷移至 Google Maps JavaScript API v3 的重點。您可能還需要了解更多資訊,但這取決於您的應用程式。在以下各節中,我們將針對您可能遇到的案例,提供遷移操作說明。此外,還提供幾個在您進行升級程序時,可能會覺得實用的資源。

如您有任何關於本文的問題或建議,請使用本頁頂端的意見回饋連結。

詳細參考資料

本節提供 Google Maps JavaScript API 版本 2 與版本 3 最常用功能的詳細比較。此參考資料的各節旨在讓您個別閱讀。建議您不要一下完整閱讀此參考資料;反之,請根據實際狀況逐一參考此份材料,以協助完成遷移。

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

事件

Google Maps JavaScript API v3 的事件模型和 v2 所用的類似,但做了許多變更。

控制項

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

疊加層

疊加層反映您「新增」到地圖來指定點、線、面或物件集合的物件。

地圖類型

v2 和 v3 提供的地圖類型有些微不同,但這兩版 API 皆提供全部的基本地圖類型。根據預設,v2 使用標準版「繪製」道路地圖方塊。然而,建立 google.maps.Map 物件時,在 v3 中必須指定特定的地圖類型。

圖層

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

服務

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps JavaScript API
Google Maps JavaScript API
需要協助嗎?請前往我們的支援網頁