高德地图SDK Android版开发 6 显示覆盖物

前言

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

地图类中覆盖物的接口

• AMap类中添加Overlay的接口：

类型	方法	说明
Marker	addMarker(MarkerOptions options)	在地图上添一个图片标记（marker）对象。
ArrayList< Marker >	addMarkers(ArrayList< MarkerOptions > options, boolean moveToCenter)	在地图上添一组图片标记（marker）对象，并设置是否改变地图状态以至于所有的marker对象都在当前地图可视区域范围内显示。
Polyline	addPolyline(PolylineOptions options)	在地图上添加一个折线对象（polyline）对象。
Polygon	addPolygon(PolygonOptions options)	在地图上添加一个多边形（polygon）对象。
Arc	addArc(ArcOptions options)	在地图上添加一个圆弧（arc）对象。
Circle	addCircle(CircleOptions options)	在地图上添加一个圆（circle）对象。
Text	addText(TextOptions options)	在地图上添一个文字标记（text）对象。

• AMap类中删除Overlay的接口：

类型	方法	说明
void	clear()	从地图上删除所有的overlay（marker，circle，polyline 等对象）。
void	clear(boolean isKeepMyLocationOverlay)	从地图上删除所有的覆盖物（marker，circle，polyline 等对象）， 但myLocationOverlay（内置定位覆盖物）除外。

覆盖物类

类型	说明	覆盖物类	选项
点	定义地图 Marker 覆盖物。 Marker 是在地图上的一个点绘制图标。 这个图标和屏幕朝向一致，和地图朝向无关，也不会受地图的旋转、倾斜、缩放影响。	Marker	MarkerOptions
折线	定义地图线段覆盖物。一个线段是多个连贯点的集合线段。	Polyline	PolylineOptions
多边形	定义在地图上绘制多边形覆盖物。一个多边形可以凸面体，也可是凹面体。	Polygon	PolygonOptions
弧线	定义了在地图上绘制弧形的类。	Arc	ArcOptions
圆	定义了在地图上绘制圆的类。	Circle	CircleOptions
文本	定义在地图中绘制的文字覆盖物。	Text	TextOptions

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()
        .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()
        .strokeColor(Color.RED)
        .strokeWidth(10)
        .point(p1, p2, p3);

// 在地图上显示弧线
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，circle，polyline 等对象），
// 但myLocationOverlay（内置定位覆盖物）除外。
boolean isKeepMyLocationOverlay = true;
map.clear(isKeepMyLocationOverlay);

效果图

Marker的更多属性

Marker有如下属性：

• 锚点：图标摆放在地图上的基准点。默认情况下，锚点是从图片下沿的中间处。
• 位置：Marker是通过经纬度的值来标注在地图上的。
• 标题：当点击Marker显示在信息窗口的文字，随时可以更改。
• 片段：除了标题外其他的文字，随时可以更改。
• 图标：Marker显示的图标。如果未设置图标，API 将使用默认的图标，高德为默认图标提供了10 种颜色备选。默认情况下，Marker 是可见的。可随时更改Marker 的可见性。

常用属性

类型	方法	说明
MarkerOptions	icon(BitmapDescriptor icon)	设置Marker覆盖物的图标。
MarkerOptions	position(LatLng position)	设置Marker覆盖物的位置坐标。
MarkerOptions	alpha(float alpha)	设置Marker覆盖物的透明度
MarkerOptions	perspective(boolean perspective)	已过时。
MarkerOptions	draggable(boolean enable)	设置Marker覆盖物是否可拖拽。
MarkerOptions	setFlat(boolean flat)	设置Marker覆盖物是否平贴地图。
MarkerOptions	anchor(float u, float v)	设置Marker覆盖物的锚点比例。
MarkerOptions	rotateAngle(float rotate)	设置Marker覆盖物的图片旋转角度，从正北开始，逆时针计算。
MarkerOptions	visible(boolean visible)	设置Marker覆盖物是否可见。

交互

启用允许拖拽时，在拖拽Marker时，会回调AMap.OnMarkerDragListener。

类型	方法	说明
MarkerOptions	draggable(boolean enable)	设置Marker覆盖物是否可拖拽。

动画

• SDK提供了给Marker增加帧动画的功能，通过MarkerOptions类来设置，一次传入一个Icon列表，通过period设定刷新的帧间隔。
• 自地图 SDK V4.0.0 版本起，SDK 提供了给 Marker 设置动画的方法。通过Marker类setAnimation方法设置。

类型	方法	说明
MarkerOptions	icons(ArrayList< BitmapDescriptor > icons)	设置Marker覆盖物的动画帧图标列表，多张图片模拟gif的效果。
MarkerOptions	period(int period)	设置多少帧刷新一次图片资源，Marker动画的间隔时间，值越小动画越快。

其它属性

