腾讯地图SDK Android版开发 6 显示覆盖物

前言

在地图应用中，Overlay（覆盖层）是指在地图图层之上叠加显示的额外信息层。这些覆盖层可以用来展示各种数据，如交通状况、用户位置、兴趣点（POI）等。在腾讯地图SDK中，可以使用多种类型的覆盖层来增强地图的功能和视觉效果。文本介绍简单的点线面覆盖物使用方法和属性。

地图类中覆盖物的接口

• TencentMap类中添加Overlay的接口：

类型	方法	说明
Marker	addMarker(MarkerOptions options)	添加标注(Marker)
Polyline	addPolyline(PolylineOptions options)	添加线
Polygon	addPolygon(PolygonOptions options)	添加多边形
Arc	addArc(ArcOptions options)	添加弧线
Circle	addCircle(CircleOptions options)	添加圆

• TencentMap类中删除Overlay的接口：

类型	方法	说明
void	clearAllOverlays()	清除地图上所有的标注类（Marker、Polyline、Polygon，TileOverlay除外）

• 覆盖物类移除接口Removable：

类型	方法	说明
void	remove();	从地图移除覆盖物
boolean	isRemoved();
void	releaseData();

覆盖物类

类型	覆盖物类	选项
点	Marker	MarkerOptions
折线	Polyline	PolylineOptions
多边形	Polygon	PolygonOptions
弧线	Arc	ArcOptions
圆	Circle	CircleOptions

Marker示例

// 定义Maker坐标点
LatLng point = new LatLng(39.963175, 116.400244);
// 构建Marker图标
BitmapDescriptor bitmap = BitmapDescriptorFactory
        .fromResource(R.drawable.icon_mark_a);
// 构建MarkerOption，用于在地图上添加Marker
MarkerOptions option = new MarkerOptions(point)
        .position(point)
        .icon(bitmap);
// 在地图上添加Marker，并显示
Marker marker = map.addMarker(option);

Polyline示例

// 构建折线点坐标
LatLng p1 = new LatLng(39.97923, 116.357428);
LatLng p2 = new LatLng(39.94923, 116.397428);
LatLng p3 = new LatLng(39.97923, 116.437428);
List<LatLng> points = new ArrayList<>();
points.add(p1);
points.add(p2);
points.add(p3);

// 设置折线的属性
PolylineOptions polylineOptions = new PolylineOptions()
        .width(10)
        .color(0xAA00FF00)
        .addAll(points);
// 在地图上绘制折线
Polyline polyline = map.addPolyline(polylineOptions);

Polygon示例

// 多边形顶点位置
List<LatLng> points = new ArrayList<>();
points.add(new LatLng(39.93923, 116.357428));
points.add(new LatLng(39.91923, 116.327428));
points.add(new LatLng(39.89923, 116.347428));
points.add(new LatLng(39.89923, 116.367428));
points.add(new LatLng(39.91923, 116.387428));

// 构造PolygonOptions
PolygonOptions polygonOptions = new PolygonOptions()
        .addAll(points)
        .fillColor(0xAAFFFF00) // 填充颜色
        .strokeColor(0xAA00FF00) // 边框颜色
        .strokeWidth(5); // 边框宽度

// 在地图上显示多边形
Polygon polygon = map.addPolygon(polygonOptions);

Arc示例

// 添加弧线坐标数据
LatLng p1 = new LatLng(39.97923, 116.357428); // 起点
LatLng p2 = new LatLng(40.00923, 116.397428); // 中间点
LatLng p3 = new LatLng(39.97923, 116.437428); // 终点

// 构造ArcOptions对象
ArcOptions arcOptions = new ArcOptions()
        .color(Color.RED)
        .width(10)
        .points(p1, p3)
        .pass(p2);

// 在地图上显示弧线
Arc arc = map.addArc(arcOptions);

Circle示例

// 圆心位置
LatLng center = new LatLng(39.90923, 116.447428);

// 构造CircleOptions对象
CircleOptions circleOptions = new CircleOptions()
        .center(center)
        .radius(1400)
        .fillColor(0xAAFFFF00) // 填充颜色
        .strokeColor(0xAA00ff00) // 边框颜色
        .strokeWidth(5); // 边框宽度

// 在地图上显示圆
Circle circle = map.addCircle(circleOptions);

移除示例

// 清除地图上所有的标注类（Marker、Polyline、Polygon，TileOverlay除外）
map.clearAllOverlays();

marker.remove();
polyline.remove();
polygon.remove();
arc.remove();
circle.remove();

