騰訊位置服務Flutter業務實踐——地圖SDK Flutter外掛實現(一)

前言

Flutter 作為目前通用的業界跨平臺解決方案，開闢了一套全新的設計理念，通過自研的 UI 框架，支援高效構建多端平臺上的應用，同時保持著原生應用一樣的高效能。 在Flutter專案開發過程中，對外掛的開發和複用能夠提高開發效率，降低工程的耦合度。Flutter開發者可以引入對應外掛就可以為專案快速整合相關能力，從而專注於具體業務功能的實現。 而在Flutter專案開發過程中面對通用業務邏輯拆分、或者需要對原生能力封裝等場景時，開發者需要開發新的元件。

為減少開發者同時開發Android和iOS應用的成本，提升開發效率，降低整合地圖SDK的門檻，騰訊位置服務團隊也計劃於業務實踐中基於原生地圖SDK能力封裝一套地圖Flutter外掛，支援Flutter開發者跨平臺呼叫地圖SDK介面。 筆者在2019年實習期間，曾基於當時的最新版本4.2.4的Android地圖SDK，將地圖SDK中一些常用的基礎的地圖操作功能封裝，構建了一套Android端的地圖SDK Flutter外掛。

現如今，地圖SDK已經迭代到了4.4.0版本，筆者也將地圖Flutter外掛進行了一次相關版本升級。 本篇文章將介紹地圖Flutter外掛專案的構建、地圖例項的載入以及demo示例呈現。對於地圖基礎操作的功能封裝細節將在後續文章中進行詳細講解說明。

地圖Flutter外掛專案的構建

地圖Flutter外掛專案結構

地圖Flutter外掛專案構架的整體結構如下圖所示：

android/ios目錄：原生程式碼。對應為Android/iOS Flutter外掛目錄。
lib目錄：Dart 程式碼。Flutter開發者將會使用這裡的Flutter外掛實現的介面。
example目錄：地圖SDK的demo程式。用於驗證Flutter外掛的可用性的使用示例。

地圖Flutter外掛依賴配置項

Android端的Flutter外掛配置項與官閘道器於Android地圖SDK的配置說明類似，需要配置android目錄下的兩個檔案：build.gradle、AndroidManifest.xml。 其中Android端的Flutter外掛的包名為com.tencent.tencentmap，AndroidManifest.xml檔案配置如下：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  package="com.tencent.tencentmap">
    <!-- 騰訊地圖 sdk 要求的許可權(開始) -->
    <!-- 訪問網路獲取地圖服務 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- 檢查網路可用性 -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- 訪問WiFi狀態 -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <!-- 需要外部儲存寫許可權用於儲存地圖快取 -->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <!-- 獲取 device id 辨別裝置 -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <!-- 獲取日誌讀取許可權，幫助我們提高地圖 sdk 穩定性 -->
    <uses-permission android:name="android.permission.READ_LOGS" />
    <!-- 騰訊地圖 sdk 要求的許可權(結束) -->


    <!-- 騰訊定位 sdk 要求的許可權  (開始) -->
    <!-- 通過GPS得到精確位置 -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <!-- 通過網路得到粗略位置 -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <!-- 訪問網路. 某些位置資訊需要從網路伺服器獲取 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- 訪問WiFi狀態. 需要WiFi資訊用於網路定位 -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <!-- 修改WiFi狀態. 發起WiFi掃描, 需要WiFi資訊用於網路定位 -->
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <!-- 訪問網路狀態, 檢測網路的可用性. 需要網路運營商相關資訊用於網路定位 -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- 訪問網路的變化, 需要某些資訊用於網路定位 -->
    <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
    <!-- 訪問手機當前狀態, 需要device id用於網路定位 -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

    <!-- 騰訊定位 sdk 要求的許可權 (結束) -->
    <application>

        <!-- 如果您key確認無誤，卻依然授權沒有通過，請檢查您的key的白名單配置 -->
        <meta-data
            android:name="TencentMapSDK"
            android:value="Your key"/>
    </application>
</manifest>
複製程式碼

本文使用的Android端地圖SDK版本為4.4.0。同時，本文Flutter外掛的實現語言是基於Kotlin實現。build.gradle的依賴配置項如下：

dependencies {
    implementation 'com.android.support:appcompat-v7:27.1.1'
    implementation 'com.tencent.map:tencent-map-vector-sdk:4.4.0'
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
    compile "org.jetbrains.kotlin:kotlin-script-runtime:1.2.71"
}

複製程式碼

地圖Flutter外掛載入地圖例項

Flutter外掛在上層UI Dart端與底層Native SDK端之間起到了一層橋接的作用。 Flutter端與Native端之間通訊的流程如下圖所示：

Flutter 跟Native程式碼可以通過 MethodChannel 進行通訊。客戶端通過 MethodChannel 將方法呼叫和引數發生給服務端，服務端也通過 MethodChannel 接收相關的資料。 因此，在Flutter外掛開發中，MethodChannel與EventChannel是兩個不可避免用到的類。 用比較通俗的語言來解釋這兩個類的功能：

MethodChannel的作用是傳遞方法呼叫，例如在flutter端呼叫native端的方法或native端呼叫flutter端的方法。MethodChannel主要用於方法呼叫。

EventChannel的作用是傳送訊息，當native層想通知flutter層一些訊息的時候，native層傳送訊息，Flutter接收訊息。EventChannel通常用於資料流通訊。

