谷歌地圖開發

<!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://ditu.google.cn/maps?file=api&v=2&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(39.9493, 116.3975), 13);
     }
   }

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

您能夠查看此示例及下載、編輯和調試該示例，但必須將該文件中的密鑰替換爲您本身的 Google 地圖 API 密鑰。（若是註冊了特定目錄的密鑰，也能夠將其用於全部子目錄。）

即便在此簡單的示例中，也須要注意五點：

7 使用 script 標籤包含 Google 地圖 API JavaScript。

8 建立名爲「map_canvas」的 div 元素來包含地圖。

9 編寫 JavaScript 函數建立「map」對象。

10 將地圖的中心設置爲指定的地理點。

11 從 body 標籤的 onLoad 事件初始化地圖對象。

下面說明了這些步驟。

加載 Google 地圖 API

http://ditu.google.cn/maps?file=api&v=2&key=abcdefg 網址指向包含使用 Google 地圖 API 所需全部符號和定義的 JavaScript 文件的位置。您的頁面必須包含指向此網址的 script 標籤，使用註冊 API 時收到的密鑰。在此示例中，該密鑰顯示爲「abcdefg」。

請注意，咱們也傳遞 sensor 參數以指明此應用程序是否使用傳感器來肯定用戶位置。在此示例中，咱們將其設爲變量「true_or_false」以強調您必須顯式地將此值設置爲 true 或 false。

地圖 DOM 元素

要讓地圖在網頁上顯示，必須爲其留出一個位置。一般，咱們經過建立名爲 div 的元素並在瀏覽器的文檔對象模型 (DOM) 中獲取此元素的引用執行此操做。

在上述示例中，咱們定義名爲「map_canvas」的 div，並使用樣式屬性設置其尺寸。地圖會自動使用容器尺寸調整自身的尺寸，除非使用構造函數中的 GMapOptions 顯式地爲地圖指定尺寸。

GMap2 - 基本對象

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

GMap2 類是表示地圖的 JavaScript 類。此類的對象在頁面上定義單個地圖。（能夠建立此類的多個實例，每一個對象將在頁面上定義一個不一樣的地圖。）咱們使用 JavaScript new 操做符建立此類的一個新實例。

當建立新的地圖實例時，在頁面中指定一個 DOM 節點（一般是 div 元素）做爲地圖的容器。HTML 節點是 JavaScript document 對象的子對象，並且咱們經過 document.getElementById() 方法得到該元素的引用。

此代碼定義了一個變量（名爲 map），並將新 GMap2 對象賦值給該變量。函數 GMap2() 稱爲「構造函數」，其定義（在 Google 地圖 API 參考中簡述）以下所示：

構造函數	說明
GMap2(container, opts?)	在一般是一個 DIV 元素的指定 HTML container 內建立新地圖。您也能夠經過 opts 參數傳遞 GMap2Options 類型的可選參數。

請注意由於 JavaScript 是鬆散類型的語言，咱們能夠不填寫構造函數的任何可選參數，此處也未這樣作。

初始化地圖

map.setCenter(new GLatLng(39.9493, 116.3975), 13);

經過 GMap2 構造函數建立地圖後，咱們須要再作一件事：將其初始化。初始化經過地圖的 setCenter() 方法完成。setCenter() 方法要求有 GLatLng 座標和縮放級別，並且必須先發送此方法，而後再在地圖上執行其餘任何操做，包括設置地圖自己的其餘任何屬性。

加載地圖

當 HTML 頁面顯示時，文檔對象模型 (DOM) 即會擴展，接收其餘外部圖像和腳本並將其合併到 document 對象中。爲確保咱們的地圖僅放置在徹底加載後的頁面上，咱們僅在 HTML 頁面的 <body> 元素收到 onload 事件後才執行構造 GMap2 對象的函數。這樣作能夠避免出現不可預期的行爲，並使咱們能夠對地圖繪製的方式和時間進行更多控制。

onload 屬性是事件處理程序的示例。Google 地圖 API 還提供了大量事件能夠用來「監聽」狀態變化。請參閱地圖事件和事件監聽器以瞭解更多信息。

GUnload() 函數是用來防止內存泄漏的實用工具函數。

經度和緯度

既然如今已經有地圖了，咱們還須要一種方法來引用地圖上的位置。在 Google 地圖 API 中，GLatLng 對象提供了此類機制。能夠構造一個 GLatLng 對象，按照製圖學的慣例以 {經度, 緯度} 的順序傳遞參數：

var myGeographicCoordinates= new GLatLng(myLatitude, myLongitude)

注意：將「地址」轉變爲地理點的過程稱爲「地址解析」，將在「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(39.9493, 116.3975), 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://ditu.google.cn 上同樣，地圖對象會對用戶的活動作出反應。但您可使用大量實用工具方法改變此行爲。例如，GMap2.disableDragging() 方法禁止了點擊並拖拽地圖到新位置的功能。

您還能夠經過編程與地圖交互。GMap2 對象支持能夠直接改變地圖狀態的大量方法。例如，setCenter()、panTo 和 zoomIn() 方法經過編程來操做地圖，而不是經過用戶交互來操做地圖。

下面的示例顯示一個地圖，等待兩秒鐘，而後平移到新中心點。panTo 方法將地圖中心設置在指定點處。若是指定點位於地圖的可見部分，則地圖會平穩地平移到該點，不然會跳至該點。

var map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(39.9493, 116.3975), 13);
window.setTimeout(function() {
map.panTo(new GLatLng(39.927, 116.407));
}, 1000);

查看示例 (map-animate.html)

能夠經過使用 Google 地圖 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(39.9493, 116.3975), 13);
map.openInfoWindow(map.getCenter(),
document.createTextNode("Hello, world"));

查看示例 (map-infowindow.html)

有關信息窗口的完整文檔，請查閱 Google 地圖 API 參考

事件

1 地圖事件概述

2 事件監聽器

3 在事件監聽器中使用閉包

4 在事件中使用傳遞的參數

5 將事件綁定到對象

6 監聽 DOM 事件

7 刪除事件監聽器

地圖事件概述

瀏覽器中的 JavaScript 是「事件驅動的」，這表示 JavaScript 經過生成事件來響應交互，並指望程序可以「監聽」感興趣的活動。例如，在瀏覽器中，用戶的鼠標和鍵盤交互能夠建立在 DOM 內傳播的事件。對某些事件感興趣的程序會爲這些事件註冊 JavaScript 事件監聽器，並在接收這些事件時執行代碼。

Google 地圖 API 經過爲地圖 API 對象定義自定義事件而添加到此事件模型中。請注意，地圖 API 事件是獨立的，與標準 DOM 事件不一樣。可是，因爲不一樣的瀏覽器實現不一樣的 DOM 事件模型，所以地圖 API 還提供監聽和響應這些 DOM 事件但無需處理各類跨瀏覽器特性的機制。

事件監聽器

經過使用 GEvent 命名空間中的實用工具函數註冊事件監聽器，來處理 Google 地圖 API 中的事件。每一個地圖 API 對象都導出大量已命名的事件。例如，GMap2 對象導出 click、dblclick 和 move 事件，以及其餘許多事件。每一個事件都在指定的環境下發生，而且能夠傳遞標識環境的參數。例如，當用戶在地圖對象中移動鼠標時，會觸發 mousemove 事件，而且該事件會傳遞鼠標所在地理位置的 GLatLng。

有關 GMap2 事件及其生成的參數的完整列表，請參見 GMap2.Events。

註冊用來獲取這些事件的相關通知的監聽器，請使用靜態方法 GEvent.addListener()。該方法有三個參數，一個對象，一個待監聽事件以及一個在指定事件發生時調用的函數。例如，每當用戶點擊地圖時,下面的代碼段都會顯示警告:

var map= new GMap2(document.getElementById("map"));
map.setCenter(new GLatLng(39.9493, 116.3975), 13);
GEvent.addListener(map, "click", function() {
alert("您點擊了地圖。");
});

查看示例 (event-simple.html)

監聽器也可以捕獲事件的環境。在下面的示例代碼中，顯示用戶拖動地圖後地圖中心的經度和緯度。

var map= new GMap2(document.getElementById("map"));
GEvent.addListener(map, "moveend", function() {
var center= map.getCenter();
document.getElementById("message").innerHTML= center.toString();
});
map.setCenter(new GLatLng(39.9493, 116.3975), 13);

查看示例 (event-context.html)

在事件監聽器中使用閉包

當執行事件監聽器時，一個經常使用的好方法就是將私有數據和持久性數據附加到一個對象。JavaScript 不支持「私有」實例數據，但它卻支持閉包，閉包容許內部函數訪問外部變量。在事件監聽器中，訪問一般不附加到發生事件的對象的變量時，閉包很是有用。

下面的示例在事件監聽器中使用函數閉包將加密消息分配給一組標記。點擊每一個標記均可以看到加密消息的一部分，該消息並不包含在標記自身內部。

查看示例 (event-closure.html)

在事件中使用傳遞的參數

地圖 API 事件系統中的許多事件在觸發事件時都會傳遞參數。例如，若是地圖點擊發生在疊加層上，GMap2「點擊」事件會傳遞 overlay 和 overlaylatlng；不然，它傳遞地圖座標的 latlng。能夠經過將指定的符號直接傳遞給事件監聽器中的函數來訪問這些參數。

在下面的示例中，咱們首先進行測試，即檢查是否認義了 latlng 參數，以確保點擊發生在地圖圖塊上；這樣，咱們就能夠在座標點的上方打開一個信息窗口，並在信息窗口中顯示轉化爲像素的座標以及地圖的縮放級別。

var map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(39.9493, 116.3975), 13);

GEvent.addListener(map,"click", function(overlay, latlng) {
if (latlng) {
   var myHtml= "GPoint 爲: " + map.fromLatLngToDivPixel(latlng) + ",
縮放級別:" + map.getZoom();
    map.openInfoWindow(latlng, myHtml);
}
});
map.addControl(new GSmallMapControl());    //增長控制條
map.addControl(new GMapTypeControl());      //增長衛星地圖和普通地圖的顯示

查看示例 (event-arguments.html)

將事件綁定到對象方法

當您但願將事件監聽器附加到對象的特定實例時，函數很是有用。若是您不但願這樣，而是但願響應事件時對象的全部實例都調用某方法，可使用 GEvent.bind()。在下面的示例中，MyApplication 的實例將地圖事件與其成員方法綁定在一塊兒，當觸發事件時會修改類狀態：

function MyApplication() {
this.counter= 0;
this.map= new GMap2(document.getElementById("map"));
this.map.setCenter(new GLatLng(39.9493, 116.3975), 13);
GEvent.bind(this.map, "click", this, this.onMapClick);
}

