Android
Подключение
Для подключения Maps SDK необходимо добавить в главный gradle файл проекта ссылку на maven репозиторий:
allprojects { repositories { maven { 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)