百度地图SDK Android版开发 5 地图交互操作

前言
控件
- 控件介绍
- 接口
- 示例代码
- 效果图
地图手势
地图状态
其它地图事件
- 地图加载完成回调接口
- 地图渲染完成回调接口

前言

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

百度地图支持多种地图交互操作，用户可以通过手势或控件进行地图操作，以实现更好的地图浏览体验。另一方面开发者通过代码实现特定业务场景的地图交互。
百度地图通过设定不同的地图状态，来改变地图视野。
最后是不属于地图操作的地图事件，但是也很重要。
- 比如地图加载完成事件 ，一些特定接口需要在地图加载完成后才能调用（在显示定位 和本文均有提及）。

控件

控件介绍

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

控件	功能	默认显示	默认位置
LOGO	可设置显示相对位置（左下，中下，右下，左上，中上，右上）	显示	左下角
指南针	设置是否显示，设置中心点绝对位置	不显示	左上角
比例尺	设置是否显示，设置左上角显示绝对位置	显示	左下角
缩放按钮	设置是否显示，设置左上角绝对位置	显示	右下角

注意：地图Logo不允许遮挡，可通过设置地图上控件边距来避免遮挡。

注意：根据百度地图API使用条款您的应用不得删除或覆盖百度地图logo或版权声明。地图内边距允许您在必要时重新定位这些元素，若您需要在地图布局顶底部显示自定义UI，请设置内边距以保证百度地图logo和版权声明始终可见。

接口

MapView

MapView类中Logo、比例尺、缩放按钮的接口：

类型	方法	说明
`final void`	`setLogoPosition(LogoPosition position)`	设置Logo位置
`final LogoPosition`	`getLogoPosition()`	获取Logo位置
`int`	`getScaleControlViewHeight()`	获取比例尺控件的高度
`int`	`getScaleControlViewWidth()`	获取比例尺控件的宽度
`boolean`	`isShowScaleControl()`	获取比例尺控件是否显示
`void`	`showScaleControl(boolean show)`	设置是否显示比例尺控件
`Point`	`getScaleControlPosition()`	获取比例尺控件对应的屏幕位置
`void`	`setScaleControlPosition(Point p)`	设置比例尺控件的位置，在`onMapLoaded`后生效
`void`	`showZoomControls(boolean show)`	设置是否显示缩放控件
`Point`	`getZoomControlsPosition()`	获取缩放控件的屏幕位置
`void`	`setZoomControlsPosition(Point p)`	设置缩放控件的位置，在 `onMapLoaded` 后生效

BaiduMap

BaiduMap类中指南针，地图上控件边距、地图UI控制器的接口：

类型	方法	说明
`void`	`setCompassEnable(boolean enable)`	设置指南针是否显示
`void`	`setCompassIcon(Bitmap icon)`	设置指南针自定义图标
`Point`	`getCompassPosition()`	获取屏幕坐标系下指南针位置
`void`	`setCompassPosition(Point p)`	设置指南针的位置
`final void`	`setViewPadding(int left, int top, int right, int bottom)`	设置地图上控件与地图边界的距离，包含比例尺、缩放控件、logo、指南针的位置。只有在 OnMapLoadedCallback.onMapLoaded() 之后设置才生效。参数依次为左边距、上边距、右边距、下边距（单位为pixel）
`UiSettings`	`getUiSettings()`	获取地图UI控制器

UiSettings

UiSettings类中指南针的接口：

类型	方法	说明
`boolean`	`isCompassEnabled()`	获取是否允许指南针
`void`	`setCompassEnabled(boolean enabled)`	设置是否允许指南针

LogoPosition

Logo位置枚举，左下开始顺时针的6个位置：

位置	说明
`logoPostionleftBottom`	屏幕左下位置
`logoPostionleftTop`	屏幕左上位置
`logoPostionCenterTop`	屏幕中上位置
`logoPostionRightTop`	屏幕右上位置
`logoPostionRightBottom`	屏幕右下位置
`logoPostionCenterBottom`	屏幕中下位置

示例代码

Logo

java 复制代码

// 获取Logo位置
LogoPosition position = mapView.getLogoPosition();
// 设置Logo位置
mapView.setLogoPosition(LogoPosition.logoPostionRightBottom);

指南针

java 复制代码

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

// 设置指南针是否显示
map.setCompassEnable(true);
Point point = map.getCompassPosition();
// map.setCompassPosition(new Point(100, 100));
// map.setCompassIcon(icon);

比例尺

java 复制代码

// 获取比例尺控件的宽度
int width = mapView.getScaleControlViewWidth();
// 获取比例尺控件的高度
int height = mapView.getScaleControlViewHeight();

