開發人員指南

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

TGOS MAP API開啟視野

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

取得API

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

初始化地圖

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

<!DOCTYPE html>

<html>

<head>

<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />

<title>Getting Start TGOS MAP</title>

<script type="text/javascript"

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

<script type="text/javascript">

function InitWnd() {

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

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

}

</script>

</head>

<body style="margin: 0px" onload="InitWnd();">

<div id="TGMap" style="width: 800px; height: 600px; border: 1px solid #C0C0C0;">

</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中的yourIDyourkey替換為您申請所取得的API金鑰,包含APPIDAPIKEY,方能順利驗證載入必要之地圖功能。

地圖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可供使用。詳細狀態變更與設定可參考地圖一般事件

 

回到上方