类型	方法	说明
MarkerOptions	title(String title)	设置 Marker覆盖物 的标题
MarkerOptions	snippet(String snippet)	设置 Marker覆盖物的 文字描述
MarkerOptions	infoWindowEnable(boolean enabled)	设置Marker覆盖物的InfoWindow是否允许显示,默认为true
MarkerOptions	setInfoWindowOffset(int offsetX, int offsetY)	设置Marker覆盖物的InfoWindow相对Marker的偏移。
MarkerOptions	altitude(float altitude)	marker的海拔
MarkerOptions	zIndex(float zIndex)	设置Marker覆盖物 zIndex。
MarkerOptions	setGps(boolean isGps)	设置Marker覆盖物的坐标是否是Gps，默认为false。

折线的更多属性

地图线段覆盖物。一个线段是多个连贯点的集合线段。它拥有以下属性：

• 顶点：线段是由两个顶点之间连贯的点构成的。如果两个顶点相同，则一个线段将闭合。
• 宽度：宽度是单位是像素。宽度是可视区域的缩放级别无关。默认为10。
• 颜色：线段的颜色是ARGB格式，颜色格式可以参考 Color。默认是黑色(0xff000000)。
• Z轴：Z轴是控制地图覆盖物之间的绘制层次的参数。这个参数能够控制Circles、Polygons、Polyline的绘制层次，但不会影响Marker。 Z轴数值越大的覆盖物将会绘制在更上层。如果两个及两个以上覆盖物的Z轴数值相同，则最后的绘制结果是随机的。 覆盖物的Z轴默认为0。
• 可见：这个属性表示了线段是否可以显示在地图上。如果设置为不可见，则绘制地图时不会绘制此线段，但其他属性不受影响。默认为可见。

常用属性

类型	方法	说明
PolylineOptions	width(float width)	设置线段的宽度，默认为10。
PolylineOptions	color(int color)	设置线段的颜色，需要传入32位的ARGB格式。
PolylineOptions	transparency(float transparency)	设置线段的透明度0~1，默认是1,1表示不透明
PolylineOptions	add(LatLng… points)	追加一批顶点到线段的坐标集合。
PolylineOptions	add(LatLng point)	追加一个顶点到线段的坐标集合。
PolylineOptions	addAll(Iterable< LatLng > points)	追加一批顶点到线段的坐标集合。
PolylineOptions	colorValues(List< Integer > colors)	设置线段的颜色
PolylineOptions	setCustomTexture(BitmapDescriptor customTexture)	设置线段的纹理图，图片为2的n次方。
PolylineOptions	setCustomTextureList(List< BitmapDescriptor > customTextureList)	设置线段纹理list
PolylineOptions	setCustomTextureIndex(List< Integer > custemTextureIndexs)	设置线段纹理index数组
PolylineOptions	setUseTexture(boolean useTexture)	设置是否使用纹理贴图画线。
PolylineOptions	visible(boolean isVisible)	设置线段的可见性。
PolylineOptions	setDottedLine(boolean isDottedLine)	设置是否画虚线，默认为false，画实线。
PolylineOptions	setDottedLineType(int type)	设置虚线形状。

其它属性

类型	方法	说明
PolylineOptions	geodesic(boolean isGeodesic)	设置线段是否为大地曲线，默认false，不画大地曲线。
PolylineOptions	useGradient(boolean useGradient)	设置线段是否使用渐变色
PolylineOptions	setEraseColor(boolean eraseVisible, int eraseColor)	设置线段擦除（显示范围外）颜色，需要传入32位的ARGB格式，针对颜色线段生效。
PolylineOptions	lineCapType(PolylineOptions.LineCapType lineCapType)	设置Polyline尾部形状
PolylineOptions	lineJoinType(PolylineOptions.LineJoinType lineJoinType)	设置Polyline连接处形状
PolylineOptions	zIndex(float zIndex)	设置线段Z轴的值。

多边形的更多属性

多边形覆盖物。一个多边形可以凸面体，也可是凹面体。它有以下属性:

• 边框：一个多边开的边框由一系列的顺时针或逆时针顶点组成。边框不需要声明起点和终点一致。如果边框的起点与终点不一致，API会自动将它封闭。
• 边框宽度：边框的宽度以像素为单位，不会受可视区域缩放级别的影响。默认为10。
• 边框颜色：边框颜色是一个ARGB格式，ARGB请参考android.graphics.Color。默认为黑色。
• 填充颜色：填充颜色是一个ARGB格式，ARGB格式可参考android.graphics.Color。默认是透明的。如果多边形的几何图形不正确，则填充颜色不会被绘制。
• Z轴：Z轴是控制覆盖物重复区域的绘制顺序的值。Z轴较大的覆盖物会在绘制在Z轴较小的覆盖物上面。如果两个覆盖物的Z轴数值相同，则覆盖情况将随机。默认为0。
• 可见性：标示多边形是否可见。如果可见性为否，则不会被绘制。

多边形方法必须在主线程中调用，否则会抛出IllegalStateException。

常用属性

