實例方法

關於資料層使用API的詳細說明及範例。

Data

實例方法描述
addGeoJson將整份 Geojson 資料集加入地圖。
add可獨立加入 Feature 到地圖上。
removeFeature從地圖中移除指定的 Feature，支援單筆或批次移除。
removeFeatureById依據唯一值的屬性 ID，從地圖中移除 Feature。
getFeatureById根據唯一 id 取得地圖中的指定項目。
setStyle設定資料層上所有地圖項目的樣式，可針對地圖項目個別設定。
setGlobalStyle全局設定資料層上地圖項目的樣式，不可針對地圖項目個別設定，所有的地圖項目皆須統一套用同一樣式設定。
overrideStyle覆蓋指定 Feature 的樣式，暫時改變其外觀。
revertStyle移除使用 overrideStyle 覆蓋的樣式。
revertGlobalStyle恢復全域樣式屬性為預設值。
toGeoJson將資料層內的地圖項目輸出至 GeoJSON 格式。
forEachFeature遍歷地圖中的所有 Feature ，用於重複呼叫指定函式。
filterFeature根據條件篩選資料層中的 Feature，回傳符合條件的陣列。
clear移除資料層內所有的地圖項目。
enableCluster是否啟用資料層叢集功能。
toggleClusterPoints顯示或隱藏所有資料層叢集點。
toggleNonClusterPoints顯示或隱藏所有資料層非叢集點。
Point.moveUp將點圖層群組往上移動一層。
Point.moveDown將點圖層群組往下移動一層。
LineString.moveUp將線圖層群組往上移動一層。
LineString.moveDown將線圖層群組往下移動一層。
FlattenPoint.moveUp將平貼地圖的點圖層群組往上移動一層。
FlattenPoint.moveDown將平貼地圖的點圖層群組往下移動一層。

Feature

實例方法描述
setProperty設定指定屬性的內容。
getProperty回傳屬性的值。
removeProperty移除特定屬性。
setGeometry設定地圖項目的經緯度位置。
getGeometry回傳地圖項目的經緯度位置。
setVisible設定地圖項目的顯示與否。
getBounds回傳地圖項目的邊界點。
getCenter回傳地圖項目的中心點。
getLeft回傳地圖項目的最左座標點。
getRight回傳地圖項目的最右座標點。
getTop回傳地圖項目的最頂部座標點。
getBottom回傳地圖項目的最底部座標點。
forEachProperty遍歷所有屬性內容 ，用於重複呼叫指定函式。
displayFeatureText添加幾何圖形的文字說明，圖形類別：線條為間距顯示，多邊形及圓形則顯示在圖形中央。
removeDisplayText移除以 displayFeatureText 方法添加的文字項目。
iconAlongLinestring增加 ICON 至線條圖形上。

Feature Group

實例方法描述
Point.moveUp將座標點群組往上移動一層。
Point.moveDown將座標點群組往下移動一層。
FlattenPoint.moveUp將平貼地圖的座標點群組（帶有 rotationAlignmentMap: true 的座標點）往上移動一層。
FlattenPoint.moveDown將平貼地圖的座標點群組（帶有 rotationAlignmentMap: true 的座標點）往下移動一層。
LineString.moveUp將線條群組往上移動一層。
LineString.moveDown將線條群組往下移動一層。

Data

處理地理幾何圖形的圖層，支援座標點、線條、多邊形及圓形，包含 Features 的集合資料。每個 map 內都會有 Data 物件，不用再自行建構。

addGeoJson

addGeoJson(geojson)

將整份 Geojson 資料集加入地圖。

參數

  • geojson (object): 符合 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.data.addGeoJson(  "https://kw3dmap.autoking.com.tw/kwmap/assets/demo/geojson/example.geojson");

add

add(feature)

加入單筆或多筆 Feature 到地圖上。若傳入的 feature 的 id 已存在，則更新該筆資料而不重複新增。

參數

  • feature (object | Array<object>) : 單筆 feature 或多筆 feature 陣列，每筆 feature 需包含 geometry 及 properties 兩種物件。

範例

javascript
// 單筆新增map.data.add({  geometry: new mapPlus.Data.Point({    lng: 121.52375708643336,    lat: 25.0306273554757,  }),  properties: {    id: 0,  },});
// 批次新增（陣列）map.data.add([  {    geometry: new mapPlus.Data.Point({      lng: 121.52375708643336,      lat: 25.0306273554757,    }),    properties: { id: 0 },  },  {    geometry: new mapPlus.Data.Point({      lng: 121.53012345678901,      lat: 25.0412345678901,    }),    properties: { id: 1 },  },]);