// 获取比例尺控件是否显示
boolean isShow = mapView.isShowScaleControl();
// 设置是否显示比例尺控件
mapView.showScaleControl(isShow);

// 获取比例尺控件对应的屏幕位置
Point point = mapView.getScaleControlPosition();
// 设置比例尺控件的位置，在 onMapLoadFinish 后生效
// mapView.setScaleControlPosition(new Point(20, 20));

缩放按钮

java 复制代码

mapView.showZoomControls(true);
Point point = mapView.getZoomControlsPosition();
// mapView.setZoomControlsPosition(new Point(0, 0));

地图上控件边距

java 复制代码

// 设置地图上控件与地图边界的距离，包含比例尺、缩放控件、logo、指南针的位置。
// 只有在 OnMapLoadedCallback.onMapLoaded()之后设置才生效。
// 参数依次为左边距、上边距、右边距、下边距（单位为 pixel）
int left = 20;
int top = 0;
int right = 20;
int bottom = 0;
map.setViewPadding(left, top, right, bottom);

效果图

地图手势

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

地图手势默认开启，可以通过UiSetting类提供的接口来控制手势的开关。

地图手势方法说明

手势	说明	状态开关	默认
地图平移	如果启用，则用户可以平移地图。	控制是否启用或禁用平移的功能	开启
地图缩放	如果启用，用户可以双指点击或缩放地图视图。	控制是否启用或禁用缩放手势	开启
地图俯视（3D）	如果启用，则用户可使用双指向下或向上滑动到俯视图。	控制是否启用或禁用俯视（3D）功能	开启
地图旋转	如果启用，则用户可使用双指旋转来旋转地图。	控制是否启用或禁用地图旋转功能	开启
地图双击放大	如果启用，则用户可双击放大当前地图中心点。	控制是否设置双击地图按照当前地图中心点放大。	开启
禁止所有手势	如果启用，所有手势都将被禁用。	控制是否一并禁止所有手势	关闭

地图手势开关接口

UiSetting手势开关1

类型	方法	说明
`void`	`setScrollGesturesEnabled(enable)`	控制是否启用或禁用平移的功能
`void`	`setZoomGesturesEnabled(enable)`	控制是否启用或禁用缩放手势
`void`	`setOverlookingGesturesEnabled(enable)`	控制是否启用或禁用俯视（3D）功能
`void`	`setRotateGesturesEnabled(enable)`	控制是否启用或禁用地图旋转功能
`void`	`setEnlargeCenterWithDoubleClickEnable(enable)`	控制是否设置双击地图按照当前地图中心点放大。
`void`	`setAllGesturesEnabled(enable)`	控制是否一并禁止所有手势

UiSetting手势开关2

类型	方法	说明
`void`	`setDoubleClickZoomEnabled(boolean enabled)`	设置是否允许双击放大地图手势
`void`	`setDoubleClickMoveZoomEnable(boolean enabled)`	设置是否允许双击拖动缩放地图
`void`	`setFlingEnable(boolean enabled)`	设置是否允许抛出手势
`void`	`setInertialAnimation(boolean enabled)`	缩放动画惯性开关
`void`	`setTwoTouchClickZoomEnabled(boolean enabled)`	设置是否允许双指同时点击缩小地图手势
`void`	`setLatLngGesturesCenter(LatLng latLng)`	设置地理坐标为手势中心点
`void`	`setPointGesturesCenter(Point point)`	设置屏幕坐标为手势中心点

地图手势事件

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

类型	方法	说明
`void`	`setOnMapClickListener(BaiduMap.OnMapClickListener listener)`	设置地图单击事件监听者
`void`	`setOnMapDoubleClickListener(BaiduMap.OnMapDoubleClickListener listener)`	设置地图双击事件监听者
`void`	`setOnMapLongClickListener(BaiduMap.OnMapLongClickListener listener)`	设置地图长按事件监听者
`void`	`setOnMapGestureListener(BaiduMap.onMapGestureListener listener)`	Android地图SDK自7.5.2起支持手势事件回调，开发者可以根据回调信息判断当前手势事件与地图状态变化的关系，还可以决定手势事件消费时机。
`void`	`setOnMapTouchListener(BaiduMap.OnMapTouchListener listener)`	设置触摸地图事件监听者

地图单击事件监听接口

java 复制代码

// 地图单击事件监听接口
public interface OnMapClickListener {
    /**
     * 地图单击事件回调函数
     * @param point 点击的地理坐标
     */
    void onMapClick(LatLng point);

