開始使用

摘要

您可以使用 javascript API ，將點、線條、多邊形以疊加層的型態加入地圖當中，其中疊加層會結合樣式資訊與位置資料。

kwmap.Data 類別則是可以同時存放任意地理空間資料的容器，您可以透過資料層將任意地理資料的型態加入到地圖中，而不需要每個地理資料都使用一次疊加層。當資料內有包含幾何圖形時（例如點、線、多邊形），API 預設會將這些幾何圖形轉換成點、折線和多邊形的資料型態，您可以依照一般疊加圖層來設定這些圖形的外觀樣式，也可以套用資料層的其他屬性來設計樣式。

kwmap.Data 類別可以達成以下功能：

• 在地圖中加入 GeoJSON 資料。
  GeoJSON 是網路上常用地理空間資料的標準格式。Data 類別依照 GeoJSON 的結構呈現資料，可讓您輕鬆顯示 GeoJSON 資料。使用 addGeoJson() 方法即可輕鬆匯入 GeoJSON 資料，以及顯示點、線和多邊形。
• 在地圖上繪製多邊形。
  您可在單個多邊形中組合多個路徑，建立較複雜的形狀，例如填滿的環形 (又稱「甜甜圈」形，即多邊形區域內有另一個「獨立」的多邊形)。複雜的形狀都是由多個較簡單的路徑組成。
• 使用 kwmap.Data 即可建立任意資料的模型。
  現實生活中大多數的實體都有相關聯的其他屬性。舉例來說，商店有營業時間、道路有車流速度。您可以透過 kwmap.Data 建立這些屬性的模型，然後據此設定資料樣式。
• 選擇資料的呈現方式，隨時都能改變想法。
  資料層可讓您決定資料的視覺化呈現和互動方式。舉例來說，在查看資料圖層時，您可以選擇各幾何圖形呈現不同顯示樣式。

加入 GeoJSON 資料

GeoJSON 是在網路上分享地理空間資料的常見標準。這個標準十分簡潔，容易閱讀，因此很適合在分享和協作時使用。透過資料層，只要使用一行程式碼，就將 GeoJSON 資料加入 Kwmap 地圖中 。

每張地圖都有 data 物件，用於存放任意地理空間資料 (包括 GeoJSON) 的資料層。如要載入並顯示 GeoJSON 檔案，您可以呼叫 addGeoJson() 方法。以下範例說明如何加入地圖並載入外部 GeoJSON 資料。

提供 GeoJSON 測試資料

本頁大部分的範例都是使用常見的 GeoJSON 檔案。這個檔案將「KW」兩個字定義為位在臺北市大安區上的多邊形。測試資料層時，歡迎複製或修改這個檔案。

注意：如要從其他網域載入 JSON 檔案，該網域必須已啟用跨來源資源共享功能。

點線面圓四種預設圖形

mapPlus.Data 類別 : 分為點，線條，多邊形及圓形四種幾何圖形。

座標點使用方式

線條使用方式

多邊形使用方式

圓形使用方式

彈性調整幾何圖形

資料層包含多種不同類型的幾何圖形，使用 add() 以及 removeFeature()可即時新增或移除地圖上的座標點、線條和多邊形等元素，方便動態更新地圖內容以匹配使用需求或實時數據。

使用 add() 方法將新的幾何圖形添加到資料層，例如新增一個多邊形或線條來反映最新的地理資訊。

另外，透過 removeFeature() 方法，可以移除特定的幾何圖形。

繪製多邊形

Data.Polygon 類別可為您處理 polygon winding 的情況。您可以將一或多個線性環陣列 (內容為經緯度座標) 傳遞給這個類別。第一個線性環定義多邊形的外邊輪廓。如果您傳遞多個線性環，可以使用第二個和後續的線性環來定義多邊形的內部形狀 (孔洞)。

以下範例一個長方形的多邊形，其中含有兩個孔洞：

設定 GeoJSON 資料樣式

使用 Data.setStyle() 方法即可指定資料的呈現方式。setStyle() 方法會採用 Style 物件常值，或是用於計算各個地圖項目樣式的函式。

樣式選項

