EASYMAP API v7.0 說明文件 最後更新時間:
對於本 API 使用上之 bug 與建議,請 email 至jeffrey@gis.tw 向我們回報錯誤或提出相關建議,並請耐心等待我們將漏洞修復,但我們並不保證 bug 修復的時間。
對象
要利用 EASYMAP API 進行開發之前您必須先熟悉 Javascript 語法及物件導向程式設計,同時也應該熟悉 EASYMAP 的網站操作。
版本更新說明
跟 EASYMAP 說聲 Hello World
觀看範例是開始學習 EASYMAP API 的最簡易方式,下面的網頁會顯示一個以座標(121.3, 24.5)為中心,大小 500x400 的地圖:
<!DOCTYPE html> <html> <head> <title>EASYMAP API 範例 - 基本</title> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <script type="text/javascript" src="http://easymap.gis.tw/easymap/latest/easymap.js"></script> </head> <body onload="init();"> <div id="map" style="width:500px; height:400px; border:1px solid red;"></div> <script type="text/javascript"> var map = null; function init() { map = new Easymap('map'); //'map'為div的id map.zoomToXY(new dgXY(121.3, 24.5), 9); } </script> </body> </html>
嵌入 EASYMAP API
在上述範例中所列出的 URL (easymap.js) 是用來在您的網頁中嵌入 EASYMAP 電子地圖前所必須載入 Javascript 檔的網址。您的網頁必須包含一個指向此 URL 的 <script> tag,寫法會像下面這樣:
<script src="easymap.js" type="text/javascript"> </script>
在 EASYMAP API 中最主要的類別就是用來代表網頁上每一幅地圖的 easymap,您可以在同一個網頁中創造出多個 easymap 物件以嵌入多張地圖。當您在創造一個新的 easymap 物件時,必須指定一個網頁元件 ( 通常是用 DIV 元件 ),EASYMAP API 會自動依照該元件的大小將地圖嵌入其中。
後面我們會詳細描述如何對地圖進行操作以及加上地標的方法。
瀏覽器相容性
EASYMAP API 目前支援下列瀏覽器版本,如果您發現有其他可正常運作的瀏覽器我們未列出,歡迎到告訴我們。
- IE 6.0+
- Chrome 最新版本
- Firefox 1.0+
- Safiri 5.1.x
- iOS7.0
API 更新
EASYMAP 開發小組會持續對 API 進行 bug 修正與效率改進,更新後的 API 會自動生效,您所開發的程式無須做任何變動即可套用到最新的 API。
接下來的每個範例及範例demo頁面都只列出相關的 Javascript 程式碼的部份,而不是完整的 HTML 檔,您可以自行將這些程式片段插入您的 HTML 檔中,或是直接下載每個範例中的 HTML 檔回去修改。
初始化
下面的範例會產生一個地圖,您可以自由的用滑鼠拖曳此地圖。
var map = new Easymap(document.getElementById('map'));
基本
下面的範例會將地圖拉至顯示圖層9且以(121.3, 24.5)為中心點的區域。
map.zoomToXY(new dgXY(121.3, 24.5), 9);
easymap 物件
每個 easymap 物件就代表網頁上的一幅地圖,您可以在同一個網頁中創造出多個 easymap 物件以嵌入多張地圖。當您在創造一個新的 easymap 物件時,必須指定一個網頁元件 ( 通常是用 DIV 元件 ),EASYMAP API 會自動依照該元件的大小將地圖嵌入其中。
easymap 類別提供了各種函式讓您可以控制地圖的中心位置、顯示比例以及新增地標,另外也可以開啟訊息視窗來顯示更多的資訊。
想知道更多有關 easymap 的用法請參考 Easymap 類別說明 。
訊息視窗
每個地圖都擁有一個可以用來顯示 HTML 內容的浮動訊息視窗,這個訊息視窗看起來就像是漫畫中的對話框,有一塊顯示內容的區域與一根指向地圖上特定地點的尖端部份。您無法同時在地圖上顯示一個以上的訊息視窗,但是訊息視窗的位置及內容是可以隨時改變的。
要開啟訊息視窗的方法就是呼叫 openInfoWindow 函式,並傳入一個坐標點以及一段 HTML 內容當作參數,訊息視窗會出現在該坐標點的上方並將尖端指向該點,同時在內容區顯示傳入的 HTML 內容。
dgMarker 類別也同樣提供了 openInfoWindow 函式,您只需傳入 HTML 內容做為參數,這個函式會自動將訊息視窗開啟在 dgMarker 物件的上方,並且依照 dgMarker 所使用的圖示(dgIcon)來計算訊息視窗的平移量以讓尖端部份指向該圖示建立時所指定的位置。
套疊物件(Overlays)
套疊物件是用來放置在地圖上並具有真實地理座標的物件,當您移動地圖的時候他們也會隨之移動。
例如: 地標點(dgMarker),也就是放在地圖上的小圖示。
地標以及圖示
要建立一個自訂的 dgMarker 物件需要傳入一個 dgXY 坐標點及一個 dgIcon 圖示(DOM object)做為參數。如果您只需要使用預設的一般圖示,那您就不用在建立 dgMarker 時傳入任何 dgIcon 圖示。
每個圖示都必須有一張圖片,並指定好圖片長寬,以下就是建立一個可以使用的圖示的最簡單程式碼:
var icon = new dgIcon();
dgIcon 類別另外還有一些屬性可以讓您設定圖示與地標實際坐標的對齊位置,以及訊息視窗與圖示的對齊位置。詳細的用法請參考 dgIcon 類別說明 。
控制列
想要在地圖上使用各種控制工具列,EASYMAP API 目前提供下列幾種控制列類型供您在地圖上使用:
- addWMap() -- 鷹眼
map.addWMap();
- addMapTypeSelector() -- 多主題圖
map.addMapTypeSelector();
- addMapControl() -- 工具列
map.addMapControl();
註:參數後面如果帶有「?」表示此一參數可以忽略
Easymap
每個 Easymap 物件就代表網頁上的一幅地圖。
建構式
建構式 | 說明 |
Easymap(container) | 在指定的 HTML container(HTML element,通常是一個 DIV element) 內建立一個地圖。 |
函式
函式 | 說明 | return value |
addMapControl(?[x,y]) | 加入工具列(可填入工具列位移位置)。 | |
setMapControl(?[x,y]) | 可更改工具列位置。 | |
addWMap() | 加入鷹眼。 | |
setWMapV(true/false) | 設定地圖鷹眼是否可視。 | |
addMapTypeSelector(1/null,[x,y]/null) | 加入圖層選擇鈕。 | |
setMapTypeSelectorV(true/false) | 設定地圖主題圖是否可視。 | |
setMapControlV(boolean) | 設定地圖工具列是否可視。 | |
wheelZoom(true/false) | 設定是否關閉滾輪功能,預設為true | |
setDraggable(boolean) | 設定地圖是否可被拖曳的功能。 | |
getWidth() | 取得目前地圖的寬(px)。 | int |
getHeight() | 取得目前地圖的高(px)。 | int |
getCenter() | 取得目前地圖中心點的坐標。 | dgXY |
getRectBound() | 取得目前地圖範圍座標。(左上、右下) | [dgXY,dgXY] |
resize(width(int),height(int)) | 調整地圖大小。 | |
rotate(angle(int)) | 調整地圖的方向。 | |
getZoomLevel() | 取得目前地圖的顯示層級。 | int |
setZoomLevel(zoomLevel(int)) | 設定顯示層級。不做動作 | |
zoomTo(zoom) | 將縮放到指定的顯示層級 zoomto(integer)。目前所支援最小的 zoomTo 值為 0,最大為9。 | |
zoomToXY(dgXY, zoom) | 將地圖的中心點移動至指定的坐標 xy並縮放到指定的顯示層級 zoom(integer)。若是新的中心點也位在原本的地圖範圍之內時,地圖會以滑動的方式移至新的中心點。 | |
panTo(dgXY, dis?) | 平移地圖到dgXY,dis 指定最長平移距離,超過則以goXY的方式。 | |
goXY(dgXY) | 將地圖的中心點移動至指定的坐標,不改變目前的顯示層級。 | |
zoomIn() | 將地圖放大一個顯示層級。 | |
zoomOut() | 將地圖縮小一個顯示層級。 | |
getCX() | 取得目前地圖中心點的X坐標。 | int |
getCY() | 取得目前地圖中心點的Y坐標。 | int |
switchMapType(mapName, zoomLevel?) | 切換圖層(如同 MapTypeSelector 的功能)。 | |
getMapName() | 取得目前圖層名稱。 | string |
tranXY(dgXY) | 轉換地圖座標(dgXY)為螢幕座標[x,y]。 | Array[x,y] |
revXY(sX, sY) | 轉換螢幕地圖座標(sx,sy)為地圖座標dgXY。 | dgXY |
openInfoWindow(dgXY, html/DOMo, dialogWidth?, dialogHeight?) | 在地圖上的 x,y(dgXY) 位置上開啟一個訊息視窗,視窗的內容為 html(string,內容可包含 HTML 語法)。 若要控制訊息視窗的大小,可選擇性傳入 dialogWidth 與 dialogHeight 參數,代表訊息顯示區域的長寬 pixel 值,若未傳入則使用預設大小。 | |
closeInfoWindow() | 關閉地圖上的訊息視窗。 | |
addItem(overlay) | 新增一個 dgMarker / dgPoint... 等物件到地圖中。 | |
removeItem(overlay) | 將物件由地圖中移除。 | |
addItem(overlay) | 新增一個 dgMarker / dgPoint... 等物件到地圖中。 | |
setItemTop(overlay) | 將該物件至頂。 | |
clearMarker() | 移除所有的地標點物件。 | |
clearDraw() | 清除所有繪製的圖形。 | |
setDrawMode((string)mode,eproc,aproc) |
切換繪圖模式(包含觸發的事件)。polygon, polyline, circle, rectangle。eproc = 繪圖結束事件。aproc=繪製過程事件。
相關功能:
|
|
getDrawMeasure() | 取得量測結果。 | |
getDrawResult() | 取得繪圖結果。 | Array[dgXY,...] |
getDrawResultObject() | 取得剛繪圖完的物件,可方便未來removeItem或是addItem使用。 | Overlay |
【暫未開放】setWMSMode(modeType(int),wmsUrl(string),wmsParas(sttring)) |
設定動態圖層模式。 modeType = 0(關閉),1(image link),2(iframe) |
wms image |
【暫未開放】refreshWMS() | 重整動態圖層 | |
createDiv() | 在Map上建立一個Div,設定z-index要在3以上 | |
removeDiv(object) | 在Map上移除一個Div | |
【暫未開放】getRectPic() | 取得目前視窗之圖片路徑 | Array[w,h,url....] |
【暫未開放】getRectPic4(x1,y1,x2,y2) | 取得目前視窗之圖片路徑,輸入左上x1,y1,右下x2,y2 | Array[w,h,url....] |
【暫未開放】getRectPicBBOX() | 取得目前視窗之圖片之BBOX | Array[w,h,minx,miny,maxx,maxy....] |
【暫未開放】getRectPicBBOX4(x1,y1,x2,y2) | 取得目前視窗之圖片之BBOX,輸入左上x1,y1,右下x2,y2 | Array[w,h,minx,miny,maxx,maxy....] |
【暫未開放】getPicPath(x,y) | 取得某個XY點位之圖片路徑 | url |
getUpperZoomByBoundary(dgXY,dgXY) | 輸入左上XY,右下XY Zoom到最適合的範圍 | |
setScaleLineVisible(boolean) | 設定ScaleLine顯示或隱藏 | |
enableDragBox(eproc) [v7版提供] | 啟用畫方框,eproc繪圖結束事件 | |
disableDragBox() [v7版提供] | 關閉畫方框 | |
openDragRotate() [v7版提供] | 啟用旋轉 | |
closeDragRotate() [v7版提供] | 關閉旋轉 |
附加事件
attachEvent(eventType, function) | 附加事件至地圖 |
目前提供之 eventType:
- onmousedown
- onmouseup
- onmousemove
- onclick
- ondblclick
- movestart
- moveend
- zoomstart
- zoomend
dgXY
dgXY 物件是定義一個坐標的物件。
建構式
建構式 | 說明 |
dgXY(x, y) | 建立一個二維坐標。 |
屬性
屬性 | 類別 | 說明 |
x | number | 這個點的 x(水平) 坐標。 |
y | number | 這個點的 y(垂直) 坐標。 |
dg3D [v7版提供]
dg3D 。
建構式
建構式 | 說明 |
dg3D(layertype, url, options) | 建立一個二維坐標。 |
屬性
屬性 | 類別 | 說明 |
layertype | Type | note。 |
url | string | note。 |
options | string | note。 |
dgMarker
dgMarker 是可以套疊在地圖上的一種物件,會以圖示的方式顯示於地圖上的某一坐標點。(在addItem的時候,可以先放進一個陣列 例如: aa=new Array(),在一起放到addItem(aa))
建構式
建構式 | 說明 |
dgMarker(dgXY, icon/html?,da?) | 建立一個地標,其坐標為 dgXY,顯示圖示為 icon(dgIcon)或html文件亦可,若沒有傳入 icon 則會使用 API 預設的圖示。 |
函式
函式 | 說明 |
openInfoWindow(html, dialogWidth?, dialogHeight?) | 在此地標上開啟一個訊息視窗,視窗的內容為 html(string,內容可包含 HTML 語法)。 若要控制訊息視窗的大小,可選擇性傳入 dialogWidth 與 dialogHeight 參數,代表訊息顯示區域的長寬 pixel 值,若未傳入則使用預設大小。 |
getXY() | 取得此地標的坐標值(dgXY) |
setXY(XY) | 重新設定此地標的坐標為 XY(dgXY) |
setContent(html/DOMo) | 重新設定此地標的顯示圖示為 html/DOMo |
以下為可自訂之滑鼠事件 | |
onclick=function() | |
ondblclick=function() | |
onmouseout=function() | |
onmousedown=function() | |
onmouseup=function() | |
onmouseover=funciton() | |
ondragend=funciton() [v7版提供] | |
onmousein=funciton() [v7版提供] | |
onmouseout=funciton() [v7版提供] |
dgPoint
dgPoint 物件是用來繪製點的物件。
建構式
建構式 | 說明 |
dgPoint(dgXY, color?, radius?) | 繪製一個座標為 dgXY 的點XY |
屬性
屬性 | 類別 | 說明 |
x | number | 這個點的 x(水平) 坐標。 |
y | number | 這個點的 y(垂直) 坐標。 |
dgSource
dgSource 物件圖資來源建構物件。
建構式
建構式 | 說明 |
dgSource(layer,options) | 產生圖示的物件 |
屬性
屬性 | 類別 | 說明 | ||||||||||||||||||||||||
layer | string |
圖資類別,目前提供的類別有:
|
||||||||||||||||||||||||
options | object |
圖資使用的參數,使用object的方式存放
GOOGLE情況下的參數
WMTS情況下的參數
|
dgKml
dgKml 物件載入kml連結使用的物件。
建構式
建構式 | 說明 |
dgKml(url,callback) | 載入url提供的kml/kmz |
屬性
屬性 | 類別 | 說明 |
url | string | kml網址。 |
callback | function | 載入kml結束後,將乎叫這個function |
函示
函式 | 說明 |
setFeatureClick(callback_function) |
設定選取KML Feature的事件 callback_function:回傳事件 回傳結果 arguments[0] (object) 回傳Feature的屬性 arguments[1] (string) 回傳Feature的類型Point|LineString|MultiPolygon|KmlCluster(開啟群組功能時回傳類型) arguments[2] (object) 回傳Feature的所有點位 |
setZoomWithoutCluster(boolean,zoom)[v7] | 設定開關開啟分群功能時,到哪一個zoom以上不分群 |
setUpperZoomByBoundary(boolean) | 是否縮放到該區範圍 |
setLabelVisible(boolean) | 是否顯示Label |
setIconVisible(boolean)【暫未開放】 | 是否顯示icon |
setOpacity(boolean)【暫未開放】 | 透明度設定 |
setFeatureSelectDisabled(boolean)【暫未開放】 | 是否啟用kml選擇 |
enableCluster(distance, threshold, dgGStyle)[v7] | 設定為簇的顯示方式。 distance:多少距離內當成群組; threshold:多少數量以上當成群組; dgGStyle:請參考dgGStyle說明文件。 |
enableCluster(distance, threshold, dgGStyle)[v7] | 設定為簇的顯示方式。 distance:多少距離內當成群組; threshold:多少數量以上當成群組; dgGStyle:請參考dgGStyle說明文件。 |
enableLineStringArrow(iconsrc, strokeStyle,strokeWidth)[v7] | 讓KML的Placemark為LineString產生方向箭頭 iconsrc:箭頭icon路徑 strokeStyle(string): 線段style, ex: "rgba(211,211,211,0.6)" strokeWidth(int):線段寬 |
dgGMarker
dgGMarker 物件為marker群組功能的物件。大量marker的情況下適用
建構式
建構式 | 說明 |
dgGMarker(markers,distance,threshold) | marker群組功能 |
屬性
屬性 | 類別 | 說明 |
markers | array[dgMarker] | 陣列中存放欲分群的dgMarker |
distance | int | 多少距離內的marker要合成一個cluster |
threshold | int | 至少要多少marker才合成一個cluster |
函式
函式 | 說明 |
setZoomWithoutCluster(int)【暫未開放】 | 大於等於哪個階層就不做cluster, 輸入的數值不可大於圖台的階層數 |
setRole(object)【暫未開放】 | 分群顯示方式自訂。請參照範例"的marker分群(GMarker)原始碼說明 |
register(eventType, callback) | 事件註冊。eventType目前僅提供click |
dgGStyle [v7版提供]
dgGStyle 物件為所有Cluster的風格
建構式
建構式 | 說明 |
dgGStyle() | Cluster風格 |
函式
函式 | 說明 |
setHigh(high) | 設定Cluster數量大於該數值顯示為紅色 |
setMedium(medium) | 設定Cluster數量大於該數值且小於heigh顯示為黃色 |
getHigh() | 取得heigh |
getMedium() | 取得Medium |
dgIcon
dgIcon 物件是產生圖示的物件。
建構式
建構式 | 說明 |
dgIcon(icon src, width, height) | 產生圖示的物件 |
繪圖物件附加參數說明:
color 參數說明:
為代表顏色之string, 如: "rgba(200,0,200,0.5)"; RGB值: 範圍為 0~255 如同一般色彩之定義; A為alpha值: 範圍 0~1
radius/weight 參數說明:
為代表半徑/寬度之int, 單位為 px
easymap 預設框線顏色為 "rgba(0,0,200,0.5)", 填滿顏色為 "rgba(200,0,200,0.5)", 點半徑為 5, 線寬為 8
dgPolyline
dgPolyline 是可以套疊在地圖上的一種物件,會以線段的方式顯示於地圖上。
建構式
建構式 | 說明 |
dgPolyline(dgXYs, color?, weight?) | 建立一個折線段物件,dgXYs(dgXY array)為此線段各折點之坐標,最少要有兩點,color 為此線段之顏色(預設值為藍色),weight 為此線段之螢幕寬度,單位為 px,預設值為 8 px。 |
函式
函式 | 說明 |
getVertexCount() | 取得此一折線段總共有多少折點。 |
getVertex(idx) | 取得第 idx 個折點的坐標值(dgXY)。 |
addVertex(XY) | 在此折線段的尾端加入一個坐標點 XY(dgXY)。 |
dgPolygon
dgPolygon 是可以套疊在地圖上的一種物件,會以多邊形的方式顯示於地圖上。
建構式
建構式 | 說明 |
dgPolygon(dgXYs,bordercolor?, fillcolor?, weight?) | 建立一個折線段物件,dgXYs(dgXY array)為此多邊形各折點之坐標,最少要有三點,bordercolor 為此多邊型外框之顏色,fillcolor 為此多邊形填滿之顏色,weight 為多邊形框線寬度,單位為 px,預設值為 8 px。 |
函式
函式 | 說明 |
getVertexCount() | 取得此一折線段總共有多少折點。 |
getVertex(idx) | 取得第 idx 個折點的坐標值(dgXY)。 |
addVertex(XY) | 在此折線段的尾端加入一個坐標點 XY(dgXY)。 |
dgCurve
dgCurve 是可以套疊在地圖上的一種物件,會以圓形的方式顯示於地圖上,可以是橢圓、圓、弧的方式出現。
建構式
建構式 | 說明 |
dgCurve(xy,ss,fs,ptR,sw,ang1,ang2,clockw) | 可以繪製於地圖上的一個圓物件。 |
屬性
屬性 | 類別 | 說明 |
xy | dgXY | 這個圓的圓心點。 |
ss | rgba | 填滿的顏色值 |
fs | rgba | 外框的顏色值 |
ptR | number | 半徑 |
sw | number | 線寬 |
ang1 | number | 畫圓的起始角度 |
ang2 | number | 畫圓的結束角度 |
clockw | number | 圓寬 |
EX: var dd = new parent.dgCurve(new parent.dgXY(x, y),"rgba(200,0,0,0.2)", "rgba(200,0,0,0.2)", range,2,90,90,1); parent.map.addItem(dd);
【暫未開放】dgRect
dgRECT 物件是用來表示一個坐標的矩形範圍。
建構式
建構式 | 說明 |
dgRect(dgXY,dgXY,fillcolor?,border?,bodercolor?) | 建立一個的矩形範圍。若未傳入這兩個參數則會建立一個空的(Empty)的矩形範圍。 |
函式
函式 | 說明 |
getSW() | 取得這個矩形範圍的西南角坐標(dgXY)。 |
getNE() | 取得這個矩形範圍的東北角坐標(dgXY)。 |
getWidth() | 取得這個矩形範圍的東西向涵蓋寬度,回傳值的單位為度(經度)。 |
getHeight() | 取得這個矩形範圍的南北向涵蓋高度,回傳值的單位為度(緯度)丑C |
getCenter() | 取得這個矩形範圍的中心點坐標(dgXY)。 |
contains(x,y) | 檢查 x,y(dgXY) 這個坐標是否包含在這個矩形範圍之內,是則傳回 true。 |
containsBounds(bounds) | 檢查 bounds(UBounds) 是否包含在這個矩形範圍之內,是則傳回 true。 |
extend(x,y) | 將這矩形範圍擴大到可以包含 x,y(dgXY) 的坐標。 |
isEmpty() | 檢查這個矩形範圍是否為空(不包含任何空間),若為空則傳回 true。 |
內建函數
函式 | 回為傳 | 說明 |
calLength(drawRval) | int | 計算多邊形長度。drawRval=getDrawResult()函數回傳值 |
calArea(drawRval) | int | 計算多邊形面積。drawRval=getDrawResult()函數回傳值 |
dgFMenu() | 顯示選單。可利用dgCMenu.push(new dgMenuFunc('列印',方法));增加右鍵功能 |
鷹眼修改範例
//初始化/resize/開啟鷹眼觸發
function wmapfunc0(iitems)
{
iitems[1].style.display = 'block';
iitems[1].style.visibility = 'visible';
iitems[1].style.left = '0px';
iitems[1].style.top = (tt.getHeight() - parseInt(iitems[1].height)) + 'px';
iitems[0].style.visibility = 'visible';
iitems[0].style.left = '0px';
iitems[0].style.top = (tt.getHeight()-Math.floor(tt.getHeight()/4)-parseInt(iitems[0].style.borderWidth)*2) + 'px';
iitems[0].style.width = (Math.floor(tt.getWidth()/5)) + 'px';
iitems[0].style.height = (Math.floor(tt.getHeight()/4)) + 'px';
}
//鷹眼圖層存在時觸發
function wmapfunc1(iitems)
{
iitems[1].src = 'imgs/rightdown.png';
iitems[1].style.left = iitems[0].style.left;
iitems[1].style.top = iitems[0].style.top;
iitems[1].style.visibility = 'visible';
}
//鷹眼圖層不存在時觸發
function wmapfunc2(iitems)
{
//alert('func2');
}
//關閉鷹眼時觸發
function wmapfunc3(iitems)
{
iitems[1].src = 'imgs/leftup.png';
iitems[1].style.left = '0px';
iitems[1].style.top = (tt.getHeight() - iitems[1].height) + 'px';
iitems[0].style.visibility = 'hidden';
}