高德地图SDK Android版开发 5 地图交互操作

前言

前文介绍了三个主题：创建显示地图；切换地图类型；显示定位。本文重点介绍地图交互操作及相关的类和接口。

• 高德地图支持多种地图交互操作，用户可以通过手势或控件进行地图操作，以实现更好的地图浏览体验。另一方面开发者通过代码实现特定业务场景的地图交互。

• 高德地图通过设定不同的地图状态，来改变地图视野。

• 最后是不属于地图操作的地图事件，但是也很重要。

  • 比如地图加载完成事件，一些特定接口需要在地图加载完成后才能调用（在显示定位和本文均有提及）。

控件

控件介绍

高德地图提供一些基础的地图控件，包括LOGO、指南针、比例尺和缩放按钮和定位按钮。

控件	功能	默认显示	默认位置
LOGO	可设置显示相对位置和边距 （左下角，底部居中，右下角）	显示	左下角
指南针	设置是否显示	不显示	左上角
比例尺	设置是否显示	不显示	左下角
缩放按钮	设置是否显示，可设置显示相对位置 （地图右边居中、地图右下角）	显示	右下角
定位按钮	设置是否显示	不显示	右上角

接口

UiSettings

UiSettings 类用于操控地图控件，以定制自己想要的视图效果。UiSettings类中地图控件的接口：

类型	方法	说明
int	getLogoPosition()	获取“高德地图”Logo的位置。
void	setLogoPosition(int position)	设置“高德地图”Logo的位置。
void	setLogoLeftMargin(int pixels)	设置Logo左边界距离屏幕左侧的边距。
void	setLogoBottomMargin(int pixels)	设置Logo下边界距离屏幕底部的边距。
boolean	isCompassEnabled()	返回指南针控件是否可见。
void	setCompassEnabled(boolean enabled)	设置指南针是否可见。
boolean	isScaleControlsEnabled()	返回比例尺控件是否可见。
void	setScaleControlsEnabled(boolean enabled)	设置比例尺控件是否可见
boolean	isZoomControlsEnabled()	返回缩放按钮是否可见。
void	setZoomControlsEnabled(boolean enabled)	设置缩放按钮是否可见。
int	getZoomPosition()	获取缩放按钮的位置。
void	setZoomPosition(int position)	设置缩放按钮的位置。
boolean	isMyLocationButtonEnabled()	返回定位按钮是否可见。
void	setMyLocationButtonEnabled(boolean enabled)	设置定位按钮是否可见。

AMapOptions

AMapOptions中的控件常量：

常量	说明
LOGO_POSITION_BOTTOM_LEFT	Logo位置（地图左下角）
LOGO_POSITION_BOTTOM_CENTER	Logo位置（地图底部居中）
LOGO_POSITION_BOTTOM_RIGHT	Logo位置（地图右下角）
LOGO_MARGIN_LEFT	LOGO边缘MARGIN（左边）
LOGO_MARGIN_RIGHT	LOGO边缘MARGIN（右边）
LOGO_MARGIN_BOTTOM	LOGO边缘MARGIN（底部）
ZOOM_POSITION_RIGHT_CENTER	缩放按钮位置常量（地图右边居中）
ZOOM_POSITION_RIGHT_BUTTOM	缩放按钮位置常量（地图右下角）

示例代码

通过 AMap 类实现UiSettings 类对象的实例化：

UiSettings uiSettings = map.getUiSettings();

Logo

// 获取Logo位置
int position = uiSettings.getLogoPosition();
// 设置Logo位置
position = AMapOptions.LOGO_POSITION_BOTTOM_RIGHT;
uiSettings.setLogoPosition(position);

uiSettings.setLogoLeftMargin(10);
uiSettings.setLogoBottomMargin(10);

指南针

// 获取是否允许指南针
// boolean enabled = uiSettings.isCompassEnabled();
// 设置是否允许指南针
uiSettings.setCompassEnabled(true);

比例尺

// 获取比例尺控件是否显示
// boolean isShow = uiSettings.isScaleControlsEnabled();
// 设置是否显示比例尺控件
uiSettings.setScaleControlsEnabled(true);

缩放按钮

// boolean isShow = uiSettings.isZoomControlsEnabled();
// 设置缩放按钮是否可见
uiSettings.setZoomControlsEnabled(true);

// int position = uiSettings.getZoomPosition();
int position = AMapOptions.ZOOM_POSITION_RIGHT_CENTER;
uiSettings.setZoomPosition(position);

效果图

地图手势

提供了多种手势供户与地图之间进行交互，如平移、滑动、缩放、旋转、倾斜。

