Google Maps JavaScript API 入門使用教學與範例

這裡透過簡單的 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>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 讓地圖在網頁載入完成後再載入。

以下是各個重點說明。

宣告 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: 0; padding: 0 }
  #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 協定,也可以使用 http://maps.googleapis.com/,而若是中國大陸的使用者,則必須改為 http://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()">

參考資料:Google Developers

程式設計, 網頁開發

1 Comment

  1. Leo

    你好小弟我最近在利用google所提供的api做有關geolocation應用,我打算首先先讓範例程式run起來(https://developers.google.com/maps/documentation/javascript/examples/map-geolocation?hl=zh-tw)
    但我按照範例在sublime上實作,連上線後發現出現的是
    http://imgur.com/71UqO1F
    無法抓到坐標
    我以為是google api key的問題
    我也回去看是啟動的
    在網站上面的範例在google的網站是可以運作的
    可是為什麼到了自己的空間卻不行呢?
    想請教一下

Leave a Reply