介紹

Kwmap 地圖資料層提供可存放任意地理空間資料的容器。您可以使用資料層來儲存自訂資料，或是在 Kwmap 地圖上顯示 GeoJSON 資料。

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

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

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

在地圖中加入 GeoJSON 資料。

GeoJSON 是網路上常用地理空間資料的標準格式。Data 類別依照 GeoJSON 的結構呈現資料，可讓您輕鬆顯示 GeoJSON 資料。使用 addGeoJson() 方法即可輕鬆匯入 GeoJSON 資料，以及顯示點、線和多邊形。
在地圖上繪製多邊形。

您可在單個多邊形中組合多個路徑，建立較複雜的形狀，例如填滿的環形 (又稱「甜甜圈」形，即多邊形區域內有另一個「獨立」的多邊形)。複雜的形狀都是由多個較簡單的路徑組成。
使用 mapPlus.Data 即可建立任意資料的模型。

現實生活中大多數的實體都有相關聯的其他屬性。舉例來說，商店有營業時間、道路有車流速度。您可以透過 mapPlus.Data 建立這些屬性的模型，然後據此設定資料樣式。
選擇資料的呈現方式，隨時都能改變想法。

資料層可讓您決定資料的視覺化呈現和互動方式。舉例來說，在查看資料圖層時，您可以選擇各幾何圖形呈現不同顯示樣式。

快速開始

建議依照以下流程快速上手資料層：

建立地圖實例並完成初始化。
透過 addGeoJson() 或 map.data.add() 新增地理資料。
使用 setStyle() 與事件監聽設定互動與外觀。

加入 GeoJSON 資料

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

javascript

map.addGeoJson(  "https://kw3dmap.autoking.com.tw/kwmap/assets/demo/geojson/example.geojson");

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

javascript

const map = await mapPlus(document.getElementById("map"), {  accessKey: 'get_your_key',  accessToken: 'get_your_token',  style: 'https://kw3dmap.localking.com.tw/openapi/map/kwmap.etxt',});
map.addGeoJson(  "https://kw3dmap.autoking.com.tw/kwmap/assets/demo/geojson/example.geojson");

提供 GeoJSON 測試資料

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

javascript

{  type: "FeatureCollection",  features: [    {      type: "Feature",      properties: {        id: 0,        letter: "K",        ascii: 75,        fillColor: "gray",        strokeColor: "gray",      },      geometry: {        coordinates: [          [            [121.52375708643336, 25.0306273554757],            [121.52375708643336, 25.026067042216397],            [121.52462827739583, 25.026067042216397],            [121.52462827739583, 25.027549378367056],            [121.52518796867085, 25.028119137700706],            [121.52644756322877, 25.026067042216397],            [121.52739209839893, 25.026067042216397],            [121.52576815003226, 25.028674327329],            [121.52753332805821, 25.0306273554757],            [121.52649044795595, 25.0306273554757],            [121.52462827739583, 25.028644048825196],            [121.52462827739583, 25.0306273554757],            [121.52375708643336, 25.0306273554757],          ],        ],        type: "Polygon",      },    },    {      type: "Feature",      properties: {        id: 1,        letter: "W",        ascii: 87,        fillColor: "gray",        strokeColor: "gray",      },      geometry: {        coordinates: [          [            [121.52801245164932, 25.030203259013177],            [121.52898528453608, 25.02608590163244],            [121.53005301651632, 25.02608590163244],            [121.53053091535037, 25.028416586705333],            [121.53101518531486, 25.02609137707593],            [121.532077886683, 25.026094617962798],            [121.53312706384492, 25.030203259013177],            [121.53216216159376, 25.030203259013177],            [121.53160467465699, 25.027343246383893],            [121.53103785347992, 25.030203259013177],            [121.5300604571566, 25.030203259013177],            [121.52951133334614, 25.02738084467012],            [121.52895708131763, 25.030203259013177],            [121.52801245164932, 25.030203259013177],          ],        ],        type: "Polygon",      },    },  ],}

幾何圖形類型

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

類型	描述
Point	座標點的幾何圖形，包含一組 `LngLat` 型態的物件。
LineString	線條的幾何圖形，包含一組陣列，內容為多組 `LngLat` 物件，最少由兩個物件組成。
Polygon	多邊形的幾何圖形，包含一組二維陣列，以 `Array[0][0]` 的內容形成多邊形外框，其中第二層若為一組陣列則圖形為實心多邊形，第二組以上陣列皆為該多邊形內的孔洞。
Circle	圓形的幾何圖形，包含一組 `LngLat` 型態的中心點座標、半徑（單位：公尺，預設為 `50`）以及分段數（預設為 `64`，用於將圓形轉換為多邊形時的平滑度）。

Point：座標點

map.data.add({  geometry: new mapPlus.Data.Point({ lng: 121.528567, lat: 25.028045 }),});

LineString：線條

map.data.add({  geometry: new mapPlus.Data.LineString([    { lng: 121.528267, lat: 25.027445 },    { lng: 121.529984, lat: 25.027291 },  ]),});

Polygon：多邊形