地图手势方法说明

手势	说明	状态开关	默认
滑动手势	1. 可以用手指拖动地图四处滚动（平移） 2. 用手指滑动地图（动画效果）	可禁用或开启	开启
缩放手势	缩放手势可改变地图的缩放级别。 1. 双击地图可以使缩放级别增加1 (放大)； 2. 两个手指捏/拉伸。	可禁用或开启	开启
旋转手势	可以用两个手指在地图上转动，旋转3D矢量地图	可禁用或开启	开启
倾斜手势	可以在地图上放置两个手指，移动它们一起向下或向上，增加或减小倾斜角	可禁用或开启	开启
指定屏幕中心点的手势操作	在对地图进行手势操作（滑动手势除外）时，可以指定屏幕中心点后执行相应手势。	可禁用或开启	禁用

地图手势开关

地图手势可以通过UiSetting类提供的接口来控制禁用或启用。

UiSetting类中获取地图手势是否可用的接口：

类型	方法	说明
boolean	isScrollGesturesEnabled()	返回拖拽手势是否可用。
boolean	isZoomGesturesEnabled()	返回缩放手势是否可用。
boolean	isRotateGesturesEnabled()	返回旋转手势是否可用。
boolean	isTiltGesturesEnabled()	返回倾斜手势是否可用。
boolean	isGestureScaleByMapCenter()	返回是否以地图中心点缩放

UiSetting类中设置地图手势是否可用的接口：

类型	方法	说明
void	setZoomGesturesEnabled(boolean enabled)	设置双指缩放手势是否可用。
void	setScrollGesturesEnabled(boolean enabled)	设置拖拽手势是否可用。
void	setRotateGesturesEnabled(boolean enabled)	设置旋转手势是否可用。
void	setTiltGesturesEnabled(boolean enabled)	设置倾斜手势是否可用。
void	setGestureScaleByMapCenter(boolean isGestureScaleByMapCenter)	设置是否以地图中心点缩放。 注：优先级低于 AMap.setPointToCenter(int x, int y)
void	setAllGesturesEnabled(boolean enabled)	设置所有手势是否可用

指定屏幕中心点的手势操作

在对地图进行手势操作时（滑动手势除外），可以指定屏幕中心点后执行相应手势。

AMap类指定屏幕中心点的方法：

// x、y均为屏幕坐标，屏幕左上角为坐标原点，即(0,0)点。
map.setPointToCenter(x, y);

开启以中心点进行手势操作的方法：

uiSettings.setGestureScaleByMapCenter(true);

地图手势事件

AMap类地图手势事件监听接口：

类型	方法	说明
void	setOnMapClickListener(AMap.OnMapClickListener listener)	设置地图点击事件监听接口。
void	setOnMapLongClickListener(AMap.OnMapLongClickListener listener)	设置地图长按事件监听接口。
void	setOnMapTouchListener(AMap.OnMapTouchListener listener)	设置地图触摸事件监听接口。
void	setAMapGestureListener(AMapGestureListener listener)	设置手势监听接口

地图点击事件监听接口

// 地图点击事件监听接口
public interface OnMapClickListener {
    /**
     * 当用户点击地图时回调此方法，如果点击在某个覆盖物（如marker、polyline）上，且处理了该点击事件，则不会回调此方法。
     * @param point 用户所点击的地理坐标
     */
    void onMapClick(LatLng point);
}

地图长按事件监听接口

// 地图长按事件监听接口
public interface OnMapLongClickListener {
    /**
     * 当用户长按地图时回调此方法，如果长按时触发某一个marker对象的拖动事件，则不会回调此方法。
     * @param point 用户长按的地理坐标
     */
    void onMapLongClick(LatLng point);
}

地图触摸事件监听接口

// 地图触摸事件监听接口
public interface OnMapTouchListener {
    /**
     * 当用户触摸地图时回调此方法
     * @param motionEvent 触摸事件
     */
    void onTouch(MotionEvent motionEvent);
}

地图手势识别的回调

// 地图手势识别的回调，包含单双击、滑动等以及地图操作地图后稳定下来的回调
public interface AMapGestureListener {
    /**
     * 双击
     * @param x 像素 x坐标
     * @param y 像素 y坐标
     */
    void onDoubleTap(float x, float y);

    /**
     * 单击
     * @param x 像素 x坐标
     * @param y 像素 y坐标
     */
    void onSingleTap(float x, float y);

    /**
     * 惯性滑动
     * @param velocityX 惯性滑动的水平速度
     * @param velocityY 惯性滑动的垂直速度
     */
    void onFling(float velocityX, float velocityY);

