腾讯地图SDK Android版开发 5 地图交互操作

程序喵D2024-08-17 10:41

腾讯地图SDK Android版开发 5 地图交互操作

前言

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

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

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

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

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

控件介绍

控件介绍

腾讯地图提供一些基础的地图控件，包括LOGO、指南针、比例尺、定位按钮。

控件 功能 默认显示 默认位置
LOGO 可设置显示相对位置（左下，中下，右下，左上，中上，右上） 设置Logo的缩放比例 显示 右下角
指南针 设置是否显示，设置罗盘的填边 不显示 左上角
比例尺 设置是否显示，设置比例尺是否淡出，设置比例尺的显示相对位置位置 不显示 左下角
定位按钮 设置是否显示 不显示 右下角

接口

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

  • LOGO
类型 方法 说明
void setLogoPosition(int logoAnchor) 设置Logo的显示位置
void setLogoPosition(int logoAnchor, int[] marginParams) 根据地图四个Anchor 模式（左上、左下、右下、右上）以及相应的Margins来设置Logo位置
void setLogoPositionWithMargin(int position, int top, int bottom, int left, int right) 设置Logo的显示位置，带偏移量，单位像素 设置Logo的显示位置
void setLogoScale(float logoScale) 设置Logo的缩放比例，比例范围(0.7~1.3)
void setLogoSize(int logoSize) 设置图标大小，暂时不生效
  • 指南针
类型 方法 说明
boolean isCompassEnabled() 获取当前是否开启罗盘控件
void setCompassEnabled(boolean flag) 设置是否显示指南针
void setCompassExtraPadding(int xPadding, int yPadding) 设置罗盘的填边
void setCompassExtraPadding(int padding) 设置罗盘的填边，只对Y轴生效
  • 比例尺
类型 方法 说明
boolean isScaleViewEnabled() 获取当前是否显示比例尺
void setScaleViewEnabled(boolean show) 设置当前是否显示比例尺
void setScaleViewFadeEnable(boolean enable) 设置比例尺是否淡出
void setScaleViewPosition(int position) 设置比例尺的显示位置
void setScaleViewPositionWithMargin(int position, int top, int bottom, int left, int right) 设置比例尺的显示位置，带偏移量，单位像素
  • 定位按钮
类型 方法 说明
boolean isMyLocationButtonEnabled() 获取当前是否显示定位控件
void setMyLocationButtonEnabled(boolean flag) 设置是否显示定位按钮

控件常量

TencentMapOptions类中的控件常量：

  • 定位
常量 说明
LOGO_POSITION_BOTTOM_LEFT 设置地图logo的显示位置：左下角
LOGO_POSITION_TOP_LEFT 设置地图logo的显示位置：左上角
LOGO_POSITION_TOP_CENTER 设置地图logo的显示位置：顶部居中
LOGO_POSITION_TOP_RIGHT 设置地图logo的显示位置：右上角
LOGO_POSITION_BOTTOM_RIGHT 设置地图logo的显示位置：右下角(默认)
LOGO_POSITION_BOTTOM_CENTER 设置地图logo的显示位置：底部居中
  • 比例尺
常量 说明
SCALEVIEW_POSITION_BOTTOM_LEFT 设置地图比例尺的显示位置：左下角,默认
SCALEVIEW_POSITION_TOP_LEFT 设置地图比例尺的显示位置：左上角
SCALEVIEW_POSITION_TOP_CENTER 设置地图比例尺的显示位置：顶部居中
SCALEVIEW_POSITION_TOP_RIGHT 设置地图比例尺的显示位置：右上角
SCALEVIEW_POSITION_BOTTOM_RIGHT 设置地图比例尺的显示位置：右下角
SCALEVIEW_POSITION_BOTTOM_CENTER 设置地图比例尺的显示位置：底部居中

地图控件点击事件

类型 接口 说明
static interface TencentMap.OnCompassClickedListener 当地图的罗盘被点击时的回调接口
static interface TencentMap.OnMyLocationClickListener 点击我的位置时的回调接口
类型 方法 说明
void setOnCompassClickedListener(TencentMap.OnCompassClickedListener onCompassClickedListener) 设置罗盘位按钮监听接口

示例代码

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

java 复制代码 
UiSettings uiSettings = map.getUiSettings();
  • Logo
java 复制代码 
// 设置Logo的显示位置
int logoAnchor = TencentMapOptions.LOGO_POSITION_BOTTOM_LEFT;
uiSettings.setLogoPosition(logoAnchor);
  • 指南针
