在 Web SDK 中叢集處理點資料

發行項
08/29/2024

當地圖上有太多資料點時，有些資料點可能會彼此重疊。重疊會導致地圖無法閱讀且難以使用。群集位置點資料的程序會結合彼此接近的位置點資料，並在地圖上以單一群集資料點的方式加以表示。當使用者放大地圖時，群集便會分解成個別的資料點。在處理大量資料點時，請使用叢集程序來改善使用者體驗。

對資料來源啟用叢集

將 cluster 選項設定為 true，以在 DataSource 類別中啟用群集。設定 clusterRadius 以選取附近的點，並將這些點合併成叢集。 clusterRadius 的值是以像素為單位。使用 clusterMaxZoom 指定停用群集邏輯的縮放層級。以下範例示範如何在資料來源中啟用叢集。

//Create a data source and enable clustering.
var datasource = new atlas.source.DataSource(null, {
    //Tell the data source to cluster point data.
    cluster: true,
    
    //The radius in pixels to cluster points together.
    clusterRadius: 45,
    
    //The maximum zoom level in which clustering occurs.
    //If you zoom in more than this, all points are rendered as symbols.
    clusterMaxZoom: 15
});

提示

如果兩個資料點彼此很靠近，不論使用者放大到什麼程度，叢集可能都不會拆分開。若要解決此問題，您可將 clusterMaxZoom 選項設為停用叢集邏輯，只顯示所有項目。

DataSource 類別也提供下列群集相關方法。

方法	傳回類型	描述
getClusterChildren(clusterId: number)	Promise<Array<Feature<Geometry, any> \| Shape>>	擷取給定群集在下一個縮放層級上的子系。這些子系可以是圖形和子群集的組合。子叢集是屬性符合 ClusteredProperties 的功能。
getClusterExpansionZoom(clusterId: number)	Promise<number>	計算叢集要開始擴大或分解的縮放層級。
getClusterLeaves(clusterId: number, limit: number, offset: number)	Promise<Array<Feature<Geometry, any> \| Shape>>	擷取叢集中的點。依預設會傳回前 10 個點。若要逐頁瀏覽點，請使用 `limit` 來指定要傳回的點數，並使用 `offset` 逐步執行點的索引。若要傳回所有點，請將 `limit` 設定為 `Infinity`，並且不要設定 `offset`。

使用泡泡圖層顯示叢集

泡泡圖層是呈現叢集資料點的絕佳方式。使用運算式調整半徑，並根據叢集中的資料點數量變更色彩。如果使用泡泡圖層顯示叢集，則建議使用其他圖層呈現未叢集化的資料點。

若要在泡泡頂端顯示叢集大小，請使用符號圖層搭配文字，且不要使用圖示。

如需如何使用泡泡圖層實作顯示叢集的完整工作範例，請參閱 Azure 地圖服務範例 (英文) 的泡泡圖層中的點叢集 (英文)。如需此範例的原始程式碼，請參閱泡泡圖層中的點叢集原始程式碼 (英文)。

使用符號圖層顯示叢集

視覺化資料點時，符號圖層會自動隱藏彼此重疊的符號，以確保使用者介面更整潔。如果想在地圖上顯示資料點的密度，則可能不需要這種預設行為。但您可變更這些設定。若要顯示所有符號，請將符號圖層 iconOptions 屬性的 [allowOverlap] 選項設為 [true]。

使用叢集顯示資料點密度，同時保持乾淨的使用者介面。以下範例示範如何使用符號圖層來新增自訂符號，以及表示叢集和個別資料點。

如需如何使用符號圖層實作顯示叢集的完整工作範例，請參閱 Azure 地圖服務範例 (英文) 的使用符號塗層顯示叢集 (英文)。如需此範例的原始程式碼，請參閱使用符號圖層顯示叢集原始程式碼 (英文)。

叢集和熱度圖圖層

