手把手教你玩轉HarmonyOS版地圖應用開發

一、導讀

7月31日，華為HarmonyOS開發者日將在杭州舉行。為了方便更多開發者，高德開放平臺地圖SDK已在業內率先實現鴻蒙化遷移和重構， 全面適配HarmonyOS並面向開發者免費釋出。開發者可到高德開放平臺官網瞭解更多內容，獲取版本下載、開發文件、常見問題等支援。

在今年6月2日，華為就正式釋出了HarmonyOS。由於HarmonyOS在相容Android上有特殊要求，如果APP應用是用Android API開發，開發者可以直接使用Android的SDK。

但如果APP用了HarmonyOS的API開發，就不能用Android的SDK而需要使用HarmonyOS版本的SDK。

為了方便開發者在HarmonyOS的相應裝置中進行LBS服務的開發，高德開放平臺率先進行了HarmonyOS適配，首批適配範圍包括地圖和搜尋SDK，支援嵌入搭載HarmonyOS的手機、Pad及其他智慧終端裝置。

二、HarmonyOS地圖SDK特性介紹

與高德開放平臺Android地圖SDK平滑切換

• 已整合高德開放平臺Android地圖SDK的開發者可無縫切換到HarmonyOS地圖SDK，無額外開發量。HarmonyOS與Android系統間的介面變化由高德開放平臺SDK適配層消化，SDK對外介面保持不變。

• 高德底層引擎對接HarmonyOS NDK，上層程式碼全面對接HarmonyOS SDK，所有系統介面均使用HarmonyOS API。

繼承高德開放平臺Android/iOS地圖SDK功能亮點

• 開發者可以透過高德開放平臺API和SDK，輕鬆完成地圖的構建工作，將地圖精緻地呈現在您的應用中。地圖SDK不僅提供豐富的地圖覆蓋物繪製能力，也支援搜尋、多種路徑規劃、座標轉換、距離測量、面積計算等功能。

• 適配HarmonyOS後的地圖SDK依舊支援與自定義地圖SaaS平臺等周邊工具配合使用，開發者可以在平臺中定製區域面、建築物、水系、天空、道路、標註、行政邊界共7大類40餘種地圖元素，靈活設計心儀的地圖樣式。更多地圖SDK基礎能力、自定義、視覺化能力詳情請參考高德開放平臺官網。

HarmonyOS版地圖SDK整體框架

HarmonyOS和Android系統差異很大，幾乎所有的API都有調整，不少API都調整了實現方案，所以不能透過改包名來實現適配。我們將原生SDK中所有呼叫Android的程式碼均切換為適配層，在適配層將SDK的介面一一適配到HarmonyOS介面。

HarmonyOS版地圖SDK整體框架大致如下：

三、如何整合-從零開始

第一步 搭建HarmonyOS開發環境

完成DevEco Studio安裝、環境配置和工程建立，參考HarmonyOS官網說明： https://developer.harmonyos.com/cn/docs/documentation/doc-guides/start-overview-000000000002960

第二步 配置應用的簽名資訊

應用工程建立完成後，需要配置簽名資訊，才可以使用真機除錯和釋出應用。

第三步 獲取應用的appId

配置完簽名資訊之後，就可以獲取當前應用的appId了，這個appId主要用於申請高德的apiKey，請確定最終釋出應用的appId，防止最終高德SDK鑑權失敗。

透過程式碼獲取應用的appId方式如下：

getApplicationContext().getBundleManager().getBundleInfo(getBundleName(), 0).getAppId()

注意：目前透過DevEco Studio連線雲真機獲取到的appId不全，只獲取到了"包名_", 使用雲真機除錯高德地圖SDK時會導致鑑權不透過。正確的appId形式為："包名_簽名資訊"， 例如：com.amap.demo_BGtGgVB3ASqU7XXXXV2/zhoYh6tFQHAd5DASWVTEAgvZfzrEGljjs=

第四步 在高德開放平臺官網控制檯申請API Key

建立新應用

從開放平臺官網右上角入口-控制檯，建立一個新應用。如果您之前已經建立過應用，可直接跳過這個步驟。

新增新Key

在建立的應用上點選"新增新Key"按鈕，在彈出的對話方塊中，依次：輸入應用名名稱，選擇繫結的服務為“Harmony平臺SDK”，輸入AppID，如下圖所示：

需要注意：1個Key只能用於一個應用（多渠道安裝包屬於多個應用），1個Key在多個應用上使用會出現服務呼叫失敗。

在閱讀完高德地圖API服務條款後，勾選此選項，點選“提交”，完成Key的申請，此時您可以在所建立的應用下面看到剛申請的Key了。

第五步 在程式碼中設定申請的Key

請使用API的方式將申請的高德API Key設定給高德地圖SDK。

/**
 * 動態設定apiKey。
 *
 * @param apiKey 在高德官網上申請的apiKey。 */MapsInitializer.setApiKey(String apiKey)

注意：請確保在呼叫任何高德地圖SDK的介面之前將API Key設定給高德地圖SDK，建議放到Application的初始化之中。

完成以上5步之後，就可以愉快的使用HarmonyOS版高德地圖SDK了。

四、如何使用-建立地圖

使用地圖SDK之前，需要在config.json檔案中進行相關許可權設定，確保地圖功能可以正常使用。

第一步 配置config.json

首先，宣告許可權。

..."reqPermissions": [
      {        "usedScene": {          "ability": [            "com.example.harmonysearchsdk.MainAbility"
          ],          "when": "always"
        },        "reason": "request internet",        "name": "ohos.permission.INTERNET"
      }
    ]
...

第二步 向工程中新增地圖開發包

將har包放入libs目錄下，依次新增依賴。

dependencies {
    implementation files("libs/xxx.har")    //...}

或者直接使用引入libs下所有har包的方式：

dependencies {
  implementation fileTree(dir: 'libs', include: ['*.jar', '*.har'])    //...}

第三步 初始化地圖容器

設定Key

獲取Key方式請參考上方“從零開始”章節第四步。

MapsInitializer.setApiKey("您的key");

建立MapView

public class BasicMapDemoSlice extends Ability {    private MapView mapView;
    @Override    protected void onStart(Intent intent) {        super.onStart(intent);
        initMapView();
    }    private void initMapView() {
        mapView = new MapView(this);
        mapView.onCreate(null);
        mapView.onResume();
        DirectionalLayout.LayoutConfig config = new DirectionalLayout.LayoutConfig(
                DirectionalLayout.LayoutConfig.MATCH_PARENT, DirectionalLayout.LayoutConfig.MATCH_PARENT);
        mapView.setLayoutConfig(config);        super.setUIContent(mapView);
    }
    @Override    protected void onStop() {        super.onStop();        if (mapView != null) {
            mapView.onDestroy();
        }
    }
}

初始化地圖並獲取AMap物件

AMap aMap = mapView.getMap();
aMap.setOnMapLoadedListener(new AMap.OnMapLoadedListener() {
    @Override    public void onMapLoaded() {    // todo    }
});

至此就可以看到地圖展示，並且拿到AMap物件後，就可以往地圖上新增點線面等覆蓋物了。