getFeatureById

getFeatureById(id)

根據 id 取得地圖中的指定項目。

參數

  • id (number | string) : 各 Feature 的唯一鍵值。

回傳

object : geojson 的 feature 格式。

範例

javascript
const theFeature = map.data.getFeatureById(1);

removeFeature

removeFeature(feature)

從地圖中移除指定的 Feature，支援單筆或批次移除，可傳入 Feature 物件或其唯一值 id。

參數

  • feature (object | number | string | Array<object | number | string>) : 待移除的對象，可為單筆 Feature 物件、單筆 id，或由多筆 Feature 物件、id 組成的陣列。

範例

javascript
// 單筆移除（Feature 物件）const removeFea = map.data.getFeatureById(1);map.data.removeFeature(removeFea);
// 單筆移除（id）map.data.removeFeature(1);
// 批次移除（Feature 物件陣列）const fea1 = map.data.getFeatureById(1);const fea2 = map.data.getFeatureById(2);map.data.removeFeature([fea1, fea2]);
// 批次移除（id 陣列）map.data.removeFeature([1, 2, 3]);
// 搭配 filterFeature 篩選後批次移除const targetFeas = map.data.filterFeature((fea) => fea.properties.type === "A");map.data.removeFeature(targetFeas);

removeFeatureById

removeFeatureById(id)

依據唯一值的屬性 ID，從地圖中移除 Feature。

參數

  • id (number | string) : 接收待刪除的地圖項目 id。

範例

javascript
map.data.removeFeatureById(1);

setStyle

setStyle(callback | style)

設定資料層上所有地圖項目的樣式，可針對地圖項目個別設定。

參數

  • callback (function) : 回調函數，返回資料層中所有地圖項目。
  • style (object) : 樣式更改結果。

範例

javascript
// callback 使用條件判斷，針對各個地圖項目分開設定樣式map.data.setStyle((fea) => {  if (fea.getProperty("id") === 1) fea.setProperty("strokeColor", "red");  else fea.setProperty("strokeColor", "blue");});
// object 一次修改全部地圖項目的樣式map.data.setStyle({  icon: "B01",  fillColor: "green",});

setGlobalStyle

setGlobalStyle(style)

全局設定資料層上的點幾何圖形樣式，不可針對地圖項目個別設定，所有的地圖項目皆須統一套用同一樣式設定。

  • 目前支援可設定的屬性：iconOverlap、textOverlap。

參數

  • style (object) : 樣式更改結果。

範例

javascript
// 所有地圖項目統一套用以下樣式設定map.data.setGlobalStyle({  iconOverlap: "never",  textOverlap: "never"});

overrideStyle

overrideStyle(feature, style)

覆蓋指定 Feature 的樣式，暫時改變其外觀。

參數

  • feature (object) : 資料層中的地圖項目。
  • style (object) : 覆蓋的樣式。

範例

javascript
map.data.overrideStyle(feature, { fillColor: "red" });

revertStyle

revertStyle()

移除使用 overrideStyle 所渲染的覆蓋樣式。

範例

javascript
map.data.revertStyle();

revertGlobalStyle

revertGlobalStyle()

恢復全域樣式屬性為預設值。

範例

javascript
map.data.revertGlobalStyle();

toGeoJson

toGeoJson(callback)

將資料層內的地圖項目輸出至 GeoJSON 格式。

參數

  • callback : 以 Geojson 格式輸出整個資料層的地圖項目。

範例

javascript
map.data.toGeoJson((data) => {  console.log(data);});

forEachFeature

forEachFeature(callback)

遍歷地圖中的所有 Feature，用於重複呼叫指定函式。

參數

  • callback (function) : 回調函數，返回資料層中所有地圖項目。

範例

javascript
map.data.forEachFeature((feature) => {  map.data.removeFeature(feature);});

filterFeature

filterFeature(predicate)

根據條件篩選資料層中的所有 Feature，回傳符合條件的 Feature 陣列。若 predicate 不是函式，則回傳空陣列。

參數

  • predicate (function) : 回調函數，對每個 Feature 執行判斷，返回 true 的項目會被納入結果。

回傳

Array<object> : 符合條件的 Feature 陣列。

範例

