示例中心
功能在线体验
控制台

高德 开发 地图 JS API 参考手册 - UI组件库 行政地理 行政区划聚合

更新时间:2018年07月02日

DistrictCluster(行政区划聚合)基于 DistrictExplorer(行政区划浏览) 实现,功能上主要有两个部分:

  1. 区划游历:随着地图的缩放、平移,自动加载最优的区划节点(AreaNode),并支持绘制相关的区划面。
  2. 区划聚合:计算出包含在各区划范围内的点,并支持通过Marker显示相关信息,比如区划名称,点的总数等。如果需要绘制单独的数据点,可以配合使用海量点组件示例

除了数量意义上的"聚合",以区划为维度展示相关信息的场景,也可以使用本组件,比如利用搜索展示各地美食

本组件目前存在一些功能性的缺陷,需开发者予以留意。为便于说明,这里简单先重复一下 DistrictExplorer 中的一些内容:

区划数据是按照父级+子级打包的方式组织,比如全国+各个省份,上海+下辖区县等,每一组成为一个AreaNode(区划节点),以父级区划代指。同样是上海,它既作为子级存在于全国的AreaNode中,也作为父级存在于上海的AreaNode中,区别在于:两者的边界数据不一样(抽稀程度不同),前者较”粗“,后者较”细“,前者”直来直去“,后者”蜿蜒曲折“。这种不一致导致了两个问题:

1. 显示方面,区划的交界处的边界不完全重合,个别位置会显得相对明显。以下图左侧红圈处为例,江苏和上海相邻,共享一段边界。在较小的级别,全国代表的AreaNode中的数据(上海和江苏都是其中的子级)是足够”精细“的,交界处也严丝合缝。但随着地图级别的增大,上海或者江苏的边界会显得越来越粗,到一定程度,DistrictCluster就会自动载入上海或者江苏的AreaNode进行替代,此时共享的边界就不再严丝合缝了。

2. 聚合计算方面,区划交界处会出现悬挂点( hangingDataItems )问题。区划聚合类似于一个多层漏斗过程,比如从全国范围开始,先把点分配到省,每个省再分配到下辖的市,每个市再分配到下辖的区县。以上海市为例,全国分配到上海,是利用全国代表的AreaNode(100000)中的上海边界数据,而上海分配到区县,是利用上海代表的AreaNode(310000)中的边界数据,两份边界数据的抽稀程度不一样,后者更加“精细”,连线更加“曲折”。如果点恰好落在这两份边界数据的空隙内(如上图右侧,红圈中的3个点),就会出现这样一种情况:在全国范围内被分配到上海的点,在上海范围内却找不到对应的下级区县,被“悬挂”在某个层级上无法继续参与下层的聚合,即成为悬挂点。在聚合总数上,比如上图上海有7001个点,但展示到区县一级后,所有区县的聚合总数加总的数字实际上小于7001。


浏览器支持:

现代浏览器和 IE9 及以上 

名词释义

名称

说明

数据源(data) 

一个数组,每个元素即点的相关信息(dateItem)   

数据项(dataItem) 

数据源数组的元素,通常就是点的相关信息。数据项自身的格式没有强制要求,只要能索引或者包含点的信息即可。 

数据项索引(dataIndex) 

数据项在数据源数组中的的索引位置,即 0,1,2.... 

区划特征(Feature)

某个区划的GeoJSON格式的数据信息,包括一些属性(名称,中心),以及边界信息等(详细内容请参见DistrictExplorer),这里也同时代指区划面。

聚合信息标注(ClusterMarker)

展示聚合信息(默认包括区划名称和区划下辖的店的数量)的标注

如何使用

1、引入UI组件库

