百度地图SDK Android版开发 5 地图交互操作
- 前言
- 控件
- 控件介绍
- 接口
- MapView
- BaiduMap
- UiSettings
- LogoPosition
- 示例代码
- Logo
- 指南针
- 比例尺
- 缩放按钮
- 地图上控件边距
- 效果图
- 地图手势
- 地图手势方法说明
- 地图手势开关接口
- 地图手势事件
- 地图单击事件监听接口
- 地图双击事件监听接口
- 地图长按事件监听接口
- 地图手势事件回调接口
- 用户触摸地图时回调接口
- 地图状态
- 地图状态类
- 地图状态更新类
- 改变地图状态接口
- 地图状态改变接口
- 限制地图显示范围和缩放级别
- 其它地图事件
- 地图加载完成回调接口
- 地图渲染完成回调接口
前言
前文介绍了三个主题：创建显示地图；切换地图类型；显示定位。本文重点介绍地图交互操作及相关的类和接口。
-
百度地图支持多种地图交互操作，用户可以通过手势或控件进行地图操作，以实现更好的地图浏览体验。另一方面开发者通过代码实现特定业务场景的地图交互。
-
百度地图通过设定不同的地图状态，来改变地图视野。
-
最后是不属于地图操作的地图事件，但是也很重要。
- 比如地图加载完成事件，一些特定接口需要在地图加载完成后才能调用（在显示定位和本文均有提及）。
控件
控件介绍
百度地图提供一些基础的地图控件，包括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
// 获取Logo位置
LogoPosition position = mapView.getLogoPosition();
// 设置Logo位置
mapView.setLogoPosition(LogoPosition.logoPostionRightBottom);
指南针
// 获取是否允许指南针
boolean enabled = uiSettings.isCompassEnabled();
// 设置是否允许指南针
uiSettings.setCompassEnabled(true);// 设置指南针是否显示
map.setCompassEnable(true);
Point point = map.getCompassPosition();
// map.setCompassPosition(new Point(100, 100));
// map.setCompassIcon(icon);
比例尺
// 获取比例尺控件的宽度
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));
缩放按钮
mapView.showZoomControls(true);
Point point = mapView.getZoomControlsPosition();
// mapView.setZoomControlsPosition(new Point(0, 0));
地图上控件边距
// 设置地图上控件与地图边界的距离，包含比例尺、缩放控件、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) | 设置触摸地图事件监听者 |
地图单击事件监听接口
// 地图单击事件监听接口
public interface OnMapClickListener {/*** 地图单击事件回调函数* @param point 点击的地理坐标*/void onMapClick(LatLng point);/*** 地图内 Poi 单击事件回调函数* @param mapPoi 点击的 poi 信息*/void onMapPoiClick(MapPoi mapPoi);
}
地图双击事件监听接口
// 地图双击事件监听接口
public interface OnMapDoubleClickListener {/*** 地图双击事件监听回调函数* @param point 双击的地理坐标*/void onMapDoubleClick(LatLng point);
}
地图长按事件监听接口
// 地图长按事件监听接口
public interface OnMapLongClickListener {/*** 地图长按事件监听回调函数* @param point 长按的地理坐标*/void onMapLongClick(LatLng point);
}
地图手势事件回调接口
// 地图手势事件回调接口
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);
}
用户触摸地图时回调接口
// 用户触摸地图时回调接口
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) | 设置地图状态监听者 |
地图状态改变接口
// 地图状态改变接口
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新增接口 |
地图加载完成回调接口
// 地图加载完成回调接口
public interface OnMapLoadedCallback {/*** 地图加载完成回调函数*/void onMapLoaded();
}
地图渲染完成回调接口
// 地图渲染完成回调接口
public interface OnMapRenderCallback {/*** 地图渲染完成回调函数*/void onMapRenderFinished();
}
