騰訊位置服務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/f...
具體解決方法爲：在main.dart文件中的main方法中，須要在runApp()前顯式調用以下代碼：

WidgetsFlutterBinding.ensureInitialized();

總結

本文主要介紹了騰訊地圖SDK Flutter插件項目的構建、地圖實例加載、demo呈現，對地圖基礎功能性接口的封裝細節，將會在後續文章持續講解。