--- metadata: - name: generator content: Diplodoc Platform v5.39.1 alternate: - https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/dg/concepts/geoobjects.md --- # Объекты на карте [Геометрия геообъекта](#geometry) [Визуальное редактирование](#visual_editing) [Задание стиля метки](#icon-style) [Коллекции геообъектов](#geoobject_collections) [Кластеры](#clusters) Географическим объектам реального мира ставятся в соответствие программные объекты — _геообъекты_. К геообъектам относятся метки, круги, ломаные, прямоугольники, многоугольники, а также их коллекции. Каждый геообъект описывается [геометрией](#geometry), которая задается геометрическим типом и географическими координатами. Базовым классом, реализующим геообъект является [GeoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/GeoObject.md). Экземпляр карты размещает геообъекты в собственном хранилище, реализованном в виде [коллекции](#geoobject_collections), ссылка на которую находится в поле [geoObjects](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Map.md#geoObjects). Добавление геообъекта на карту, его изменение и удаление производится с помощью обращения к этой коллекции. ```javascript var myMap = new ymaps.Map("map", { center: [55.76, 37.64], zoom: 10 }), myGeoObject = new ymaps.GeoObject({ geometry: { type: "Point",// тип геометрии - точка coordinates: [55.8, 37.8] // координаты точки } }); myMap.geoObjects.add(myGeoObject); // Размещение геообъекта на карте. ``` Для каждого типа геометрии определен вспомогательный класс, предоставляющий упрощенный синтаксис для создания геообъекта. ```javascript // Вспомогательный класс, который можно использовать // вместо GeoObject c типом геометрии «Point» (см. предыдущий пример) var myPlacemark = new ymaps.Placemark([55.8, 37.6]); myMap.geoObjects.add(myPlacemark); ``` ## Геометрия геообъекта {#geometry} В следующей таблице приведен список геометрий, их идентификаторов, используемых в классе [GeoObject](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/GeoObject.md) и соответствующих вспомогательных классов. #| || **Тип геометрии / Идентификатор/ Вспомогательный класс** | **Пример** || || Точка / Point / [Placemark](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Placemark.md) ![](../_images/placemark.png) | Создание метки с помощью класса `GeoObject`: ```javascript var myPlacemark = new ymaps.GeoObject({ geometry: { type: "Point", coordinates: [55.76, 37.56] }}); ``` Создание метки c помощью вспомогательного класса `Placemark`: ```javascript var myPlacemark = new ymaps.Placemark([55.8, 37.6]); ``` || || Ломаная линия / LineString / [Polyline](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Polyline.md) ![](../_images/polyline.png) | Создание ломаной с помощью класса `GeoObject`: ```javascript var myPolyline = new ymaps.GeoObject({ geometry: { type: "LineString", coordinates: [[...]] } }); ``` Создание ломаной c помощью вспомогательного класса `Polyline`: ```javascript var myPolyline = new ymaps.Polyline( [[55.80, 37.30],[55.80, 37.40],[55.70, 37.30],[55.70, 37.40]] ); ``` || || Прямоугольник / Rectangle / [Rectangle](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Rectangle.md) ![](../_images/rectangle.png) | Создание прямоугольника с помощью класса `GeoObject`: ```javascript var myRectangle = new ymaps.GeoObject({ geometry: { type: "Rectangle", coordinates: [[...]] } }); ``` Создание прямоугольника c помощью вспомогательного класса `Rectangle`: ```javascript var myRectangle = new ymaps.Rectangle( [[55.70, 37.30],[55.80, 37.40]] ); ``` || || Многоугольник / Polygon / [Polygon](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Polygon.md) ![](../_images/polygon.png) | Создание многоугольника с помощью класса `GeoObject`: ```javascript var myPolygon = new ymaps.GeoObject({ geometry: { type: "Polygon", coordinates: [ [[...]], [[...]] ] } }); ``` Создание многоугольника c помощью вспомогательного класса `Polygon`: ```javascript var myPolygon = new ymaps.Polygon( [ [[55.75, 37.50],[55.75, 37.71],[55.70, 37.70]], [[55.73, 37.58],[55.72, 37.70],[55.70, 37.70]] ] ); ``` || || Круг / Circle / [Circle](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/Circle.md) ![](../_images/circle.png) | Создание круга с помощью класса `GeoObject`: ```javascript var myCircle = new ymaps.GeoObject({ geometry: { type: "Circle", coordinates: [55.76, 37.64], radius: 10000 } }); ``` Создание круга c помощью вспомогательного класса `Circle`: ```javascript var myCircle = new ymaps.Circle([[55.76, 37.64], 10000]); ``` || |# Тип геометрии присваивается геообъекту в момент его создания и не может быть изменен в дальнейшем. При этом координаты геометрии могут быть изменены как программно, так и пользователем с помощью [визуального редактора](#visual_editing). ```javascript var myPlacemark = new ymaps.Placemark( [55.754952, 37.615319], {}, { draggable: true, // метку можно перемещать preset: 'twirl#whiteStretchyIcon' } ); myPlacemark.events.add('dragend', function(e) { // Получение ссылки на объект, который был передвинут. var thisPlacemark = e.get('target'); // Определение координат метки var coords = thisPlacemark.geometry.getCoordinates(); // и вывод их при щелчке на метке thisPlacemark.properties.set('balloonContent', coords); }); ``` Если геообъект был инициализирован без указания геометрии, то он не будет отображаться на карте. Присвоить тип геометрии такому геообъекту также будет невозможно. ## Визуальное редактирование {#visual_editing} Географические свойства геообъекта могут быть изменены пользователем в визуальном режиме. Для этого API предоставляет два способа: перемещение геообъекта как целого и визуальный редактор. За возможность перетаскивания геообъекта как целого отвечает опция `draggable`, которая может принимать значения `true` и `false`. Визуальный редактор доступен для геообъектов с типом геометрии точка, ломаная и многоугольник. Ссылка на редактор содержится в поле [editor](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/GeoObject.md#editor) экземпляра соответствующего класса. #| || ![](../_images/polyline_editor.png) | ```javascript var myPolyline = new ymaps.Polyline( [[55.86, 37.84], [55.70, 37.55], [55.8, 37.4]], {}, { strokeWidth: 6, strokeColor: '#0000FF', draggable: true } ); myPolyline.editor.startEditing(); ``` || |# ## Задание стиля метки {#icon-style} API предоставляет возможность выбрать стиль для значка метки из [набора встроенных стилей](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/option.presetStorage.md). С помощью стилей задается цвет значка метки, а также его тип (например, значок без содержимого или значок, растягивающийся под контент). Каждому стилю из набора ставится в соответствие уникальный ключ. Для того, чтобы установить нужный стиль, следует указать в качестве значения опции `preset` соответствующий ключ: #| || ![](../_images/red_icon.png) | ``` var myPlacemark = new ymaps.Placemark([55.8, 37.6], {}, { preset: 'twirl#redIcon' }); ``` || |# {% note info %} Стилем по умолчанию является `'twirl#blueIcon'`. {% endnote %} В качестве значка метки можно использовать также собственное изображение. Для этого необходимо в опции `iconImageHref` указать URL графического файла значка. При необходимости можно указать опции `icon_imagesize` и `iconImageOffset` — размер изображения и его сдвиг относительно точки привязки соответственно. #| || ![](../_images/user_icon.png) | ``` var myPlacemark = new ymaps.Placemark([55.76, 37.56], {}, { iconImageHref: '/myIcon.gif', icon_imagesize: [30, 42], iconImageOffset: [-3, -42] }); ``` || |# Если же на карту необходимо добавить большое число меток с разными пользовательскими значками, то целесообразно использовать технологию [CSS спрайтов](http://www.w3schools.com/css/css_image_sprites.asp). Суть технологии заключается в том, что все изображения объединяются в одном графическом файле - _спрайте_. Посредством CSS нужное изображение извлекается из спрайта и устанавливается в качестве значка определенной метки. Ниже приведен пример спрайта, содержащего три изображения: ![](../_images/sprite.png) Для того, чтобы установить нужное изображение в качестве значка метки, необходимо данной метке задать следующие опции: - `iconImageCliptRect` — позиция нужного изображения в спрайте. Определяется пиксельными координатами левого верхнего и правого нижнего углов прямоугольника, в котором размещается изображение. - `iconImageHref` — URL спрайта; При необходимости можно указать опции `icon_imagesize` и `iconImageOffset`. #| || ![](../_images/icon_styles.png) | ``` var myPlacemark1 = new ymaps.Placemark([55.85, 60.64], {}, { iconImageClipRect: [[0,0], [26, 46]], iconImageHref: '/maps/doc/jsapi/2.0/dg/_images/sprite.png', icon_imagesize: [15, 27], iconImageOffset: [-15, -27] }); var myPlacemark2 = new ymaps.Placemark([55.85, 32.64], {}, { iconImageClipRect: [[34,0], [62, 46]], iconImageHref: '/maps/doc/jsapi/2.0/dg/_images/sprite.png', icon_imagesize: [26, 46], iconImageOffset: [-26, -46] }); var myPlacemark3 = new ymaps.Placemark([55.85, 1.0], {}, { iconImageClipRect: [[69,0], [97, 46]], iconImageHref: '/maps/doc/jsapi/2.0/dg/_images/sprite.png', icon_imagesize: [35, 63], iconImageOffset: [-35, -63] }); ``` || |# {% note info %} С помощью спрайтов можно задавать изображения также и для других объектов, добавляемых на карту (например, для кластеров или элементов управления). {% endnote %} Использование технологии спрайтов позволяет сократить число HTTP-запросов к серверу, так как вместо большого числа изображений загружается только одно. Подробнее о задании стиля для иконок меток см. в [примере](https://tech.yandex.ru/maps/jsbox/placemark). ## Коллекции геообъектов {#geoobject_collections} Геообъекты могут объединяться в коллекции, которые позволяют определять свойства сразу всех своих членов и проводить групповые операции над ними. В API Яндекс.Карт реализовано два вида коллекций: упорядоченные ([GeoObjectArray](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/GeoObjectArray.md)) и неупорядоченные ([GeoObjectCollection](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/GeoObjectCollection.md)). Первые реализованы на основе массивов, вторые — на основе двусвязных списков. Геообъект может принадлежать только одной коллекции. При добавлении геообъекта, принадлежащего одной коллекции, в другую коллекцию, он будет удален из первой. При реализации собственных коллекций на основе этих классов рекомендуется использовать неупорядоченные коллекции во всех случаях, когда нет необходимости обращаться к элементу по порядковому номеру. Удаление элементов из неупорядоченной коллекции производится значительно быстрее, чем из упорядоченной. #| || ![](../_images/placemark_collection.png) | ```javascript var coords = [ [55.75, 37.50],[55.75, 37.71],[55.70, 37.70] ], myCollection = new ymaps.GeoObjectCollection({}, { preset: 'twirl#redIcon', //все метки красные draggable: true // и их можно перемещать }); // или myCollection = new ymaps.GeoObjectArray(...); for (var i = 0; i < coords.length; i++) { myCollection.add(new ymaps.Placemark(coords[i])); } myMap.geoObjects.add(myCollection); // При клике на карту все метки будут удалены. myCollection.getMap().events.add('click', function() { myCollection.removeAll(); }); ``` || |# Класс коллекции, которая может быть размещена на карте, должен реализовывать интерфейс [IMapObjectCollection](https://yandex.ru/dev/maps/archive/doc/jsapi/2-0/ru/ref/reference/IMapObjectCollection.md). Все упомянутые коллекции реализуют этот интерфейс и могут быть отображены на карте. ## Кластеры {#clusters} Точечные геообъекты могут находиться настолько близко друг другу, что на каком-то масштабе их метки начинают накладываться друг на друга. В этом случае пользователю приходится тщательно «прицеливаться», чтобы попасть курсором мыши на видимый фрагмент нужной метки. Существует даже специальный термин, описывающий эффекты такого рода — pixel hunting ([пиксель-хантинг](http://ru.wikipedia.org/wiki/Пиксель-хантинг)). #| || ![](../_images/pixel_hunting.png) | ```javascript var coords = [ [56.023, 36.988], [56.025, 36.981], [56.020, 36.981], [56.021, 36.983], [56.027, 36.987] ]; var myCollection = new ymaps.GeoObjectCollection(); for (var i = 0; i![](../_images/clusterer_balloon.png) | ```javascript var myGeoObjects = []; for (var i = 0; i < coords.length; i++) { myGeoObjects[i] = new ymaps.GeoObject({ geometry: { type: "Point", coordinates: coords[i] }, properties: { clusterCaption: 'Геообъект № '+(i+1), balloonContentBody: 'Текст балуна № '+(i+1) } }); } var myClusterer = new ymaps.Clusterer( {clusterDisableClickZoom: true} ); myClusterer.add(myGeoObjects); myMap.geoObjects.add(myClusterer); ``` || |# {% note info %} Если при отображении кластера коэффициент масштабирования карты является максимальным, то кластер не будет распадаться на отдельные метки при щелчке на его маркере. В этом случае независимо от значения параметра `clusterDisableClickZoom` всегда будет открываться балун. {% endnote %} Таким образом, отобразить информацию о близко расположенных геообъектах можно даже в том случае, если их метки накладываются друг на друга при максимальном коэффициенте масштабирования. Использование кластеризатора позволяет значительно увеличить производительность при отображении большого количества геообъектов в браузере. Отрисовка и обработка геообъекта — дорогостоящая с точки зрения потребления ресурсов операция, и чем больше объектов кластеризуется, тем больше ресурсов экономится. Сильное снижение производительности наблюдается уже при отображении нескольких сотен объектов без кластеризации.