效果图

Marker的更多属性

点标记，是在地图上用来标记一个经纬度坐标的覆盖物，包括点图标和浮在点之上的信息窗（常称之为InfoWindow）。腾讯地图SDK为点标记提供了丰富的样式和场景使用。

腾讯地图SDK提供很多默认的Marker样式，通过TencentMap添加Marker接口，即可添一个默认样式的Marker。

Marker marker = mTencentMap.addMarker(new MarkerOptions(position));

开发者如果想自定义Marker的样式属性，可以通过两个阶段进行修改：

1. 创建Marker对象之前，可以通过修改MarkerOptions选项来初始化Marker
2. 创建Marker对象之后，可以通过Marker对象，来修改属性

常用属性

类型	方法	说明
MarkerOptions	icon(BitmapDescriptor icon)	设置标注的样式
MarkerOptions	position(LatLng latlng)	设置标注的位置
MarkerOptions	alpha(float alpha)	设置标注的透明度
MarkerOptions	flat(boolean flat)	设置是不是3D标注，3D标注会随着地图倾斜面倾斜
MarkerOptions	anchor(float anchorU, float anchorV)	设置标注的锚点
MarkerOptions	clockwise(boolean clockwise)	旋转角度是否沿顺时针方向
MarkerOptions	rotation(float rotation)	设置标注的旋转角度
MarkerOptions	visible(boolean flag)	设置标注是否可见

交互

• 启用可点击时，在点击Marker时，会回调TencentMap.OnMarkerClickListener。
• 启用允许拖拽时，在拖拽Marker时，会回调TencentMap.OnMarkerDragListener。

类型	方法	说明
MarkerOptions	draggable(boolean flag)	设置标注是否可以被拖动

碰撞

腾讯地图SDK4.4.1版本起，支持点标记与地图POI元素的碰撞功能，当开启碰撞功能时，与点标记重合的POI元素将会被隐藏。

类型	方法	说明
MarkerOptions	collisionBy(MarkerCollisionItem… item)	设置可被碰撞的类型，默认无碰撞关系 构造子MarkerMarkerCollisionRelationUnit时，如果主Marker的getCollisionRelation() == MarkerCollisionRelation.TOGETHER,碰撞类型不支持配置，默认使用主Marker的碰撞类型
MarkerOptions	setCollisionRelation(MarkerCollisionRelation collisionRelation)	设置碰撞关联类型

动画

• Marke支持轮播的功能，通过Marker类setIconLooper方法来传入轮播图数组，并通过MarkerOptions类iconLooper设定轮播模式。
• Marker还支持Animation动画，目前支持平移、缩放、旋转、渐变四种。通过Marker类setAnimation方法设置。

类型	方法	说明
MarkerOptions	iconLooper(boolean enable)	设置图标轮播模式, 默认周期时长为300ms
MarkerOptions	iconLooper(boolean enable, int duration)	设置图标轮播模式

其它属性

类型	方法	说明
MarkerOptions	title(String s)	设置标注的InfoWindow(气泡)的标题，如果设置了 TencentMap.setInfoWindowAdapter(TencentMap.InfoWindowAdapter) 则失效
MarkerOptions	snippet(String snippet)	设置标注的InfoWindow(气泡)的内容，如果设置了 TencentMap.setInfoWindowAdapter(TencentMap.InfoWindowAdapter) 则失效
MarkerOptions	infoWindowEnable(boolean enabled)	设置标注是否可以弹出InfoWindow(气泡)
MarkerOptions	viewInfoWindow(boolean enabled)	设置此 marker 的 infowindow 是否用 view 实现 infowindow
MarkerOptions	infoWindowAnchor(float u, float v)	设置infowindow anchor point
MarkerOptions	infoWindowOffset(int offsetX, int offsetY)	设置InfoWindow的偏移，在基准（InfoWindow在Marker正上方中间处显示 —— 默认位置）上偏移 方向：向右，向下为正方向，向左,向上为负方向
MarkerOptions	infoWindowCollisionBy(MarkerCollisionItem… infoWindowCollisions)	设置InfoWindow 可被碰撞的类型，默认无碰撞关系
MarkerOptions	zIndex(float zIndex)	设置相同显示Level level(int) 的Marker的堆叠顺序，相同显示level，zIndex越大越靠上显示 level优先级大于zIndex
MarkerOptions	level(int level)	设置Marker的显示Level，level用于控制Marker与楼块，道路，POI的显示层级关系。
MarkerOptions	tag(Object tag)	设置标签对象
MarkerOptions	indoorInfo(IndoorInfo indoorInfo)	为Marker添加室内图信息（buildingId，floorName） 当添加室内图信息后，Marker将会随着绑定的室内图状态改变而展示和隐藏
MarkerOptions	fastLoad(boolean fastLoad)	设置是否允许 marker 快速加载，默认此选项为 true 如果当前屏幕内有大量 marker 动态变化其 icon 可能会有性能问题 可以尝试关闭不需要此功能的 marker，关闭此功能后可能导致切换 icon 时闪烁
MarkerOptions	contentDescription(String contentDescription)	设置无障碍相关描述信息