java 复制代码 
// 获取当前是否开启罗盘控件
boolean enabled = uiSettings.isCompassEnabled();
// 设置是否显示指南针
uiSettings.setCompassEnabled(true);

int xPadding = 20;
int yPadding = 20;
// 设置罗盘的填边
uiSettings.setCompassExtraPadding(xPadding, yPadding);
  • 比例尺
java 复制代码 
// 获取当前是否显示比例尺
boolean isShow = uiSettings.isScaleViewEnabled();
// 设置当前是否显示比例尺
uiSettings.setScaleViewEnabled(true);
// 设置比例尺是否淡出
uiSettings.setScaleViewFadeEnable(false);

// 设置比例尺的显示位置
int position = TencentMapOptions.LOGO_POSITION_BOTTOM_LEFT;
uiSettings.setScaleViewPosition(position);
  • 定位按钮
java 复制代码 
// 获取当前是否显示定位控件
boolean isShow = uiSettings.isMyLocationButtonEnabled();
// 设置是否显示定位按钮
uiSettings.setMyLocationButtonEnabled(true);

效果图

地图手势

腾讯地图SDK支持多种手势，比如单指按下、单指抬起、单指点击、单指双击、单指长按、滑动、滚动、缩放、倾斜、旋转等手势，还有包含一些组合手势，比如双击放大地图、双指单击缩小地图、单指双击上下滑动缩放地图等。

地图手势方法说明

手势 说明 状态开关 默认
平移 单指长按， 用手指拖动地图四处滚动平移 可禁用或开启 开启
滑动 单指滑动， 用手指滑动地图，显示动画效果 可禁用或开启 开启
缩放 1.单指双击 2.双指单击 3.单指双击长按屏幕上下滑动， 缩放手势可改变地图的缩放级别 可禁用或开启 开启
倾斜 双指长按屏幕上下滑动， 通过两个手指的移动，控制地图的倾斜角 可禁用或开启 开启
旋转 双指长按屏幕左右交替旋转 通过两个手指控制，旋转3D地图 可禁用或开启 开启

地图手势开关

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

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

类型 方法 说明
boolean isScrollGesturesEnabled() 获取当前是否支持滚动手势
boolean isZoomGesturesEnabled() 获取当前是否支持缩放手势
boolean isTiltGesturesEnabled() 获取当前是否支持倾斜手势
boolean isRotateGesturesEnabled() 获取当前是否支持旋转手势

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

类型 方法 说明
void setFlingGestureEnabled(boolean flag) 设置是否开启地图滑动手势
void setScrollGesturesEnabled(boolean flag) 设置是否开启地图滚动手势
void setZoomGesturesEnabled(boolean flag) 设置是否开启地图缩放手势
void setTiltGesturesEnabled(boolean flag) 设置是否开启地图倾斜手势
void setRotateGesturesEnabled(boolean flag) 设置是否开启地图旋转手势
void setAllGesturesEnabled(boolean flag) 设置是否开启地图所有手势

地图手势事件

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

类型 方法 说明
void setOnMapClickListener(TencentMap.OnMapClickListener onMapClickListener) 设置地图点击事件的监听接口
void setOnMapLongClickListener(TencentMap.OnMapLongClickListener onMapLongClickListener) 设置地图长按事件的监听接口
void addTencentMapGestureListener(TencentMapGestureListener listener) 添加一个腾讯地图手势监听接口
void removeTencentMapGestureListener(TencentMapGestureListener listener) 移除一个腾讯地图手势监听接口

当地图被点击时回调接口

java 复制代码 
// 当地图被点击时回调接口
public interface OnMapClickListener {
    /**
     * 当地图被点击时的回调函数
     * @param latlng 点击点的经纬度
     */
    void onMapClick(LatLng latlng);
}

当地图被长按时回调接口

java 复制代码 
// 当地图被长按时回调接口
public interface OnMapLongClickListener {
    /**
     * 当地图被长按时的回调函数
     * @param latlng 按住点的经纬度
     */
    void onMapLongClick(LatLng latlng);
}

地图手势识别的回调

java 复制代码 
// 地图手势识别的回调
public interface TencentMapGestureListener {
    /**
     * 单指双击
     * @param x 像素 x坐标
     * @param y 像素 y坐标
     * @return
     */
    boolean onDoubleTap(float x, float y);

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

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

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

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

    /**
     * 单指按下
     * @param x 像素 x坐标
     * @param y 像素 y坐标
     * @return
     */
    boolean onDown(float x, float y);

    /**
     * 单指抬起
     * @param x 像素 x坐标
     * @param y 像素 y坐标
     * @return
     */
    boolean onUp(float x, float y);

    /**
     * 地图稳定下来
     */
    void onMapStable();
}

