這裡透過簡單的 Hello, World 範例,介紹 Google Maps JavaScript API 的基本使用方式。
Google Maps JavaScript API 是設計給網頁開發者所使使用的開發工具,您可以使用這個 API 將 Google 地圖安插在自己的網頁中,並且將自己的資料放在地圖上面呈現。
以下是 Google Maps JavaScript API 的 Hello, World 入門使用教學。
取得 API 金鑰
只要是需要使用到 Google 地圖 API 的應用程式,都會需要一個 API 金鑰,如果您沒有申請過 API 金鑰,請參考從 Google Developers Console 取得開發者用的 API 金鑰。
這個 API 金鑰除了可以讓應用程式使用 Google API 所提供的服務之外,也是紀錄使用量的依據,每一個應用程式專案有一定的配額限制,若是使用量太大以致於超出配額,就必須要付費另外購買配額。
Hello, World
這是一段 Google 地圖 API 的 Hello, World 程式碼:
<!DOCTYPE html>
<html>
<head>
<style type="text/css">
html, body, #map-canvas { height: 100%; margin: ; padding: ;}
</style>
<script type="text/javascript"
src="https://maps.googleapis.com/maps/api/js?key=API_KEY">
</script>
<script type="text/javascript">
function initialize() {
var mapOptions = {
center: { lat: -34.397, lng: 150.644},
zoom: 8
};
var map = new google.maps.Map(
document.getElementById('map-canvas'),
mapOptions);
}
google.maps.event.addDomListener(
window, 'load', initialize);
</script>
</head>
<body>
<div id="map-canvas"></div>
</body>
</html>
以下是各個重點說明。
宣告 HTML5 網頁應用程式
這裡在一開始加入的
<!DOCTYPE html>
是用來宣告這個網頁是屬於最新的 HTML5 格式,這樣可以確保瀏覽器使用標準模式(standards mode)來處理這個網頁,若是沒有加上這一行,或是無法解析這一行的瀏覽器,就以怪癖模式(quirks mode)來顯示網頁,這會造成一些 CSS 無法正常運作。
而有一些在怪癖模式中可以正常顯示的 CSS,反而在正常模式中會有問題,例如所有的以百分比為基礎的大小,都必需繼承自其父元素,如果其父元素中有任何一個無法判定大小,那麼該元素的大小就會變成 0 x 0 像素,為了解決這個問題,所以我們加入了這段 CSS 程式碼:
<style type="text/css">
html { height: 100% }
body { height: 100%; margin: ; padding: }
#map-canvas { height: 100% }
</style>
這裡指定 map-canvas 這個 <div> 的高度為 100%,這裡要注意 <body> 與 <html> 的高度也要明確指定,不可省略。
引入 Google Maps API
在引入 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 協定,也可以使用 https://maps.googleapis.com/,而若是中國大陸的使用者,則必須改為 https://maps.google.cn/。
在引入 Google Maps API 時,可以在 URL 中使用 libraries 參數加入一些額外的功能,其使用方式可以參考 Libraries。
非同步載入(Asynchronously Loading)API
如果想要使用非同步載入的方式,讓 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 載入完成後執行。
放置地圖的 DOM 元素
在使用 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()">