    /**
     * 地图内 Poi 单击事件回调函数
     * @param mapPoi 点击的 poi 信息
     */
    void onMapPoiClick(MapPoi mapPoi);
}

地图双击事件监听接口

java 复制代码

// 地图双击事件监听接口
public interface OnMapDoubleClickListener {
    /**
     * 地图双击事件监听回调函数
     * @param point 双击的地理坐标
     */
    void onMapDoubleClick(LatLng point);
}

地图长按事件监听接口

java 复制代码

// 地图长按事件监听接口
public interface OnMapLongClickListener {
    /**
     * 地图长按事件监听回调函数
     * @param point 长按的地理坐标
     */
    void onMapLongClick(LatLng point);
}

地图手势事件回调接口

java 复制代码

// 地图手势事件回调接口
public interface onMapGestureListener {
    /**
     * 平移
     * @param start 平移手势开始屏幕坐标点
     * @param end   平移手势结束屏幕坐标点
     * @param curStatus 当前地图状态
     * @return 该手势事件是否由SDK消费
     */
    boolean onMapScroll(Point start, Point end, MapStatus curStatus);

    /**
     * 双击放大
     * @param point 屏幕坐标点
     * @param curStatus 当前地图状态
     * @return 该手势事件是否由SDK消费
     */
    boolean onMapDoubleTouch(Point point, MapStatus curStatus);

    /**
     * 双指点击缩小
     * @param p1 第一个屏幕坐标点
     * @param p2 第二个屏幕坐标点
     * @param curStatus 当前地图状态
     * @return 该手势事件是否由SDK消费
     */
    boolean onMapTwoClick(Point p1, Point p2, MapStatus curStatus);

    /**
     * 捏合
     * @param p1 第一个屏幕坐标点
     * @param p2 第二个屏幕坐标点
     * @param curStatus 当前地图状态
     * @return 该手势事件是否由SDK消费
     */
    boolean onMapKneading(Point p1, Point p2, MapStatus curStatus);

    /**
     * 俯视
     * @param p1 第一个屏幕坐标点
     * @param p2 第二个屏幕坐标点
     * @param curStatus 当前地图状态
     * @return 该手势事件是否由SDK消费
     */
    boolean onMapOverLooking(Point p1, Point p2, MapStatus curStatus);

    /**
     * 惯性抛出手势
     * @param event 触摸事件
     * @param velocityX X轴上的移动速度，像素/秒
     * @param velocityY Y轴上的移动速度，像素/秒
     * @param curStatus 当前地图状态
     * @return 该手势事件是否由SDK消费
     */
    boolean onMapFling(MotionEvent event, float velocityX, float velocityY,
                       MapStatus curStatus);

    /**
     * 手势事件结束后地图状态
     * @param status 当前地图状态
     */
    void onMapStatusChangeFinish(MapStatus status);
}

用户触摸地图时回调接口

java 复制代码

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

地图状态

地图状态类

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

类型	方法	说明
`LatLng`	`target`	地图操作的中心点。
`LatLngBounds`	`bound`	当前屏幕显示范围内的地理范围，当旋转或俯视时，是当前屏幕可见显示范围的最大外接矩形。
`Point`	`targetScreen`	地图操作中心点在屏幕中的坐标
`WinRound`	`winRound`	屏幕范围
`float`	`zoom`	地图缩放级别 4~21，室内图支持到22
`float`	`overlook`	地图俯仰角度。
`float`	`rotate`	地图旋转角度。

地图状态更新类

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

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

类型	方法	说明
static MapStatusUpdate	`newLatLng`(LatLng latLng)	设置地图新中心点
static MapStatusUpdate	`newLatLngBounds`(LatLngBounds bounds)	设置显示在屏幕中的地图地理范围
static MapStatusUpdate	`newLatLngBounds`(LatLngBounds bounds, int width, int height)	设置显示在规定宽高中的地图地理范围
static MapStatusUpdate	`newLatLngBounds`(LatLngBounds bounds, int paddingLeft, int paddingTop, int paddingRight, int paddingBottom)	设置显示在指定相对于MapView的padding中的地图地理范围
static MapStatusUpdate	`newLatLngZoom`(LatLngBounds bounds, int paddingLeft, int paddingTop, int paddingRight, int paddingBottom)	根据Padding设置地理范围的合适缩放级别
static MapStatusUpdate	`newLatLngZoom`(LatLng latLng, float zoom)	设置地图中心点以及缩放级别
static MapStatusUpdate	`newMapStatus`(MapStatus mapStatus)	设置地图新状态
static MapStatusUpdate	`scrollBy`(int xPixel, int yPixel)	按像素移动地图中心点
static MapStatusUpdate	`zoomBy`(float amount)	根据给定增量缩放地图级别
static MapStatusUpdate	`zoomBy`(float amount, Point focus)	根据给定增量以及给定的屏幕坐标缩放地图级别
static MapStatusUpdate	`zoomIn`()	放大地图缩放级别
static MapStatusUpdate	`zoomOut`()	缩小地图缩放级别
static MapStatusUpdate	`zoomTo`(float zoom)	设置地图缩放级别