MyApplication.prototype.onMapClick= function() {
this.counter++;
alert("這是您第" + this.counter+ " " +
"次點擊"
}

var application= new MyApplication();

查看示例 (event-bind.html)

監聽 DOM 事件

Google 地圖 API 事件模型建立並管理本身的自定義事件。可是，DOM 也會根據當前使用的特定瀏覽器事件模型建立和調度本身的事件。若是您但願捕獲並響應這些事件，Google 地圖 API 提供的獨立於瀏覽器的包裝器能夠監聽和綁定 DOM 事件而不須要自定義代碼。

GEvent.addDomListener() 靜態方法爲 DOM 節點上的 DOM 事件註冊事件處理程序。一樣，GEvent.bindDom() 靜態方法容許您爲類實例上的 DOM 事件註冊事件處理程序。

刪除事件監聽器

再也不須要事件監聽器時，應將其刪除。甚至在事件只需觸發一次的狀況下，也可能須要刪除。刪除閉包內的匿名函數所定義的事件監聽器可能很困難。可是，addListener()、addDomListener()、bind() 和 bindDom() 函數會返回 GEventListener 句柄，可用來最終取消註冊處理程序。

下面的示例經過在地圖上放置標記來響應點擊。任何後續點擊均可刪除事件監聽器。請注意，這會致使再也不執行 removeOverlay() 代碼。另請注意，您甚至能夠從事件監聽器自身內部刪除事件監聽器。

查看示例 (event-removal.html)

控件

1 地圖控件概述

2 向地圖添加控件

3 在地圖上放置控件

4 修改標準控件的結構

5 建立自定義控件

控件概述

http://ditu.google.cn 上的地圖包含容許用戶與地圖交互的 UI 元素，這些元素稱爲「控件」。您能夠在 Google 地圖 API 應用程序中添加這些控件的多種組合。您還能夠經過子類化 GControl 類來構建本身的自定義控件。

地圖 API 帶有大量能夠在地圖中使用的內置控件：

· GLargeMapControl - 一個在 Google 地圖上使用的大平移/縮放控件。默認狀況下顯示在地圖的左上角。

· GSmallMapControl - 一個在 Google 地圖上使用的小一點的平移/縮放控件。默認狀況下顯示在地圖的左上角。

· GSmallZoomControl - 小型縮放控件（無平移控件），用於在 Google 地圖上顯示行車路線的小地圖彈出窗口。

· GScaleControl - 地圖比例尺

· GMapTypeControl - 讓用戶切換地圖類型（例如「地圖」和「衛星」）的按鈕

· GHierarchicalMapTypeControl - 用於放置多個地圖類型選擇器的一組精選的嵌套按鈕和菜單項。

· GOverviewMapControl - 位於屏幕一角的可摺疊概覽地圖。

全部這些控件都基於 GControl 對象。

GMapTypeControl 和 GHierarchicalMapTypeControl 是特殊狀況，由於它們還能夠進行配置。這些控件增長的功能能夠更改 Google 地圖 API 中的地圖當前所用的 GMapType。有關配置這些控件的詳細信息，請參見修改標準控件的結構。

下面是當前支持的地圖類型列表：

· G_NORMAL_MAP 顯示 Google 地圖默認的普通二維圖塊

· G_SATELLITE_MAP 顯示拍攝的圖塊

· G_HYBRID_MAP 同時顯示拍攝的圖塊和普通（突出顯示道路、城市名等明顯地圖特徵）圖塊

· G_PHYSICAL_MAP 根據地形信息顯示實際地圖圖塊

若是您有圖像或者已經定義好的疊加層，也能夠定義本身的自定義地圖類型。

默認狀況下，Google 地圖 API 提供三種地圖類型：G_NORMAL_MAP、G_SATELLITE_MAP 和 G_HYBRID_MAP。您能夠經過這兩種方式來改變地圖上可用的地圖類型：使用 GMap2.removeMapType() 刪除地圖類型；使用 GMap2.addMapType() 添加地圖類型。不管您什麼時候建立地圖類型控件，它都使用當前地圖上已經添加的地圖類型，並經過控件讓用戶能夠切換這些地圖類型。請注意，您必須在添加地圖類型控件（主要指 GHierarchicalMapTypeControl）以前指定各地圖類型之間的階層關係，以便地圖類型控件能夠準確反映這些關係。

使用下面的代碼可將 G_HYBRID_MAP 從添加到地圖上的可用地圖類型中刪除，只剩下兩種地圖類型。添加 GMapTypeControl 後，便只有這兩種地圖類型可用。

var map= new GMap2(document.getElementById("map_canvas"),
{ size: new GSize(640,320) } );
map.removeMapType(G_HYBRID_MAP);
map.setCenter(new GLatLng(39.927, 116.407), 11);
var mapControl= new GMapTypeControl();
map.addControl(mapControl);
map.addControl(new GLargeMapControl());

查看示例 (control-maptypes.html)

向地圖添加控件

可使用 GMap2 方法 addControl() 向地圖添加控件。例如，要將 Google 地圖上顯示的平移/縮放控件添加到您的地圖中，您能夠在您的地圖初始化代碼中添加下面這行語句：

map.addControl(new GLargeMapControl());

能夠向地圖添加多個控件。在本例中，咱們添加內置 GSmallMapControl 和 GMapTypeControl 控件，它們分別能夠平移/縮放地圖以及切換「地圖」與「衛星」這兩種類型。在地圖中添加標準控件後，它們即刻徹底生效。

var map= new GMap2(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(39.9493, 116.3975), 13);

查看示例 (control-simple.html)

在地圖上放置控件

addControl 方法有第二個可選的參數 GControlPosition，可用於指定控件在地圖上的位置。它能夠是如下值之一，這些值分別指定要放置控件的地圖某個角：

· G_ANCHOR_TOP_RIGHT

· G_ANCHOR_TOP_LEFT

· G_ANCHOR_BOTTOM_RIGHT

· G_ANCHOR_BOTTOM_LEFT

若是不包含此參數，則地圖 API 會使用控件指定的默認位置。

GControlPosition 還能夠指定偏移量，來指示控件的放置位置與地圖邊界間隔多少像素。這些偏移量使用 GSize 對象指定。

本示例會將 GMapTypeControl 添加到地圖的右上角，填充爲 10 個像素。雙擊地圖上的任何位置能夠刪除該控件，將其放在地圖的右下角。

var map= new GMap2(document.getElementById"map_canvas"));
var mapTypeControl= new GMapTypeControl();
var topRight= new GControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(10,10));
var bottomRight= new GControlPosition(G_ANCHOR_BOTTOM_RIGHT, new GSize(10,10));
map.addControl(mapTypeControl, topRight);
GEvent.addListener(map, "dblclick", function() {
map.removeControl(mapTypeControl);
map.addControl(new GMapTypeControl(), bottomRight);
});
map.addControl(new GSmallMapControl());
map.setCenter(new GLatLng(39.9493, 116.3975), 13);

查看示例 (control-positioning.html)

請參見 GControlPosition 類參考以瞭解詳細信息。

修改標準控件的結構

Google 地圖 API 內的大多數控件都提供具備標準行爲的簡單控件。可是，有些控件須要初始化才能正常使用。例如，GHierarchicalMapTypeControl 一般須要必定的初始化才能在層疊「菜單」中以正確順序顯示地圖類型。

此示例將帶有十字準線圖塊層疊加層的 G_PHYSICAL_MAP 地圖類型添加到地圖中，而後建立 GHierarchicalMapTypeControl 來排列添加到地圖的其餘地圖類型。

// define the crosshair（標準線） tile layer and its required functions
var crossLayer= new GTileLayer(new GCopyrightCollection(""), 0, 15);

crossLayer.getTileUrl= function(tile, zoom) {
return "./include/tile_crosshairs.png";
}
crossLayer.isPng= function() {return true;}

// Create a new map type incorporating the tile layer
var layerTerCross= [ G_PHYSICAL_MAP.getTileLayers()[0], crossLayer];
var mtTerCross= new GMapType(layerTerCross,
G_PHYSICAL_MAP.getProjection(), "Ter+");

var map= new GMap2(document.getElementById("map_canvas"),
{ size: new GSize(640,320) } );
map.addMapType(G_PHYSICAL_MAP);
map.addMapType(mtTerCross);
map.setCenter(new GLatLng(39.9493, 116.3975), 4);
var mapControl= new GHierarchicalMapTypeControl();

// Set up map type menu relationships
mapControl.clearRelationships();
mapControl.addRelationship(G_SATELLITE_MAP, G_HYBRID_MAP, "文字標記", false);
mapControl.addRelationship(G_PHYSICAL_MAP, mtTerCross, "十字交叉");

// Add control after you've specified the relationships
map.addControl(mapControl);

map.addControl(new GLargeMapControl());

查看示例 (control-initialization.html)

自定義地圖控件

Google 地圖 API 還容許您經過子類化 GControl 來建立自定義地圖控件。（您並無在 JavaScript 中實現一個「子類化」對象，而是把這個對象的 prototype 指定爲 GControl 對象的實例。）

要建立可用的自定義控件，您須要實如今該類中定義的至少兩個方法：initialize() 和 getDefaultPosition()。initialize() 方法必須返回 DOM 元素，而 getDefaultPosition() 方法必須返回類型爲 GControlPosition 的對象。

全部自定義的地圖控件中的 DOM 元素最終都應該添加到地圖容器（也是 DOM 元素）中去，這個地圖容器能夠經過 GMap2 getContainer() 方法得到。

在此示例中，咱們建立一個簡單的縮放控件，它具備文本連接，而不是標準 Google 地圖縮放控件中使用的圖形圖標。

// A TextualZoomControl is a GControl that displays textual "Zoom In"
// and "Zoom Out" buttons (as opposed to the iconic buttons used in
// Google Maps).

// We define the function first
function TextualZoomControl() {
}

// To "subclass" the GControl, we set the prototype object to
// an instance of the GControl object
TextualZoomControl.prototype= new GControl();

// Creates a one DIV for each of the buttons and places them in a container
// DIV which is returned as our control element. We add the control to
// to the map container and return the element for the map class to
// position properly.
TextualZoomControl.prototype.initialize= function(map) {
var container= document.createElement("div");

var zoomInDiv= document.createElement("div");
this.setButtonStyle_(zoomInDiv);
container.appendChild(zoomInDiv);
zoomInDiv.appendChild(document.createTextNode("放大"));
GEvent.addDomListener(zoomInDiv, "click", function() {
map.zoomIn();
});

var zoomOutDiv= document.createElement("div");
this.setButtonStyle_(zoomOutDiv);
container.appendChild(zoomOutDiv);
zoomOutDiv.appendChild(document.createTextNode("縮小"));
GEvent.addDomListener(zoomOutDiv, "click", function() {
map.zoomOut();
});

map.getContainer().appendChild(container);
return container;
}

// By default, the control will appear in the top left corner of the
// map with 7 pixels of padding.
TextualZoomControl.prototype.getDefaultPosition= function() {
return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(7, 7));
}

// Sets the proper CSS for the given button element.
TextualZoomControl.prototype.setButtonStyle_= function(button) {
button.style.textDecoration= "underline";
button.style.color= "#0000cc";
button.style.backgroundColor= "white";
button.style.font= "small Arial";
button.style.border= "1px solid black";
button.style.padding= "2px";
button.style.marginBottom= "3px";
button.style.textAlign= "center";
button.style.width= "6em";
button.style.cursor= "pointer";
}

var map= new GMap2(document.getElementById("map"));
map.addControl(new TextualZoomControl());
map.setCenter(new GLatLng(37.441944, -122.141944), 13);

查看示例 (control-custom.html)

地圖疊加層

1 地圖疊加層概述

2 標記

2 圖標

3 折線

4 多邊形

5 底面疊加層

6 圖塊疊加層

7 層

8 自定義疊加層

地圖疊加層概述

疊加層是地圖上綁定到經度/緯度座標的對象，會隨您拖動或縮放地圖而移動。疊加層用於反映您「添加」到地圖上以指明點、線或區域的對象。。

地圖 API 有以下幾種疊加層：

· 地圖上的點使用標記來顯示，一般顯示自定義圖標。標記是 GMarker 類型的對象，而且能夠利用 GIcon 類型的對象來自定義圖標。

· 地圖上的線使用折線（表示點的集合）來顯示。線是類型爲 GPolyline 的對象。

· 地圖上的區域顯示爲多邊形（若是是任意形狀的區域）或底面疊加層（若是是矩形區域）。多邊形相似於閉合的折線，所以能夠是任何形狀。地面疊加層一般用於地圖上與圖塊有直接或間接關聯的區域。

· 地圖自己使用圖塊疊加層顯示。若是您有本身的系列圖塊，可使用 GTileLayerOverlay 類來改變地圖上已有的圖塊，甚至可使用 GMapType 來建立您本身的地圖類型。

· 信息窗口也是一種特殊的疊加層。可是請注意，信息窗口會自動添加到地圖中，而且地圖只能添加一個類型爲 GInfoWindow 的對象。

每一個疊加層都實現 GOverlay 接口。可使用 GMap2.addOverlay() 方法向地圖添加疊加層，使用 GMap2.removeOverlay() 方法刪除疊加層。（請注意，默認狀況下信息窗口會自動添加到地圖。）

標記

標記標識地圖上的點。默認狀況下，它們使用 G_DEFAULT_ICON（您也能夠指定自定義圖標）。GMarker 構造函數將 GLatLng 和 GMarkerOptions（可選）對象做爲參數。

