My favorites | 中文(繁體) | Sign in
英文版或許有比此中譯版新的內容

Google 地圖 API 專業版

同樣好用的地圖，再加上 SLA、支援以及廣告的控制

Google 地圖基本資料

  1. 簡介
  2. Google 地圖的「Hello, World」
    1. 載入 Google 地圖 API
    2. 地圖 DOM 元素
    3. GMap2 - 基本物件
    4. 初始化地圖
    5. 載入地圖
  3. 緯度和經度
  4. 地圖屬性
  5. 地圖互動
  6. 資訊視窗

簡介

任何「Google 地圖 API」應用程式的基本元素就是「地圖」本身。本說明文件討論基本 GMap2 物件的用法，以及地圖操作的基本資料。

Google 地圖的「Hello, World」

要學習「Google 地圖 API」，最簡單的方法就是查看簡單的範例。下列網頁顯示 500x300 地圖，中心位於加州的 Palo Alto：

<!DOCTYPE html "-//W3C//DTD XHTML 1.0 Strict//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Google Maps JavaScript API Example</title>
    <script src="http://maps.google.com/maps?file=api&amp;v=2&amp;key=abcdefg&sensor=true_or_false"
            type="text/javascript"></script>
    <script type="text/javascript">

    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(document.getElementById("map_canvas"));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
      }
    }

    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map_canvas" style="width: 500px; height: 300px"></div>
  </body>
</html>

您可以查看此範例，並下載加以編輯和測試。但是，您必須以自己的地圖 API 金鑰取代該檔案中的金鑰。(只要為特定目錄註冊金鑰，就能在該目錄的所有子目錄中使用該金鑰。)

就算只是這個簡單的範例，仍然有五個地方值得注意：

  1. 我們使用 script 標籤來載入「地圖 API JavaScript」。
  2. 我們建立 div 元素 (命名為「map_canvas」) 來容納「地圖」。
  3. 我們撰寫 JavaScript 函式以建立「地圖」物件。
  4. 我們將地圖的中央置於指定地理位置點。
  5. 我們從 body 標籤的 onLoad 事件初始化地圖物件。

這些步驟說明如下。

載入 Google 地圖 API

<script src="http://maps.google.com/maps?file=api&v=2&key=abcdefg&sensor=true_or_false"
        type="text/javascript">
</script>

http://maps.google.com/maps?file=api&v=2&key=abcdefg 網址指向 JavaScript 檔案的位置，這些檔案包括使用「Google 地圖 API」時所需要的所有符號和定義。您的網頁必須包含指向此網址的 script 標籤，當您申請使用 API 時，請使用收到的金鑰。在此範例中，金鑰顯示為「abcdefg」。

請注意，我們也傳送 sensor 參數，以指出此應用程式是否使用感應器來判斷使用者的位置。我們特別用 true_or_false 做為範例中變數的名稱，以強調您必須明確地將此值設定為 true 或 false。

地圖 DOM 元素

<div id="map_canvas" style="width: 500px; height: 300px"></div>

我們必須在網頁上預留顯示地圖的位置。通常，我們會建立名稱為 div 的元素，並取得瀏覽器文件物件模型 (DOM) 中此元素的參照。

在上述範例中，我們定義名稱為「map_canvas」的 div，並使用樣式屬性來設定它的大小。除非您在建構函式中使用 GMapOptions 為地圖明確地指定大小，否則地圖會使用容器本身的大小。

GMap2 - 基本物件

var map = new GMap2(document.getElementById("map_canvas"));

代表地圖的 JavaScript 類別為 GMap2 類別。此類別的物件會定義網頁上的單一地圖。(您可以建立此類別一個以上的實例 - 每個物件會在網頁上定義個別的地圖。) 我們使用 JavaScript new 運算子來新增此類別的實例。

您建立新的地圖實例時，可以指定網頁中的 DOM 節點 (通常是 div 元素) 做為地圖的容器。HTML 節點是 JavaScript document 物件的子項，而我們可以透過 document.getElementById() 方法來取得此元素的參照。