依據地圖項目類型，提供設定樣式時可用的選項。舉例來說，fillColor 只會顯示在多邊形幾何圖形上，而 icon 只會顯示在點幾何圖形上。

適用於所有幾何圖形

• clickable (boolean)：預設為 true，如果為 true，這個地圖項目就會接收滑鼠和觸控事件。
• visibility (string)：預設為 visible，如果為 none，資料層的地圖項目則會隱藏。
• zIndex (number)：所有地圖項目皆按照 zIndex 順序顯示在地圖上，值較高的地圖項目會在比值較低的地圖項目上層。點一律會顯示在線串和多邊形的上方。
• title (string)：滑鼠游標懸停顯示的文字內容。
• textField (string)：為預設顯示的文字內容，可以是靜態文字或來自屬性字段的動態值，若幾何圖形為線或面，可視需求另外使用 displayFeatureText 實例方法來顯示指定的欄位內容。
• textSize (number)：預設為 15，用於控制符號文字的字體大小，以像素為單位進行設定。
• textColor (string)：預設為 black，設定符號文字的顏色，支持靜態值或表達式控制不同條件下的顏色。
• textLetterSpacing (number)：預設為 0，文字間距，範圍介於 -5 至 1 之間。
• textOffset (array[number, number])：預設為 [-1, 0]，文字相對於 icon 的偏移量 [x, y]。
• textStrokeColor (string)：預設為 transparent，文字的邊框顏色，支持靜態值或表達式控制不同條件下的顏色。
• textStrokeWidth (number)：預設為 0，文字的邊框寬度。

適用於點幾何圖形

• cursor (string)：滑鼠游標類型。
• icon (string)：預設為 black_location，針對點幾何圖形顯示的圖示。
• iconSize (number)：預設為 1，用於調整圖示的大小比例，範圍於 0.0 到無限，單位是圖示原始大小的倍數，此屬性需要設定 icon。
• iconAnchor (string)：預設為 bottom，圖示旋轉時的錨點位置，可選擇 top, center, bottom。
• textAnchor (string)：預設為 right，文字的對齊錨點位置，可選擇 center, left, right, top, bottom, top-left, top-right, bottom-left, bottom-right。
• rotationAlignmentMap (boolean)：預設為 false，圖示及文字對齊地圖的方向，true 為平行地圖方向，false 為垂直地圖方向。
• textRectEnabled (boolean)：預設為 false，是否啟用文字背景框，當為 true 時，textRect- 系列屬性才會生效。
• textRectColor (string)：預設為 white，文字背景框的背景顏色，支持靜態值或表達式控制不同條件下的顏色。
• textRectStrokeColor (string)：預設為 rgba(0, 0, 0, 0.3)，文字背景框的邊框顏色。
• textRectStrokeWidth (number)：預設為 1，文字背景框的邊框寬度。
• textRectOpacity (number)：預設為 1，文字背景框的透明度，設置範圍介於 0.001 至 1 之間。
• textRectBorderRadius (number)：預設為 16，文字背景框的圓角值，設置範圍介於 1 至 16 之間。

※注意： 添加文字邊框 (textStroke-) 與文字背景框 (textRect-) 之間只能設置一種，若同時設置，則文字邊框會失效。當文字背景框與 icon 重疊時，文字背景框會自動隱藏，因此須設置 textOffset 來調整 icon 與文字背景框的距離。

※下列屬性僅可透過 setGlobalStyle 設置，詳情參考 setGlobalStyle 介紹：

• iconOverlap (string)：預設為 always，點幾何圖形的圖示之間重疊與否，可選擇 always(可互相重疊顯示), never(不可互相重疊顯示，即當重疊時會自動隱藏)。
• textOverlap (string)：預設為 always，點幾何圖形的文字之間重疊與否，可選擇 always(可互相重疊顯示), never(不可互相重疊顯示，即當重疊時會自動隱藏)。

適用於線幾何圖形

• strokeColor (string)：預設為 black，筆觸顏色。系統支援所有 CSS3 顏色，延伸的具名顏色除外。
• strokeOpacity (number)：預設為 0.8，筆觸不透明度，範圍介於 0.0 和 1.0 之間。
• strokeWeight (number)：預設為 3，筆觸寬度 (以像素為單位)。