类型	方法	说明
PolygonOptions	strokeColor(int paramInt)	设置多边形的边框颜色，32位 ARGB格式，默认为黑色。
PolygonOptions	strokeWidth(float paramFloat)	设置多边形的边框宽度，单位：像素。
PolygonOptions	fillColor(int paramInt)	设置多边形的填充颜色，32位ARGB格式。
PolygonOptions	add(LatLng… paramArrayOfLatLng)	添加多个多边形边框的顶点
PolygonOptions	add(LatLng paramLatLng)	添加一个多边形边框的顶点
PolygonOptions	addAll(Iterable< LatLng > paramIterable)	添加多个多边形边框的顶点

其它属性

类型	方法	说明
PolygonOptions	addHoles(BaseHoleOptions… paramArrayOfOptions)	设置空心洞的配置项
PolygonOptions	addHoles(Iterable paramIterable)	添加空心洞的配置项
PolygonOptions	visible(boolean paramBoolean)	设置多边形是否可见。
PolygonOptions	zIndex(float paramFloat)	设置多边形的Z轴数值
PolygonOptions	lineJoinType(AMapPara.LineJoinType lineJoinType)	设置边框连接处形状

Arc的更多属性

弧形的类。它有以下属性:

• 边框宽度：弧形边框的宽度。这个值设置后不会受到可视区域缩放级别的影响。默认为10。
• 边框颜色：边框颜色是一个ARGB格式，ARGB请参考android.graphics.Color。默认为黑色。
• Z轴：Z轴是控制覆盖物重复区域的绘制顺序的值。Z轴较大的覆盖物会绘制在Z轴较小的覆盖物上面。如果两个覆盖物的Z轴数值相同，则覆盖情况将随机。默认值为0。
• 可见性：标示弧形是否可见。如果可见性为否，则不会被绘制。

弧形方法必须在主线程中调用，否则会抛出IllegalStateException。

类型	方法	说明
ArcOptions	strokeColor(int color)	设置弧形边框颜色参数，ARGB格式。
ArcOptions	strokeWidth(float width)	设置弧形边框宽度参数，单位：像素。
ArcOptions	point(LatLng startpoint, LatLng passedpoint, LatLng endpoint)	设置弧线的起终点和途径点。
ArcOptions	visible(boolean visible)	设置弧形是否可见参数。
ArcOptions	zIndex(float zIndex)	设置弧形Z轴数值参数，默认为0。

Circle的更多属性

圆对象有以下属性：

• 圆心 ：圆心的经纬度。
• 半径： 圆的半径，单位：米。这个值应该大于等于0。
• 边框宽度： 圆的边框宽度。这个值设置后不会受到可视区域缩放级别的影响。默认为10。
• 边框颜色：圆的边框颜色，ARGB格式。默认为黑色。
• 填充颜色：圆的填充颜色，ARGB格式。默认为透明。
• Z轴：Z轴是控制覆盖物重复区域的绘制顺序的值。Z轴较大的覆盖物会绘制在Z轴较小的覆盖物上面。如果两个覆盖物的Z轴数值相同，则覆盖情况将随机。默认值为0。
• 可见属性：标识多边形是否可见。如果可见性为否，则不会被绘制。

圆形方法必须在主线程中调用，否则会抛出IllegalStateException。

类型	方法	说明
CircleOptions	radius(double radius)	设置圆的半径，单位米。
CircleOptions	fillColor(int color)	设置圆的填充颜色。
CircleOptions	strokeColor(int color)	设置圆的边框颜色，ARGB格式。
CircleOptions	strokeWidth(float width)	设置圆的边框宽度，单位像素。
CircleOptions	setStrokeDottedLineType(int type)	设置圆的边框虚线形状。
CircleOptions	center(LatLng point)	设置圆心经纬度坐标。
CircleOptions	addHoles(BaseHoleOptions… paramArrayOfOptions)	添加空心洞的配置项
CircleOptions	addHoles(Iterable paramIterable)	添加空心洞的配置项
CircleOptions	visible(boolean visible)	设置圆的可见属性
CircleOptions	zIndex(float zIndex)	设置圆的Z轴数值，默认为0。

Text的更多属性

类型	方法	说明
TextOptions	text(String text)	设置文字覆盖物的文字内容。
TextOptions	backgroundColor(int backgroundColor)	设置文字覆盖物的背景颜色
TextOptions	fontSize(int fontSize)	设置文字覆盖物字体大小
TextOptions	fontColor(int fontColor)	设置文字覆盖物的字体颜色,默认黑色。
TextOptions	rotate(float rotate)	设置文字覆盖物的旋转角度,逆时针。
TextOptions	position(LatLng position)	设置文字覆盖物的地理坐标。
TextOptions	align(int alignX, int alignY)	设置文字覆盖物的对齐方式,默认居中对齐。
TextOptions	typeface(Typeface typeface)	设置文字覆盖物的字体。
TextOptions	setObject(Object object)	设置文字覆盖物的额外信息
TextOptions	visible(boolean visible)	设置文字覆盖物的可见性。
TextOptions	zIndex(float zIndex)	设置文字覆盖物 zIndex。