javascript
// 篩選出 type 屬性為 "A" 的所有 Featureconst result = map.data.filterFeature((fea) => fea.properties.type === "A");console.log(result);

clear

clear()

移除資料層內所有的地圖項目。

範例

javascript
map.data.clear();

enableCluster

enableCluster(enabled, options)

是否啟用資料層叢集功能。詳細使用方法可見資料層叢集。

參數

  • enabled (boolean) : 是否啟用叢集功能。
  • options (object) : 叢集圖的參數。
參數描述
options.radius number選填，叢集半徑，以像素為單位，預設為 50。
options.maxZoom number選填，叢集圖層會停止叢集化的最大縮放級別，預設為 14。
options.styles object選填，叢集圖的樣式設置。

範例

javascript
map.data.enableCluster(true);

toggleClusterPoints

toggleClusterPoints(visible)

顯示或隱藏所有資料層叢集點。

參數

  • visible (boolean): 是否顯示資料層叢集點。

範例

javascript
// 隱藏叢集點map.data.toggleClusterPoints(false);
// 顯示叢集點map.data.toggleClusterPoints(true);

toggleNonClusterPoints

toggleNonClusterPoints(visible)

顯示或隱藏所有資料層非叢集點。

參數

  • visible (boolean): 是否顯示資料層非叢集點。

範例

javascript
// 隱藏非叢集點map.data.toggleNonClusterPoints(false);
// 顯示非叢集點map.data.toggleNonClusterPoints(true);

Feature

地圖項目包含唯一 ID、幾何圖形及屬性資料。請搭配 data.setStyle 或 data.getFeatureById 一起使用。

setProperty

setProperty(property, value)

設定指定屬性的內容。

參數

  • property (string) : 地圖項目的屬性名稱。
  • value (string | number) : 需設定的值。

範例

javascript
const theFeature = map.data.getFeatureById(1);theFeature.setProperty("strokeColor", "red");

getProperty

getProperty(property)

回傳屬性的值。

參數

  • property (string) : 指定的屬性名稱。

範例

javascript
map.data.setStyle((fea) => {  if (fea.getProperty("id") === 1) fea.setProperty("strokeColor", "red");});

removeProperty

removeProperty(property)

移除特定屬性，其中 id 為識別地圖項目的唯一值，因此不可刪除。

參數

  • property (string) : 移除的屬性名稱。

範例

javascript
const theFeature = map.data.getFeatureById(1);theFeature.removeProperty("name");

setGeometry

setGeometry(geometry)

設定地圖項目的經緯度位置，經度在前緯度在後。

參數

  • geometry (array) : 包含經緯度的陣列。

範例

javascript
const theFeature = map.data.getFeatureById(1);const newCoordinates = [121.528327, 25.041783];theFeature.setGeometry(newCoordinates);

getGeometry

getGeometry()

回傳地圖項目的經緯度位置。

回傳

  • geometry (array) : 幾何圖形的經緯度陣列。

範例

javascript
const theFeature = map.data.getFeatureById(1);console.log(theFeature.getGeometry());

setVisible

setVisible(visible)

設定地圖項目的顯示與否。

參數

  • visible (boolean) : 是否顯示地圖項目。

範例

javascript
const theFeature = map.data.getFeatureById(1);theFeature.setVisible(false);

getBounds

getBounds()

回傳地圖項目的邊界點。

回傳

  • geometry (array) : 幾何圖形的邊界經緯度陣列。

範例

javascript
const theFeature = map.data.getFeatureById(1);console.log(theFeature.getBounds());// [//   [121.528007, 25.026569],//   [121.530466, 25.0281305]// ]

getCenter

getCenter()

回傳地圖項目的中心點。

回傳

  • geometry (array) : 幾何圖形的中心點經緯度陣列。

範例

javascript
const theFeature = map.data.getFeatureById(1);console.log(theFeature.getCenter());// [121.5292365, 25.02734975]

getLeft

getLeft()

回傳地圖項目的最左座標點。

回傳

  • geometry (array) : 幾何圖形的最左經緯度陣列。

範例

javascript
const theFeature = map.data.getFeatureById(1);console.log(theFeature.getLeft());// [121.528007, 25.026766]

getRight

getRight()

回傳地圖項目的最右座標點。

回傳

  • geometry (array) : 幾何圖形的最右經緯度陣列。

範例

javascript
const theFeature = map.data.getFeatureById(1);console.log(theFeature.getRight());// [121.530466, 25.027895]

