TGOS MAP API (Web)開發人員指南

用TGOS MAP API開啟視野

本指南是給以JavaScript程式設計的開發人員，如何將TGOS MAPAPI功能嵌入網頁平台的使用教程。在閱讀本指南並開始利用TGOS MAP API多元而豐富的功能，來充實您的網頁之前，您需要有JavaScript程式設計方法以及物件導向程式設計概念的基礎。

取得API金鑰

您必須先取得API金鑰，才能使用TGOS MAP API。API金鑰可以方便您管理網頁，並在功能使用上或流量有問題時，讓TGOS團隊及時的瞭解情形，協助您處理。申請使用TGOS MAP API為免費的，詳細的功能、圖資授權以及API的申請方式，請參考申請說明。

初始化地圖

以下程式碼初始化一個最簡單的TGOS MAP，我們將以此程式碼範例來介紹如何將TGOS地圖呈現於網頁框架中。

<!DOCTYPE html>

<html>

<head>

<title>Getting Start TGOS MAP</title>

src="http://api.tgos.tw/TGOS_API/tgos?ver=2&AppID=yourID&APIKey=yourkey" charset="utf-8"></script>

function InitWnd() {

var pOMap = document.getElementById("TGMap");

var pMap = new TGOS.TGOnlineMap(pOMap, TGOS.TGCoordSys.EPSG3826);

}

</script>

</head>

</div>

</body>

</html>

在這段程式碼中，使用了以下規範來建構地圖：

1.以<!DOCTYPE html>將程式宣告為HTML5。

2.使用script標記載入Maps API JavaScript。

3.建立div物件來容納地圖。

4.建立JavaScript物件以存放多個地圖屬性。

5.撰寫JavaScript函式以建立地圖「物件」。

6.從body標記的onload事件來初始化地圖物件。

載入TGOS MAP API

要初始化地圖功能，我們必須先載入TGOS MAP API，將來源設定為http://api.tgos.tw/TGOS_API/tgos?ver=2&AppID=yourID&APIKey=yourkey，此網址會指向該JavaScript檔案服務的位置，載入所有地圖初始必要的符號(如標記點或是其他圖像物件)以及字串定義。使用者建構的網頁必須包含指向這個網址的script標記，接下來才可利用TGOS MAP API對地圖做客製的設定。

在網址中，必需帶入API金鑰參數，請將引用字串http://api.tgos.tw/TGOS_API/tgos?ver=2&AppID=yourID&APIKey=yourkey中的yourID及yourkey替換為您申請所取得的API金鑰，包含APPID及APIKEY，方能順利驗證載入必要之地圖功能。

地圖DOM元素

要顯示適當的地圖，必須在網頁上預留顯示地圖的位置，亦即容器。因此我們會建立一個div元素，並取得瀏覽器文件物件模型(DOM)中此元素的參照。在本範例中，定義名稱為「TGMap」的div，並使用樣式(Style)屬性設定div的大小為640*480 pixel，邊框(border)屬性為實心線條樣式(solid)、寬度1px、顏色為#C0C0C0。因此您可以根據瀏覽器螢幕大小、邊框間距以及網頁美工樣式，自行調整數值，設定div之寬高大小，以及邊框線條樣式、粗細與顏色。必須注意的是，div的主要功能為設定明確的大小，其所包含的元素將決定地圖展示時的大小。

TGOS MAP基本地圖物件

pMap代表地圖的JavaScript類別物件，可定義網頁上的單一地圖，並可建立實例，讓每個物件在網頁上定義個別的地圖，而TGOS MAP API使用JavaScript new這個運算子來新增實例。

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

使用document.getElementById()的過程中，程式碼定義一個變數(本範例命名為pOMap)，以及該變數所包含的setOptions物件定義的選項，同時指派給新的pMap物件，並設定地圖的坐標系統，建立新的地圖。這些選項主要用於地圖屬性的初始化作業，完整的TGOnlineMap()函式「建構式」，定義如下：

建構式

說明

TGOnlineMap(Node mapDiv, TGCoordSys coordSys, TGMapOptions opts)

此物件為地圖物件，提供於指定容器內建立地圖，給予參數指定坐標系統、相關地圖屬性設定。

mapDiv：此參數指定容納地圖的容器。

coordSys：此參數指定地圖使用之坐標系統。

opts：此參數指定地圖相關之屬性設定。

坐標系統

TGOS MAP API提供底圖3種坐標系統的切換，以方便您依據您的資料及需求，搭配使用適合的坐標底圖。

1. EPSG:3826 TWD97(台灣)坐標系統。

2. EPSG:3825 TWD97(澎湖)坐標系統。

3. EPSG:3857 Web麥卡托坐標系統，若您的資料為經緯度坐標，請選用此坐標系統。

地圖選項

要完整呈現初始化地圖，還須先建立TGMapOptions物件以納入地圖初始化的變數。這個物件會以Object Literal形式建立，成為TGMapOptions的實例。在此，將決定地圖初始的形態及樣式，詳細介紹請參考說明與範例之初始化地圖設定值。

初始底圖類型

TGOS MAP API共提供八種底圖顯示，利用setMapTypeId()方法，您可以指定使用者在開啟您的地圖網頁時，預設呈現的底圖類別。TGOS MAP API支援的底圖種類有：

1.TGOSMAP：顯示台灣通用電子地圖（原TGOS MAP已下架）。

2.NLSCMAP：顯示台灣通用電子地圖。

3.MOTCMAP：顯示台灣通用電子地圖（原路網數值圖已下架）。

4.F2IMAGE：顯示福衛二號衛星影像。

5.ROADMAP：顯示含有福衛影像與道路資訊之福衛影像混合地圖。

6.HILLSHADE：顯示地形暈渲圖。

7.HILLSHADEMIX：顯示地形暈渲與道路資訊之地形暈渲混合地圖。

8.SEGISMAP：顯示含有統計區界線之統計區MAP。

在地圖使用中，也允許使用者切換底圖，您甚至可以設定只提供使用者部分底圖的切換。底圖類型切換設定，請參考地圖類型控制與地圖類型控制項。

地圖位置

在初始化地圖時，可以利用setCenter()方法設定地圖中心點位置，讓使用者開啟地圖就可以直接顯示到您指定的位置。

TGOS底圖以內政部發布之產製圖磚規格進行切割，依比例尺產製適合臺灣尺度之層級，而圖片瀏覽時，API會進行「等級縮放」。如果縮放等級較低，地圖選取比例尺較小的圖磚瀏覽，可視範圍較大；如縮放等級較高，圖磚的解析度就較高，可專門瀏覽小區域範圍的地圖。TGOS MAP API提供setZoom()功能，可指定地圖放大縮小的等級，縮放顯示臺澎金馬的全域地圖，或市街道路。

要進一步了解如何指定位置，請參考指定地圖位置、地圖中心點坐標及地圖縮放層級控制之說明。

載入地圖

呈現HTML網頁時，會建立文件物件模型(DOM)，接收任何外部的圖片和指令碼，並與document物件進行整合。

為了確保網頁完全載入之後地圖才會放到網頁，只有在HTML網頁的Map元素body標記的onload屬性是事件處理常式的一個範例，並收到body事件時，我們才會建構onload物件的函式。這樣做可以避免意外而無法預期的行為，而且讓使用者更能控制繪製地圖的方式和時機。

如果需要產生地圖事件，TGOS MAP API有一系列可判斷狀態變更的API可供使用。詳細狀態變更與設定可參考地圖一般事件。