熱度圖是在地圖上顯示資料密度的絕佳方式。這個視覺效果方法可自行處理大量的資料點。如果資料點已叢集化，且叢集大小作為熱度圖的權數使用，則此熱度圖可處理更多資料。若要完成此選項，請將熱度圖圖層的 [weight] 選項設為 [['get', 'point_count']]。如果叢集半徑很小，則此熱度圖和使用未叢集化資料點的熱度圖看起來幾乎一致，但執行效果更好。不過，叢集半徑愈小，熱度圖的精確度就愈高，但效能優勢也隨之減少。

如需示範如何在資料來源上建立使用叢集的熱度圖的完整工作範例，請參閱 Azure 地圖服務範例 (英文) 中的叢集加權熱度圖 (英文)。如需此範例的原始程式碼，請參閱叢集權重熱度圖原始程式碼 (英文)。

已叢集化資料點的滑鼠事件

當滑鼠事件發生在包含叢集資料點的圖層上時，叢集資料點會以 GeoJSON 點功能物件的形式傳回事件。此點功能具有下列屬性：

屬性名稱	類型	描述
`cluster`	boolean	指出功能是否代表群集。
`cluster_id`	string	群集的唯一識別碼，可與 DataSource 的 `getClusterExpansionZoom`、`getClusterChildren` 和 `getClusterLeaves` 方法搭配使用。
`point_count`	數值	群集包含的位置點數目。
`point_count_abbreviated`	string	會縮寫較長 `point_count` 值的字串。 (例如，4,000 變成 4K)

泡泡圖層中的點叢集 (英文) 範例使用會呈現叢集點並新增 click 事件的泡泡圖層。觸發 click 事件時，程式碼會計算地圖，將其縮放至可拆分叢集的下一個縮放層級。這項功能是使用 DataSource 類別的 getClusterExpansionZoom 方法，並按一下叢集資料點的 cluster_id 屬性來實作。

下列程式碼片段顯示泡泡圖層中的點叢集 (英文) 範例中的程式碼，該範例會將 click 事件功能新增至叢集資料點：

//Add a click event to the layer so we can zoom in when a user clicks a cluster.
map.events.add('click', clusterBubbleLayer, clusterClicked);

//Add mouse events to change the mouse cursor when hovering over a cluster.
map.events.add('mouseenter', clusterBubbleLayer, function () {
    map.getCanvasContainer().style.cursor = 'pointer';
});

map.events.add('mouseleave', clusterBubbleLayer, function () {
    map.getCanvasContainer().style.cursor = 'grab';
});

function clusterClicked(e) {
    if (e && e.shapes && e.shapes.length > 0 && e.shapes[0].properties.cluster) {
        //Get the clustered point from the event.
        var cluster = e.shapes[0];

        //Get the cluster expansion zoom level. This is the zoom level at which the cluster starts to break apart.
        datasource.getClusterExpansionZoom(cluster.properties.cluster_id).then(function (zoom) {

            //Update the map camera to be centered over the cluster. 
            map.setCamera({
                center: cluster.geometry.coordinates,
                zoom: zoom,
                type: 'ease',
                duration: 200
            });
        });
    }
}

顯示叢集區域

叢集代表的點資料會散佈在某個區域。在此範例中，當滑鼠暫留在叢集上時，會發生兩種主要行為。首先，會使用包含在叢集中的個別資料點來計算凸殼。然後，凸殼會顯示在地圖上以顯示某個區域。凸殼是一個多邊形，其類似橡皮筋一樣包裹住一組可用 atlas.math.getConvexHull 方法計算的資料點。您可使用 getClusterLeaves 方法，以從資料來源擷取出所有包含在叢集中的點。

如需示範如何執行此作業的完整工作範例，請參閱 Azure 地圖服務範例 (英文) 中的使用凸殼顯示叢集區域 (英文)。如需此範例的原始程式碼，請參閱使用凸殼顯示叢集區域原始程式碼 (英文)。