腾讯地图离线地图接入指南
以下内容转载自Tencent位置服务的文章《离线地图接入指南》
作者：Tencent位置服务
链接：hhttps://my.oschina.net/u/4209404/blog/4308580
来源：开源中国
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。
为了在⽆⽹、弱⽹或者特殊外⽹环境下也能流畅地显示地图，腾讯地图SDK从4.3.5版本开始，提供了⼀套离线地图⽅案。可⽀持离线地图开关、城市列表获取、离线城市数据下载、下载状态回调、离线缓存管理等能⼒。
离线地图下载地址：
iOS地图SDK、Android地图SDK
本篇文章为Android地图SDK离线地图使用教程，iOS离线地图教程请参考：https://lbs.qq.com/mobile/iOSMapSDK/mapGuide/offline
开启离线地图能力可按照以下步骤进⾏:
-
打开离线地图开关
-
获取离线地图的城市列表
-
获取某个城市的离线控制器
-
判断该城市是否有数据更新
-
执⾏离线数据下载
打开离线地图开关
通过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<OfflineItem> getOfflineItemList();
/**
* 异步获取离线数据列表，触发重新请求
*
* @param callback 回调最新离线Item列表
*/
void getOfflineItemList(Callback<List<OfflineItem>> callback);
}
通过syncLatestData接口，刷新获取最新的数据
offlineComp.syncLatestData(new OfflineMapSyncedListener() {
@Override
public void onSynced(boolean result) {
Log.i("初始化同步结果：" + result);
if (result) {
//处理离线数据
}
}
});
通过getOfflineItemList接⼝可异步获取离线城市列表数据，也可以等待syncLatestData结果，同步获
取离线列表
//异步获取离线城市列表
offlineComp.getOfflineItemList(new Callback<List<OfflineItem>>(){
@Override
public void callback(List<OfflineMapCity> 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();
