Как я писал враппер для Яндекс Карт на KMP. Часть 1

Вступление

Приветствую! Я Владимир Ненашкин (@vollllodya), сейчас работаю на позиции KMP разработчика в компании EllowTech ^{[ссылка уд. мод.].} Мы разрабатываем по большей части мультиплатформенные приложения на KMP, однако в этой статье расскажу про личный опыт написания библиотеки как пет-проекта.

В разработке совсем другого приватного пет-проекта понадобилось отображать объекты на карте. Только готового и поддерживаемого решения для работы с картой пока не было. Наиболее актуальным решением для нашей страны был выбран MapKit SDK от Яндекс Карт. В самом пет проекте до какого-то момента писался модуль для работы с картой и реализацией в платформенных исходниках, правда быстро подошел к тому, что дальше расширять доступный функционал становится всё труднее и труднее.

Как решение выбрал приостановить разработку того проекта и переписать этот модуль как отдельную библиотеку с сохранением официального API Яндекс Карт. И вот в этой статей я пишу про промежуточные итоги разработки библиотеки и трудности с которыми пришлось столкнуться.

Термины

• Платформенный код – код в androidMain, iosMain.

• Common код – код в commonMain.

• Платформенный тип – тип, используемый в платформенном коде. Пример: com.yandex.mapkit.map.Map, YMKMap, UIColor, View и т.д.

• Нативные вызовы – вызовы нативного коде. Например: используемый под капотом MapKit SDK на Android как NativeObject.

Требования

• Покрытие lite версии MapKit SDK.

  • Конечно, желательно покрыть всё, однако время ограниченный ресурс, поэтому первостпенную важность имеют: инициализация SDK, управление картой, управление камерой, добавление объектов на карту, работа с местоположением, самые простые элементы настройки карты.

• Сохранение официального API.

  • Если метод находится в объекте Map, то у враппера он там и должен находиться.

  • Если имя пакета имеет суффикс .mapkit.map.user_location – то он таким и остаётся. Меняется только часть com.yandex на ru.sulgik.

  • Если названия в iOS и Android версиях SDK отличаются, то выбрать наиболее релевантное. iOS – YMKLogoAlignment, Android – Alignment, выбрано – LogoAlignment; iOS – YMKMap, android – Map, выбрано – Map.

  • Всё в iOS версии SDK имеет префикс YMK, его не используем

• Конвертация объектов из SDK в библиотечные и обратно. Все поддерживаетмые объекты должны иметь toNative() и toCommon() .

• Поддержка Compose Multiplatform

  • Отрисовка карты на всех платформах.

  • Управление картой как взаимодействие с SDK. Controller API

  • Управление картой как полноценный Composable UI компонент, использование контекста композиции для добавления объектов и управления состоянием карты. States API. ?

  • Composable контент как ImageProvider ?

• Мультиплатформенные ресурсы

  • moko-resources (тот пет проект писался до появления compose multiplatform resources). Используязование как с compose так и без.

  • Compose Multiplatform Resources

Список требований вышел достаточно обширным из чего получился и обширный фронт работ.

Начало работы

Я уже работал с Yandex MapKit SDK и примерно понимал, что у меня должно получится и что для этого потребуется. Огромный плюс, в том числе из-за него возможно создание библиотеки в формате враппера, – это относительная схожесть API на Android и iOS. Да, есть расхождения, где используются конкретно платформенные фичи. Например: у некоторых MapObject есть параметр цвета, на iOS – это UIColor, на Android – Int, и др.

Главная цель, это практически бесшовный переход с официального SDK на мою библиотеку. Это обеспечивается сменой пакета com.yandex.mapkit на ru.sulgik.mapkit и сохранением API по большей части.

Второй момент – это присутствие deprecated API. Такие части я решил не переносить, поскольку оно, как не сложно догадаться, deprecated, и: возможно, удалится ещё до выхода моей библиотеки.

Третья особенность – это подключение зависимости. Библиотека является мультиплатформенной и на Android мы просто подключаем зависимость официальной MapKit SDK.

sourceSets {     androidMain.dependencies {         api("com.yandex.android:maps.mobile:4.7.0-lite")     } }