getTop

getTop()

回傳地圖項目的最頂部座標點。

回傳

  • geometry (array) : 幾何圖形的最頂部經緯度陣列。

範例

javascript
const theFeature = map.data.getFeatureById(1);console.log(theFeature.getTop());// [121.528262, 25.0281305]

getBottom

getBottom()

回傳地圖項目的最底部座標點。

回傳

  • geometry (array) : 幾何圖形的最底部經緯度陣列。

範例

javascript
const theFeature = map.data.getFeatureById(1);console.log(theFeature.getBottom());// [121.530385, 25.026569]

forEachProperty

forEachProperty(callback)

遍歷所有屬性內容 ，用於重複呼叫指定函式。

參數

  • callback (function) : 回調函數，該回調函式返回包含 屬性內容 以及屬性名稱的物件。

範例

javascript
feature.forEachProperty((value, property) => {  console.log(value, property);});

displayFeatureText

displayFeatureText(text)

添加幾何圖形的文字說明，若為線條幾何圖形則文字為間距顯示；多邊形及圓形幾何圖形文字則會顯示在圖形中央。

此方法會直接將文字同步到地圖上，不須搭配 setStyle 即可直接使用並即時更新畫面。

參數

  • text (string) : 可輸入屬性名稱或是文字內容。

範例

直接取得 Feature 後呼叫，即可立即顯示文字：

javascript
const fea = map.data.getFeatureById(0);
// 1. 接收文字的 string 型態fea.displayFeatureText("板南線");
// 2. 接收要顯示的 property namefea.displayFeatureText("name");

也可在 setStyle 中搭配使用：

javascript
map.data.setStyle((fea) => {  const { id } = fea.properties;
  if (id === 0) {    // 1. 接收文字的string型態    fea.displayFeatureText("板南線");  } else {    // 2. 接收要顯示的property name    fea.displayFeatureText("name");  }});

removeDisplayText

removeDisplayText()

移除以 displayFeatureText 方法添加的文字項目。

範例

javascript
map.data.setStyle((fea) => {  fea.removeDisplayText();});

iconAlongLinestring

iconAlongLinestring()

沿著線條 Feature 增加 ICON 顯示，可依據使用情況調整 ICON 的樣式。 詳細使用方法可見範例：

參數

  • options(object) : 要設定的 ICON 樣式。

    參數描述
    options.iconImage (string)圖案名稱，預設為 "black_location"。
    options.iconSize (number)圖案大小，預設為 1。
    options.rotationAlignmentMap (boolean)ICON 的垂直目標，true 為垂直線條方向, false 為垂直地圖視窗方向。
    options.iconRotate (number)順時針的旋轉角度，以角度為單位，預設為 0。

範例

javascript
map.data.setStyle((fea) => {  if (fea.getProperty("id") === 3) {    fea.iconAlongLinestring({      iconImage: "newImage",      iconSize: 0.1,      rotationAlignmentMap: false,    });  }});

Feature Group

資料層會依幾何類型或特性分為數個群組，並依繪製順序由下而上堆疊。以下方法可調整各群組相對於其他群組的上下層級，藉此控制不同類型圖形之間的覆蓋關係，下表為由上到下層的排列順序。

群組描述
map.data.Point座標點群組
map.data.FlattenPoint平貼地圖的座標點群組（rotationAlignmentMap: true 的座標點）
map.data.LineString線條群組

Point.moveUp

Point.moveUp()

將座標點群組往上移動一層。

範例

javascript
map.data.Point.moveUp();

Point.moveDown

Point.moveDown()

將座標點群組往下移動一層。

範例

javascript
map.data.Point.moveDown();

FlattenPoint.moveUp

FlattenPoint.moveUp()

將平貼地圖的座標點群組（帶有 rotationAlignmentMap: true 的座標點）往上移動一層。

範例

javascript
map.data.FlattenPoint.moveUp();

FlattenPoint.moveDown

FlattenPoint.moveDown()

將平貼地圖的座標點群組（帶有 rotationAlignmentMap: true 的座標點）往下移動一層。

範例

javascript
map.data.FlattenPoint.moveDown();

LineString.moveUp

LineString.moveUp()

將線條群組往上移動一層。

範例

javascript
map.data.LineString.moveUp();

LineString.moveDown

LineString.moveDown()

將線條群組往下移動一層。

範例

javascript
map.data.LineString.moveDown();