開發人員指南

TGOS 3D API (Web)開發人員指南

用TGOS 3D API開啟視野

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

初始化三維圖台

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

<!DOCTYPE html>

<html>

<head>

<title>Getting Start TGOS 3D EARTH</title>

src="http://3dapi.tgos.tw/TG3D_API/TGOS3D?ver=1&AppID=yourID&APIKey=yourkey" charset="utf-8"></script>

var tg3dEarth;

function InitWnd() {

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

tg3dEarth = new TGOS.TEOnlineMap(pBody);

}

</script>

</head>

</div>

</body>

</html>

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

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

2.使用script標記載入TGOS 3D API JavaScript。

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

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

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

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

載入TGOS MAP API

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

地圖DOM元素

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

TGOS 3D EARTH基本圖台物件

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

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

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

建構式

說明

TEOnlineMap(Node mapDiv,TEMapOptions opts?)

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

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

opts：此參數指定地圖相關之屬性設定，若不填寫則使用API預設值。

三維圖台選項

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

圖台初始位置

在初始化圖台時，可以利用視點(View Point)設定的方式，讓使用者開啟後就可以直接顯示到您指定的位置。

要進一步了解如何指定位置，請參考指定圖台初始位置之說明。

載入地圖

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

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

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