改变地图状态接口

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

类型	方法	说明
MapStatus	`getMapStatus`()	获取地图的当前状态
void	`setMapStatus`(MapStatusUpdate update)	改变地图状态
void	`animateMapStatus`(MapStatusUpdate update)	以动画方式更新地图状态，默认动画耗时 300 ms
void	`animateMapStatus`(MapStatusUpdate update, int durationMs)	以动画方式更新地图状态
void	`setOnMapStatusChangeListener`(BaiduMap.OnMapStatusChangeListener listener)	设置地图状态监听者

地图状态改变接口

java 复制代码

// 地图状态改变接口
public interface OnMapStatusChangeListener {
    int REASON_GESTURE = 1; // 用户手势触发导致的地图状态改变, 比如双击、拖拽、滑动底图
    int REASON_API_ANIMATION = 2; // SDK导致的地图状态改变, 比如点击缩放控件、指南针图标
    int REASON_DEVELOPER_ANIMATION = 3; // 开发者调用,导致的地图状态改变

    /**
     * 手势操作地图，设置地图状态等操作导致地图状态开始改变。
     * @param status 地图状态改变开始时的地图状态
     */
    void onMapStatusChangeStart(MapStatus status);

    /**
     * 手势操作地图，设置地图状态等操作导致地图状态开始改变。
     * @param status 地图状态改变开始时的地图状态
     * @param reason 地图状态改变的原因
     */
    void onMapStatusChangeStart(MapStatus status, int reason);

    /**
     * 地图状态变化中
     * @param status 当前地图状态
     */
    void onMapStatusChange(MapStatus status);

    /**
     * 地图状态改变结束
     * @param status 地图状态改变结束后的地图状态
     */
    void onMapStatusChangeFinish(MapStatus status);
}

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

BaiduMap类中限制地图显示范围和缩放级别的接口：

类型	方法	说明
LatLngBounds	`getMapStatusLimit`()	获取当前地图可移动的实际地理范围
void	`setMapStatusLimits`(LatLngBounds bounds)	设置地图的可移动区域 V4.5.0版本起，该方法不与BaiduMap.OnMapLoadedCallback.onMapLoaded()关联，实际上该方法与 setMapStatus(MapStatusUpdate)并列同级该方法执行完成之后，不可再调用setMapStatus(MapStatusUpdate)，否则可能会更改 MapStatus，造成可移动区域设置不生效，setMapStatus(MapStatusUpdate) 方法可以放在该方法之前执行。
float	`getMaxZoomLevel`()	获取地图最大缩放级别
float	`getMinZoomLevel`()	获取地图最小缩放级别
void	`setMaxAndMinZoomLevel`(float max, float min)	设置地图最大以及最小缩放级别，地图支持的最大最小级别分别为[4-21] V5.0.0版本起，为了优化显示效果，地图支持最小缩放级别为4，即1000公里该方法如果不是在初始化方法（如onCreate方法）中使用，则需要在该方法执行完成后，调用 setMapStatus(MapStatusUpdate)或者animateMapStatus(MapStatusUpdate)方法否则出现不生效的情况。

其它地图事件

BaiduMap类中加载完成和渲染完成的接口：

类型	方法	说明
void	`setOnMapLoadedCallback`(BaiduMap.OnMapLoadedCallback callback)	设置地图加载完成回调，该接口需要在地图加载到页面之前调用，否则不会触发回调。
void	`setOnMapRenderCallbadk`(BaiduMap.OnMapRenderCallback callback)	设置地图渲染完成回调
void	`setOnMapRenderValidDataListener`(BaiduMap.OnMapRenderValidDataListener listener)	设置地图数据渲染是否有效监听者 V5.4.2新增接口

地图加载完成回调接口

java 复制代码

// 地图加载完成回调接口
public interface OnMapLoadedCallback {
    /**
     * 地图加载完成回调函数
     */
    void onMapLoaded();
}

地图渲染完成回调接口

java 复制代码

//  地图渲染完成回调接口
public interface OnMapRenderCallback {
    /**
     * 地图渲染完成回调函数
     */
    void onMapRenderFinished();
}