標記設計爲可交互。例如，默認狀況下它們接收 "click" 事件，經常使用於在事件偵聽器中打開信息窗口。

var map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(39.9493, 116.3975), 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));
}

查看示例 (marker-simple.html)

可拖動的標記

標記是能夠點擊和拖動到新位置的交互式對象。在此示例中，咱們將一個可拖動的標記放置在地圖上，並監聽它的幾個較簡單事件。可拖動標記經過實現如下四類事件來表示其拖動狀態：click、dragstart、drag 和 dragend。默認狀況下，標記可點擊但不可拖動，因此它們須要經過將額外的標記選項 draggable 設置爲 true 來初始化。可拖動標記拖動結束後默認有彈跳效果。若是不喜歡這種效果，請將 bouncy 選項設置爲 false，標記會平緩放下。

查看示例 (marker-drag.html)

圖標（標記）

標記能夠用自定義的新圖標來顯示，以替代默認圖標。由於地圖 API 中一個圖標（GIcon 對象）須要由多個不一樣的圖像組成，因此定義圖標較爲複雜。一個圖標最少應定義前景圖像、類型爲 GSize 的尺寸和用於定位圖標的圖標偏移值。

最簡單的自定義圖標是基於 G_DEFAULT_ICON 類型來建立。基於此類型建立圖標讓您僅經過修改若干屬性便可快速更改默認圖標。

在下面的示例中，咱們先用 G_DEFAULT_ICON 類型建立一個圖標，而後使用其餘圖像來改變默認圖像。（使用不一樣圖像時要謹慎，由於它們須要設置爲與默認圖像相同的正確尺寸才能正常顯示。）

var map= new GMap2(document.getElementById("map_canvas"));
map.addControl(new GSmallMapControl());
map.setCenter(new GLatLng(39.9493, 116.3975), 13);

// Create our "tiny" marker icon
var blueIcon= new GIcon(G_DEFAULT_ICON);
blueIcon.image= "http://www.google.cn/intl/en_us/mapfiles/ms/micons/blue-dot.png";

// Set up our GMarkerOptions object
markerOptions= { icon:blueIcon};

// 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, markerOptions));
}

查看示例 (icon-simple.html)

多數圖標包含前景圖像和陰影圖像。陰影圖像應該和前景圖像成 45 度夾角（向右上方傾斜），陰影圖像的左下角應與圖標前景圖像的左下角對齊。陰影圖像應是通過 Alpha 透明處理的 24 位 PNG 圖像，以便圖像邊界能夠在地圖上正確顯示。

如下示例使用 Google Ride Finder「迷你」標記爲例，建立一種新類型的圖標。咱們必須指定前景圖像、陰影圖像以及一些將圖標錨定到地圖、將信息窗口錨定到圖標的點。請注意該圖標的參數都是經過 GMarkerOptions 中的選項來指定的。

var map= new GMap2(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(39.9493, 116.3975), 13);

// Create our "tiny" marker icon
var tinyIcon= new GIcon();
tinyIcon.image= "http://labs.google.com/ridefinder/images/mm_20_red.png";
tinyIcon.shadow= "http://labs.google.com/ridefinder/images/mm_20_shadow.png";
tinyIcon.iconSize= new GSize(12, 20);
tinyIcon.shadowSize= new GSize(22, 20);
tinyIcon.iconAnchor= new GPoint(6, 20);
tinyIcon.infoWindowAnchor= new GPoint(5, 1);

// Set up our GMarkerOptions object literal
markerOptions= { icon:tinyIcon};

// 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, markerOptions));
}

請注意 GMarkerOptions 對象的定義演示了「對象常量」表示法的用法。該對象不是使用構造函數實例化的，而只是使用名-值對進行聲明。

查看示例 (icon-complex.html)

自定義圖標

GIcon 對象也有若干其餘屬性，應對其進行適當設置，以便使您的圖標獲取最佳的瀏覽器兼容性和功能。例如，imageMap 屬性指定圖標圖像不透明部分的形狀。若是不在圖標中設置此屬性，則整個圖標圖像（包括透明部分）在 Firefox/Mozilla 中都將是可點擊的。有關詳細信息，請參閱 GIcon 類參考。

在許多狀況下，圖標能夠有不一樣的前景，但具備相同的形狀和陰影。最簡單的實現方式是使用 GIcon 類的構造函數「複製」已有的圖標（好比 G_DEFAULT_ICON，將其做爲 GIcon 的 copy 參數），它將複製該圖標全部的默認屬性，而後您能夠對其進行自定義。

查看示例 (icon-custom.html)

使用標記管理器

向 Google 地圖添加大量標記可能會下降顯示地圖的速度，還會使視覺效果過於混亂，對於某些縮放級別尤爲如此。標記管理器實用工具提供了一個解決這些問題的方案，容許在同一個地圖上高效顯示數百個標記，並可以指定應顯示標記的縮放級別。

GMaps 實用工具庫中提供標記管理器實用工具。該庫爲開源，包含不屬於核心 Google 地圖 API 的工具。要添加該庫中包含的工具，可使用 <script> 標籤直接添加 JavaScript 源代碼。

markermanager.js 庫中的 MarkerManager 對象會用實用工具管理已註冊的標記，記錄當前視圖的特定縮放級別中哪些標記可見，並僅將這些標記傳遞給地圖以進行繪製，從而免除了管理重擔。管理器監控地圖的當前視圖和縮放級別，動態地從地圖中添加或刪除有效標記。此外，開發人員能夠經過容許標記指定顯示自身的縮放級別來實現標記集羣。此類管理能夠大大加快地圖的顯示並減小視覺混亂。

要使用標記管理器，請建立一個 MarkerManager 對象。在最簡單的狀況下，只需向其傳遞地圖便可。

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

還能夠指定大量選項來微調標記管理器的性能。這些選項經過 MarkerManagerOptions 對象傳遞，該對象包含如下屬性：

· maxZoom：指定受此標記管理器所監控的最高縮放級別。默認值是 Google 地圖支持的最高縮放級別。

· borderPadding：指定當前視口外受管理器監控的其餘填充區域（以像素爲單位）。這容許視線外的標記在地圖上預加載，提升了地圖小範圍平移的性能。默認值是 100。

· trackMarkers：指定標記管理器是否應跟蹤標記的移動。若是要管理經過 setPoint() 方法更改位置的標記，請將此值設置爲 true。默認狀況下，此標記設置爲 false。請注意，若是在此值設置爲 false 的狀況下移動標記，標記將同時在原始位置和新位置顯示。

MarkerManagerOptions 對象是對象常量，因此只需聲明該對象而無需構造函數：

var map= new GMap2(document.getElementById("map_canvas"));
var mgrOptions= { borderPadding: 50, maxZoom: 15, trackMarkers: true };
var mgr= new MarkerManager(map, mgrOptions);

建立管理器後，您可能想向其中添加標記。MarkerManager 支持使用 addMarker() 方法一次添加一個標記，或者使用 addMarkers() 方法添加由多個標記組成的數組。若是使用 addMarker() 添加的單個標記位於當前視圖並在指定的縮放級別限制內，則它們會在地圖上當即顯示。

建議使用 addMarkers() 集中添加標記，由於這樣更高效。只有顯式地調用 MarkerManager 的 refresh() 方法，使用 addMarkers() 方法添加的標記纔會顯示在地圖上，這會將當前視口和邊界填充區域內的全部標記添加到地圖中。首次顯示後，MarkerManager 能夠經過監控地圖的「moveend」事件來監控全部可見的更新。

縮放級別示例：天氣地圖

如下示例建立歐洲的模擬天氣地圖。在縮放級別 3 時，顯示 20 個隨機分佈的天氣圖標。在級別 6 時，能夠輕鬆地辨別出全部 200 我的口超過 30 萬的城市，並顯示額外 200 個標記。最後，在級別 8 時，會顯示 1000 個標記。（注意：爲了簡化示例，標記將添加在隨機位置。）

查看示例 (weather_map.html)

集羣示例：Google 辦事處

標記管理器也能夠執行簡單的標記集羣。雖然不是自動執行此操做，但您能夠經過設置顯示指定標記的最大縮放級別和最小縮放級別來實現所需效果。在此示例中，咱們建立 Google 在北美的辦事處地圖。在最高的級別，咱們在辦事處所處國家或地區顯示標記。對於縮放級別 3 到 7，咱們在一個或多個辦事處所處人口中心顯示圖標。最後，在級別 8 或更高級別，咱們爲每一個辦事處顯示一個標記。

查看示例 (google_northamerica_offices.html)

有關詳細信息，請參閱開源標記管理器的參考文檔。

折線

GPolyline 對象可在地圖上建立線性疊加層。GPolyline 包括一系列點，並建立一系列有序鏈接這些點的線段。

繪製折線

折線在地圖上繪製爲一系列直線段。能夠自定義這些線段的顏色、粗細和透明度。顏色應是十六進制數字 HTML 樣式，例如使用 #ff0000 而非 red。GPolyline 沒法識別命名顏色。

GPolyline 對象使用瀏覽器的矢量繪製功能（若是可用）。在 Internet Explorer 中，Google 地圖使用 VML（請參閱 XHTML 和 VML）繪製折線；在其餘瀏覽器中使用 SVG（若是可用）。在全部其餘環境中，咱們從 Google 服務器請求一個線段圖像並將該圖像疊加到地圖上，當地圖縮放和拖動時按須要刷新圖像。

如下代碼段會在兩點之間建立 10 像素寬的紅色折線：

var polyline= new GPolyline([
new GLatLng(39.9493, 116.3975),
new GLatLng(39.9593, 116.4071)
], "#ff0000", 10);
map.addOverlay(polyline);

查看示例 (polyline-simple.html)

測地折線

在地圖上表示的折線是符合當前投影的直線。即它們在地圖上顯示爲直的，但實際上可能沒有正確考慮到地球的弧度。若是想繪製測地線（「大圓球」的一段，表示地球表面上兩點之間的最短距離），則須要經過 GPolyline 的 GPolylineOptions 參數傳遞 geodesic:true。

GPolylineOptions 對象是一個對象常量的示例。若是使用對象常量，則無需構造對象。而是能夠將參數做爲一系列名/值對在花括號中傳遞。對象常量常常用於不須要實例化對象的狀況。

var map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37, 107), 2);

// Create GPolylineOptions argument as an object literal.
// Note that we don't use a constructor.

var polyOptions= {geodesic:true};
var polyline= new GPolyline([
new GLatLng(50, 120),
new GLatLng(30, 100)
], "#ff0000", 10, 1, polyOptions);
map.addOverlay(polyline);

查看示例 (polyline-geodesic.html)

編碼折線

Google 地圖中的 GPolyline 對象將直線表示爲一系列點，使其易於使用但不必定緊湊。長線和複雜的線須要大量內存，繪製起來也須要更長時間。同時，在地圖上繪製非編碼折線中的線段時，不會考慮較大縮放級別時的分辨率。

Google 地圖 API 可以讓您使用編碼折線表示路徑，編碼折線使用 ASCII 字符的壓縮格式在 GPolyline 中指定一系列點。編碼折線還可以讓您指定繪製線段時應忽略的縮放級別組，這樣您就能夠指定一條折線在指定縮放級別的詳細程度。儘管編碼折線設置起來更困難，但它們可以使您更高效地繪製疊加層。

例如，3 個點的 GPolyline（兩條線段）一般表示爲：

var polyline= new GPolyline([
   new GLatLng(39.9493, 116.3975),
   new GLatLng(39.9593, 116.4071),
   new GLatLng( 37.4619, -122.1819)
], "#FF0000", 10);
map.addOverlay(polyline);

這些點的編碼 GPolyline 以下所示（眼下先不考慮編碼算法的特殊要求）。

var encodedPolyline= new GPolyline.fromEncoded({
    color: "#FF0000",
    weight: 10,
    points: "yzocFzynhVq}@n}@o}@nzD",
    levels: "BBB",
    zoomFactor: 32,
    numLevels: 4
});
map.addOverlay(encodedPolyline);

關於此代碼要注意兩點。

