離線地圖接入指南

爲了在⽆⽹、弱⽹或者特殊外⽹環境下也能流暢地顯示地圖，騰訊地圖SDK從4.3.5版本開始，提供了⼀套離線地圖⽅案。可⽀持離線地圖開關、城市列表獲取、離線城市數據下載、下載狀態回調、離線緩存管理等能⼒。

離線地圖下載地址：
iOS地圖SDK、Android地圖SDK

本篇文章爲Android地圖SDK離線地圖使用教程，iOS離線地圖教程請參考：https://lbs.qq.com/mobile/iOS...

開啓離線地圖能力可按照如下步驟進⾏:

1. 打開離線地圖開關
2. 獲取離線地圖的城市列表
3. 獲取某個城市的離線控制器
4. 判斷該城市是否有數據更新
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<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分三類：

1. OfflineNation（國家）
2. OfflineProvince（省會）
3. OfflineCity（城市）

數據	類型	說明
name	String	下載項顯示名稱
pinyin	String	惟⼀標示的拼⾳
size	long	數據⼤⼩
upgrade	boolean	是否須要更新
percentage	int	數據百分⽐[0-100]

獲取某個城市的離線控制器

經過離線地圖組件獲取對某個城市的離線控制器，在三種狀況下，會返回Null：

1. 離線地圖開關沒有開啓
2. 傳⼊⾮法城市（只⽀持全國概要、直轄市、地級市，不⽀持下載⼀個省）
3. 地圖初始化未完成

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();