    /**
     * 滑动
     * @param distanceX 滑动的水平距离
     * @param distanceY 滑动的垂直距离
     */
    void onScroll(float distanceX, float distanceY);

    /**
     * 长按
     * @param x 像素 x坐标
     * @param y 像素 y坐标
     */
    void onLongPress(float x, float y);

    /**
     * 按下
     * @param x 像素 x坐标
     * @param y 像素 y坐标
     */
    void onDown(float x, float y);

    /**
     * 抬起
     * @param x 像素 x坐标
     * @param y 像素 y坐标
     */
    void onUp(float x, float y);

    /**
     * 地图稳定下来会回到此接口
     */
    void onMapStable();
}

地图状态

地图状态类

CameraPosition类定义了地图的状态，如中心点经纬度，缩放级别，旋转角度，俯视角度等。

类型	方法	说明
LatLng	target	目标位置的屏幕中心点经纬度坐标。
float	zoom	目标可视区域的缩放级别。
float	bearing	可视区域指向的方向，以角度为单位，从正北向逆时针方向计算，从0 度到360 度。
float	tilt	目标可视区域的倾斜度，以角度为单位。
boolean	isAbroad	该位置是否在国内（此属性不是精确计算，不能用于边界区域）

CameraPosition类中的方法：

类型	方法	说明
-	CameraPosition(LatLng target, float zoom, float tilt, float bearing)	构造一个CameraPosition 对象。
static CameraPosition.Builder	builder()	创建一个CameraPosition.Builder 对象
static CameraPosition.Builder	builder(CameraPosition camera)	根据传入的CameraPosition 创建一个CameraPosition.Builder 对象。
static CameraPosition	fromLatLngZoom(LatLng target, float zoom)	根据传入的经纬度、缩放级别构造一个CameraPosition 对象。

地图状态构造类

CameraPosition.Builder类创建一个摄像机的位置。

类型	方法	说明
-	Builder()	构造一个新的CameraPosition对象。
-	Builder(CameraPosition previous)	根据给定的参数构造一个CameraPosition的新对象。
CameraPosition.Builder	target(LatLng location)	设置目标位置的地图中心点经纬度坐标。
CameraPosition.Builder	zoom(float zoom)	设置目标可视区域的缩放级别。
CameraPosition.Builder	bearing(float bearing)	设置可视区域的旋转方向，以角度为单位，正北方向到地图方向逆时针旋转的角度，范围从0度到360度
CameraPosition.Builder	tilt(float tilt)	设置目标可视区域的倾斜度
CameraPosition	build()	构造一个CameraPosition 对象。

地图状态更新类

CameraUpdate类描述地图状态将要发生的变化。

通过CameraUpdate类构建地图缩放等级、地图显示范围，改变地图中心点等地图更新实例。

类型	方法	说明
static CameraUpdate	changeBearing(float bearing)	设置地图的旋转角度。
static CameraUpdate	changeLatLng(LatLng latLng)	设置地图的中心点。
static CameraUpdate	changeTilt(float tilt)	设置地图倾斜度。
static CameraUpdate	newCameraPosition(CameraPosition cameraPosition)	给地图设置一个新的状态。
static CameraUpdate	newLatLng(LatLng latLng)	设置地图的中心点。
static CameraUpdate	newLatLngBounds(LatLngBounds bounds, int padding)	设置显示在规定屏幕范围内的地图经纬度范围。
static CameraUpdate	newLatLngBounds(LatLngBounds bounds, int width, int height, int padding)	设置显示在规定宽高中的地图经纬度范围。
static CameraUpdate	newLatLngBoundsRect(LatLngBounds latlngbounds, int paddingLeft, int paddingRight, int paddingTop, int paddingBottom)	设置显示在规定屏幕范围内的地图经纬度范围。
static CameraUpdate	newLatLngZoom(LatLng latLng, float zoom)	设置地图中心点以及缩放级别。
static CameraUpdate	scrollBy(float xPixel, float yPixel)	按像素移动地图中心点
static CameraUpdate	zoomBy(float amount)	根据给定增量缩放地图级别，在当前地图显示的级别基础上加上这个增量。
static CameraUpdate	zoomBy(float amount, android.graphics.Point focus)	根据给定增量并以给定的屏幕像素点为中心点缩放地图级别。
static CameraUpdate	zoomIn()	放大地图缩放级别，在当前地图显示的级别基础上加1。
static CameraUpdate	zoomOut()	缩小地图缩放级别，在当前地图显示的级别基础上减1。
static CameraUpdate	zoomTo(float zoom)	设置地图缩放级别。