後續文章將詳細講解MethodChannel與EventChannel在地圖SDK外掛中的使用。 言歸正傳，本文重點要講解使用PlatformView對地圖例項進行載入的流程。 PlatformView的使用方式是與MethodChannel的使用方式類似的，具體的載入地圖例項流程如下：

（1）Native端建立TencentMapView

TencentMapView繼承自PlatformView。 PlatformView為Flutter 1.0版本中的通用元件，區分為Android和iOS。在Android平臺上叫做 AndroidView元件，在iOS平臺，叫UIKitView元件。 因此利用PlatformView構建載入Native SDK中的地圖例項並在PlatformView中維護地圖例項的生命週期。 TencentMapView中也加入了MethodChannel與EventChannel的註冊邏輯，主要用於地圖的介面進行雙端互動，對於這兩部分的說明將在後續文章中進行詳細介紹。 Android端的TencentMapView實現如下：

class TencentMapView(context: Context, private val id: Int, private val activityState: AtomicInteger, tencentMapOptions: TencentMapOptions) : PlatformView, Application.ActivityLifecycleCallbacks{

	// 載入構建地圖例項
    private val mapView = MapView(context, tencentMapOptions)
    private val registrarActivityHashCode: Int = TencentmapPlugin.registrar.activity().hashCode()
    
	// 維護地圖例項生命週期
    fun setup(){
        when(activityState.get()){
            STOPPED -> {
                mapView.onStop()
            }
            RESUMED -> {
                mapView.onResume()
            }
            CREATED -> {
				mapView.onStart()
            }
            DESTROYED -> {
	            mapView.onDestroy()
            }
        }

        // flutter端呼叫地圖native SDK相關功能的MethodChannel
        val mapChannel = MethodChannel(registrar.messenger(), "$mapChannelName$id")
        mapChannel.setMethodCallHandler { methodCall, result ->
            MAP_METHOD_HANDLER[methodCall.method]
                    ?.with(mapView.map)
                    ?.onMethodCall(methodCall, result) ?: result.notImplemented()
        }
        
        // native SDK通知flutter層相關訊息的EventChannel
        val mapEventChannel = EventChannel(registrar.messenger(), "$mapChannelName$id")

    }
}
複製程式碼

（2）在外掛Native層的入口檔案TencentmapPlugin.kt中註冊剛寫好的TencentMapView例項tencentMapView：

@JvmStatic
    fun registerWith(registrar: PluginRegistry.Registrar){
	//將TencentMapView例項註冊到外掛中
	registrar.platformViewRegistry().registerViewFactory("com.tencentmap/map", tencentMapView)
    }
複製程式碼

（3）在Flutter端的dart程式碼使用AndroidView，將AndroidView嵌入到TencentMapView中：

class TencentMapView extends StatelessWidget{
  const TencentMapView({
    this.onTencentMapViewCreated,
});
  final MapCreatedCallback onTencentMapViewCreated;
  @override
  Widget build(BuildContext context) {
    if (defaultTargetPlatform == TargetPlatform.android) {
      return AndroidView(
          viewType: 'com.tencentmap/map',
          onPlatformViewCreated: _onViewCreated,
          creationParams: {

          },
          creationParamsCodec: const StandardMessageCodec(),
      );
    }
  }
}
複製程式碼

這裡要注意的一點是，在Android端和Flutter端註冊的viewType中的字串值必須保持一致，用於唯一標識。在本文中的標識字串為'com.tencentmap/map'，將Flutter端的AndroidView與Native端的TencentMapView建立了關聯。

Flutter外掛對應Demo示例呈現

Demo示例

demo UI採用了Flutter自支援的Material Design風格的一套UI元件。 Flutter demo呼叫地圖SDK展示地圖例項的介面如圖所示：

demo中還實現了地圖基礎操作的相關功能性介面，例如相關覆蓋物的繪製等，示例如下圖所示：

版本升級過程中遇到的小坑

在實際版本升級過程中，原有專案的demo執行起來是白屏，控制檯列印出如下資訊：

[VERBOSE-2:ui_dart_state.cc(157)] Unhandled Exception: ServicesBinding.defaultBinaryMessenger was accessed before the binding was initialized.
If you're running an application and need to access the binary messenger before `runApp()` has been called (for example, during plugin initialization), then you need to explicitly call the `WidgetsFlutterBinding.ensureInitialized()` first.
If you're running a test, you can call the `TestWidgetsFlutterBinding.ensureInitialized()` as the first line in your test's `main()` method to initialize the binding.
#0      defaultBinaryMessenger.<anonymous closure> (package:flutter/src/services/binary_messenger.dart:76:7)
#1      defaultBinaryMessenger (package:flutter/src/services/binary_messenger.dart:89:4)
#2      MethodChannel.binaryMessenger (package:flutter/src/services/platform_channel.dart:140:62)
#3      MethodChannel.invokeMethod (package:flutter/src/services/platform_channel.dart:314:35)
#4      MethodChannel.invokeMapMethod (package:flutter/src/services/platfo<…>
複製程式碼

根據控制檯的輸出資訊，經過查閱相關資料後找到了原因：該問題由Flutter版本升級導致的重大更改引起的：groups.google.com/g/flutter-a… 具體解決方法為：在main.dart檔案中的main方法中，需要在runApp()前顯式呼叫如下程式碼：

WidgetsFlutterBinding.ensureInitialized();
複製程式碼

總結

本文主要介紹了騰訊地圖SDK Flutter外掛專案的構建、地圖例項載入、demo呈現，對地圖基礎功能性介面的封裝細節，將會在後續文章持續講解。