9 第一，各系列點在編碼折線中表示爲一系列 ASCII 字符，而在基本 GPolyline 中卻使用常見的經度和緯度。將這些點建立爲一系列編碼 ASCII 值的算法位於此處。若是要經過服務器進程動態計算編碼折線（舉例而言），則須要此算法。可是，若是隻想要轉換現有點指定的經度和緯度，則可使用咱們的交互實用工具。

10 第二，編碼折線還容許您指定每一個線段在 Google 地圖上繪製自身的最大縮放級別。若是在較高的縮放級別上未顯示某個點，則只繪製先前可顯示的點到下一個可顯示的點之間的路徑。請注意，此特性在非編碼 GPolyline 中不可用，它在如下狀況下特別有用：容許在高縮放級別（某些線段的細節可能不相關）下快速繪製。例如，當地圖縮小到州級別時，表示從紐約到芝加哥行車路線的編碼折線應不關心表示曼哈頓特定街道的線段。

查看示例 (polyline-encoding.html)

交互編碼折線實用工具

請參閱折線算法以瞭解有關底層編碼折線算法的信息。

多邊形

GPolygon 對象相似於 GPolyline 對象，由於它們都包括一系列有序的點。可是，多邊形不像折線同樣有兩個端點，而是設計爲定義造成閉環的區域。和折線同樣，您能夠自定義多邊形邊（線）的顏色、粗細和透明度，以及封閉的填充區域的顏色和透明度。顏色應是十六進制數字 HTML 樣式。

GPolygon 對象相似於 GPolyline對象，使用瀏覽器的矢量繪製功能（若是可用）。

下面的代碼段用四個點建立一個 10 像素寬的方框。請注意，此多邊形是「封閉的」，即線段路徑的終點與始點重合；始終應閉合多邊形以免發生未定義的行爲。

var map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(39.9493, 116.3975), 13);
map.addControl(new GSmallMapControl());
GEvent.addListener(map, 'click', function(overlay, latlng) {
var lat= latlng.lat();
var lon= latlng.lng();
var latOffset= 0.01;
var lonOffset= 0.01;
var polygon= new GPolygon([
   new GLatLng(lat, lon- lonOffset),
   new GLatLng(lat+ latOffset, lon),
   new GLatLng(lat, lon+ lonOffset),
   new GLatLng(lat- latOffset, lon),
   new GLatLng(lat, lon- lonOffset)
], "#f33f00", 5, 1, "#ff0000", 0.2);
map.addOverlay(polygon);
});

查看示例 (polygon-simple.html)

底面疊加層

多邊形是很是有用的疊加層，可表示任意大小的區域，但不能顯示圖像。若是您有一個要放置在地圖上的圖像，可使用 GGroundOverlay 對象。 GGroundOverlay 的構造函數將圖像的網址和圖像的 GLatLngBounds 做爲參數。

下面的示例將美國新澤西州紐華克的舊地圖做爲疊加層放在地圖上：

var map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(36.0, 113), 12);
// ground overlay

var boundaries= new GLatLngBounds(new GLatLng(35.5, 112), new GLatLng(36.5, 114));
var oldmap= new GGroundOverlay("http://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg", boundaries);
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.addOverlay(oldmap);

查看示例 (groundoverlay-simple.html)

圖塊疊加層

Google 地圖 API 中的地圖在每一個縮放級別都包含一組圖塊，涵蓋地球的整個表面。每種地圖類型使用的圖塊有：G_NORMAL_MAP、G_SATELLITE_MAP、G_HYBRID_MAP 和 G_PHYSICAL_MAP。圖塊不必定在全部縮放級別中都涵蓋全部區域。例如，太平洋的許多區域在高縮放級別中不顯示。

在最低的縮放級別（級別 0），一個圖塊表示整個地球：

每一個後繼的縮放級別將地圖分紅 4 N 個圖塊，其中「N」表明縮放級別。例如，在縮放級別 1，Google 地圖將世界分爲 2x2 網格，共 4 個圖塊；在縮放級別 2，Google 地圖將世界分爲 4x4 網格，共 16 個圖塊，以此類推。

若是要修改這些圖塊的顯示，您有兩種選擇：

· 使用 GTileLayerOverlay 在現有的地圖類型上實現您本身的圖塊疊加層

· 使用 GMapType 實現您本身的自定義地圖類型

第一種狀況簡單得多，但使用較受限制，而第二種狀況可以讓您在應用中對顯示進行更多控制。下面討論了這兩種狀況，可是本文檔中未講述怎樣徹底實現自定義地圖類型。

每一種狀況都須要從 GTileOverlay 接口實現三種抽象方法：

· getTileUrl() 會向地圖返回包含圖塊的網址（傳遞 GPoint 和縮放級別的狀況下）。

· isPng() 會向地圖返回 Boolean，表示圖像是否爲 PNG 文件（PNG 文件能夠透明地顯示）。若是爲 true，則假定該圖像爲 PNG。

· getOpacity() 返回 0.0 和 1.0 之間的值，表示顯示此圖像的透明度級別。

咱們將在接下來的兩部分中討論這些不一樣的方法。

圖塊層疊加層

若是要在現有地圖類型上顯示疊加層，請使用 GTileLayerOverlay 對象。此對象要求您建立 GCopyrightCollection，並將其與圖塊層相關聯，以表示容許使用該圖像（或這些圖像）。

如下代碼在每一個圖塊的全部縮放級別上顯示一個簡單的透明疊加層，使用浮動十字光標表示圖塊的輪廓。

// Set up the copyright information
// Each image used should indicate its copyright permissions
var myCopyright= new GCopyrightCollection("© ");
myCopyright.addCopyright(new GCopyright('Demo',
new GLatLngBounds(new GLatLng(-90,-180), new GLatLng(90,180)),
0,'©2007 Google'));

// Create the tile layer overlay and
// implement the three abstract methods
var tilelayer= new GTileLayer(myCopyright);
tilelayer.getTileUrl= function() { return "../include/tile_crosshairs.png"; };
tilelayer.isPng= function() { return true;};
tilelayer.getOpacity= function() { return 1.0; }

var myTileLayer= new GTileLayerOverlay(tilelayer);
var map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(39.9493, 116.3975), 13);
map.addOverlay(myTileLayer);

查看示例 (tileoverlay-simple.html)

自定義地圖類型

注意：這是一個高級主題

若是以爲 GTileLayerOverlay 太受限制，則您能夠定義本身的自定義地圖類型，並開發全新的顯示樣式。要執行此操做，請構造一個 GMapType 對象，並使用 GMap2.addMapType() 方法將其添加到地圖。

從頭構造地圖類型是一個複雜的過程。您須要構建一種方式，在提供當前圖標的狀況下，定義和檢索在地圖上顯示的動態數據，並須要肯定怎樣引用和顯示圖塊。您怎麼作由您本身決定，但咱們能夠經過說明 Google 地圖怎樣實現其圖塊引用來向您提供一些幫助。

Google 地圖座標

Google 地圖 API 使用三種座標系：

· 像素座標，引用圖塊上的一個點

· 圖塊座標，引用圖塊層中的一個圖塊

· 縮放層，定義總的圖塊數

下面對其中每一個系統進行討論。

像素座標

Google 地圖中的每一個圖塊都包含 256 x 256 個像素。可使用 GPoint(x,y) 對來引用特定圖塊上的某個點。每一個圖塊的原點 (0,0) 表示爲圖塊的西北角。所以，對於表示整個地球的單個圖塊，原點設置爲在北極，經度 -180 度，您能夠在該位置看到阿拉斯加。x（經度）值越往東越大，而 y（緯度）值越往南越大，一直到東南角 (255,255)。

在高一級的縮放級別，像素空間在 x 和 y 方向都擴大一倍。例如，在縮放級別 1，地圖包括 4 個 256x256 像素的圖塊，產生 512x512 的像素空間。在縮放級別 19，地圖上的每一個 x 和 y 像素都可以使用 0 和·256 * 219 之間的值來引用。

圖塊座標

引用整個地圖上這樣一個惟一的點一般是不實際的。在較高的縮放級別，Google 地圖 API 不能使用一個圖像文件顯示整個地球。所以肯定正在使用哪一個圖塊，而後相對於該圖塊的原點計算像素座標很是有用。您實現的任何自定義地圖都須要進行相同的計算。

Google 地圖中的圖塊從與像素相同的原點開始計算，以便使原點圖塊始終處於地圖的西北角。圖塊使用從該原點算起的 x,y 座標進行索引。例如，在縮放級別 2，當地球分爲 16 個圖塊時，每一個圖塊能夠經過一個惟一的 x,y 對來引用：

所以索引特殊縮放級別的特殊點可使用兩個 GPoint 值：一個引用正在使用的圖塊，一個引用圖塊 256 x 256 像素圖像中的座標。

若是不是少量簡單縮放級別，則實現圖塊疊加層是一個麻煩的任務，由於您須要添加邏輯來肯定處理哪一個特定的圖塊。Google 地圖·API 可以讓您構建一個 GTileLayer，將 GTileLayerOptions 參數做爲對象常量傳遞。GTileLayerOptions 參數包含 tileUrlTemplate 屬性，可根據圖塊座標將圖塊請求映射到網址。疊加層的構造函數可能以下所示：

var tileLayerOverlay= new GTileLayerOverlay(
new GTileLayer(null, null, null, {
    tileUrlTemplate: 'http://domain.com/myimage_{Z}_{X}_{Y}.png',
    isPng:true,
    opacity:1.0
})
);

map.addOverlay(tlo);

此模板方案可以讓您像處理 Google 地圖同樣處理使用圖塊座標命名的一組圖塊。

處理版權信息

地圖一般包含從一些外部機構購買、生成或許可的圖像。這些圖像一般須要顯示版權信息，在某些狀況下（例如衛星數據），地圖上不一樣位置的圖像可能來自不一樣的來源。爲了在自定義地圖類型上顯示動態版權信息，地圖 API 提供了大量對象來存放版權信息，並提供了基於當前視口和縮放級別對此版權信息實現檢索的方法和接口。

版權對象

GCopyright 對象是一個用於存放基礎版權信息的簡單對象。此對象的 minZoom 和 bounds 屬性定義此版權信息有效的限制條件，包含版權字符串的 text 將在這些條件下顯示。

GTileLayer 接口的構造函數須要 copyrights 參數。處理這些圖塊層的類（例如 GTileLayerOverlay 和 GMapType）須要預先建立 GCopyrightCollection 對象，並將該對象傳遞給圖塊層的構造函數。

Google 地圖 API 使用如下方法來顯示版權信息的，您能夠覆蓋這些方法來提供自定義行爲：

· GMapType.getCopyrights() 在其全部子圖塊層上調用 GTileLayer.getCopyright()。

· 每一個 GTileLayer.getCopyright() 都在其版權集合上調用 GCopyrightCollection.getCopyrightNotice()。

其中每一個方法都包含 bounds 和 zoom 參數，能夠覆蓋它們並肯定要顯示哪些版權信息。

默認狀況下，只要 Google 地圖 API 顯示某個地圖類型中的圖塊層，它就會經過 GTileLayer.getCopyright() 方法檢索當前正在使用的版權。某些地圖類型可能包含多個圖塊層，這可能意味着須要併發顯示多個 GCopyrightCollection 對象中的信息。（例如，G_HYBRID_MAP 地圖類型同時實現衛星地圖層和普通地圖層。）這種併發信息經過結合多個版權集合中的版權聲明來顯示。

轉換投影座標

地球是一個球形，而地圖是平面的二維對象。您在 Google 地圖 API 中看到的地圖是這個球形在平面上的「投影」。Google 地圖 API 中的投影使用 GProjection 接口實現。Google 地圖 API 中當前僅使用 GMercatorProjection 這一個投影。用最簡單的方式來講，投影能夠定義爲 GLatLng 值與地圖上的座標之間的一對一對應，GProjection 接口提供了用於此用途的轉換實用工具。

GProjection.fromLatLngToPixel() 方法可將 GLatLng 值轉換爲指定縮放級別的像素座標。相似地，GProjection.fromPixelToLatLng() 方法可將指定縮放級別的像素座標轉換爲 GLatLng 值。當實現地圖類型時這些方法很是有用，由於它們可以讓您肯定顯示哪些圖塊、怎樣顯示它們以及顯示它們時所使用的偏移值。