地图状态

地图状态类

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

类型 方法 说明
LatLng target 目标经纬度
float zoom 缩放级别
float bearing 旋转角度
float tilt 倾斜角度

CameraPosition类中的方法：

类型 方法 说明
- CameraPosition(LatLng latlng, float zoomLevel, float skew, float rotate) 构造一个 CameraPosition
static CameraPosition fromLatLngZoom(LatLng latlng, float zoomLevel) 创建一个 CameraPosition
static CameraPosition.Builder builder() 创建一个 CameraPosition.Builder
static CameraPosition.Builder builder(CameraPosition cameraposition) 由一个 CameraPosition 对象创建一个 CameraPosition.Builder

地图状态构造类

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

类型 方法 说明
CameraPosition.Builder target(LatLng latlng) 地图目标经纬度
CameraPosition.Builder zoom(float zoomLevel) 地图的目标缩放级别
CameraPosition.Builder bearing(float rotate) 旋转角度
CameraPosition.Builder tilt(float skew) 倾斜角度
CameraPosition build() 构造一个CameraPosition 对象。

地图状态更新类

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

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

类型 方法 说明
static CameraUpdate newCameraPosition(CameraPosition cameraposition) 由一个CameraPosition来生成新的状态变化对象
static CameraUpdate newLatLng(LatLng latlng) 生成一个把地图移动到指定的经纬度到屏幕中心的状态变化对象
static CameraUpdate newLatLngBounds(LatLngBounds latlngbounds, int padding) 把地图移到到以指定的经纬度范围的，并且在这个范围四周加上padding像素的填充。
static CameraUpdate newLatLngBoundsRect(LatLngBounds latlngbounds, int leftPadding, int rightPadding, int topPadding, int bottomPadding) 把地图移动到指定经纬度范围，以适应当前屏幕的显示，并且可以为上下左右分别设置填充的像素
static CameraUpdate newLatLngBoundsWithMapCenter(LatLngBounds latLngBounds, LatLng mapCenter, int padding) 以mapCenter为中心，将latLngBounds对应的区域刚好缩放到可视区域内，并且在这个范围四周加上padding像素填充
static CameraUpdate newLatLngZoom(LatLng latlng, float zoom) 把地图以latlng为中心，以zoom为缩放级别，移到屏幕中心
static CameraUpdate rotateTo(float rotate, float skew) 将地图顺时针旋转rotate度，并且向后倾斜skew度
static CameraUpdate scrollBy(float xPixel, float yPixel) 将地图向左下移动xPixel和yPexil像素
static CameraUpdate zoomBy(float zoomLevelDelta) 在当前的缩放级别下，把缩放级别变化zoomLevelDelta，如果超出了范围，则停止在范围内
static CameraUpdate zoomBy(float zoomLevelDelta, android.graphics.Point point) 在当前的缩放级别下，把缩放级别变化zoomLevelDelta，如果超出了范围，则停止在范围内 注：因为依赖于MapView的尺寸，所以在onCreate中直接调用会有问题，可以放在OnMapLoadedCallback中调用
static CameraUpdate zoomIn() 把地图放大一级 注：执行放zoomIn操作需要获取当前地图状态，如果必须要在onCreate中调用，需要放在OnMapLoadedCallback中执行。
static CameraUpdate zoomOut() 把地图缩小一级 注：执行放zoomOut操作需要获取当前地图状态，如果必须要在onCreate中调用，需要放在OnMapLoadedCallback中执行。
static CameraUpdate zoomTo(float zoomLevel) 把地图缩放到目标级别

改变地图状态接口

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

类型 方法 说明
void moveCamera(CameraUpdate cameraUpdate) 把地图变换到指定的状态
void animateCamera(CameraUpdate cameraUpdate) 把地图变换到指定的状态,带动画
void animateCamera(CameraUpdate cameraUpdate, long duration, TencentMap.CancelableCallback cancelableCallback) 以动画的方式把地图变换到指定的状态
void animateCamera(CameraUpdate cameraUpdate, TencentMap.CancelableCallback cancelableCallback) 以动画的方式把地图变换到指定的状态
void setOnCameraChangeListener(TencentMap.OnCameraChangeListener onCameraChangeListener) 设置地图变换的监听接口

当地图发生变化时的调用接口

java 复制代码 
// 当地图发生变化时的调用接口
public interface OnCameraChangeListener {
    /**
     * 地图状态发生变化
     * @param cameraPosition 地图当前的状态对象
     */
    void onCameraChange(CameraPosition cameraPosition);