此程式碼會定義一個變數 (名稱為 map) 並指派該變數為新的 GMap2 物件。函式 GMap2() 稱為「建構函式」，其定義 (擷取於 Google 地圖 API 參考文件) 如下：

建構函式 說明
GMap2(container, opts?) 在指定 HTML container 中建立新地圖，通常是 DIV 元素。您也可以在 opts 參數中傳送選用類型 GMap2Options 的參數。

請注意，因為 JavaScript 是弱型別語言，我們不需要在建構函式傳送任何選用的參數 (如此處示範)。

初始化地圖

  map.setCenter(new GLatLng(37.4419, -122.1419), 13);

透過 GMap2 建構函式建立地圖後，需要再做一件事：將它初始化。我們會使用 setCenter() 方法來完成地圖的初始化。setCenter() 方法需要 GLatLng 座標和縮放等級，而且此方法必須在地圖執行其他任何操作之前 (包括設定地圖本身的任何其他屬性)，就先行傳送。

載入地圖

  <body onload="initialize()" onunload="GUnload()">

呈現 HTML 網頁時，會建立文件物件模型 (DOM)，接收任何外部的圖片和指令碼，並與 document 物件進行整合。如果想確認地圖要在網頁完全載入後才會放上網頁，只要在 HTML 網頁的 <body> 元素接收到 onload 事件時，執行建構 GMap2 物件的函式即可。這樣做可以避免無法預期的行為，並讓我們更能控制繪製地圖的方式和時機。

onload 屬性是事件處理常式的範例。「Google 地圖 API」也提供一系列您可以接聽的事件，以便判斷狀態變更。請參閱地圖事件和事件接聽程式以取得詳細資訊。

GUnload() 函式是一種公用程式，其目的是為了防止記憶體流失。

緯度和經度

現在我們已經有了地圖，我們還需要指出地圖上位置的方式。GLatLng 物件在「Google 地圖 API」中就提供這樣的機制。您建構 GLatLng 物件，以 { latitude, longitude } 順序傳送其參數，如同製圖時的慣例。

  var myGeographicCoordinates = new GLatLng(myLatitude, myLongitude)

注意：將「地址」轉換為地理位置點的程序稱為「地理編碼」(Geocoding)，在 Google 地圖 API 服務章節會有詳細討論。

經度和緯度的概念除了可以指出地理位置，對於定義物件的地理界限也很有用。例如，在所謂的檢視區中，地圖會將全世界顯示成一個「視窗」。此檢視區可以用矩形的四個角來定義。GLatLngBounds 物件提供此功能，使用兩個 GLatLng 物件定義矩形區域，分別代表該界限方塊的西南和東北角。

GLatLng 物件在「Google 地圖 API」中有多種功能。例如，GMarker 物件在其建構函式中接受 GLatLng，並於地圖的指定地理位置放置疊加層標記。

下列範例使用 getBounds() 傳回目前的檢視區，然後在地圖上該範圍內隨機放置 10 個標記：

function initialize() {
  var map = new GMap2(document.getElementById("map_canvas"));
  map.setCenter(new GLatLng(37.4419, -122.1419), 13);
 
  // Add 10 markers to the map at random locations
  var bounds = map.getBounds();
  var southWest = bounds.getSouthWest();
  var northEast = bounds.getNorthEast();
  var lngSpan = northEast.lng() - southWest.lng();
  var latSpan = northEast.lat() - southWest.lat();
  for (var i = 0; i < 10; i++) {
    var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
        southWest.lng() + lngSpan * Math.random());
    map.addOverlay(new GMarker(point));
  }
}

檢視範例 (map-markers.html)

注意：GMarker 物件的詳細資訊位於疊加層章節。

地圖屬性

按照預設，在「Google 地圖 API」中顯示的地圖會使用標準的「繪製」地圖方塊。不過，「Google 地圖 API」也支援其他地圖類型。下列皆為標準地圖類型：

  • G_NORMAL_MAP- 預設檢視
  • G_SATELLITE_MAP - 顯示「Google 地球」衛星圖片
  • G_HYBRID_MAP - 顯示一般和衛星檢視的混合圖
  • G_DEFAULT_MAP_TYPES - 這三種類型的陣列，在反覆操作時很有用