折线的更多属性

线是由一组经纬度点按照一定的顺序连接而成，在地图上绘制线由 Polyline 类定义实现。通常用来表示一段路、轨迹等线型场景。

常用属性

类型	方法	说明
PolylineOptions	width(float width)	设置线宽度
PolylineOptions	color(int i)	设置线的颜色
PolylineOptions	alpha(float a)	设置透明度
PolylineOptions	add(LatLng[] latLngs)	添加顶点
PolylineOptions	add(LatLng latlng, LatLng… args)	添加顶点
PolylineOptions	addAll(Iterable< LatLng > latLngs)	添加顶点
PolylineOptions	latLngs(List< LatLng > listLatlngs)	设置折线坐标
PolylineOptions	updatePoints(Iterable< LatLng > latLngs)	添加顶点,该方法会清空原来顶点集合
PolylineOptions	colors(int[] colors, int[] indexes)	设置线的分段颜色
PolylineOptions	colorTexture(BitmapDescriptor bitmapDescriptor)	注意：1、当调用此接口，且LineType不为LINE_TYPE_DOTTEDLINE时，color和colors接口指定的值代表用此接口设置纹理的第几像素行，以绘制纹理线。2、当调用此接口，且LineType设置为LINE_TYPE_DOTTEDLINE时，绘制线时会连续绘制此接口设置的纹理。
PolylineOptions	colorType(PolylineOptions.ColorType type)	设置颜色类型
PolylineOptions	visible(boolean visible)	设置折线可见性
PolylineOptions	lineType(int lineType)	设置线的类型，必须LineType里面的一种
PolylineOptions	pattern(List< Integer > pattern)	设置ARGB虚线的样式

交互

类型	方法	说明
PolylineOptions	clickable(boolean clickable)	是否可以点击

其它属性

类型	方法	说明
PolylineOptions	gradient(boolean enable)	渐变色开关 只有 getLineType() == PolylineOptions.LineType.LINE_TYPE_MULTICOLORLINE 且 isRoad() == true 才生效
PolylineOptions	borderColor(int borderColor)	设置线ARGB的描边颜色：当线是纯色线的时候，设置border的颜色可用此接口
PolylineOptions	borderColors(int[] borderColors)	设置ARGB线的描边颜色，borderColors的数量应该与 colors(int[], int[])接口中的colors的长度保持一致。
PolylineOptions	borderWidth(float borderWidth)	设置ARGB线 描边的宽度
PolylineOptions	eraseColor(int eraseColor)	设置ARGB类型线的擦除色，默认为Color.GRAY
PolylineOptions	lineCap(boolean cap)	设置路线是否显示半圆端点
PolylineOptions	zIndex(int zIndex)	设置相同显示Level level(int) 的折线堆叠顺序，相同显示level，zIndex越大越靠上显示 level优先级大于zIndex
PolylineOptions	animation(Animation a)	执行一个动画
PolylineOptions	indoorInfo(IndoorInfo indoorInfo)	为Polyline添加室内图信息（buildingId，floorName） 当添加室内图信息后，Marker将会随着绑定的室内图状态改变而展示和隐藏
PolylineOptions	level(int level)	设置Polyline的显示Level，level用于控制Polyline与楼块，道路，POI的显示层级关系。
PolylineOptions	road(boolean isRoad)	设置线是否为路线
PolylineOptions	text(PolylineOptions.Text text)	设置沿 polyline 展示的文字。只要调用 TencentMap.addPolyline(PolylineOptions) 构造出 PolylineOptions.Text 就不可以再调用 Polyline.setPoints(List) 修改展示的路径，只能创建新的 Polyline

多边形的更多属性

多边形是由 Polygon 类定义的一组在地图上的封闭线段组成的图形，它由一组 LatLng 点按顺序连接而成。可以设置多边形顶点、描边的宽度和颜色、多边形的填充色、层级关系、可见性、可点击性等属性。

