這裡透過簡單的 Hello, World 範例,介紹 Google Maps JavaScript API 的基本使用方式。
Google Maps JavaScript API 是設計給網頁開發者所使使用的開發工具,您可以使用這個 API 將 Google 地圖安插在自己的網頁中,並且將自己的資料放在地圖上面呈現。
只要是需要使用到 Google 地圖 API 的應用程式,都會需要一個 API 金鑰,如果您沒有申請過 API 金鑰,請參考從 Google Developers Console 取得開發者用的 API 金鑰。
這個 API 金鑰除了可以讓應用程式使用 Google API 所提供的服務之外,也是紀錄使用量的依據,每一個應用程式專案有一定的配額限制,若是使用量太大以致於超出配額,就必須要付費另外購買配額。
這是一段 Google 地圖 API 的 Hello, World 程式碼:
<!DOCTYPE html>1 <html> <head> <style type="text/css"> html, body, #map-canvas { height: 100%; margin: 0; padding: 0;} </style> <script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=API_KEY"> </script>2 <script type="text/javascript"> function initialize() { var mapOptions = { center: { lat: -34.397, lng: 150.644}, zoom: 8 };4 var map = new google.maps.Map( document.getElementById('map-canvas'), mapOptions);5 } google.maps.event.addDomListener( window, 'load', initialize);6 </script> </head> <body> <div id="map-canvas"></div>3 </body> </html>
這段程式碼主要的重點如下:
1 宣告這是一個 HTML5 的網頁應用程式。
2 引入 Google Maps API。
3 使用一個 <div>
放置地圖。
4 建立一個 JavaScript 變數,存放地圖相關的參數。
5 建立一個地圖物件,指定要顯示地圖的 <div>
與相關參數。
6 使用 event listener 讓地圖在網頁載入完成後再載入。
以下是各個重點說明。
這裡在一開始加入的
<!DOCTYPE html>
是用來宣告這個網頁是屬於最新的 HTML5 格式,這樣可以確保瀏覽器使用標準模式(standards mode)來處理這個網頁,若是沒有加上這一行,或是無法解析這一行的瀏覽器,就以怪癖模式(quirks mode)來顯示網頁,這會造成一些 CSS 無法正常運作。
而有一些在怪癖模式中可以正常顯示的 CSS,反而在正常模式中會有問題,例如所有的以百分比為基礎的大小,都必需繼承自其父元素,如果其父元素中有任何一個無法判定大小,那麼該元素的大小就會變成 0 x 0 像素,為了解決這個問題,所以我們加入了這段 CSS 程式碼:
<style type="text/css"> html { height: 100% } body { height: 100%; margin: 0; padding: 0 } #map-canvas { height: 100% } </style>
這裡指定 map-canvas
這個 <div>
的高度為 100%
,這裡要注意 <body>
與 <html>
的高度也要明確指定,不可省略。
在引入 Google Maps API 時,必需傳入自己的 API 金鑰,實際使用時要把上面的 API_KEY
替換為自己的金鑰,就像這樣:
<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=AIzaSyAUOrXGoWf6bt5U4qgfvtFIiz-_Hp_Oc4s"> </script>
Google 地圖所有的 API 都可以透過 https 加密連線的方式引入,如果您有需要一般的 http 協定,也可以使用 http://maps.googleapis.com/
,而若是中國大陸的使用者,則必須改為 http://maps.google.cn/
。
在引入 Google Maps API 時,可以在 URL 中使用 libraries
參數加入一些額外的功能,其使用方式可以參考 Libraries。
如果想要使用非同步載入的方式,讓 Google 地圖的 API 延後載入,不要讓 API 拖慢整體網頁的速度,可以使用下面這樣的方式:
function initialize() { var mapOptions = { zoom: 8, center: new google.maps.LatLng(-34.397, 150.644) }; var map = new google.maps.Map(document.getElementById('map-canvas'), mapOptions); } function loadScript() { var script = document.createElement('script'); script.type = 'text/javascript'; script.src = 'https://maps.googleapis.com/maps/api/js?v=3.exp' + '&signed_in=true&callback=initialize'; document.body.appendChild(script); } window.onload = loadScript;
這裡在載入 API 的 JavaScript 時,加入一個 callback
參數,指定在 API 完全載入後的回呼函數,透過這樣的方式確保 initialize()
會在 API 載入完成後執行。
在使用 Google 地圖 API 時,我們需要保留一個顯示地圖用的地方,通常最常見的方式就是新增一個 <div>
元素,並且為的個元素命名,然後從 DOM 取得這個元素傳給 API:
<div id="map-canvas" style="width: 100%; height: 100%"></div>
這裡我們可以自行利用 CSS 調整它的大小,Google 地圖會自動依據包含地圖的元素大小來繪製地圖。
建立地圖時,都會需要至指定地圖中心(center
)與縮放層級(zoom
)這兩個參數。
var mapOptions = { center: new google.maps.LatLng(-34.397, 150.644), zoom: 8 };
地圖中心的經緯度可以使用下面三種方式來指定:
center: new google.maps.LatLng(-34.397, 150.644) center: {lat: -34.397, lng: 150.644} center: {lng: 150.644, lat: -34.397}
縮放層級的數值越小,顯示的範圍越大,當設為 0
時,則會顯示最大的範圍(世界地圖)。
Google 的地圖是以 Map
這個類別來代表的,一個 Map
物件代表一個地圖。
var map = new google.maps.Map( document.getElementById("map-canvas"), mapOptions);
您可以在一個網頁中同時產生多的 Map
物件,建立多個地圖。
在建立 Map
物件時,要連同 container 一起指定,這裡我們是使用 document.getElementById()
來取得作為 container 的 <div>
元素。
為了確保地圖會在網頁載入之後才進行繪製,避免一些不可預期的問題,我們在 onload 事件發生之後才執行繪製地圖的 JavaScript 程式:
google.maps.event.addDomListener(window, 'load', initialize);
您也可以直接寫在 <body>
標籤的 onload
屬性中:
<body onload="initialize()">
參考資料:Google Developers