您可以使用 GMap2 物件的 setMapType() 方法來設定地圖類型。例如，下列程式碼設定地圖使用「Google 地球」的衛星檢視：

  var map = new GMap2(document.getElementById("map_canvas"));
  map.setMapType(G_SATELLITE_MAP);

地圖也包含許多屬性，要進行查證時很有用。例如，要找出目前檢視區的維度，可使用 GMap2 物件的 getBounds() 方法，以傳回 GLatLngBounds 值。

每個地圖也都包含「縮放等級」，定義目前檢視的解析度。在一般地圖檢視中，縮放等級最低為 0 (可顯示全世界)，最高則為 19 (可看到個別的建築物)。能使用的縮放等級會視您查看世界的哪個角落而有所不同，某些區域的資料會比其他區域精細。在衛星檢視中，縮放等級可高達 20。

您也可以使用 GMap2 物件的 getZoom() 方法來抓取目前的縮放等級。

更多關於縮放等級、地圖方塊以及建立您自己的自訂地圖類型的詳細資訊，請參考地圖方塊疊加層章節。

地圖互動

現在，您已經有 GMap2 物件，便可與它互動了。基本地圖物件的外觀和行為，與「Google 地圖」網站的地圖極為相似，還內建很多行為。GMap2 物件也有一系列設定方法，可以改變地圖物件本身的行為。

按照預設，地圖物件回應使用者活動的行為與 http://maps.google.com 相同。不過，您可以使用各種公用程式方法來變更此行為。例如，GMap2.disableDragging() 方法會停用按一下地圖並拖曳至新位置的功能。

您也可以用程式設計方式與地圖互動。GMap2 物件支援一系列方法，可直接改變地圖狀態。例如，setCenter()、panTo 以及 zoomIn() 方法是透過程式設計方式來操作地圖，而非透過使用者互動。

下列範例會顯示地圖、等候兩秒鐘，然後移動至新的中心點。panTo 方法會以指定點為中心來顯示地圖。如果指定的點位於地圖的可視範圍內，則地圖會平滑地移動到該點；如果不是，則會跳至該點。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
window.setTimeout(function() {
  map.panTo(new GLatLng(37.4569, -122.1569));
}, 1000);

檢視範例 (map-animate.html)

如果要進行更複雜的互動，可以使用地圖 API 事件達成。

資訊視窗

「Google 地圖 API」中的每個地圖，可能會顯示類型 GInfoWindow 的單一個「資訊視窗」(可在地圖上的浮動視窗中顯示 HTML 內容)。資訊視窗看起來有點像是漫畫中的對話泡泡；有顯示內容的區域，以及拉長的指示部分，此拉長部分的尖端就位於地圖上的指定點。按下 Google 地圖中的標記，您就可以看到資訊視窗的實際樣子。

GInfoWindow 物件沒有建構函式。建立地圖時，會自動建立資訊視窗，並附加至該地圖。在指定地圖中，一次只能顯示一個資訊視窗，不過您可以移動資訊視窗，並視需要變更其內容。

GMap2 物件提供 openInfoWindow() 方法，可接受點和 HTML DOM 元素為引數。HTML DOM 元素已附加至資訊視窗容器，而該資訊視窗視提示會錨定在指定的點。

GMap2 的 openInfoWindowHtml() 方法也類似，但是它接受 HTML 字串做為它的第二個引數，而不是 DOM 元素。

要建立資訊視窗，請呼叫 openInfoWindow 方法，並將要顯示的位置和 DOM 元素傳送給它。下列範例程式碼顯示的資訊視窗，會位於地圖的中央，並顯示簡單的「Hello, world」訊息。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
map.openInfoWindow(map.getCenter(),
                   document.createTextNode("Hello, world"));

檢視範例 (map-infowindow.html)

如需關於資訊視窗的完整說明，請參閱 Google 地圖 API 參考文件