Перейти к основному содержимому

Android

Maps SDK позволяет добавить карту в ваше Android приложение.

Подключение​

Для подключения Maps SDK необходимо добавить в главный gradle-файл проекта ссылку на maven репозиторий.

Пример кода gradle файла с ссылкой на maven-репозиторий

allprojects {
    repositories {
         maven {
           url  'https://maven.pkg.github.com/geors/maps-sdk-android'
           credentials {
               username = "your personal github account"
               password = "yor personal token"
           }
        }
    }
}

Также в gradle-файле модуля, использующего SDK, необходимо прописать зависимость, как показано в примере.

Пример добавления зависимостей

implementation('ru.rustore.geo:mapkit:x.x.x')

Здесь: x.x.x — версия SDK.

Рекомендуется использовать самую свежую версию SDK. Релизные версии SDK имеют нумерацию 1.0.x. Последнюю версию SDK можно найти по адресу: https://github.com/geors/maps-sdk-android/packages/1735721.

Использование​

Необходимо инициализировать глобальные настройки карты до использования других компонентов SDK. Лучший вариант — в наследнике класса Application.

Пример объекта глобальных настроек​

MapViewConfig(
    val apiKey: String, // уникальный ключ для предоставления доступа к
работе с SDK
)

Установить его нужно следующим образом, как показано в примере.

Пример установки

MapGlobalConfig.setMapGlobalConfig(
            MapViewConfig(
                apiKey = apiKey
        )
)

Пример объекта MapStartOptions​

data  class MapStartOptions(
    val center: LatLon, // точка начального расположения карты (учитываются только lat, lon)
    val zoomLevel: Float, // начальное значение уровня масштабирования (zoomLevel)
    val style: MapStyle, // стиль карты, может быть выбран из соответствующего enum или использован свой
    val compassLocationMode: CompassLocationMode, // настройка компаса, может быть выбран из соответствующего enum
    val logoConfig: LogoConfig  // конфигурация логотипа
)

Установить стартовые настройки нужно как показано в примере.

Пример установки

MapGlobalConfig.setMapStartOptions(MapStartOptions(...))

Пример объекта LogoConfig​

data  class LogoConfig(
    val logoAlignment: Alignment, // выравнивание логотипа, может быть выбран из четырех возможных вариантов Alignment: BottomRight, BottomLeft, TopRight, TopLeft
    val logoAdditionalPaddings: AdditionalPaddings  // дополнительные паддинги, с помощью которого можно задать горизонтальные и вертикальные отступы
)

Для работы с SDK предусмотрен ряд классов, реализующих в той или иной форме View:

  • MapView — является основным представлением в SDK, которое отображает карту;
  • ZoomView — используется для отображения контролов + и -, которые можно использовать для приближения и отдаления карты;
  • CurrentLocationView — кнопка для фокусировки карты на текущей позиции пользователя и следования за его положением;
  • CompassView — компонент, отображающий направление физического устройства относительно севера.

Для отображения данных элементов управления необходимо разместить их в XML-файле разметки страницы.

Пример отображения карты​

< FrameLayout
    android:id = "@+id/mainLayout"
    android:layout_width = "match_parent"
    android:layout_height = "match_parent"
    ...>
    < ru.mail.maps.sdk.views.MapView
        android:id = "@+id/mapView"
        android:layout_width = "match_parent"
        android:layout_height = "match_parent" />
</ FrameLayout >

Этого может быть достаточно для работы с картой, если остальные элементы управления не требуются. В противном случае необходимо разместить другие элементы управления в том же самом layout, в котором находится карта. В примере выше это mainLayout. Также необходимо прописать ссылку на карту для каждого из контролов.

Пример с контролами​