如下示例經過計算當前縮放級別的像素座標而處理點擊事件，並同時返回該位置的像素座標和圖塊座標：

查看示例 (tile-detector.html)

有關實現地圖類型的詳細信息，請查閱 GMapType 參考。

層

GLayer 對象是疊加層對象，存儲第三方地理信息集合。「層」是地理相關功能的集合，可共享某些經常使用函數，在地圖上顯示爲一個組。Google 經過從其餘源獲取的數據提供這些集合，並將它們包含在一個層內。

層一般包含多種項目，一般有標記、折線和多邊形，可是這些項目不被視爲單獨對象。層自身（及其全部組件）被視爲地圖 API 的一個疊加層，經過標準 addOverlay() 方法添加到地圖。層還能夠進行交互，例如，可對組件執行操做以調出信息窗口。

每一個層均包含惟一的命名空間 ID，以即可以輕鬆地引用、惟一地定位它們。命名空間 ID 當前基於源層的域。例如，英文的「Geotagged Wikipedia © Articles」層的命名空間 ID 爲「org.wikipedia.en」。

Google 地圖 API 當前能夠訪問這些公共層。會按期將新的層添加到地圖 API。咱們會維護此電子表格中的這個列表。

如下代碼段會將英文的「Wikipedia」層添加到紐約城格林威治村：

function initialize() {
if (GBrowserIsCompatible()) {
   var map= new GMap2(document.getElementById("map_canvas"));
    map.setCenter(new GLatLng(39.90822, 116.4055), 13);
   var myLayer= new GLayer("org.wikipedia.en");
    map.addOverlay(myLayer);
}
}

查看示例 (layer-simple.html)

自定義疊加層

Google 地圖 API 還可以讓您經過實現 GOverlay 接口而建立自定義疊加層。經過實現 GOverlay 接口，Google 地圖 API 提供了若干服務，例如 GTrafficOverlay、GGeoXml 和 GStreetviewPanorama 對象。（這些服務在服務部分講述。）

GOverlay 接口須要您實現四種抽象方法：

· initialize()，用於響應 GMap2.addOverlay()

· remove()，用於響應 GMap2.removeOverlay()

· copy()，容許複製新建的疊加層

· redraw()，用於響應地圖中的顯示更改

Google 地圖 API 接口的實現方式是在 JavaScript 中將 prototype 屬性賦值爲繼承對象的一個實例。例如，Rectangle 對象可以使用如下代碼從 GOverlay 接口繼承：

OverlaySubclass.prototype= new GOverlay();

經過爲對象的 prototype 上的抽象方法賦值，能夠輕鬆地實現 GOverlay 接口中的這些抽象方法：

OverlaySubclass.prototype.initialize= myInitializeMethod;
OverlaySubclass.prototype.remove= myRemoveMethod;
OverlaySubclass.prototype.copy= myCopyMethod;
OverlaySubclass.prototype.redraw= myRedrawMethod;

在如下示例中，咱們建立了一個 Rectangle 疊加層，在地圖上勾勒出一個地理區域。Rectangle 類定義 GOverlay 接口的四個必需方法。特別請記下 initialize() 方法（建立表示疊加層的 DOM 元素）和 redraw() 方法（基於當前投影和縮放級別在地圖上定位疊加層並調整疊加層大小）。

組成疊加層的每一個 DOM 元素都位於一個「地圖窗格」上，地圖窗格定義繪製的 Z 軸次序。例如，折線對於地圖來講是平面，因此在最低的 G_MAP_MAP_PANE 中繪製。標記將其陰影元素放置在 G_MAP_MARKER_SHADOW_PANE 中，將前景元素放置在 G_MAP_MARKER_PANE 中。將疊加層元素放置在正確的窗格中能夠確保地圖上的折線在標記陰影下方繪製，信息窗口在其餘疊加層上方繪製。在此示例中，咱們的疊加層相對於地圖是平面，因此咱們將其和 GPolyline 同樣添加到最低繪製順序窗格 G_MAP_MAP_PANE。請參閱類參考以查看地圖窗格的完整列表。

// A Rectangle is a simple overlay that outlines a lat/lng bounds on the
// map. It has a border of the given weight and color and can optionally
// have a semi-transparent background color.
function Rectangle(bounds, opt_weight, opt_color) {
this.bounds_= bounds;
this.weight_= opt_weight|| 2;
this.color_= opt_color|| "#888888";
}
Rectangle.prototype= new GOverlay();

// Creates the DIV representing this rectangle.
Rectangle.prototype.initialize= function(map) {
// Create the DIV representing our rectangle
var div= document.createElement("div");
div.style.border= this.weight_+ "px solid " + this.color_;
div.style.position= "absolute";

// Our rectangle is flat against the map, so we add our selves to the
// MAP_PANE pane, which is at the same z-index as the map itself (i.e.,
// below the marker shadows)
map.getPane(G_MAP_MAP_PANE).appendChild(div);

this.map_= map;
this.div_= div;
}

// Remove the main DIV from the map pane
Rectangle.prototype.remove= function() {
this.div_.parentNode.removeChild(this.div_);
}

// Copy our data to a new Rectangle
Rectangle.prototype.copy= function() {
return new Rectangle(this.bounds_, this.weight_, this.color_,
                       this.backgroundColor_, this.opacity_);
}

// Redraw the rectangle based on the current projection and zoom level
Rectangle.prototype.redraw= function(force) {
// We only need to redraw if the coordinate system has changed
if (!force) return;

// Calculate the DIV coordinates of two opposite corners of our bounds to
// get the size and position of our rectangle
var c1= this.map_.fromLatLngToDivPixel(this.bounds_.getSouthWest());
var c2= this.map_.fromLatLngToDivPixel(this.bounds_.getNorthEast());

// Now position our DIV based on the DIV coordinates of our bounds
this.div_.style.width= Math.abs(c2.x- c1.x) + "px";
this.div_.style.height= Math.abs(c2.y- c1.y) + "px";
this.div_.style.left= (Math.min(c2.x, c1.x) - this.weight_) + "px";
this.div_.style.top= (Math.min(c2.y, c1.y) - this.weight_) + "px";
}

var map= new GMap2(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(39.9493, 116.3975), 13);

// Display a rectangle in the center of the map at about a quarter of
// the size of the main map
var bounds= map.getBounds();
var southWest= bounds.getSouthWest();
var northEast= bounds.getNorthEast();
var lngDelta= (northEast.lng() - southWest.lng()) / 4;
var latDelta= (northEast.lat() - southWest.lat()) / 4;
var rectBounds= new GLatLngBounds(
   new GLatLng(southWest.lat() + latDelta, southWest.lng() + lngDelta),
   new GLatLng(northEast.lat() - latDelta, northEast.lng() - lngDelta));
map.addOverlay(new Rectangle(rectBounds));

查看示例 (overlay-custom.html)

服務

1 服務概述

2 XML 和數據解析

3 地址解析

4 GStreetviewPanorama 對象

5 與 Google 地球集成

6 本地搜索

7 KML 和 GeoRSS 疊加層

8 交通疊加層

9 Directions

服務概述

Google 地圖 API 會按期擴展，添加新的功能和特性，一般這些功能和特性會先在 ditu.google.cn 上發佈。本部分講述這些服務。注意：因爲「服務」的定義在某種程度上較難懂，所以本部分會涉及的內容也較廣。咱們基本上將沒法放到其餘部分的內容都放到了本部分中。

XML 和數據解析

Google 地圖 API 導出一種工廠方法，用於建立適用於各類瀏覽器的 XmlHttpRequest() 對象（在 Internet Explorer、Firefox 和 Safari 的最新版本中都可使用）。和全部的 XmlHttpRequest 同樣，任何檢索的文件都必須在本地域中。如下示例下載名爲 myfile.txt 的文件，並使用 JavaScript alert() 顯示其內容：

var request= GXmlHttp.create();
request.open("GET", "myfile.txt", true);
request.onreadystatechange= function() {
if (request.readyState== 4) {
alert(request.responseText);
}
}
request.send(null);

該 API 還爲典型的 HTTP GET 請求導出一種更簡單的 GDownloadUrl() 方法，無需檢查 XmlHttpRequest() readyState。上面的示例能夠以下使用 GDownloadUrl() 從新編寫：

GDownloadUrl("myfile.txt", function(data, responseCode) {
alert(data);
});

可使用靜態方法 GXml.parse() 解析 XML 文檔，該方法取 XML 的一個字符串做爲其惟一的參數。此方法與多數流行的瀏覽器兼容，但若是瀏覽器自己不支持 XML 解析，它會拋出異常。

在此示例中，咱們使用 "data.xml"GDownloadUrl 方法下載一個靜態文件 ()，它包含一個 XML 格式的經緯座標列表。當下載完成後，咱們使用 GXml 解析該 XML，並在 XML 文檔中的每一個點處建立一個標記符。

var map= new GMap2(document.getElementById("map_canvas"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(39.9493, 116.3975), 13);

// Download the data in data.xml and load it on the map. The format we
// expect is:
// <markers>
//   <marker lat="39.945" lng="116.375"/>
//   <marker lat="39.872" lng="116.423"/>
// </markers>
GDownloadUrl("data.xml", function(data, responseCode) {
var xml= GXml.parse(data);
var markers= xml.documentElement.getElementsByTagName("marker");
for (var i= 0; i< markers.length; i++) {
   var point= new GLatLng(parseFloat(markers[i].getAttribute("lat")),
                            parseFloat(markers[i].getAttribute("lng")));
    map.addOverlay(new GMarker(point));
}
});

查看示例 (xhr-requests.html)。此示例使用外部 XML 數據文件 data.xml。

有關詳細信息，請參見 GXmlHttp 和 GXml 類參考。

地址解析

地址解析是將地址（如「1600 Amphitheatre Parkway, Mountain View, CA」）轉換爲地理座標（如經度 -122.083739 和緯度 37.423021）的過程，能夠用於放置標記符或定位地圖。Google 地圖 API 包含地址解析服務，能夠經過 HTTP 請求直接訪問，也能夠經過使用 GClientGeocoder 對象來訪問。

請注意，地址解析是一種時間和資源密集型任務。儘可能爲您的地址預先進行地址解析（使用 HTTP 地址解析器或其它地址解析服務），並使用地址解析緩存存儲您的結果。

地址解析對象

能夠經過 GClientGeocoder 對象訪問 Google 地圖 API 地址解析服務。使用 GClientGeocoder.getLatLng() 將字符串地址轉換爲 GLatLng。此方法採用要轉換的字符串地址以及在檢索到地址後要執行的回調函數做爲參數。該回調函數是必要的，由於地址解析涉及向 Google 的服務器發送請求，可能須要一些時間。

在此示例中，咱們將對一個地址進行地址解析，在該點添加標記，並打開一個顯示該地址的信息窗口。請注意，該回調函數做爲函數顯式聲明傳遞。

查看示例 (geocoding-simple.html)

還能夠經過 GLatLngBounds 方法修改地圖 API 地址解析器以指定解析結果在指定的視口內（視口是一個 GClientGeocoder.setViewport() 類型的矩形區域)。您可使用 GClientGeocoder.setBaseCountryCode() 方法返回爲特定地區（國家）定製的結果。能夠對 Google 地圖主應用程序提供地址解析的每一個主要地區發送地址解析請求。例如，搜索「Toledo」將返回西班牙地區內（http://maps.google.es）由國家或地區代碼「es」指定的不一樣結果，而不是默認的美國 (http://maps.google.com) 地區內的結果。

抽取結構化地址

若是要訪問有關某個地址的結構化信息，GClientGeocoder 還提供了 getLocations() 方法，該方法返回包括如下信息的 JSON 對象：

· Status

o request - 請求類型。在本例中，始終是 geocode。

o code - 響應代碼，相似於 HTTP 狀態代碼，指示地址解析請求是否成功。請參見狀態代碼完整列表。

· Placemark - 若是地址解析器發現多個匹配項，則可能返回多個地標。

o address - 格式化良好，大小寫正確的地址版本。