2、加载DistrictCluster(模块名:ui/geo/DistrictCluster

//加载DistrictCluster,loadUI的路径参数为模块名中 'ui/' 之后的部分 
AMapUI.loadUI(['geo/DistrictCluster'], function(DistrictCluster) {

    //启动页面
    initPage(DistrictCluster);
});

function initPage(DistrictCluster) {

    var distCluster = new DistrictCluster({
        map: map, //所属的地图实例
        //返回数据项中的经纬度位置
        getPosition: function(item) {
            return item.position;
        }
    });

    //随机创建一批点,仅作示意
    var data = createPoints(map.getCenter(), 100000);
    //设置数据
    distCluster.setData(data);
}

//随机生产点
function createPoints(center, num) {
    var data = [];
    for (var i = 0, len = num; i < len; i++) {
        data.push({
            position: [
                center.getLng() + (Math.random() > 0.5 ? 1 : -1) * Math.random() * 30,
                center.getLat() + (Math.random() > 0.5 ? 1 : -1) * Math.random() * 20
            ]
        });
    }
    return data;
}

示例中心

接口文档

构造参数

参数名称

类型

说明

map

AMap.Map

地图对象实例 

zIndex

Number

绘制用图层的叠加顺序值 。如果需要叠加在地图的最上层,可以设置一个较大的值,比如300 

data

Array

数据源数组,每个元素即为点相关的信息 

getPosition

Function

 返回数据项中的经纬度信息

@param  {*} dataItem 数据项

@param  {number} dataIndex 数据项索引 

@return {AMap.LngLat|Array.<number>} 

                返回经纬度实例(AMap.LngLat)或者经纬度数字组成的数组([lng, lat])

比如:

function(dataIte, dataIndex) {
return [dateItem.lng, dataItem.lat];
}

autoSetFitView

Boolean

是否在绘制后自动调整地图视野以适合全部点,默认true

topAdcodes

Array.<number>

顶层区划的adcode列表 (TXTJSON) 。默认为[100000],即全国范围。


假如仅需要展示河北和北京,可以设置为[130000, 110000]示例

excludedAdcodes

Array.<number>

需要排除的区划的adcode列表,示例

boundsQuerySupport

Boolean

是否开启范围查询,默认false。开启后将增加一项辅助性的功能支持,即快速查询某个矩形范围内(比如当前地图窗口)的点。

renderConstructor 

Constructor 

绘制引擎的构造类,目前仅提供一个默认引擎。


如果有特殊需求,也可以参照现有引擎代码自主实现(示例)。

renderOptions 

Object

绘制引擎的构造参数,请参见下方 绘制引擎 部分 

方法

方法名称

返回值

说明

setData(data:Array) 


设定数据源数组,并触发重新绘制。 

renderLater([delay:number]) 


延时设定的毫秒(默认10)后绘制;该时间段内重复调用只会触发一次。该函数适合短时间内多次触发绘制的场景。 

render()


立即重新绘制。因绘制操作较”重“,推荐优先考虑 renderLater 方法。

on(eventName:String, handler:Function) 


监听 eventName 事件,多个事件用空格分隔 

off(eventname:String, handler:Function) 


注销 eventName 事件,多个事件用空格分隔 

show()


显示

hide()


隐藏

isHidden()

Boolean

返回是否处于隐藏状态

getDataItemsInView()

Array.<{

dataIndex:number,

dataItem:*

position:[lng, lat]

}>

返回当前地图窗口范围内的数据点信息(boundsQuerySupport开启后有效)。



getDataItemsByBounds(bounds:AMap.Bounds)

同上

返回指定范围内的数据点信息(boundsQuerySupport开启后有效)

zoomToShowSubFeatures(

  adcode:number,[ center.LngLat ])


缩放地图至某一级别,此时adcode对应的区划刚好展开显示自身的子级;同时移动地图中心到center(默认为区划行政中心)所指位置。


比如adcode传入110000(北京),调用后地图将展示北京下辖的区县。


默认情况下,点击聚合信息标注会执行该操作。

getMinZoomToShowSub(adcode:number) 


返回一个最小的zoom级别,该级别下adcode对应的区划将切换到子级展示 。子级显示的控制可参数见下述 minHeightToShowSubFeatures 部分。

getAreaNodeProps(adcode:number)

{

  name:string,

  adcode:number,

  center:[lng, lat]

}

返回adcode(不支持区县一级)对应的区划节点的属性。

getClusterRecord(adcode:number, 

    callback:function)


异步获取adcode对应的区划节点的聚合结果信息,callback的类型为:


@param {null|*} error 错误信息,正常情况下为null

@param {

    adcode: number 区划编码,

    name: string 区划名称,

    dataItems: Array.<Object> 该区划下辖的数据点的信息

    hangingDataItems: Array.<Object> 

          该区划内的悬挂(没有对应子级)数据点

    children:Array.<{

        adcode, name, dataItem

    }> 子级区划的聚合信息

} record 聚合结果信息


事件

事件监听示例

事件名称

参数

说明

featureClick

event:{type:String, originalEvent:event} 

               originalEvent为原始事件,通常由map触发,手动触发时可能为空

feature:Feature 相关的feature

鼠标点击feature对应的区域时触发

featureMouseover

featureClick 

鼠标移入feature对应的区域触发 

featureMouseout

featureClick  

鼠标移出 feature对应的区域触发  

featureMousemove

featureClick  

鼠标在feature对应的区域上移动时触发 

outsideClick

featureClick,但feature为空

鼠标点击了无法识别的区域时触发

clusterMarkerClick

event:{type:String, originalEvent:event} 

              originalEvent为原始事件,通常由map触发,手动触发时可能为空

record: {

    adcode:number 关联的adcode

    feature:Feature 关联的feature

    dataItems:Array  关联的点的信息

}

鼠标点击聚合标注时触发

clusterMarkerAdd

event:{type:String, originalEvent:event} 

             originalEvent为原始事件,通常由map触发,手动触发时可能为空

marker:AMap.Marker 关联的Marker对象

record:Object 见上方 clusterMarkerClick 

聚合信息标注添加到地图上时触发

clusterMarkerRemove

event:{type:String, originalEvent:event} 

            originalEvent为原始事件,通常由map触发,手动触发时可能为空

marker:AMap.Marker 关联的Marker对象

record:Object 见上方 clusterMarkerClick 

聚合信息标注从到地图上删除时触发 

绘制引擎 

DistrictCluster.Render.DefaultRender(默认)

构造参数

参数名称

类型

说明

animEnable

Boolean

是否启用动画,默认true

目前的动画包括聚合标注相对父级区划的移入/移出,区划面的边界过渡效果等。

animDuration

Number

动画持续时长,单位毫秒,默认300

areaNodeCacheLimit

Number

AreaNode缓存的数量,默认-1,即不限制。

极端场景下,假设用户拖动地图一个不漏的查看了全国所有的区县,加载的AreaNode的数量会非常大(360个左右),从而占用较大的内存。如果您的应用对内存方面较为敏感,可以适当设置一个有限的数值,比如100

clusterMarkerEventSupport

Booean

聚合标注是否开启事件支持,默认true

clusterMarkerEventNames

Array.<string>

聚合标注上需要监听的事件类型列表,默认['click']


对应的事件监听方式为:


distCluster(DistrictCluster实例)

       .on('clusterMarker'+事件类型首字母大写, handler:function)


如果配置为['click', 'mouseover', 'mouseout'],则可相应监听:

clusterMarkerClickclusterMarkerMouseoverclusterMarkerMouseout


事件监听示例

clusterMarkerClickToShowSub

Boolean

点击聚合标注是否触发展示子级区划(即调用 zoomToShowSubFeatures 方法),默认true

getClusterMarkerPosition

Function

返回聚合信息标注的位置。

 

@param  Object feature 区划的Feature信息

@param  {Array} dataItems 区划内的点的信息 

@return {AMap.LngLat|Array.<number>} 

            返回经纬度实例(AMap.LngLat)或者经纬度数字组成的数组([lng, lat])


比如:

function(feature, dataItems) {
        return feature.properties.center;  //返回行政中心
}


DistrictCluster内部提供了几类实现,以便快捷赋值,包括:


1.DistrictCluster.ClusterMarkerPositionStrategy.CENTER(默认)

返回行政中心


2.DistrictCluster.ClusterMarkerPositionStrategy.CENTROID

返回区划面的质心(区划面为凹多边形时返回行政中心,比如甘肃)


3.DistrictCluster.ClusterMarkerPositionStrategy.AVERAGE_POINTS_POSITION

返回该区划面下辖的数据点的平均位置(各个点的经纬度加总平均)


getClusterMarker

Function

返回聚合信息标注。


@param  Object feature 区划的Feature信息

@param  {Array} dataItems 区划内的点的信息 

@param  {AMap.Marker} recycledMarker 前期创建的、被回收的Marker  

@return {AMap.Marker} 返回一个Marker实例


关于recycledMarker

随着地图的缩放、平移,有些标注会移出视野范围,或者不再显示(比如切换到下级区划),这类Marker就会被”回收“(清除事件绑定以及map关联)。

如果接收到了不为空的recycledMarker,推荐的做法是,直接更新该Marker的内容并返回,这样可以避免新建大量的Marker,从而降低了内存损耗。


普通Marker示例


默认实现的代码 (clusterMarkerStrategy.DEFAULT)

clusterMarkerKeepConsistent 

Booean 

聚合信息标注在参数不变时( getClusterMarker 中的featuredataItems)是否保持一致。默认true

如果maker的内容与其他可变信息相关,比如地图中心位置等,可以设置为false,这样每次render都会调用getClusterMarker方法。

clusterMarkerRecycleLimit

Number

保留在回收站中的聚合信息标注的最大数量,默认30

featureEventSupport

Boolean

区划面是否开启事件支持,默认true

featureClickToShowSub

Boolean

点击区划面是否触发进入子级区划,默认false

minHeightToShowSubFeatures


minSiblingAvgHeightToShowSubFeatures


minSubAvgHeightToShowSubFeatures  

Number

这3个参数用于控制某个区划(父级)在何种级别会切换到子级显示,比如上海切换到下辖的各个区县,上海就是父级,下辖区县就是子级。


minHeightToShowSubFeatures : 父级区划的最小显示高度,默认630


minSiblingAvgHeightToShowSubFeatures:父级区划的同级兄弟区划的最小平均显示高度,默认600


minSubAvgHeightToShowSubFeatures :子级区划的最小平均显示高度,默认300


当3个条件同时满足时,切换到子级显示。

featureStyle

Object

区划面的基本样式。该参数优先级最低。


{

   fillStyle: {string} 填充色,比如 red, rgb(255,0,0), rgba(0,0,0,1)等

   lineWidth:  {number}   描边宽度

   strokeStyle: {string}  描边颜色

   hoverOptions:{

          fillStyle:string, 

          lineWidth:number, 

          strokeStyle:string

   } 鼠标Hover时的样式, 可以为null

}

featureStyleByLevel 

Object

按区划级别(如下4类)定义的区划面样式,优先级高于 featureStyle 


{

    country:{同featureStyle} 全国,

    province:{同featureStyle} 省级,

    city:{同featureStyle} 市级, 属性

    district:{同featureStyle} 区县级 

}


默认的配置是:


{

country: {

fillStyle: 'rgba(49, 163, 84, 0.8)'

},

province: {

fillStyle: 'rgba(116, 196, 118, 0.7)'

},

city: {

fillStyle: 'rgba(161, 217, 155, 0.6)'

},

district: {

fillStyle: 'rgba(199, 233, 192, 0.5)'

}

}

getFeatureStyle 

Function

直接指定某个区划的样式,优先级最高


@param  Object feature 区划的Feature信息

@param  {Array} dataItems 区划内的点的信息 

@return {Object,见featureStyle} 

            返回该区划的样式


示例

移动端
示例中心
功能
在线体验
常见问题