Skip to main content

介紹

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

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

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

  • 在地圖中加入 GeoJSON 資料。

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

  • 在地圖上繪製多邊形。

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

  • 使用 mapPlus.Data 即可建立任意資料的模型。

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

  • 選擇資料的呈現方式，隨時都能改變想法。

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

快速開始​

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

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

加入 GeoJSON 資料​

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

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

每張地圖都有 data 物件，用於存放任意地理空間資料 (包括 GeoJSON) 的資料層。如要載入並顯示 GeoJSON 檔案，您可以呼叫 addGeoJson() 方法。以下範例說明如何加入地圖並載入外部 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.addGeoJson(
  "https://kw3dmap.autoking.com.tw/kwmap/assets/demo/geojson/example.geojson"
);

提供 GeoJSON 測試資料​

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

warning

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

{
  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 之間。
warning

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

info

※下列屬性僅可透過 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，筆觸寬度 (以像素為單位)。

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

info

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

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，改為回傳 event
map.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