< FrameLayout
    xmlns:custom = "http://schemas.android.com/apk/res-auto"
    android:id = "@+id/mainLayout"
    android:layout_width = "match_parent"
    android:layout_height = "match_parent"
    ...>
    < ru.mail.maps.sdk.views.MapView
        android:id = "@+id/mapView"
        android:layout_width = "match_parent"
        android:layout_height = "match_parent" />
    < ru.mail.maps.sdk.views.ZoomView
        android:id = "@+id/zoomView"
        android:layout_width = "wrap_content"
        android:layout_height = "wrap_content"
        ...
        custom:mapView = "@+id/mapView" />
    < ru.mail.maps.sdk.views.CompassView
        android:layout_width = "wrap_content"
        android:layout_height = "wrap_content"
        ...
        custom:mapView = "@+id/mapView" />
    < ru.mail.maps.sdk.views.CurrentLocationView
        android:layout_width = "wrap_content"
        android:layout_height = "wrap_content"
        ...
        custom:mapView = "@+id/mapView" />
</ FrameLayout >

Таким образом все элементы управления будут отображаться поверх карты и будут иметь привязку к ней. Чтобы напрямую вызывать методы карты, необходимо получить сущность Map — вызвать метод getMapAsync у визуального контрола карты.

Пример прямого вызова метода карты​

mapView = findViewById(R.id.mapView)
mapView.getMapAsync { map ->  // тот самый объект Map
    ...
}

Для корректной работы контролов CurrentLocationView и CompassView необходимо передать в объект Map реализацию интерфейса LocationSource.

Пример передачи в объект Map реализации интерфейса LocationSource​

map.setLocationSource(locationSource)

Методы интерфейса LocationSource​

fun activate(listener: (mapLocation: MapLocation) -> Unit)  // используется для старта процесса получения gps фиксов от системы
fun deactivate()  // вызывается при необходимости остановить получение GPS-данных

SDK самостоятельно вызывает методы activate и deactivate, когда это необходимо (согласно внутренней логике). При вызове activate в качестве параметра передается listener, который необходимо вызывать при получении каждого нового GPS-фикса с аргументом типа MapLocation.

Пример

data  class MapLocation(
    val latitude: Double? = null, // широта [-90, 90]
    val longitude: Double? = null, // долгота [-180, 180]
    val speed: Float? = null, // скорость
    val bearing: Float? = null, // направление [0, 360]
    val accuracy: Float? = null, // точность
    val altitude: Double? = null // высота над уровнем моря в метрах
)

Каждое из полей класса может быть null, но для корректной работы необходимо подставлять соответствующие значения, полученные от системы. Помимо метода setLocationSource у объекта Map есть следующие.

Примеры методов объекта Map​

// Изменить координаты центра карты

// За анимацию изменений отвечает аргумент animated, за длительность duration, а за кривую движения камеры cameraCurve

// Указание длительности анимации и кривой движения камеры необязательно fun flyTo(mapLocation: MapLocation, animated: Boolean, durationMs: Int?, cameraCurve: CameraCurve = CameraCurve.Standard()) // Увеличить карту, step — значение шага, на который будет увеличена карта fun zoomIn(step: Float = .5f, animated: Boolean = true ) // Уменьшить карту, step — значение шага, на который будет уменьшена карта fun zoomOut(step: Float = .5f, animated: Boolean = true ) // Выставляет направление карты, bearing лежит в полуинтервале [0, 360) fun setBearing(bearing: Float, animated: Boolean = true ) // Выставляет уровень масштаба карты, zoom лежит в полуинтервале (0, 20] fun setZoom(zoom: Float, animated: Boolean = true )

// Добавляет маркер на карту, где MarkerEntity — модель маркера, id — уникальный для каждого маркера идентификатор, coordinates — координаты точки, к которой будет привязан маркер (учитывается только latitude и longitude, остальные null) и image — одно из значений enum MarkerImage fun addMarker(marker: MarkerEntity)

