Skip to main content

實例方法

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 格式的幾何圖形資料。

範例​

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 兩種物件。

範例​

// 單筆新增
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 格式。

範例​

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

removeFeature​

removeFeature(feature)

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

參數​

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

範例​

// 單筆移除（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 移除。建議改用 removeFeature，其同時支援單筆／批次移除，並可傳入 Feature 物件或 id。

參數​

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

範例​

map.data.removeFeatureById(1);

setStyle​

setStyle(callback | style)

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

參數​

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

範例​

// 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) : 樣式更改結果。

範例​

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

overrideStyle​

overrideStyle(feature, style)

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

參數​

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

範例​

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

revertStyle​

revertStyle()

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

範例​

map.data.revertStyle();

revertGlobalStyle​

revertGlobalStyle()

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

範例​

map.data.revertGlobalStyle();

toGeoJson​

toGeoJson(callback)

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

參數​

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

範例​

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

forEachFeature​

forEachFeature(callback)

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

參數​

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

範例​

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

filterFeature​

filterFeature(predicate)

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

參數​

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

回傳​

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

範例​

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

clear​

clear()

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

範例​

map.data.clear();

enableCluster​

enableCluster(enabled, options)

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

參數​

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

範例​

map.data.enableCluster(true);

toggleClusterPoints​

toggleClusterPoints(visible)

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

參數​

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

範例​

// 隱藏叢集點
map.data.toggleClusterPoints(false);

// 顯示叢集點
map.data.toggleClusterPoints(true);

toggleNonClusterPoints​

toggleNonClusterPoints(visible)

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

參數​

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

範例​

// 隱藏非叢集點
map.data.toggleNonClusterPoints(false);

// 顯示非叢集點
map.data.toggleNonClusterPoints(true);

Feature​

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

setProperty​

setProperty(property, value)

設定指定屬性的內容。

參數​

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

範例​

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

getProperty​

getProperty(property)

回傳屬性的值。

參數​

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

範例​

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

removeProperty​

removeProperty(property)

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

參數​

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

範例​

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

setGeometry​

setGeometry(geometry)

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

參數​

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

範例​

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

getGeometry​

getGeometry()

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

回傳​

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

範例​

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

setVisible​

setVisible(visible)

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

參數​

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

範例​

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

getBounds​

getBounds()

回傳地圖項目的邊界點。

回傳​

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

範例​

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

getCenter​

getCenter()

回傳地圖項目的中心點。

回傳​

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

範例​

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

getLeft​

getLeft()

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

回傳​

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

範例​

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

getRight​

getRight()

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

回傳​

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

範例​

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

getTop​

getTop()

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

回傳​

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

範例​

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

getBottom​

getBottom()

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

回傳​

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

範例​

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

forEachProperty​

forEachProperty(callback)

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

參數​

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

範例​

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

displayFeatureText​

displayFeatureText(text)

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

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

參數​

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

範例​

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

const fea = map.data.getFeatureById(0);

// 1. 接收文字的 string 型態
fea.displayFeatureText("板南線");

// 2. 接收要顯示的 property name
fea.displayFeatureText("name");

也可在 setStyle 中搭配使用：

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 方法添加的文字項目。

範例​

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。

範例​

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線條群組
說明
  • 移動時會以整個群組一併搬移，並維持群組內各個 feature 的相對順序。
  • 每次呼叫會相對於相鄰的群組移動「一層」；若已位於最上層或最下層，則維持不變。
  • 多邊形（Polygon）及圓形（Circle）預設位於最下層，不提供移動 API。

Point.moveUp​

Point.moveUp()

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

範例​

map.data.Point.moveUp();

Point.moveDown​

Point.moveDown()

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

範例​

map.data.Point.moveDown();

FlattenPoint.moveUp​

FlattenPoint.moveUp()

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

範例​

map.data.FlattenPoint.moveUp();

FlattenPoint.moveDown​

FlattenPoint.moveDown()

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

範例​

map.data.FlattenPoint.moveDown();

LineString.moveUp​

LineString.moveUp()

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

範例​

map.data.LineString.moveUp();

LineString.moveDown​

LineString.moveDown()

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

範例​

map.data.LineString.moveDown();