map.data.add({  geometry: new mapPlus.Data.Polygon([    [      { lng: 121.528262, lat: 25.0281305 },      { lng: 121.528007, lat: 25.026766 },      { lng: 121.530385, lat: 25.026569 },      { lng: 121.530466, lat: 25.027895 },    ],  ]),});

繪製有孔洞的多邊形

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

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

// 宣告外輪廓的經緯度座標const outerCoords = [  { lat: 25.02403, lng: 121.52375 },  { lat: 25.01803, lng: 121.52375 },  { lat: 25.01803, lng: 121.53353 },  { lat: 25.02403, lng: 121.53353 },];
// 宣告左內輪廓的經緯度座標const innerCoords1 = [  { lat: 25.02253, lng: 121.5255 },  { lat: 25.01953, lng: 121.5255 },  { lat: 25.01953, lng: 121.5275 },  { lat: 25.02253, lng: 121.5275 },];
// 宣告右內輪廓的經緯度座標const innerCoords2 = [  { lat: 25.02253, lng: 121.5295 },  { lat: 25.01953, lng: 121.5295 },  { lat: 25.01953, lng: 121.5315 },  { lat: 25.02253, lng: 121.5315 },];
// 將多邊形加進資料層，並填為黃色map.data.add({  geometry: new mapPlus.Data.Polygon([    outerCoords,    innerCoords1,     innerCoords2,  ]),  properties: {    fillColor: "yellow",  },});

Circle：圓形

map.data.add({  geometry: new mapPlus.Data.Circle({    lng: 121.528567,    lat: 25.028045,    radius: 100, // 半徑（單位：公尺）    segments: 64, // 分段數（可選，預設為 64）  }),});

增刪幾何圖形

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

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

map.data.add({  geometry: new mapPlus.Data.Point({    lng: 121.52375708643336,    lat: 25.0306273554757,  }),  properties: {    id: 0,  },});

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

const removeFea = map.data.getFeatureById(1);map.data.removeFeature(removeFea);

設定資料層樣式

使用 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` 之間。

適用於線幾何圖形

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

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

屬性	描述
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 屬性，即可將點及多邊形同時套用所設定的樣式。

javascript

map.data.setStyle({  icon: "B01",  fillColor: "green",});

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

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

// 將 geojson 資料加進圖層await map.addGeoJson(  "https://kw3dmap.autoking.com.tw/kwmap/assets/demo/geojson/example.geojson");
// 設置多邊形的外框寬度及填充顏色map.data.setStyle({  fillColor: "green",  strokeWeight: 1,});

透過宣告設定樣式規則

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

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

// 將 ASCII 編碼小於 80 的字母設為紅色，其餘為藍色map.data.setStyle(function (feature) {  const ascii = feature.getProperty("ascii");  const color = ascii > 80 ? "red" : "blue";  return {    fillColor: color,    strokeWeight: 1,  };});

新增自訂 icon 圖示

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

// 加載 url 圖片檔，並設定圖片名稱map.loadImage({  png: "https://kw3dmap.localking.com.tw/3dmap/img/kingway.png",  imageName: "newImage",});
// 變更 icon 圖案樣式map.data.setStyle({ icon: newImage });

移除樣式

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

// 移除自訂樣式map.data.setStyle({});

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

// 隱藏資料層的所有地圖項目map.data.setStyle({ visible: false });

覆蓋預設樣式

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

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

// 設置所有地圖項目的樣式map.data.setStyle({  fillColor: "green",  strokeWeight: 3,});
// 當點擊 feature 時，只會將填滿顏色樣式覆蓋變更為紅色，不會影響到外框寬度map.addListener("click", function (feature) {  map.data.overrideStyle(feature, { fillColor: "red" });});

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

動態變更外觀

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

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

// 將 geojson 資料加進圖層await map.addGeoJson(  "https://kw3dmap.autoking.com.tw/kwmap/assets/demo/geojson/example.geojson");
// 當點擊字母時，將自訂屬性 isColorful 設為 true，並將字母依 ascii 設置相應的顏色map.addListener("click", (feature) => {  feature.setProperty("isColorful", true);  map.data.setStyle((feature) => {    // 抓取 ascii 欄位，以此作為顏色劃分的條件    const ascii = feature.getProperty("ascii");    const color = ascii > 80 ? "#014099" : "#009fa8";    if (feature.getProperty("isColorful")) {      return {        fillColor: color,        strokeColor: color,      };    }  });});
// 當鼠標懸浮在字母上時，先回歸原本樣式，再加粗外框寬度map.addListener("mouseover", function (feature) {  map.data.revertStyle();  map.data.overrideStyle(feature, { strokeWeight: 8 });});
// mouseout 因事件為鼠標離開 feature，改為回傳 eventmap.addListener("mouseout", function (event) {  map.data.revertStyle();});

事件處理

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

// 將 geojson 資料加進圖層await map.addGeoJson(  "https://kw3dmap.autoking.com.tw/kwmap/assets/demo/geojson/example.geojson");
// 在每個 feature 上加入鼠標移入事件 map.addListener("mouseover", function (feature) {  document.getElementById("info-box").textContent =    feature.getProperty("letter");});

資料層事件

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

click
mousedown
mouseup
mouseover
mouseout