// Добавить список маркеров на карту fun addMarker(markers: List<MarkerEntity>) // Удалить маркер с указанным идентификатором fun removeMarker(id: String) // Удалить все маркеры с карты fun removeAllMarkers() // Показать PopUp окно над маркером, markerId — идентификатор маркера, к которому будет привязано окно; content — HTML-строка, текст которой будет отображен в окне fun showPopUp(markerId: String, content: String)

// Скрыть PopUp окно для соответствующего идентификатору маркера fun hidePopUp(markerId: String) // Добавить метод-callback, который будет вызван, когда пользователь сделает клик на один из маркеров id — идентификатор маркера, на который кликнул пользователь, location — координаты, которые соответствуют маркеру (учитывается только latitude и longitude, остальные null) fun setOnMarkerClickListener(onCLickListener: (id: String, location: MapLocation) -> Unit) // Удалить метод-callback, отвечающий за клик по маркеру fun removeMarkerClickListener() // Задать перемещение маркеру с соответствующим id в позицию location. animated — необходима ли анимация перемещения маркера duration — длительность анимации перемещения fun moveMarker(id: String, location: MapLocation, animated: Boolean, duration: Double) // Добавить callback, который будет вызываться в случае возникновения тех или иных ошибок в SDK. Все ошибки являются наследниками класса MapError fun addOnErrorListener(onErrorListener: (error: MapError) -> Unit) // Переместить карту, чтобы центр экрана совпадал с параметром center (учитывается только latitude и longitude, остальные null) fun setCenter(center: MapLocation, animated: Boolean) // Изменить стиль карты без необходимости переинициализации fun changeStyle(style: MapStyle) // Разрешить или запретить управление картой жестами fun enableDragPan(enable: Boolean) // Разрешить или запретить изменение масштаба карты и вращение пользователем fun enableZoomRotate(enable: Boolean) // Установить метод-коллбэк, который будет вызван при изменении масштаба карты fun setOnZoomChangedListener(listener: (zoom: Double) -> Unit) // Удалить метод-коллбэк, отвечающий за изменение масштаба карты fun removeZoomChangedListener() // Установить метод-коллбэк, отвечающий за событие клика по карте fun setOnMapClickListener(onClickListener: (location: MapLocation, screenLocation: ScreenLocation) -> Unit)

// Установить метод-callback, отвечающий за событие длительного клика по карте fun setOnMapLongClickListener(onClickListener: (location: MapLocation, screenLocation: ScreenLocation) -> Unit)

// Добавить новый слой на карту fun addLayer(layer: Layer) // Добавить новый источник данных для карты fun addMapDataSource(source: MapDataSource) // Удалить источник данных по id fun removeSource(sourceId: String) // Удалить слой с карты по id fun removeLayer(layerId: String) // Добавить кластер на карту, где в объекте Cluster содержатся: id — идентификатор кластера, markers — список объектов маркеров, radius — радиус кластера в метрах, textColor — цвет текста в HEX ("#ff0000"), backgroundColor — цвет фона в HEX ("#ffffff") fun addCluster(cluster: Cluster) // Удалить кластер по идентификатору fun removeCluster(id: String)

С помощью этих методов можно вручную управлять картой, независимо от предоставленных SDK-контролов. Все методы SDK необходимо вызывать в потоке main. Коллбеки также возвращаются в поток main.

Для использования метода addMapDataSource необходимо создать объект абстрактного типа MapDataSource, который может быть одним из трех конкретных типов: CircleSource, GeojsonSource и PolylineSource.

class CircleSource(
    val id: String, // уникальный id источника данных
    val center: LatLon, // центр круга
    val radius: Double, // радиус в метрах
    val steps: Int  // количество ребер в интерполяции круга
)
class GeojsonSource(
    val id: String, // уникальный id источника данных
    val geojsonData: ByteArray  // GeoJson строка в виде ByteArray
)
class PolylineSource(
    val id: String, // уникальный id источника данных
    val polylineData: String  // закодированная в строку информация о полилинии
)

Ограничения​

Минимально поддерживаемая версия Android: 7.0 (min sdk 24).