o AddressDetails - 格式化爲 xAL（或可擴展地址語言，一種地址格式化的國際標準）的地址。

§ Accuracy - 表示指定地址的地址解析所能達到的精確度的屬性。請參見可能值列表。

o Point - 三維空間中的點。

§ coordinates - 地址的經度、緯度和海拔。在本例中，海拔始終設置爲 0。

下面咱們展現使用地址解析器解析 Google 總部地址返回的 JSON 對象：

{
"name": "1600 Amphitheatre Parkway, Mountain View, CA, USA",
"Status": {
   "code": 200,
   "request": "geocode"
},
"Placemark": [
   {
     "address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
     "AddressDetails": {
       "Country": {
         "CountryNameCode": "US",
         "AdministrativeArea": {
           "AdministrativeAreaName": "CA",
           "SubAdministrativeArea": {
             "SubAdministrativeAreaName": "Santa Clara",
             "Locality": {
               "LocalityName": "Mountain View",
               "Thoroughfare": {
                 "ThoroughfareName": "1600 Amphitheatre Pkwy"
               },
               "PostalCode": {
                 "PostalCodeNumber": "94043"
               }
             }
           }
         }
       },
       "Accuracy": 8
     },
     "Point": {
       "coordinates": [-122.083739, 37.423021, 0]
     }
   }
]
}

在此示例中，咱們使用 getLocations() 方法對地址進行地址解析，從 JSON 抽取地址的良好格式化版本和兩字母的國家或地區代碼，並在信息窗口中顯示。

var map;
var geocoder;

function addAddressToMap(response) {
map.clearOverlays();
if (!response|| response.Status.code!= 200) {
    alert("\"" + address+ "\" not found");
} else {
    place= response.Placemark[0];
    point= new GLatLng(place.Point.coordinates[1],
                        place.Point.coordinates[0]);
    marker= new GMarker(point);
    map.addOverlay(marker);
    marker.openInfoWindowHtml(place.address+ '<br>' +
     '<b>Country code:</b> ' + place.AddressDetails.Country.CountryNameCode);
}
}

查看示例 (geocoding-extraction.html)

反向地址解析

術語「地址解析」一般是指將用戶可閱讀的地址轉換成地圖上的點。將地圖上的點反向轉換成用戶可閱讀的地址的過程稱爲「反向地址解析」。

GClientGeocoder.getLocations() 方法支持標準地址解析和反向地址解析。若是爲此方法傳遞了一個 GLatLng 對象而不是 String 地址，地址解析器將執行反向查詢並返回最接近的可尋址位置的結構化 JSON 對象。請注意，若是提供的 GLatLng 與任何可尋址位置都不徹底匹配，那麼，最接近的可尋址位置與查詢的原始經度值和緯度值之間可能存在一段距離。

注意：反向地址解析不屬於精密科學。地址解析器會試圖在必定的誤差範圍內查找最接近的可尋址位置；若是找不到匹配項，地址解析器一般會返回 G_GEO_UNKNOWN_ADDRESS (602) 狀態代碼。

var map;
var geocoder;
var address;

function initialize() {
map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(39.90822, 116.4055), 13);
map.addControl(new GLargeMapControl);
GEvent.addListener(map, "click", getAddress);
geocoder= new GClientGeocoder();
}

function getAddress(overlay, latlng) {
if (latlng!= null) {
    address= latlng;
    geocoder.getLocations(latlng, showAddress);
}
}

function showAddress(response) {
map.clearOverlays();
if (!response|| response.Status.code!= 200) {
    alert("Status Code:" + response.Status.code);
} else {
    place= response.Placemark[0];
    point= new GLatLng(place.Point.coordinates[1],place.Point.coordinates[0]);
    marker= new GMarker(point);
    map.addOverlay(marker);
    marker.openInfoWindowHtml(
       '<b>orig latlng:</b>' + response.name+ '<br/>' +
       '<b>latlng:</b>' + place.Point.coordinates[0] + "," + place.Point.coordinates[1] + '<br>' +
       '<b>Status Code:</b>' + response.Status.code+ '<br>' +
       '<b>Status Request:</b>' + response.Status.request+ '<br>' +
       '<b>Address:</b>' + place.address+ '<br>' +
       '<b>Accuracy:</b>' + place.AddressDetails.Accuracy + '<br>' +
       '<b>Country code:</b> ' + place.AddressDetails.Country.CountryNameCode);
}
}

查看示例 (geocoding-reverse.html)

地址解析緩存

GClientGeocoder 默認配備有客戶端緩存。該緩存存儲地址解析器響應，當從新對地址進行地址解析時能夠加快響應。能夠經過執行 GClientGeocoder 對象的 setCache() 方法並傳遞一個 null 參數來關閉緩存。但咱們建議保留緩存，由於它能夠提升性能。要更改 GClientGeocoder 使用的緩存，請調用 setCache() 方法並傳遞一個新緩存做爲參數。要清空當前緩存的內容，請對地址解析器或直接對緩存調用 reset() 方法。

咱們鼓勵開發人員構建本身的客戶端緩存。在此示例中，咱們構造了一個緩存，包含對地址解析 API 所涵蓋的國家或地區中的六個首都或首府城市的預先計算的地址解析器響應。首先，咱們構建了一個地址解析響應數組。而後，咱們建立了擴展標準 GeocodeCache 的自定義緩存。定義該緩存後，咱們調用 setCache() 方法。對緩存中存儲的對象沒有嚴格檢查，因此您也能夠在緩存中存儲其它信息（例如人口規模）。

// Builds an array of geocode responses for the 6 capitals
var city= [
{
    name: "Washington, DC",
   Status: {
      code: 200,
      request: "geocode"
   },
   Placemark: [
     {
        address: "Washington, DC, USA",
        population: "0.563M",
       AddressDetails: {
         Country: {
          CountryNameCode: "US",
           AdministrativeArea: {
             AdministrativeAreaName: "DC",
             Locality: {
               LocalityName: "Washington"
             }
           }
         },
         Accuracy: 4
       },
       Point: {
          coordinates: [-77.036667, 38.895000, 0]
       }
     }
   ]
},
... // etc., and so on for other cities
];

var map;
var geocoder;

// CapitalCitiesCache is a custom cache that extends the standard GeocodeCache.
// We call apply(this) to invoke the parent's class constructor.
function CapitalCitiesCache() {
   GGeocodeCache.apply(this);
}

// Assigns an instance of the parent class as a prototype of the
// child class, to make sure that all methods defined on the parent
// class can be directly invoked on the child class.
CapitalCitiesCache.prototype= new GGeocodeCache();

// Override the reset method to populate the empty cache with
// information from our array of geocode responses for capitals.
CapitalCitiesCache.prototype.reset= function() {
   GGeocodeCache.prototype.reset.call(this);
   for (var iin city) {
     this.put(city[i].name, city[i]);
   }
}

map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.441944, -122.141944), 6);

// Here we set the cache to use the UsCitiesCache custom cache.
geocoder= new GClientGeocoder();
geocoder.setCache(new CapitalCitiesCache());

查看示例 (geocoding-cache.html)

經過 HTTP 進行地址解析

還可使用服務器端腳原本直接訪問地圖 API 地址解析器。使用客戶端地址解析器時不建議使用這種方法，但該方法在進行調試時或 JavaScript GClientGeocoder 對象不可用時卻頗有用。

要訪問地圖 API 地址解析器，請訪問 http://ditu.google.cn/maps/geo? 並在網址中添加如下參數：

· q（必填）- 您要進行地址解析的地址。

· key（必填）- 您的 API 密鑰。

· sensor（必填）- 指示地址解析請求是否來自裝有位置傳感器的設備。該值必須爲 true 或 false。

· output（必填）- 生成時輸出應採用的格式。選項有 xml、kml、csv 或默認選項 json。

· ll（可選）- 視口中心的 {經度,緯度}，表示爲以逗號分隔的字符串（例如「ll=-117.773438,40.479581」）。僅當將 spn 參數也傳遞給地址解析器時此參數纔有意義。

· spn（可選）- 視口的「範圍」，表示爲以逗號分隔的 {經度,緯度} 字符串（例如「spn=22.5,11.1873」）。僅當將 ll 參數也傳遞給地址解析器時此參數纔有意義。

· gl（可選）- 國家/地區代碼，指定爲 ccTLD（「頂級域」）雙字符值。

注意：gl 和 spn,ll 視口參數只會影響地址解析器的結果，而不會徹底限制其結果。

在如下示例中，咱們請求 Google 總部的地理座標：

http://ditu.google.cn/maps/geo?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&output=xml&sensor=true_or_false&key=abcdefg

本例中，咱們將 sensor 參數用做變量「true_or_false」，用以強調您必須將該值顯示設置爲 true 或 false。

若是指定 json 做爲輸出，則響應會格式化爲 JSON 對象。若是指定 xml 或 kml，則響應以 KML 格式返回。XML 和 KML 輸出徹底相同（對於 MIME 類型除外）。

例如，下面是地址解析器對「1600 amphitheatre mountain view ca」返回的響應。

<kml xmlns="http://earth.google.com/kml/2.0">
<Response>
   <name>1600 amphitheatre mountain view ca</name>
   <Status>
     <code>200</code>
     <request>geocode</request>
   </Status>
   <Placemark>
     <address>
        1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA
     </address>
     <AddressDetails Accuracy="8">
       <Country>
         <CountryNameCode>US</CountryNameCode>
         <AdministrativeArea>
           <AdministrativeAreaName>CA</AdministrativeAreaName>
           <SubAdministrativeArea>
             <SubAdministrativeAreaName>Santa Clara</SubAdministrativeAreaName>
             <Locality>
               <LocalityName>Mountain View</LocalityName>
               <Thoroughfare>
                 <ThoroughfareName>1600 Amphitheatre Pkwy</ThoroughfareName>
               </Thoroughfare>
               <PostalCode>
                 <PostalCodeNumber>94043</PostalCodeNumber>
               </PostalCode>
             </Locality>
           </SubAdministrativeArea>
         </AdministrativeArea>
       </Country>
     </AddressDetails>
     <Point>
       <coordinates>-122.083739,37.423021,0</coordinates>
     </Point>
   </Placemark>
</Response>
</kml>

若是想要獲得易於解析的較短響應，而且不須要特殊的特性（如多個結果或良好的格式），咱們還提供一種 csv 輸出。以 csv 格式返回的大幅包括四個數字，之間使用逗號分隔：

10 HTTP 狀態代碼

11 精確度（請參見精確度常數）

12 緯度

13 經度

如下示例按照準確性從低到高的順序顯示了對三個地址的回覆：「State St, Troy, NY」、「2nd st & State St, Troy, NY」和「7 State St, Troy, NY」

200,6,42.730070,-73.690570
200,7,42.730210,-73.691800
200,8,42.730287,-73.692511

使用「街道視圖」對象

使用「街道視圖全景」對象須要客戶端瀏覽器支持 Flash 插件。

小至指定道路，大至 Google 地圖覆蓋的整個區域，Google 街道視圖均提供 360 度的全景視圖。下面顯示了一張示例街道視圖圖像。

Google 街道視圖使用大部分瀏覽器支持的 Flash® 插件顯示這些交互圖像。如今，Google 地圖 API 提供街道視圖服務，可用於獲取及處理在 Google 地圖街道視圖中使用的圖像！

GStreetviewPanorama 對象

經過使用 GStreetviewPanorama 對象可支持街道視圖圖像，該對象可向街道視圖 Flash® 查看器提供一個 API 接口。要將街道視圖合併到地圖 API 應用程序中，您須要遵循如下簡單步驟：

14 建立一個容器（一般是 <div> 元素），來包含街道視圖 Flash® 查看器。

15 建立一個 GStreetviewPanorama 對象，而後將其放入該容器中。

16 將街道視圖對象初始化爲引用一個特定位置並顯示初始「視點」(POV)。

17 經過檢查 603 錯誤值來處理不受支持的瀏覽器。

GStreetviewPanorama 對象要求其構造函數中有一個容器元素。您還可使用 GStreetviewPanoramaOptions 參數設置該對象的位置（可選）。能夠在構造函數調用結束後調用對象的 setLocationAndPOV() 方法來更改其位置和 POV。