Однако на iOS у нас используются не исходники на Kotlin. Мы используем наливную iOS библиотеку. Для этого используем cocoapods (ныне “deprecated”).

kotlin {     cocoapods {         ios.deploymentTarget = "15.0"         framework {             baseName = "YandexMapKitKMP"         }         noPodspec()         pod("YandexMapsMobile") {             version = "4.7.0-lite"             packageName = "YandexMapKit"         }     } }

Важно! Этот pod не подтянется транзитивно в проект, использующий мой враппер. Поэтому важно подключить этот pod в своём проекте.

Способы враппинга

Объекты стоит разделить на разные типы и выбирать такой способ враппинга, подходящий именно ему. Для этого стоит обратить внимание на исходники официальной библиотеки

1. Прямой враппинг

Если объект хранит информацию, возвращает её и как-то изменяет, то стоит выбрать это метод.

Приведу пример: у нас есть тип Map (документация). У него есть геттеры, сеттеры и методы. Мы делаем обёртку и хранив в ней ссылку на наивный объект, вызывая методы у нативного объекта и конвертируя данные, если требуется.

Посмотрим на common код враппер.

public expect class Map {     public val cameraPosition: CameraPosition     public var isNightModeEnabled: Boolean     public fun set2DMode(enable: Boolean)     public fun wipe()     public fun move(cameraPosition: CameraPosition)     // ... }

• Если есть только геттер – то это val с “врапнутым” типом

• Геттер и сеттер – var

• Только сеттер – сеттер метод

• Методы остаются методами, только параметры и возвращаемые значения тоже враппятся

Теперь посмотрим на этот тип в платформенном коде.

Android

public actual class Map internal constructor(private val nativeMap: NativeMap) {     public fun toNative(): NativeMap {         return nativeMap     }     public actual val cameraPosition: CameraPosition         get() = nativeMap.cameraPosition.toCommon()     public actual var isNightModeEnabled: Boolean         get() = nativeMap.isNightModeEnabled         set(value) {             nativeMap.isNightModeEnabled = value         }     public actual fun set2DMode(enable: Boolean) {         nativeMap.set2DMode(enable)     }     public actual fun wipe() {         nativeMap.wipe()     }     public actual fun move(cameraPosition: CameraPosition) {         nativeMap.move(cameraPosition.toNative())     }     // ... }  public fun NativeMap.toCommon(): Map {     return Map(this) }

iOS:

public actual class Map internal constructor(private val nativeMap: NativeMap) {     public fun toNative(): NativeMap {         return nativeMap     }     public actual val cameraPosition: CameraPosition         get() = nativeMap.cameraPosition.toCommon()     public actual var isNightModeEnabled: Boolean         get() = nativeMap.isNightModeEnabled()         set(value) {             nativeMap.setNightModeEnabled(value)         }     public actual fun set2DMode(enable: Boolean) {         nativeMap.set2DModeWithEnable(enable)     }     public actual fun wipe() {         nativeMap.wipe()     }     public actual fun move(cameraPosition: CameraPosition) {         nativeMap.moveWithCameraPosition(cameraPosition.toNative())     }     // ... }  public fun NativeMap.toCommon(): Map {     return Map(this) }

Тут и появляются toNative() и toCommon() функции конвертами, доступные только в платформенных исходиниках.

Можно заметить, что используется некий NativeMap, это просто import alias для платформенных типов.

import YandexMapKit.YMKMap as NativeMap // iOS import com.yandex.mapkit.map.Map as NativeMap // Android

data class с конвертерами

Этот способ применим, есть тип простой, имеет лишь геттеры, конструктор и не использует обращение к нативному коду. Рассмотрим пример с Circle (документация)

common код.

public data class Circle(     val center: Point,     val radius: Float, )

В платформенном коде мы лишь конвертируем набивные типы в common и обратно. Но пишем мы это в двух вариантах для двух платформ.

public fun Circle.toNative(): NativeCircle {     return NativeCircle(center.toNative(), radius) }  public fun NativeCircle.toCommon(): Circle {     return Circle(center.toCommon(), radius) }

Когда не применям? Рассмотрим другой пример из того же пакета geometry – Polygon (документация).

Если посмотрим на исходники андроида, то найдём там и syncronized, и обращение к наивному коду при первом обращении. А нам разве нужно синхронизация и нативные вызовы при работе toCommon()?

@NonNull public synchronized LinearRing getOuterRing() {     if (!this.outerRing__is_initialized) {         this.outerRing = this.getOuterRing__Native();         this.outerRing__is_initialized = true;     }      return this.outerRing; } 

Поэтому используем прямой враппинг с одним лишь отличием – наличием secondary конструктора у expect в common коде.

public expect class Polygon {      public constructor(outerRing: LinearRing, innerRing: List<LinearRing>)      public val outerRing: LinearRing      public val innerRing: List<LinearRing>  } 

И уже в платформенном коде мы будем использовать платформенный тип и оставим ленивую инициализацию при конвертации платформенного типа.

public actual class Polygon internal constructor(private val nativePolygon: NativePolygon) {      public fun toNative(): NativePolygon {         return nativePolygon     }      override fun toString(): String {         return "Polygon(outerRing=$outerRing, innerRing=${innerRing.linearRingsListToString()})"     }      public actual constructor(          outerRing: LinearRing,         innerRing: List<LinearRing>,     ) : this(NativePolygon(outerRing.toNative(), innerRing.map { it.toNative() }))      public actual val outerRing: LinearRing by lazy { nativePolygon.outerRing.toCommon() }     public actual val innerRing: List<LinearRing> by lazy { nativePolygon.innerRings.map { it.toCommon() } }  }  public fun NativePolygon.toCommon(): Polygon {     return Polygon(this) }

Callbacks и listeners

Первый способ. Самая интересная часть это работа с колбеками. Важно понимать, что SDK держит слабые ссылки на все объекты такого типа, следовательно при враппинге мы должны оставлять возможность сохранять строгую ссылку пользователям, т.е. невозможен такой код:

// Common code public expect abstract class CameraListener() {     public abstract fun onCameraPositionChanged(         map: Map,         cameraPosition: CameraPosition,         cameraUpdateReason: CameraUpdateReason,         finished: Boolean,     ) }  // Android code. Not valid public fun CameraListener.toNative(): CameraListener {     return object : NativeCameraListener {         override fun onCameraPositionChanged(             map: NativeMap,             cameraPosition: NativeCameraPosition,             reason: NativeCameraUpdateReason,             finished: Boolean,         ) {             onCameraPositionChanged(map.toCommon(), cameraPosition.toCommon(), reason.toCommon(), finished)         }     } }  // Android code public actual class Map internal constructor(private val nativeMap: NativeMap) {     public actual fun addCameraListener(cameraListener: CameraListener) {         nativeMap.addCameraListener(cameraListener.toNative())     }     // ... } 

В момент вызова addCameraListener создаётся новый объект платформенного слушателя и никто её не сохраняет, объект числится и common слушатель никогда не сработает. Даже если нам повезёт и GC не дойдёт до этой ссылки, то как быть с removeCameraListener? Тут же toNative() создаёт новую ссылку.

Второй вариант. А если просто иметь expect класс и в платформенном коде имплементировать платформенный тип слушателя. Тут напишу сразу про iOS код, с Android всё хорошо

// Common code public expect abstract class CameraListener() {     public abstract fun onCameraPositionChanged(         map: Map,         cameraPosition: CameraPosition,         cameraUpdateReason: CameraUpdateReason,         finished: Boolean,     ) }  // iOS code. Not valid public actual abstract class CameraListener actual constructor() : NativeCameraListener,     NSObject() {      override fun onCameraPositionChangedWithMap(         map: NativeMap,         cameraPosition: NativeCameraPosition,         cameraUpdateReason: NativeCameraUpdateReason,         finished: Boolean,     ) {         onCameraPositionChanged(             map.toCommon(),             cameraPosition.toCommon(),             cameraUpdateReason.toCommon(),             finished         )     }      public fun toNative(): NativeCameraListener {         return this     }      public actual abstract fun onCameraPositionChanged(         map: Map,         cameraPosition: CameraPosition,         cameraUpdateReason: CameraUpdateReason,         finished: Boolean,     ) }

IDE не ругается, всё казалось бы хорошо, однако пытаемся собрать под iOS таргет и получаем ошибку компиляции (подробнее)

Non-final Kotlin subclasses of Objective-C classes are not yet supported

И этот способ отпадает. Попробуем следующий.

Третий метод. Храним платформенный листенер в платформенной реализации expect класса.

// Common code public expect abstract class CameraListener() {     public abstract fun onCameraPositionChanged(         map: Map,         cameraPosition: CameraPosition,         cameraUpdateReason: CameraUpdateReason,         finished: Boolean,     ) }  // iOS code. Valid public actual abstract class CameraListener actual constructor() {      private val nativeListener = object : NativeCameraListener, NSObject() {         override fun onCameraPositionChangedWithMap(             map: NativeMap,             cameraPosition: NativeCameraPosition,             cameraUpdateReason: NativeCameraUpdateReason,             finished: Boolean,         ) {             onCameraPositionChanged(                 map.toCommon(),                 cameraPosition.toCommon(),                 cameraUpdateReason.toCommon(),                 finished             )         }     }      public fun toNative(): NativeCameraListener {         return nativeListener     }       public actual abstract fun onCameraPositionChanged(         map: Map,         cameraPosition: CameraPosition,         cameraUpdateReason: CameraUpdateReason,         finished: Boolean,     ) } // iOS code public actual class Map internal constructor(private val nativeMap: NativeMap) {     public actual fun addCameraListener(cameraListener: CameraListener) {         nativeMap.addCameraListenerWithCameraListener(cameraListener.toNative())     }     // ... }

Теперь мы можем создавать слушатели в common коде и платформенный слушатель не почистится и останется возможность выполнять removeCameraListener.

Почему нет toCommon()? А для чего он нужен у колбеков? Такой метод практически не имеет смысла, а если требуется, это значит, что нужно написать код по-другому, чтобы обойтись без него

Трудности

Конечно, если рассматривать отдельные кейсы, да ещё и сразу с решением, то всё выглядит просто. Однако есть и сложные ситуации для враппинга, которые стоит рассматривать отдельно

Цвета

На iOS всё относительно просто. MapKit использует платформенный UIColor. Он задокументирован и готовые решения для преобразования. В common коде просто создаётся value класс Color, который хранит значение в ARGB32 формате.

public data class Color private constructor(internal val value: Int) {     public companion object {         public fun fromArgb(argb: Int): Color {             return Color(value = argb)         }     } } public fun Color.toArgb(): Int {     return value }

Для простоты восприятия создаются методы для создания и преобразования, из которых можно сразу понять, из чего можно получить валидный Color и во что можно его преобразовать. Но зачем? Первая причина – пользователю так понятнее, вторая – официальная документация и реализация на Android. Читаем её для метода CircleMapObject.getStrokeColor(): Int (документация):

Sets the stroke color.

Setting the stroke color to any transparent color (for example, RGBA code 0x00000000) effectively disables the stroke. default: 0x0066FFFF 

Сразу видим “sets” в документации к геттеру, ну все ошибаются. Читаем дальше RGBA код. Что, кажется, означает RGBA32 (Википедия)

У нас получается что в этом Int хранится цвет в достаточно непривычном формате, ну, наверное, у них была причина на это. В подтверждении этой теории нам даётся default: 0x0066FFFF. Если бы это был более привычный нам ARGB – то это по факту прозрачный цвет, alpha = 0F.

Почему это важно? Мы хотим создавать цвет в common коде и получать один результат на выходе. Для этого нужны конвертеры в UIColor на iOS и в Int на Android.

// iOS code public fun Color.toNative(): UIColor {     return UIColor.colorWithRed(         red = ((value shr 16) and 0xff) / 255.0,         green = ((value shr 8) and 0xff) / 255.0,         blue = (value and 0xff) / 255.0,         alpha = ((value shr 24) and 0xff) / 255.0,     ) }  // iOS code public fun UIColor.toCommon(): Color {     val red = (CIColor.red * 255).toInt()     val green = (CIColor.green * 255).toInt()     val blue = (CIColor.blue * 255).toInt()     val alpha = (CIColor.alpha * 255).toInt()     return Color.fromArgb((alpha shl 24) or (red shl 16) or (green shl 8) or (blue)) }

А на Android… А ничего там не нужно! Почему, спросите вы? В MapKit не используется никакой RGBA32! Это выяснилось эмперическим путём. Да, сначала были конвертеры с перестановкой битов альфы из начала в конец и обратно, но получался совсем не тот цвет… В итоге на Android нам хватит toArgb() и fromArgb() методов.

public actual class CircleMapObject internal constructor(private val nativeCircleMapObject: NativeCircleMapObject) :     MapObject(nativeCircleMapObject) {     public actual var strokeColor: Color         get() = nativeCircleMapObject.strokeColor.toColor()         set(value) {             nativeCircleMapObject.strokeColor = value.toArgb()     // ... } internal fun Int.toColor(): Color {     return Color.fromArgb(this) }

Казалось бы, зачем они используют такой непривычный формат RGBA32, но ответ достаточно прост – они его и не используют, просто говорят, что он есть.

PointF

Этот тип присутствует только на Android, на iOS он выражается другим способом. Присутствует он, например, в IconStyle (документация Android) (документация iOS)

// common code public data class IconStyle(     val anchor: PointF? = null,     val rotationType: RotationType? = RotationType.NO_ROTATION,     val zIndex: Float? = null,     val flat: Boolean? = false,     val isVisible: Boolean? = true,     val scale: Float? = 1f,     val tappableArea: Rect? = null, )

На Android это платформенный android.graphics.PointF, на iOS NSValue.

Для Android всё очевидно, просто конвертируем

public fun PointF.toNative(): NativePointF {     return NativePointF(x, y) }  public fun NativePointF.toCommon(): PointF {     return PointF(x, y) }

Но на iOS нужно научиться распаковывать NSValue в PointF

internal fun NSValue.toPointF(): PointF {     return CGPointValue.useContents { toCommon() } }

У NSValue берётся CGPointValue, поскольку мы уверены, что это он. Мы получаем тип CValue<CGPoint>, его дальге “распаковываем через“ useContents{} он создаёт временную копию хранимого объекта и её уже можно безопасно передавать. this внутри это блока и является искомый CGPoint, его преобразовываем как и PointF в Android исходниках.

public fun CGPoint.toCommon(): PointF {     return PointF(x.toFloat(), y.toFloat()) }

Дальше чтобы сконвертировать обратно в CGPoint мы можем лишь создать через Make функцию и получаем CValue<CGPoint>

public fun PointF.toNative(): CValue<CGPoint> {     return CGPointMake(x.toDouble(), y.toDouble()) }

Заключение

Для враппинга применяются различные приёмы, выбор зависит от типа. Я показал несколько вариантов, и если вы знаете ещё, то можете написать про это в комментариях или даже поучаствовать в поддержке библиотеки.

Но, кажись, в требованиях была прописана поддержка Compose Multiplatform. И я вам скажу, что она есть, и обширная. Но это история для второй статьи на эту тему, эта уже затянулась и совсем о другом. Как только следующая часть выйдет, здесь появится ссылка на неё.

Эта статья написана для тех, кто хочет разрабатывать на KMP, или просто интересуется этой технологией. Цель – поделиться личным опытом, который, как мне кажется, достаточно нестандартный и относительно интересный. Ну и конечно же поделиться свой библиотекой.

Найти код этой библиотеку можно у меня на GitHub а документацию на сайте. Если хотите помочь проекту, то всегда буду рад, создавайте pull requests, открывайте issue и ставьте звёздочки.

Я никак не связан с Яндекс. Я лишь автор библиотеки, позволяющий использовать их разработку, MapKit SDK, в «экосистеме» KMP проектов. Все api key, необходимые для работы с SDK получаются как и с официальной библиотекой, на сайте Яндекса. Я не претендую ни на ваши api ключи, ни на деньги с покупки тарифов Яндексу. Даже возможно, что эта библиотека привлечет Яндексу некоторое количество клиентов, заинтересованных в разработке под KMP.