常用属性

类型	方法	说明
PolygonOptions	strokeColor(int strokeColor)	设置PolygonOptions描边颜色, 与 texture(BitmapDescriptor) 互斥
PolygonOptions	strokeWidth(float strokeWidth)	设置PolygonOptions描边宽度
PolygonOptions	fillColor(int fillColor)	设置PolygonOptions填充颜色
PolygonOptions	add(LatLng… latLngs)	向PolygonOptions添加顶点
PolygonOptions	add(LatLng latLng)	向PolygonOptions添加顶点
PolygonOptions	add(List< LatLng > points)	添加顶点坐标
PolygonOptions	addAll(Iterable< LatLng > latLngs)	向PolygonOptions添加顶点

交互

类型	方法	说明
PolygonOptions	clickable(boolean clickable)	多边形是否支持点击

其它属性

类型	方法	说明
PolygonOptions	setHolePoints(List< List < LatLng > > holePoints)	设置PolygonOptions 带洞顶点
PolygonOptions	visible(boolean flag)	设置折线可见性
PolygonOptions	zIndex(int zIndex)	设置相同显示Level level(int) 的多边形堆叠顺序，相同显示level，zIndex越大越靠上显示 level优先级大于zIndex
PolygonOptions	level(int level)	设置Polygon的显示Level，level用于控制Polygon与楼块，道路，POI的显示层级关系。
PolygonOptions	pattern(List< Integer > pattern)	设置ARGB虚线的样式，与 texture(BitmapDescriptor) 互斥
PolygonOptions	texture(BitmapDescriptor texture)	设置纹理图片，这个纹理会重复地绘填充到线上，同时用户应配置纹理间隔 textureSpacing(int)， 与 strokeColor(int)、pattern(List)两个配置互斥，这三个接口最后调用的会生效
PolygonOptions	textureSpacing(int textureSpacing)	纹理间隔

Arc的更多属性

弧线是由一组经纬度点和夹角角度绘制而成，在地图上绘制弧线由 Arc类定义实现。

• 基础圆弧途径点必须在起终点有效坐标范围内，否则不能生成正确的弧线，同时设置夹角角度时，以夹角角度为准。
• 如果使用的是起终点绘制弧线，一定要添加夹角角度。

类型	方法	说明
ArcOptions	color(int color)	设置线颜色，默认黑色
ArcOptions	width(float width)	设置线宽，默认5
ArcOptions	strokeColor(int strokeColor)	设置描边颜色，不设置不显示
ArcOptions	strokeWidth(float strokeWidth)	设置描边宽度，默认1
ArcOptions	points(LatLng start, LatLng end)	设置起终点坐标
ArcOptions	angle(float angle)	设置起点到终点，与起点外切线逆时针旋转的夹角角度 通过设置起终点+夹角角度，即可确定一个圆弧线，如果同时设置途经点和夹角时，优先以夹角角度为准
ArcOptions	pass(LatLng pass)	设置途经点 通过设置起终点+途经点，即可确定一个圆弧线，途经点必须在起终点有效坐标范围内，否则不能生成正确的弧线，同时设置夹角角度时，以夹角角度为准
ArcOptions	showArrow(boolean showArrow)	设置箭头显示状态，默认为false，不显示

Circle的更多属性

圆形是由 Circle 类定义的封闭曲线，在腾讯地图构造一个圆形需要确定它的圆心和半径。可以设置圆心坐标、半径、描边的宽度和颜色、圆的填充颜色、层级、可见性、可点击性等属性。

类型	方法	说明
CircleOptions	radius(double radius)	设置圆的半径， 单位为米
CircleOptions	fillColor(int color)	设置圆的填充颜色
CircleOptions	strokeColor(int color)	设置圆的描边颜色
CircleOptions	strokeWidth(float width)	设置圆的描边宽度
CircleOptions	borderType(CircleOptions.CircleBorderType borderType)	设置描边类型
CircleOptions	pattern(List< Integer > pattern)	设置描边虚线的样式
CircleOptions	center(LatLng latlng)	设置圆心坐标
CircleOptions	clickable(boolean clickable)	圆形是否支持点击
CircleOptions	visible(boolean flag)	设置圆的可见性
CircleOptions	zIndex(int zIndex)	设置相同显示Level level(int) 的Circle的堆叠顺序，相同显示level，zIndex越大越靠上显示
CircleOptions	level(int level)	设置Circle的显示Level，level用于控制Circle与楼块，道路，POI的显示层级关系。