有關容器和設置位置及視點的詳細信息，將在下文中介紹。

街道視圖容器

街道視圖 Flash 查看器須要一個 DOM 容器節點，此節點用於顯示查看器的內容（一般是 <div> 元素）。爲使全景圖像達到最佳顯示效果，建議尺寸最小爲 200 像素 x 200 像素。也不建議使用大查看器，由於大查看器可能致使 Flash 查看器消耗太多內存，並可能對瀏覽器的性能帶來負面影響。

GStreetviewPanorama 構造函數須要一個 container 參數來肯定初始容器元素，該容器元素中將顯示街道視圖 Flash 查看器。能夠對 GStreetviewPanorama 對象應用 hide()，使其暫時不顯示；也能夠對該對象應用 show()，使其從新顯示出來。

在任什麼時候候，若是您想要更改街道視圖 Flash 查看器的容器，請向容器發送 setContainer() 方法，從而向該容器傳遞其應當關聯的新元素。若是調整了容器的大小，您能夠向 GStreetviewPanorama 對象發送 checkResize() 方法，以強制它調整大小，從而適合其新尺寸。

若是想要從 DOM 中完全刪除街道視圖 Flash 查看器並釋放其內存，請向該對象傳遞 remove() 方法。若是想要從 DOM 中刪除容器元素，則必須調用該方法，不然將致使客戶端瀏覽器的內存泄漏。

街道視圖位置

街道視圖圖像包含一個位置（對應於 GLatLng）和一個特定的方向 (GPov)，兩者共同標識圖像顯示的視圖。這兩個參數均可以在構造街道視圖對象時使用 GStreetviewPanoramaOptions 可選參數來指定。

當前受支持的街景視圖的城市列表能夠從 Google 地圖幫助中心得到。可經過三種基本方法來肯定某個位置是否支持街道視圖數據：

· 能夠存儲已知有效的街道視圖位置的 GLatLng。

· 能夠檢查 GStreetviewOverlay 圖塊疊加層，而後目測檢查道路網絡。支持街道視圖的道路在疊加層上以藍色高亮顯示。而後您可使用單擊事件或地址解析邏輯將受支持的位置傳遞給 GStreetviewPanorama 對象。（請參見街道視圖疊加層。）

· 您可使用 GStreetviewClient 對象，對指定了傳遞 GLatLng 的街道視圖對象執行查詢。GStreetviewClient 對象支持使用大量查詢來查找全景數據。（請參見街道視圖客戶端查詢。）

請注意，後兩種方法是不精確的：在這些狀況下，街道視圖服務不須要（且一般不接收）精確的經度和緯度，而是搜索是否存在「接近」指定 GLatLng 的全景數據。

如下示例使用 GStreetviewPanoramaOptions 指定要用於街道視圖的初始經度和緯度。POV 保留爲空，表示使用默認視圖朝向北方。

var fenwayPark= new GLatLng(42.345573,-71.098326);
panoramaOptions= { latlng:fenwayPark};
var myPano= new GStreetviewPanorama(document.getElementById("pano"), panoramaOptions);

查看示例 (streetview-simple.html)

街道視圖錯誤處理

因爲街道視圖要求支持 Flash® 插件，所以您的代碼應檢查該插件在用戶瀏覽器上是否可用。也能夠經過註冊一個對 GStreetviewPanorama 對象上的 error 事件進行偵聽的事件偵聽器，來在您的應用程序中進行此檢查。error 事件可傳遞一個能夠評估的錯誤代碼。

如下示例代碼將對是否支持 Flash 插件執行快速檢查，若是不支持 Flash 則顯示一個警告對話框。

街道視圖視點 (POV)

街道視圖位置定義一個圖像相機的放置位置，可是不定義該圖像相機的方向。爲了定義相機方向，GPov 對象常量定義了三個屬性：

· yaw 定義以相機位置爲圓心相對於正北方向的旋轉角度（以度爲單位）。擺角按順時針方向測量（90 度爲正東方向）。

· pitch 定義相對於相機初始默認傾斜度的「向上」或「向下」差值，默認傾斜度一般爲（但不老是）平直水平。（例如，在山上拍攝的圖像所表現出的默認傾斜度可能不是水平的。）測量傾斜角度時，向上看爲負值（最大爲 –90 度，豎直向上並與默認傾斜面垂直），向下看爲正值（最大爲 +90 度，豎直向下並與默認傾斜面垂直）。

· zoom 定義此視圖的縮放級別（有效地限制「視野」），0 表示徹底縮小。不一樣的街道視圖位置可能提供更高或更低的縮放級別。

默認狀況下，這些值均爲 0，所定義的視圖爲平直水平，方向爲正北，且顯示最寬的視野。

設置全景視圖

如前文所述，能夠在構造全景對象時使用 GStreetviewPanoramaOptions 參數設置該對象的位置和 GPov。

fenwayPark= new GLatLng(42.345573,-71.098326);
myPOV= {yaw:370.64659986187695,pitch:-20};
svOpts= {latlng:fenwayPark, pov:myPOV};
var myPano= new GStreetviewPanorama(document.getElementById("pano"), svOpts);

在構造 GStreetviewPanorama 對象後，您還可使用 setLocationAndPOV() 方法設置位置和 POV。在如下示例中，咱們將建立一個 GStreetviewPanorama 對象，而後將其位置和 POV 設置爲某個特定值。

var myPano= new GStreetviewPanorama(document.getElementById("pano"));
fenwayPark= new GLatLng(42.345573,-71.098326);
myPOV= {yaw:370.64659986187695,pitch:-20};
myPano.setLocationAndPOV(fenwayPark, myPOV);

查看示例 (streetview-object.html)

使用街道視圖疊加層

肯定道路是否支持街道視圖的最簡單方法是經過使用 GStreetviewOverlay 對象。只需建立一個此類型的疊加層，而後將其添加到地圖中；包含街道視圖數據的道路將使用藍色邊界在地圖上高亮顯示。

var map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(39.9493, 116.3975), 13);
svOverlay= new GStreetviewOverlay();
map.addOverlay(svOverlay);

查看示例 (streetview-layer.html)

當您知道某個地理區域支持街道視圖後，能夠經過填充 GStreetviewPanorama 對象在有效的街道視圖道路上添加可響應單擊操做的邏輯。

var myPano= new GStreetviewPanorama(document.getElementById("pano"));
var map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(42.345573,-71.098326), 14);
svOverlay= new GStreetviewOverlay();
map.addOverlay(svOverlay);
GEvent.addListener(map,"click", function(overlay,latlng) {
myPano.setLocationAndPOV(latlng);
});

查看示例 (streetview-click.html)

若是您知道某個特定位置支持街道視圖，則能夠保存該位置信息和 POV 並將這些信息放入對象自己。

街道視圖客戶端查詢

從用戶角度而言，經過目測檢查 GStreetviewOverlay 的方式來肯定某條道路是否支持街道視圖一般不太可行，也不可取。出於此緣由，API 提供了一種以程序方式發出請求並檢索街道視圖數據的服務。此服務經過使用 GStreetviewClient 對象獲得簡化。

執行街道視圖查找

GStreetviewClient 對象使用 Google 的街道視圖服務執行全景數據查找。因爲此種查找爲異步進行，因此此類方法須要在接收數據時執行回調函數。若是未返回值，那麼指定的全部回調都會傳遞 null，所以您應當檢查您的回調函數中是否存在這種狀況。

GStreetviewClient 方法 getNearestPanoramaLatLng() （其自己做爲 GLatLng 傳遞）會從指定的位置檢索鄰近的全景圖像的 GLatLng。

getNearestPanorama() 和 getPanoramaById() 反而會檢索 GStreetviewData 對象，該對象存儲關於特定全景對象的元數據。此類數據在下文中介紹。

處理客戶端響應

GStreetviewData 對象的結構包含三種屬性：location、copyright（包含正顯示的特定圖像的信息），以及links（提供有關鄰近全景對象的信息）。這些屬性的結構以下所述：

# The location property uses the GStreetviewLocation object literal