適用於多邊形及圓形幾何圖形

※注意： 圓形幾何圖形（Circle）在內部會被轉換為多邊形（Polygon），因此適用與多邊形相同的樣式選項。

• fillColor (string)：預設為 lightgray，填滿顏色。系統支援所有 CSS3 顏色，延伸的具名顏色除外。
• fillOpacity (number)：預設為 0.5，填滿不透明度，範圍介於 0.0 和 1.0 之間。
• strokeColor (string)：預設為 black，筆觸顏色。系統支援所有 CSS3 顏色，延伸的具名顏色除外。
• strokeOpacity (number)：預設為 0.8，筆觸不透明度，範圍介於 0.0 和 1.0 之間。
• strokeWeight (number)：預設為 3，筆觸寬度 (以像素為單位)。

設計樣式規則

要設定地圖項目樣式，最簡單的方法就是將 Style 物件常值傳遞至 setStyle()。這樣就能統一設定資料層內每個地圖項目的外觀樣式。請注意，每種地圖項目只能渲染一部分的可用選項。

不過，您可以在單一物件常值中同時使用不同幾何圖形類別的樣式。舉例來說，下方程式碼片段採用只影響點幾何圖形的自訂 icon，以及只影響多邊形的 fillColor屬性。即可同時

如要進一步瞭解有效樣式/地圖項目組合，請參閱「樣式選項」一文。

以下範例說明如何使用 Style 物件常值，同時設定多個地圖項目的線條和多邊形內部顏色。請注意，所有地圖項目的樣式皆相同。

宣告樣式規則

如果您想更新大量疊加層 (例如點或折線) 的樣式，通常必須先在地圖上反覆建立每個疊加層，並分別設定樣式。只要使用資料層，即可透過宣告方式設定規則，並套用至整個資料集。資料或規則更新完成後，樣式就會自動套用至各個地圖項目。您可以使用地圖項目屬性來自訂樣式。

舉例來說，下方程式碼會檢查 example.geojson 中每個字元在 ASCII 字元集的位置，以便分別為這些字元設定顏色。在本例中，我們已將字元位置連同資料一併編碼。

新增 icon 圖示

如果您想使用外部 URL 的圖片放入資料層中，使用 loadImage() 加載完圖片後，就能直接以座標點 Feature 呈現。

移除樣式

如要移除任何已套用的樣式，請將空白物件常值傳遞至 setStyles() 方法。

這樣會移除您指定的所有自訂樣式，而地圖項目會使用預設樣式進行算繪。如果您不想再算繪這些地圖項目，請將 Style 的 visible 屬性設為 false，隱藏資料層的地圖項目。

覆蓋預設樣式

樣式規則通常會套用至資料層中的每個地圖項目。不過，有時您可能會想將特殊樣式規則套用至特定地圖項目，例如在使用者點擊時突顯某個地圖項目。

如要套用特殊樣式規則，請使用 overrideStyle() 方法。除了已在 setStyle() 中指定的全域樣式外，系統也會套用透過 overrideStyle() 方法變更指定項目的外觀。舉例來說，下方程式碼會在使用者點擊時變更多邊形的填滿顏色，但不會設定任何其他樣式，也不會影響到其餘地圖項目。

呼叫 revertStyle() 方法即可移除所有樣式覆寫。

新增事件處理常式

地圖項目會回應鼠標事件，例如 mouseup 或 mousedown 。您可以新增事件監聽器，讓使用者能在地圖上與資料互動。在以下例子中，我們新增滑鼠游標懸停事件，讓地圖項目相關資訊顯示在視窗左上方。

資料層事件

以下是所有地圖項目常見的事件 (適用於所有幾何圖形類型)：

• click
• mousedown
• mouseout
• mouseover
• mouseup

動態變更外觀

如要設定資料層的樣式，您可以傳遞計算每個地圖項目樣式的函式至kwmap.data.setStyle()方法，當地圖在渲染時，系統就會呼叫這個函式。

在下例中，我們為 click 事件新增事件監聽器，以便動態更新地圖項目的外觀。屬性設定完成後，系統會按照上述變更內容更新地圖項目樣式。