Объекты карты
MapKit SDK позволяет отображать на карте объекты. Все объекты карты настраиваемые: вы можете создавать уникальные пользовательские сценарии с учетом потребностей разработчиков.
Метки
Добавьте пользовательские метки изображения на карту с помощью метода MapObjectCollection.addPlacemark из поля Map.getMapObjects.
Метод создает экземпляр метки на карте, который можно сконфигурировать: указать Point с координатами для метки и иконку с помощью класса ImageProvider, для инициализации которого используются ассеты
val placemark = map.mapObjects.addPlacemark().apply {
geometry = Point(59.935493, 30.327392)
setIcon(ImageProvider.fromResource(this, R.drawable.ic_pin))
}
С помощью приведенного выше кода создается экземпляр класса PlacemarkMapObject, который расширяет интерфейс MapObject.
Интерфейс MapObject представляет каждый видимый объект на карте. Существует несколько способов настройки объектов карты: изменение видимости, разрешение перетаскивания, изменение z-индекса, настройка обработчика событий касания или перетаскивания и многое другое.
Подробнее об этом можно почитать в разделе MapObject.
Настройка текста
Вы можете создавать текстовые надписи рядом с метками. Для этого используйте метод PlacemarkMapObject.setText.
Чтобы изменить внешний вид меток, включая их размер, цвет и положение текста относительно значка, используйте метод TextStyle.
placemark.setText(
"Special place",
TextStyle(/* args */)
)
Стили значков
Вы можете настроить представление значков меток с помощью класса IconStyle. Он позволяет изменять положение привязки, размер, тип поворота, z-индекс, кликабельные области, видимость и плоскость по отношению к карте.
placemark.setIconStyle(
IconStyle().apply {
anchor = PointF(0.5f, 1.0f)
scale = 0.6f
zIndex = 10
}
)
Составные значки
Объедините несколько значков, чтобы создать составной.
-
Создайте значок по умолчанию с помощью MapObjectCollection.addPlacemark.
-
Используйте PlacemarkMapObject.useCompositeIcon, чтобы создать составной значок.
-
Используйте CompositeIcon.setIcon, чтобы добавить новый значок к составному значку.
Полный пример кода для создания составного значка:
val placemark = map.mapObjects.addPlacemark().apply {
geometry = Point(59.935493, 30.327392)
setText(
"Special place",
TextStyle().apply {
size = 10f
placement = Placement.RIGHT
offset = 5f
},
)
}
placemark.useCompositeIcon().apply {
setIcon(
"pin",
ImageProvider.fromResource(this@Activity, R.drawable.ic_dollar_pin),
IconStyle().apply {
anchor = PointF(0.5f, 1.0f)
scale = 0.9f
}
)
setIcon(
"point",
ImageProvider.fromResource(this@Activity, R.drawable.ic_circle),
IconStyle().apply {
anchor = PointF(0.5f, 0.5f)
flat = true
scale = 0.05f
}
)
}
Результат:
Анимированные метки
Вы можете создать анимированную метку из анимированного PNG-файла.
-
Создайте метку с помощью MapObjectCollection.addPlacemark.
val placemark = map.mapObjects.addPlacemark() { geometry = Point(59.935493, 30.327392) }
-
Используйте метод PlacemarkMapObject.useAnimation для создания объекта анимации. Задать ресурс анимации можно при помощи экземпляра AnimatedImageProvider.
val animation = placemark.useAnimation().apply { setIcon(AnimatedImageProvider.fromAsset(this, "animation.png")) }
-
Запустите анимацию, управляя ею с помощью объекта PlacemarkAnimation.
animation.play()
Коллекции меток
Коллекции меток используются для группировки нескольких меток в новую коллекцию вложенных объектов карты.
-
Чтобы создать коллекцию вложенных объектов карты, используйте метод MapObjectCollection.addCollection.
val pinsCollection = map.mapObjects.addCollection()
-
Теперь вы можете использовать новую коллекцию
pinsCollection
для отображения меток и других объектов карты.val points = listOf( Point(59.935493, 30.327392), Point(59.938185, 30.32808), Point(59.937376, 30.33621), Point(59.934517, 30.335059), ) val imageProvider = ImageProvider.fromResource(this, R.drawable.ic_pin) points.forEach { point -> pinsCollection.addPlacemark().apply { geometry = point setIcon(imageProvider) } }
Примечание
Используйте один экземпляр ImageProvider, если вам нужно отобразить несколько похожих меток. Это будет эффективнее, чем создавать новый экземпляр для каждой метки.
Как это выглядит после добавления меток в коллекцию новых объектов карты:
После создания коллекции pinCollection
вы можете добавить в нее пины так же, как и для объектов Map.getMapObjects, поскольку они имеют тот же тип MapObjectCollection.
Примечание
Интерфейс MapObjectCollection расширяет MapObject, поэтому допускается создавать вложенные коллекции и добавлять их в другие.
Все методы, имеющие интерфейс MapObject, также доступны в MapObjectCollection.
Вы можете итерироваться по элементам MapObjectCollection, используя метод BaseMapObjectCollection.traverse.
Геометрии
MapKit SDK позволяет рисовать на карте примитивные геометрические объекты, такие как полигоны, полилинии и круги. Все они настраиваемые и реализуют интерфейс MapObject.
Полигоны
Используйте полигон, когда вам нужно отобразить область карты для пользователей.
-
Начните с создания экземпляра Polygon.
val points = listOf( Point(59.935493, 30.327392), Point(59.938185, 30.32808), Point(59.937376, 30.33621), Point(59.934517, 30.335059), ) val polygon = Polygon(LinearRing(points), emptyList())
-
Используйте метод MapObjectCollection.addPolygon для создания полигонального объекта карты.
val polygonMapObject = map.mapObjects.addPolygon(polygon)
После завершения сборки вы увидите полигон в стиле по умолчанию:
-
Задайте внутренние точки при создании полигона, чтобы исключить часть внутри него.
val points = listOf( Point(59.935493, 30.327392), Point(59.938185, 30.32808), Point(59.937376, 30.33621), Point(59.934517, 30.335059), ) val innerPoints = listOf( Point(59.937487, 30.330034), Point(59.936688, 30.33127), Point(59.937116, 30.33328), Point(59.937704, 30.331842), ) val polygon = Polygon(LinearRing(points), listOf(LinearRing(innerPoints)))
Полигон с внутренними точками:
-
Измените цвет заливки и обводки по умолчанию, используя созданный экземпляр PolygonMapObject.
polygonMapObject.apply { strokeWidth = 1.5f strokeColor = ContextCompat.getColor(this@Activity, R.color.olive) fillColor = ContextCompat.getColor(this@Activity, R.color.green) }
Подробнее про настройку полигонов см. в разделе PolygonMapObject.
Полилинии
Полилинии часто используются для отображения маршрутов и траекторий.
-
Создайте экземпляр Polyline с искомой геометрией и добавьте на карту объект полилинейной карты с помощью метода MapObjectCollection.addPolyline.
val points = listOf( Point(59.935493, 30.327392), Point(59.938185, 30.32808), Point(59.937376, 30.33621), Point(59.934517, 30.335059), ) val polyline = Polyline(points) val polylineObject = map.mapObjects.addPolyline(polyline)
-
Настройте стили полилиний, используя переменную PolylineMapObject.
polylineObject.apply { strokeWidth = 5f setStrokeColor(ContextCompat.getColor(this@Activity, R.color.gray)) outlineWidth = 1f outlineColor = ContextCompat.getColor(this@Activity, R.color.black) }
Результат после добавления полилинии на карту:
Подробнее об этом можно почитать в разделе PolylineMapObject.
Круги
Круги используются для отображения круглых областей.
-
Создайте экземпляр Circle с искомой геометрией: центральной точкой и радиусом в метрах.
val circle = Circle( Point(59.935493, 30.327392), 400f )
-
С помощью метода MapObjectCollection.addCircle добавьте на карту объект круга.
map.mapObjects.addCircle(circle).apply { strokeWidth = 2f strokeColor = ContextCompat.getColor(this, R.color.red) fillColor = ContextCompat.getColor(this, R.color.red_alpha) }
Результат после добавления круга на карту:
Подробнее о том, как настроить круговой объект карты, можно почитать в разделе CircleMapObject.
Кластеры
Кластеризованные коллекции используются для отображения нескольких меток.
-
Начните с создания ClusterListener с одним методом ClusterListener.onClusterAdded, который управляет внешним видом кластера на карте.
val clusterListener = ClusterListener { cluster -> cluster.appearance.setView( ViewProvider( ClusterView(this).apply { setText("${cluster.placemarks.size}") } ) ) }
Свойство Cluster.getAppearance возвращает объект PlacemarkMapObject. В нашем примере мы используем метод PlacemarkMapObject.setView, чтобы изменить внешний вид кластера.
ClusterView
— это определяемый пользователем класс. Чтобы узнать, как он реализован, посмотрите код в нашем репозитории на GitHub. -
Создайте новую вложенную коллекцию с помощью метода MapObjectCollection.addClusterizedPlacemarkCollection.
val clusterizedCollection = map.mapObjects.addClusterizedPlacemarkCollection(clusterListener)
-
Добавьте несколько меток в новый
clusterizedCollection
.val points = listOf( Point(59.935493, 30.327392), Point(59.938185, 30.32808), Point(59.937376, 30.33621), Point(59.934517, 30.335059), ) val imageProvider = ImageProvider.fromResource(this, R.drawable.ic_pin) points.forEach { point -> clusterizedCollection.addPlacemark().apply { geometry = point setIcon(imageProvider) } }
-
Вызовите метод ClusterizedPlacemarkCollection.clusterPlacemarks. Он принимает два аргумента:
clusterRadius
— минимальное расстояние в единицах между объектами, которые остаются в отдельных кластерах.minZoom
— минимальный уровень масштабирования, отображающий кластеры.
clusterizedCollection.clusterPlacemarks(60.0, 15)
Важно
ClusterizedPlacemarkCollection.clusterPlacemarks следует вызывать явно каждый раз, когда метки добавляются в кластеризованные коллекции или удаляются из них.
Иначе кластеризованные метки не будут повторно отображаться.
Кластеризованные метки с разным масштабом:
Исходный код
Полные примеры кода из руководства смотрите в приложении map-objects
в нашем GitHub репозитории.