    /**
     * 地图状态变化结束
     * @param cameraPosition 地图当前的状态对象
     */
    void onCameraChangeFinished(CameraPosition cameraPosition);
}

地图变换相关操作的状态回调接口

java 复制代码 
// 地图变换相关操作的状态回调接口
public interface CancelableCallback {
    /**
     * 地图变换结束
     */
    void onFinish();

    /**
     * 地图变换被取消
     */
    void onCancel();
}

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

腾讯地图 SDK 支持将地图限制在指定的经纬度范围内，即只能在一定区域内缩放、移动地图视野。

显示范围适配模式

常量 说明
FIT_HEIGHT 此模式会以 bounds 高度为参考值限制地图的控制区域，在最小限制级别时 bounds 的横向区域可能显示不完整, 可调用 TencentMap.setMinZoomLevel(int) 修改最小限制级别以展示完整的区域
FIT_WIDTH 此模式会以 bounds 宽度为参考值限制地图的控制区域，在最小限制级别时 bounds 的纵向区域可能显示不完整, 可调用 TencentMap.setMinZoomLevel(int) 修改最小限制级别以展示完整的区域

接口

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

类型 方法 说明
void setRestrictBounds(LatLngBounds restrictBounds, RestrictBoundsFitMode fitMode) 限制地图的显示范围。
float getMaxZoomLevel() 获取地图最大的支持的缩放级别
float getMinZoomLevel() 获取地图最小的支持的缩放级别
void setMaxZoomLevel(int zoomLevel) 设置地图的最大缩放级别
void setMinZoomLevel(int zoomLevel) 设置地图的最小缩放级别
  • 说明：限制地图的显示范围。此接口同时会限制地图的最小缩放整数级别，用户还可以通过 setMinZoomLevel(int) 修改自己需要的最小缩放级别获取需要的展示效果。这个方法只有在 OnMapLoadedCallback 回调后才能正常使用。

地图事件

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

类型 方法 说明
void addOnMapLoadedCallback(TencentMap.OnMapLoadedCallback onMapLoadedCallback) 设置地图加载完成回调接口
void setOnMapFrameFinished(TencentMap.OnMapFrameFinishCallback onMapFrameFinished) 设置地图渲染帧回调

##地图加载完成的回调接口

java 复制代码 
// 地图加载完成的回调接口,设置之后只回调一次，如果需要再获取，则需要重新设置回调
public interface OnMapLoadedCallback {
    /**
     * 地图加载完成回调函数
     */
    void onMapLoaded();
}

地图完成首屏渲染回调接口

java 复制代码 
// 地图完成首屏渲染回调，仅依赖当前资源的渲染完成
public interface OnMapFrameFinishCallback {
    /**
     * 地图渲染首屏开始
     */
    void onMapFrameStart();

    /**
     * 地图渲染首屏完成
     */
    void onMapFrameFinished();
}
相关推荐
拭心5 小时前
Google 提供的 Android 端上大模型组件：MediaPipe LLM 介绍
android
带电的小王7 小时前
WhisperKit: Android 端测试 Whisper -- Android手机(Qualcomm GPU)部署音频大模型
android·智能手机·whisper·qualcomm
梦想平凡7 小时前
PHP 微信棋牌开发全解析：高级教程
android·数据库·oracle
元争栈道8 小时前
webview和H5来实现的android短视频(短剧)音视频播放依赖控件
android·音视频
阿甘知识库9 小时前
宝塔面板跨服务器数据同步教程：双机备份零停机
android·运维·服务器·备份·同步·宝塔面板·建站
元争栈道9 小时前
webview+H5来实现的android短视频(短剧)音视频播放依赖控件资源
android·音视频
MuYe9 小时前
Android Hook - 动态加载so库
android
居居飒10 小时前
Android学习(四)-Kotlin编程语言-for循环
android·学习·kotlin
Henry_He13 小时前
桌面列表小部件不能点击的问题分析
android
工程师老罗13 小时前
Android笔试面试题AI答之Android基础（1）
android
热门推荐
01〔AI 绘画〕Stable Diffusion 之 解决绘制多人或面部很小的人物时面部崩坏问题 篇02ARM学习（31）编译器对overlay方式的支持03玄机平台应急响应—webshell查杀04DisplayPort AltMode On Type-c协议_Ver2.0(学习笔记)05校验 GPT-4 真实性的三个经典问题：快速区分 GPT-3.5 与 GPT-4，并提供免费测试网站06Docker 夺命连环 15 问076个主流的工业3D管道设计软件08基于大语言模型（LLM）的合成数据生成、策展和评估的综述09(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明10树莓派 5 AI 套件（Hailo-8L）使用教程