改变地图状态接口

AMap类中改变地图状态和设置地图状态监听的接口：

类型	方法	说明
CameraPosition	getCameraPosition()	获取地图的当前状态。
void	moveCamera(CameraUpdate update)	按照传入的CameraUpdate参数改变地图状态。
void	animateCamera(CameraUpdate update)	以动画方式按照传入的CameraUpdate参数更新地图状态， 默认动画耗时250毫秒。
void	animateCamera(CameraUpdate update, AMap.CancelableCallback cancelableCallback)	以动画方式按照传入的CameraUpdate参数更新地图状态， 默认动画耗时250毫秒， 同时设置一个cancelableCallback来监听动画执行的结果。
void	animateCamera(CameraUpdate update, long durationMs, AMap.CancelableCallback cancelableCallback)	按照指定的动画时长及传入的CameraUpdate参数更新地图状态， 同时设置一个cancelableCallback来监听动画执行的结果。
void	setOnCameraChangeListener(AMap.OnCameraChangeListener listener)	设置地图状态的监听接口。

地图状态发生变化的监听接口

// 地图状态发生变化的监听接口
public interface OnCameraChangeListener {
    /**
     * 在地图状态改变过程中回调此方法
     * @param position 一个cameraPosition对象，表示地图的当前状态。
     */
    void onCameraChange(CameraPosition position);

    /**
     * 在地图状态改变完成时回调此方法
     * @param position 一个cameraPosition对象，表示地图的当前状态。
     */
    void onCameraChangeFinish(CameraPosition position);
}

监听改变地图状态是否执行完成或者被中断的接口

// 在AMap.animateCamera(CameraUpdate, CancelableCallback)设置一个CancelableCallback，用来监听该CameraUpdate是否执行完成或者被中断。
public interface CancelableCallback {
    /**
     * 当CameraUpdate任务完成时回调此方法。
     */
    void onFinish();

    /**
     * 当CameraUpdate任务被中断时回调此方法。
     */
    void onCancel();
}

限制地图显示范围和缩放级别

AMap类中限制地图显示范围的接口：

类型	方法	说明
void	setMapStatusLimits(LatLngBounds latLngBounds)	设置地图显示范围，无论如何操作地图，显示区域都不能超过该矩形区域。

AMap类中限制缩放级别的接口：

类型	方法	说明
void	setMaxZoomLevel(float zoomLevel)	设置地图最大缩放级别 缩放级别范围为[3, 20],超出范围将按最大级别计算 。
void	setMinZoomLevel(float zoomLevel)	设置最小缩放级别 缩放级别范围为[3, 20],超出范围将按最小级别计算
float	getMaxZoomLevel()	返回地图可显示最大缩放级别。
float	getMinZoomLevel()	返回地图可显示最小缩放级别。
void	resetMinMaxZoomPreference()	重置最小及最大缩放级别 将恢复最小级别为3，最大级别为20 。

改变地图默认显示区域

地图默认显示北京地区，通过采用重载的MapView构造方法更改默认地图显示区域：

MapView mapView = new MapView(this, mapOptions);

代码实现片段：

// 定义北京市经纬度坐标（此处以北京坐标为例）
LatLng centerBJPoint= new LatLng(39.904989,116.405285);
// 定义了一个配置 AMap 对象的参数类
AMapOptions mapOptions = new AMapOptions();
// 设置了一个可视范围的初始化位置
// CameraPosition 第一个参数： 目标位置的屏幕中心点经纬度坐标。
// CameraPosition 第二个参数： 目标可视区域的缩放级别
// CameraPosition 第三个参数： 目标可视区域的倾斜度，以角度为单位。
// CameraPosition 第四个参数： 可视区域指向的方向，以角度为单位，从正北向顺时针方向计算，从0度到360度
mapOptions.camera(new CameraPosition(centerBJPoint, 10f, 0, 0));
// 定义一个 MapView 对象，构造方法中传入 mapOptions 参数类
MapView mapView = new MapView(this, mapOptions);
// 调用 onCreate方法 对 MapView LayoutParams 设置
mapView.onCreate(savedInstanceState);

地图事件

AMap类中加载完成的接口：

类型	方法	说明
void	setOnMapLoadedListener(AMap.OnMapLoadedListener listener)	设置地图加载完成监听接口

地图加载完成监听接口

// 地图加载完成监听接口
public interface OnMapLoadedListener {
    /**
     * 当地图加载完成后回调此方法
     */
    void onMapLoaded();
}