腾讯地图位置服务器,腾讯位置服务离线地图接入指南

作者：腾讯位置服务

来源：SegmentFault

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

为了在⽆⽹、弱⽹或者特殊外⽹环境下也能流畅地显示地图，腾讯地图SDK从4.3.5版本开始，提供了⼀套离线地图⽅案。可⽀持离线地图开关、城市列表获取、离线城市数据下载、下载状态回调、离线缓存管理等能⼒。

开启离线地图能力可按照以下步骤进⾏:

打开离线地图开关

获取离线地图的城市列表

获取某个城市的离线控制器

判断该城市是否有数据更新

执⾏离线数据下载

打开离线地图开关

通过TencentMapOptions可以配置离线地图开关，在多个地图实例的情况下，离线地图开关状态保持

⼀致。

TencentMapOptions options = new TencentMapOptions();

options.setOfflineMapEnable(true);

MapView mapView = new MapView(context, options);

TencentMap map = mapView.getMap();

获取离线地图的城市列表

在离线地图开关打开的前提下，通过TencentMap的getMapComponent接⼝，来获取离线地图组件

OfflineMapComponent offlineComp = map.getMapComponent(OfflineMapComponent.class);

离线地图组件提供4个接⼝：

public interface OfflineMapComponent extends TencentMapComponent.Component {

/**

* 判断离线地图是否打开

*

* @return 离线地图状态

*/

boolean isOfflineMapEnable();

/**

* 同步最新数据

*

* @param listener 同步结果回调

*/

void syncLatestData(OfflineMapSyncedListener listener);

/**

* 获取某一Item的离线地图数据

*

* @param item 指定离线Item

* @param listener 状态监听

* @return 离线地图数据，当传入的Item无效(null或者未包含在离线服务内)

* 或 没有开启离线地图模式

* 或 离线地图初始化未完成时，返回null

*/

OfflineItemController getOfflineItemController(OfflineItem item, OfflineStatusChangedListener listener);

/**

* 获取离线数据列表

*

* @return 最新离线Item列表

*/

List getOfflineItemList();

/**

* 异步获取离线数据列表，触发重新请求

*

* @param callback 回调最新离线Item列表

*/

void getOfflineItemList(Callback> callback);

}

通过syncLatestData接口，刷新获取最新的数据

offlineComp.syncLatestData(new OfflineMapSyncedListener() {

@Override

public void onSynced(boolean result) {

Log.i("初始化同步结果：" + result);

if (result) {

//处理离线数据

}

}

});

通过getOfflineItemList接⼝可异步获取离线城市列表数据，也可以等待syncLatestData结果，同步获

取离线列表

//异步获取离线城市列表

offlineComp.getOfflineItemList(new Callback>(){

@Override

public void callback(List result) {

if(result != null) {

mOfflineCityList = result;

//拿到数据之后，选择城市进行下一步操作

}

}

});

//同步获取，当syncLatestData结果为true时，列表不为空

mOfflineCityList = offlineComp.getOfflineItemList();

在返回的OfflineItem列表中，将提供每个离线城市的相关数据，OfflineItem分三类：

OfflineNation(国家)

OfflineProvince(省会)

OfflineCity(城市)

数据

类型

说明

name

String

下载项显示名称

pinyin

String

唯⼀标示的拼⾳

size

long

数据⼤⼩

upgrade

boolean

是否需要更新

percentage

int

数据百分⽐[0-100]

获取某个城市的离线控制器

通过离线地图组件获取对某个城市的离线控制器，在三种情况下，会返回Null：

离线地图开关没有开启

传⼊⾮法城市(只⽀持全国概要、直辖市、地级市，不⽀持下载⼀个省)

地图初始化未完成

OfflineItem beijing = findCity("北京");

OfflineItemController cityController = offlineComp.getOfflineItemController(beijing, statusChangedListener);

状态变化监听接⼝

public interface OfflineStatusChangedListener {

/**

* 离线状态回调

*

* @param item 城市

* @param status 状态

*/

void onStatusChanged(OfflineItem item, OfflineStatus status);

}

离线城市控制器提供4个接⼝：

public interface OfflineItemController {

/**

* 检查是否无效

*

* @return true表示有远程更新或者本地缓存被破坏，需要执行下载

*/

boolean checkInvalidate();

/**

* 开启离线

*

* @return 开启结果

*/

boolean open();

/**

* 关闭离线

*

* @return 关闭结果

*/

boolean close();

/**

* 开始下载

*/

void startDownload();

/**

* 停止下载

*/

void stopDownload();

/**

* 移除缓存，不影响当前正在使用的离线城市

* @return true，清理成功

*/

boolean removeCache();

}

判断该城市是否有数据更新

在获取城市控制器之后，通过控制器可以检查城市是否需要进⾏数据更新，当该城市的离线数据未下

载、数据版本升级或者缓存被清理之后，都会返回true

if(cityController != null) {

boolean needDownload = cityController.checkInvalidate();

if(needDownload) {

//执行下载

cityController.startDownload();

} else {

//跳过更新，打开离线

cityController.open();

}

}

执行离线数据下载

如果没有判断城市是否存在更新，直接执⾏下载，其内部也会进⾏数据更新的校验，结果都将在

OfflineMapStatusChangedListener回调中返回

public enum OfflineStatus {

/**

* 离线错误

*/

ERROR,

/**

* 准备下载

*/

READY,

/**

* 开始下载

*/

START,

/**

* 下载中

*/

DOWNLOADING,

/**

* 取消下载

*/

CANCEL,

/**

* 完成下载

*/

COMPLETED,

/**

* 开启离线

*/

OPEN,

/**

* 关闭离线

*/

CLOSE

}

停止下载

通过城市控制器可以停止正在下载中的城市

if (cityController != null) {

cityController.stopDownload();

}

清理缓存

通过城市控制器可以清理当前城市的缓存

//关闭离线

cityController.close();

//清理该城市缓存

boolean ret = cityController.removeCache();