騰訊位置服務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版本升級導致的重大更改引起的：https://groups.google.com/g/flutter-announce/c/sHAL2fBtJ1Y/m/mGjrKH3dEwAJ
具體解決方法為：在main.dart檔案中的main方法中，需要在runApp()前顯式呼叫如下代碼：

WidgetsFlutterBinding.ensureInitialized();

總結

本文主要介紹了騰訊地圖SDK Flutter插件專案的構建、地圖實體加載、demo呈現，對地圖基礎功能性介面的封裝細節，將會在后續文章持續講解，