目標對象
本文件適用於熟悉 JavaScript 程式設計與物件導向程式設計概念的人員。您應該也要熟悉使用者觀點下的 Google 地圖。網路上提供許多 JavaScript 教學課程。
此概念性文件旨在讓您快速探索及開發包含 Google Maps JavaScript API 的應用程式。我們也發佈了 Google Maps JavaScript API 參考資料。
Hello, World
開始學習 Google Maps JavaScript API 最簡單的方式，便是檢視簡單的範例。下面的網頁顯示以澳洲新南威爾斯省雪梨為中心的地圖：
var map;
function initMap() {
map = new google.maps.Map(document.getElementById('map'), {
center: {lat: -34.397, lng: 150.644},
zoom: 8
});
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
* element that contains the map. */
#map {
height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
height: 100%;
margin: 0;
padding: 0;
}
<!-- Replace the value of the key parameter with your own API key. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap" async defer></script>
<!DOCTYPE html>
<html>
<head>
<title>Simple Map</title>
<meta name="viewport" content="initial-scale=1.0">
<meta charset="utf-8">
<style>
/* Always set the map height explicitly to define the size of the div
* element that contains the map. */
#map {
height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<div id="map"></div>
<script>
var map;
function initMap() {
map = new google.maps.Map(document.getElementById('map'), {
center: {lat: -34.397, lng: 150.644},
zoom: 8
});
}
</script>
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
async defer></script>
</body>
</html>
即使在這個簡單的範例中，還是有幾個注意事項：
- 我們使用
<!DOCTYPE html>宣告，來將應用程式宣告為 HTML5。 - 我們建立一個名為「map」的
div元素來容納地圖。 - 我們在
div中定義建立地圖的 JavasScript 函式。 - 我們使用
script標記載入 Maps JavaScript API。
這些步驟說明如下。
將您的應用程式宣告為 HTML5
我們建議您在 Web 應用程式中宣告真正的 DOCTYPE。在這裡的範例內，我們使用簡單的 HTML5 DOCTYPE 來將應用程式宣告為 HTML5，如下所示：
<!DOCTYPE html>
目前大部分的瀏覽器會以「標準模式」來轉譯使用此 DOCTYPE 所宣告的內容，這表示您的應用程式將會具有更好的跨瀏覽器相容性。DOCTYPE 的原本的設計便是為了逐步降級，不瞭解它的瀏覽器會忽略它，並使用「Quirks 模式」來顯示其內容。
請注意，可以在 Quirks 模式內使用的一些 CSS，在標準模式中是無效的。明確來說，所有以百分比為基礎的大小，必須繼承自上層區塊元素。如果這些上層項目無法指定大小，便會將它們的大小假設為 0 x 0 像素。因此，我們必須包含下列 <style> 宣告：
<style>
#map {
height: 100%;
}
html, body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
這個 CSS 宣告指出地圖容器 <div> （搭配 id map）應該佔用 HTML 內文 100% 的高度。請注意，我們也必須為 <body> 及 <html> 明確宣告這個百分比。
載入 Google Maps JavaScript API
如果要載入 Google Maps JavaScript API，請使用與下列範例中一樣的script 標記：
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>
script 標記中所包含的網址是一個 JavaScript 檔案的位置，這個檔案會載入您使用 Maps JavaScript API 所需的所有符號與定義。必須有這個 script 標記。
async 屬性讓瀏覽器在 Maps JavaScript API 載入期間轉譯您網站上的其餘內容。當 API 準備就緒時，它會呼叫透過 callback 參數所指定的函式。
key 參數包含您應用程式的 API 金鑰。如需詳細資訊，請參閱取得金鑰。
注意：Google Maps APIs Premium Plan 客戶載入 API 時可以使用 API 金鑰或有效的用戶端 ID。如需詳細資訊，請參閱 Premium Plan 客戶的驗證參數。
HTTPS 或 HTTP
我們認為網路安全性非常重要，因此建議您儘可能使用 HTTPS。基於我們想要使網路更為安全的目的，所有 Maps JavaScript API 都可以在 HTTPS 上使用。使用 HTTPS 加密可讓您的網站更安全，並更能夠抵擋窺探或竄改。
我們建議使用上面提供的 <script> 標籤，透過 HTTPS 載入 Maps JavaScript API。
如有必要，您可以透過要求 http://maps.googleapis.com/ 或 http://maps.google.cn （針對中國的使用者），來經由 HTTP 載入 Maps JavaScript API。
程式庫
透過網址載入 Maps JavaScript API 時，您可以透過使用 libraries 網址參數，選擇性地載入其他「程式庫」。程式庫是為主要 Maps JavaScript API 提供其他功能的程式碼模組，只有在您明確要求程式庫時才會載入它們。如需詳細資訊，請參閱 Maps JavaScript API 中的程式庫。
同步載入 API
在載入 Maps JavaScript API 的 script 標記中，您可以選擇省略 async 屬性與 callback 參數。這將會封鎖 API 的載入，直到 API 下載完成。
這樣可能會拖慢頁面載入的速度。但這表示您可以編寫後續的指令碼標籤（假設 API 已經載入）。
地圖 DOM 元素
<div id="map"></div>
如果要在網頁上顯示地圖，我們必須先為它保留一個位置。保留位置的方式，通常是建立具名的 div 元素，並在瀏覽器的文件物件模型 (DOM) 中取得此元素的參照。
在上述範例中，我們使用 CSS 將地圖的 div 高度設成「100%」。這會延伸地圖以符合行動裝置上的大小。您需要根據瀏覽器的畫面大小和邊框間距，來調整寬度與高度的值。請注意，div 通常會從所包含元素取得寬度，而空的 div 通常表示高度為 0。基於這個原因，您一律要在 <div> 上明確設定高度。
地圖選項
每個地圖有兩個必要選項：center 和 zoom。
map = new google.maps.Map(document.getElementById('map'), {
center: {lat: -34.397, lng: 150.644},
zoom: 8
});
縮放層級
顯示地圖的初始解析度是由 zoom 屬性設定，其中縮放 0 對應完全縮小的地球地圖，較高的縮放層級則會放大到較高的解析度。以整數指定縮放層級。
zoom: 8
提供整個地球的地圖做為單一影像，將會需要一個巨大的地圖，或是解析度很低的小型地圖。因此，Google 地圖與 Maps JavaScript API 內的地圖影像會被分割成地圖的「地圖方塊」與「縮放層級」。在低縮放層級，一小組的地圖方塊可涵蓋寬廣區域，而在較高的縮放層級，地圖方塊的解析度將會較高，且涵蓋較小區域。下列清單顯示每個縮放層級預期看到的約略詳細程度：
- 1：全世界
- 5：地塊/大陸
- 10：城市
- 15：街道
- 20：建築物
下面三個影像分別以縮放層級 0、7 與 18反映了東京的同一位置。
如需 Maps JavaScript API 如何根據目前縮放層級載入地圖方塊的詳細資訊，請參閱「地圖類型」文件中的地圖方塊座標。
地圖物件
map = new google.maps.Map(document.getElementById("map"), {...});
Map 類別是表示地圖的 JavaScript 類別。這些類別的物件可定義頁面上的單個地圖。（您可以為此類別建立一個以上的執行個體，每個物件會定義頁面上的個別地圖。）我們要使用 JavaScript new 運算子建立此類別的新執行個體。
在您建立新的地圖執行個體時，要在頁面內指定 <div> HTML 元素做為地圖的容器。HTML 節點是 JavaScript document 物件的子項，我們會透過 document.getElementById() 方法取得對此元素的參照。
這個程式碼會定義一個變數（名為 map），並將該變數指派給新的 Map 物件。Map() 函式被稱為「建構函式」，它的定義如下所示：
| 建構函式 | 描述 |
|---|---|
Map(mapDiv:Node, opts?:MapOptions ) |
使用已傳遞的任何（選擇性）參數，在指定的 HTML 容器（通常是 DIV 元素）內部建立新的地圖。 |
疑難排解
為了協助您建立並執行地圖程式碼，Brendan Kenny 和 Mano Marks 在這個影片中會指出一些常見錯誤，以及修正這些錯誤的方法。
如果您的程式碼無法執行：
- 尋找打字錯誤。請記住，JavaScript 是有區分大小寫的程式語言。
- 檢查基本資訊，有些最常見的問題是在最初建立地圖時發生。例如：
- 確認您在地圖選項中已指定
zoom和center屬性。 - 確認您已宣告會讓地圖顯示在畫面上的 div 元素。
- 確認地圖的 div 元素設有高度。根據預設，高度於建立 div 元素時為 0，因此是看不到的。
- 確認您在地圖選項中已指定
- 使用 JavaScript 偵錯工具以協助識別問題，如 Chrome 開發人員工具中提供的偵錯工具。先從 JavaScript 主控台中查找錯誤。
- 將問題張貼到 Stack Overflow。支援頁面上有提供如何張貼重大問題的指導方針。
需要協助嗎？請前往我們的