Android

Подключение

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

allprojects {     
    repositories {
         maven {
             url = uri("https://maven.pkg.github.com/GEORS/MAPS-SDK-ANDROID")
            credentials {
                username = "GITHUB_USER"
                password = "GITHUB_TOKEN"
            }
} } }

GITHUB_TOKEN можно найти по ссылке → Personal Access Tokens → Tokens (Classic).

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

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

где x.x.x — версия SDK.

Рекомендуется использовать самую актуальную версию SDK. Релизные версии SDK имеют нумерацию 1.0.x

Последнюю версию SDK можно найти по адресу: https://github.com/geors?tab=packages&repo_name=maps-sdk-android

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

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

class MapViewConfig(
    val apiKey: String, // уникальный ключ для предоставления доступа к работе с SDK
    val center: MapLocation, // точка начального расположения карты в формате lat, lon
    val zoomLevel: Float, // начальное значение уровня zoom для карты
    val style: MapStyle // стиль карты, может быть выбран из соответствующего enum
)

установить его нужно следующим образом:

MapGlobalConfig.setMapGlobalConfig(MapViewConfig(...))

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

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

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

<FrameLayout
    android:id="@+id/mainLayout"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    ...>
 
    <ru.rustore.geo.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.rustore.geo.views.MapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
 
    <ru.rustore.geo.views.ZoomView
        android:id="@+id/zoomView"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        ...
        custom:mapView="@+id/mapView" />
 
    <ru.rustore.geo.views.CompassView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        ...
        custom:mapView="@+id/mapView" />
 
    <ru.rustore.geo.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.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?,
    val longitude: Double?,
    val speed: Float?,
    val bearing: Float?
)

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

fun zoomIn(step: Float = .5f, animated: Boolean = true) // увеличить карту, step - значение шага,
        // на который будет увеличена карта
fun zoomOut(step: Float = .5f, animated: Boolean = true) // уменьшить карту, step - значение шага,
        // на который будет уменьшена карта
fun setBearing(bearing: Float, animated: Boolean = true) // выставляет направление карты, bearing
        // лежит в полуинтервале [0, 360)
fun setZoom(zoom: Float, animated: Boolean = true) // выставляет уровень масштаба карты, zoom лежит
        // в полуинтервале (0, 20]
fun addMarker(marker: MarkerEntity) // добавить маркер на карту, где MarkerEntity - модель маркера,
        // id - уникальный для каждого маркера идентификатор, coordinates - координаты точки, к которой
        // будет привязан маркер (учитывается только latitude и longitude, остальные null) и image - одно
        // из значений enum MarkerImage
 
fun addMarker(markers: List<MarkerEntity>) // добавить список маркеров на карту
 
fun removeMarker(id: String) // удалить маркер с указанным идентификатором
 
fun removeAllMarkers() // удалить все маркеры с карты
 
fun showPopUp(markerId: String, content: String) // показать PopUp окно над маркером, markerId - идентификатор
        // маркера, к которому будет привязано окно; content - html строка, текст которой будет
        // отображен в окне
 
fun hidePopUp(markerId: String) // скрыть PopUp окно для соответствующего идентификатору маркера
 
fun setOnMarkerClickListener(onCLickListener: (id: String, location: MapLocation) -> Unit) // добавить
        // метод-callback, который будет вызван, когда пользователь сделает клик на один из маркеров
        // id - идентификатор маркера, на который кликнул пользователь, location - координаты, которые
        // соответствуют маркеру (учитывается только latitude и longitude, остальные null)
 
fun removeMarkerClickListener() // удалить метод-callback, отвечающий за клик по маркеру
 
fun moveMarker(id: String, location: MapLocation, animated: Boolean, duration: Double) // задать перемещение
        // маркеру с соответствующим id в позицию location. animated - необходима ли анимация перемещения маркера
        // duration - длительность анимации перемещения
 
fun addOnErrorListener(onErrorListener: (error: MapError) -> Unit) // добавить коллбэк, который
        // будет вызываться в случае возникновения тех или иных ошибок в сдк. Все ошибки являются
        // наследниками класса MapError
 
fun setCenter(center: MapLocation, animated: Boolean) // переместить карту, чтобы центр экрана
        // совпадал с параметром center (учитывается только latitude и longitude, остальные null)
 
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) // установить метод-коллбэк, отвечающий за событие клика по карте
 
fun setOnMapLongClickListener(onClickListener: (location: MapLocation, screenLocation: ScreenLocation) -> Unit) // установить метод-коллбэк, отвечающий за событие длительного клика по карте
 
fun addLayer(layer: Layer) // добавить новый слой на карту
 
fun addMapDataSource(source: MapDataSource) // добавить новый источник данных для карты
 
fun removeSource(sourceId: String) // удалить источник данных по id
 
fun removeLayer(layerId: String) // удалить слой с карты по id
 
fun addCluster(cluster: Cluster) // добавить кластер на карту, где в объекте Cluster содержатся:
          //    id - идентификатор кластера, markers - список объектов маркеров, radius - радиус кластера в метрах,
          // textColor - цвет текста в hex ("#ff0000"), backgroundColor - цвет фона в hex ("#ffffff")
 
fun removeCluster(id: String) // удалить кластер по айди

С помощью этих методов можно вручную управлять картой, независимо от предоставленных SDK контролов. Все методы SDK необходимо вызывать в 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: 5.0 (min sdk 21)

Обновлено 23 января 2023 г.