location: {

latlng: GLatLng,

pov: {

yaw: String,

pitch: String,

zoom: String

description: String,

panoId: String

}

# The links property uses the GStreetviewLink object literal

links[]: {

yaw: String,

description: String,

panoId: String

}

（GStreetviewLocation 和 GStreetviewLink 對象常量的完整說明位於地圖 API 參考中）。

注意：不該將 GStreetviewData.location 屬性與 window.location 屬性混淆。若是嘗試今後對象的 location 屬性中抽取數據，請確保您確實接收到了從街道視圖服務器傳回的響應（以下所示）。不然，location 屬性將默認爲 window.location，而且將發生意外行爲。

若是對 GStreetviewClient 對象的請求成功，它會將 GLatLng 或 GStreetviewData 對象傳遞給指定的回調函數。由於檢索街道視圖數據爲異步進行，然而，客戶端對象可能不檢索這些數據對象，所以您的代碼不該依賴於這些對象是否顯示。相反，您應始終檢查一定會返回的任何請求所返回的 code 值。如下代碼段說明了此概念。

panoClient= new GStreetviewClient();
panoClient.getPanoramaById(panoData.location.panoId, processReturnedData);

function processReturnedData(panoData) {
if (panoData.code!= 200) {
   GLog.write('showPanoData: Server rejected with code: ' + panoData.code);
   return;
}

// Code to actually process the GStreetviewData object is contained here

}

包含示例 GStreetviewData 結構的完整響應以下所示：

{
location: {
    latlng: GLatLng("42.345566, -71.098354")
    pov: {
      yaw: "370.64659986187695"
      pitch: "-20"
      zoom: "1"
   }
    description: "Yawkey Way"
    panoId: "-KNGDaZvSQjMqug7ISM_CA"
}
copyright: "© 2008 Google"
links:[ {
    yaw: "0"
    description: "Yawkey Way"
    panoId: "S142iWXa_4Fi7L7d8HKhuQ"
},
{
    yaw: "0"
    description: "Yawkey Way"
    panoId: "2vFI79AjOpHTAYJSCKquFg"
}
]
}

如下樣本應用程序將顯示初始全景對象，抽取其 ID，而後存儲返回的 GStreetviewData 對象中的連接全景對象，並顯示與該街道視圖對象相關的數據集。用戶每次單擊「下一步」時，該過程都會重複，容許用戶「行進」過一組鄰近全景對象。

var map;
var myPano;
var panoClient;
var nextPanoId;

function initialize() {
var fenwayPark= new GLatLng(42.345573,-71.098326);
var fenwayPOV= {yaw:370.64659986187695,pitch:-20};

   panoClient= new GStreetviewClient();

map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(fenwayPark, 15);
GEvent.addListener(map, "click", function(overlay,latlng) {
    panoClient.getNearestPanorama(latlng, showPanoData);
});

   myPano= new GStreetviewPanorama(document.getElementById("pano"));
myPano.setLocationAndPOV(fenwayPark, fenwayPOV);
GEvent.addListener(myPano, "error", handleNoFlash);
panoClient.getNearestPanorama(fenwayPark, showPanoData);
}

function showPanoData(panoData) {
if (panoData.code!= 200) {
   GLog.write('showPanoData: Server rejected with code: ' + panoData.code);
   return;
}
nextPanoId= panoData.links[[0[].panoId;
var displayString= [[
   "Panorama ID: " + panoData.location.panoId,
   "LatLng: " + panoData.location.latlng,
   "Copyright: " + panoData.copyright,
   "Description: " + panoData.location.description,
   "Next Pano ID: " + panoData.links[[0[].panoId
[].join("
");
map.openInfoWindowHtml(panoData.location.latlng, displayString);

GLog.write('Viewer moved to' + panoData.location.latlng);
myPano.setLocationAndPOV(panoData.location.latlng);
}

function next() {
// Get the next panoId
// Note that this is not sophisticated. At the end of the block, it will get stuck
panoClient.getPanoramaById(nextPanoId, showPanoData);
}

function handleNoFlash(errorCode) {
if (errorCode== 603) {
    alert("Error: Flash doesn't appear to be supported by your browser");
   return;
}
}

查看示例 (streetview-data.html)

與 Google 地球插件集成

Google 地圖 API 如今可以讓開發人員處理其地圖 API 應用程序中的 Google 地球實例（須要經過單獨安裝 Google 地球插件）。Google 地球地圖層經過外觀和行爲都像獨立 Google 地球應用程序的單獨 GMapType 顯示，這樣您就能夠在瀏覽器中旋轉視角、觀看立體圖以及查看 Google 地球 KML 信息。

注意：Google 地球插件必須安裝在用戶的計算機上才能使用該 Google 地球 GMapType。當前，此插件僅適用於 Microsoft Windows。有關完整的系統要求，請參見 Google 地球 API 開發人員指南。

加載 Google 地球插件（僅適用於 Windows）

適用於 Windows 的 Google 地球插件可從如下網址得到：

http://earth.google.com/intl/zh-CN/

Google 地球插件可經過本身的 API 進行控制，它本身的 API 與 Google 地圖 API 是互相獨立的，也是不一樣的。有關使用該插件和 Google 地球 API 的詳細信息，請參見 Google 地球 API 開發人員指南。

也可在 Google 地圖 API 中對 Google 地球插件進行實例化。

初始化 Google 地球插件

要將 Google 地球實例添加至您的地圖，只需經過 GMap2.addmapType() 將 G_SATELLITE_3D_MAP 添加至您的地圖。而後，能夠將地圖設置爲直接顯示此地圖類型（經過 GMap2.setMapType()），用戶也可本身在 GMapTypeControl 中選擇此地圖類型（經過用 GMap2.addControl() 來添加一個地圖類型控件）。

如下代碼會將 G_SATELLITE_3D_MAP 地圖類型添加到地圖，而後顯式地將地圖設置爲在地圖中顯示 Google 地球地圖類型。（請注意，第一次點擊此示例時，系統會提示您安裝 Google 地球插件）。

var map= new GMap2(document.getElementById("map_canvas"),{ size: new GSize(640,480) } );
map.setCenter(new GLatLng(39.927, 116.407), 11);
map.addMapType(G_SATELLITE_3D_MAP);
var mapControl= new GMapTypeControl();
map.addControl(mapControl);
map.setMapType(G_SATELLITE_3D_MAP);

查看示例 (services-earth-plugin.html)

本地搜索

若是要向您的網站中添加本地搜索功能，可使用 Google AJAX 搜索 API 在網站中嵌入本地搜索控件。此控件是 GControl 對象的一個子類，是一個很好的建立自定義控件的示例。

向您的地圖 API 應用程序中添加此控件以前，須要添加 Google AJAX 搜索 API 的網址，並使用地圖 API 密鑰才能使用該服務。您還須要加載該控件對象的樣式表，以下所示：

// Load the Code
<script src="http://www.google.cn/uds/api?file=uds.js&v=1.0&key=ABCDEF"
type="text/javascript"></script>
<script src="http://www.google.cn/uds/solutions/localsearch/gmlocalsearch.js"
type="text/javascript"></script>

// Load the Style Sheets
<style type="text/css">
@import url("http://www.google.cn/uds/css/gsearch.css");
@import url("http://www.google.cn/uds/solutions/localsearch/gmlocalsearch.css");
</style>

或者可使用 AJAX 加載器，經過公共加載器加載全部這些模塊。

執行完這些準備任務以後，加載控件自己相對比較簡單：

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

// create a local search control and add it to your map
var lsc= new google.maps.LocalSearch();
map.addControl(new google.maps.LocalSearch());

查看示例 (control-localsearch.html)

關於本地搜索控件的詳細信息，請參見 Google AJAX 搜索 API 參考。

KML/GeoRSS 疊加層

Google 地圖 API 支持用於顯示地理信息的 KML 和 GeoRSS 數據格式。使用 GGeoXml 對象將這些數據格式添加到地圖，該對象的構造函數採用可公開訪問的 XML 文件的網址。GGeoXml 地標顯示爲 GMarker，而 GGeoXml 折線和多邊形顯示爲 Google 地圖 API 折線和多邊形。KML 文件中的 <GroundOverlay> 元素顯示爲地圖上的 GGroundOverlay 元素。

使用 addOverlay() 方法將 GGeoXml 對象添加到地圖。（您可使用 removeOverlay() 從地圖中刪除它們。）KML 和 GeoRSS XML 文件均受支持。請注意，GGeoXml 是 Google 地圖 API 中的一個模塊化對象，而且在首次使用後纔會徹底加載。所以，請僅當頁面徹底加載後再調用其構造函數。此操做一般經過在 <body> 的 onload 處理程序中調用 GGeoXml 構造函數來完成。

// The GGeoXml constructor takes a URL pointing to a KML or GeoRSS file.
// You add the GGeoXml object to the map as an overlay, and remove it as an overlay as well.
// The Maps API determines implicitly whether the file is a KML or GeoRSS file.

var map;
var geoXml;

function initialize() {
if (GBrowserIsCompatible()) {
    map= new GMap2(document.getElementById("map_canvas"));
    geoXml= new GGeoXml("http://mapgadgets.googlepages.com/cta.kml");
    map.addControl(new GLargeMapControl());
  map.setCenter(new GLatLng(39.917, 116.397), 11);
    map.addControl(new GLargeMapControl());
    map.addOverlay(geoXml);
}
}

查看 GeoRSS 示例 (geoxml-rss.html)

查看 KML 示例 (geoxml-kml.html)

交通疊加層

Google 地圖 API 可以讓您使用 GTrafficOverlay 對象（其應用 GOverlay 接口）向地圖中添加交通訊息。可使用 GMap2.addOverlay() 方法向地圖中添加交通訊息。GTrafficOverlay 有兩種方法（hide() 和 show()）用於切換是否顯示交通疊加層。只有支持的城市才能顯示交通訊息。

也可使用 GTrafficOverlayOptions 對象常量向 GTrafficOverlay 構造函數傳遞選項。

// The GTrafficOverlay is unique in that only one object of that type
// should be added to a map. Adding multiple traffic overlays produces
// no added benefit.

var map;
var trafficInfo;

function initialize() {
map= new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(49.496675,-102.65625), 3);
var trafficOptions= {incidents:true};
trafficInfo= new GTrafficOverlay(trafficOptions);
map.addOverlay(trafficInfo);
}

查看交通示例 (trafficOverlay.html)

行車路線

您可使用 GDirections 對象添加該功能來計算行車路線（使用各類交通方式）。GDirections 對象使用查詢字符串（例如「New York, NY to Chicago, IL」）或提供的文字經度/緯度（例如「-73.967257, 40.712882 to -87.770677, 41.943181」）請求和接收行車路線結果。GDirections 對象還支持使用一系列路標的多段行車路線。行車路線能夠在地圖上顯示爲繪製路線的折線和/或 <div> 元素中的一系列文本描述（例如「向右轉到 Williamsburg Bridge 斜道」）。

要在 Google 地圖 API 中使用行車路線，請建立類型爲 GDirections 的對象，並指定用於接收和顯示結果的 GMap2 對象和/或 <div>。默認狀況下，地圖居中而且經過返回的路線限制邊界（儘管能夠在 GDirectionOptions 對象中使用參數進行更改）。

加載行車路線

行車路線使用 GDirections.load() 方法請求。此方法取查詢字符串和一組可選的 GDirectionsOptions 參數。有如下選項可用：

· locale 指定返回結果所使用的語言，以覆蓋地圖 API hl 參數（若是提供的話）。若是 locale 和 hl 參數都未指定，則使用瀏覽器的默認語言。

· travelMode 指定計算結果時使用的交通方法。

· avoidHighways 指定計算行車路線時應避開公路。

· getPolyline 指定行車路線對象應返回折線數據，以繪製返回的行車路線。默認狀況下，若是有地圖對象顯示折線數據，GDirections 對象會僅返回這些數據。若是將該值設置爲 true 而且不提供地圖，那麼您應直接處理折線數據。

· getSteps 指定行車路線對象應返回文字行車路線，即便未提供 <div> 面板來顯示這些行車路線也是如此。若是將該值設置爲 true 而且不提供面板，那麼您應直接處理路段數據。

· preserveViewport 指定地圖不該自動居中並縮放到返回的行車路線的邊界框；相反，地圖會在當前視口中保持居中位置。

出行模式

默認狀況下，行車路線會假定您是駕車行駛，但您能夠經過在調用 Directions.load() 方法時傳遞 GTravelMode 來請求其餘出行模式。支持如下出行方式：

· G_TRAVEL_MODE_DRIVING 指示使用路網的標準行車路線

· G_TRAVEL_MODE_WALKING 請求經過步行街和人行道（若是有）的步行路線。

注意：步行路線有時可能不包括暢通的步行街，所以步行路線僅當您在 GDirections 構造函數中提供了 <div> 時才受支持；此 <div> 用於在返回的分路段顯示文字路線中向用戶顯示警告。若是沒有此類 <div>，則在請求步行路線時就會返回錯誤。

處理返回的行車路線

若是 GDirections 對象使用提供的 GMap2 對象構建，則返回的行車路線將包含折線疊加層。若是使用提供的 <div> 元素構造 GDirections 對象，則返回的行車路線將包含一個 GRoute 對象，該對象包含一組 GStep 對象。（若是行車路線包括多點行車路線，則返回的行車路線將包含多個 GRoute 對象，其中每一個都包含一系列的 GStep 對象。）

請注意行車路線對象不會當即填充此返回信息。所以，GDirections 對象定義了一個「load」事件，以截獲該事件來肯定此狀態。

默認狀況下，返回行車路線後，地圖會顯示一條顯示路線的折線，而文字行車路線則會顯示在爲達到此目的而提供的 <div> 中。GDirections 對象還會內部存儲您可使用 GDirections.getPolyline() 和/或 GDirections.getRoute(i:Number) 方法檢索的結果。可使用 GRoute.getStep(i:Number) 方法檢索路線中的路段，使用 GStep.getDescriptionHtml() 方法檢索該路段的 HTML 摘要。（請參見下面的路線和路段。）

GDirections 對象還會觸發您能夠截獲的三個事件：

· 「load」：此事件在成功返回行車路線結果、但向地圖/面板添加任何疊加層元素以前觸發。

· 「addoverlay」：在將折線和/或文本格式的行車路線組件添加到地圖和/或 DIV 元素以後會觸發此事件。

· 「error」：若是行車路線請求致使錯誤，則觸發此事件。調用者可使用 GDirections.getStatus() 獲取有關該錯誤的詳細信息。

// Create a directions object and register a map and DIV to hold the
// resulting computed directions

var map;
var directionsPanel;
var directions;

function initialize() {
map= new GMap2(document.getElementById("map_canvas"));
directionsPanel= document.getElementById("my_textual_div");
map.setCenter(new GLatLng(49.496675,-102.65625), 3);
directions= new GDirections(map, directionsPanel);
directions.load("from: 500 Memorial Drive, Cambridge, MA to: 4 Yawkey Way, Boston, MA 02215 (Fenway Park)");
}

查看示例 (directions-simple.html)

如下示例與第一個示例相同，只是行車路線經過傳遞 G_TRAVEL_MODE_WALKING 調用：

查看示例 (directions-walking.html)

路線和路段

GDirections 對象還支持多點的行車路線，可使用 GDirections.loadFromWaypoints() 方法構建。此方法取文本輸入地址或文本經緯度點的數組。每一個單獨的沿途路標均計算爲單獨的路線並在單獨的 GRoute 對象中返回，其中每一個都包含一系列的 GStep 對象。

GRoute 對象存儲路線的路段（類型爲 GStep）數目、路線的起點和終點地址解析以及計算出的其餘信息，如距離、歷時和終點的精確經緯度（若是地址解析不依賴於路段，則可能與終點地址解析不一樣）。每一個 GStep 對象還包含文本描述（例如「經過到 San Jose 的斜道駛上 US-101 S」）以及計算出的信息，包括距離、歷時和精確經緯度。

有關行車路線 API 包中的各個對象、方法和事件的完整文檔，請參見 API 參考。

查看示例 (directions-advanced.html)

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。