--- metadata: - name: generator content: Diplodoc Platform v5.39.1 alternate: - https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/upgrade/index.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/jsapi-v2-1/doc/ru/llms.txt # Руководство по переходу на JS API 2.1 Руководство содержит примеры, демонстрирующие различия между JavaScript API версий 2.1 и 2.0, а также 2.1 и 1.x. В разделе рассматриваются только те операции с API, в которых нарушена обратная совместимость. [Переход с версии 2.0](#update-2.0) [Переход с версии 1.x](#update-1.x) ## Переход с версии 2.0 {#update-2.0} В разделе приведены примеры работы с JavaScript API версий 2.0 и 2.1. Следует обратить внимание на выделенные фрагменты кода. К каждому из них приводится пояснение. ### Подключение API {#load-api} #| || Версия 2.0 | Версия 2.1 || || ```xml ... ``` URL API: https://api-maps.yandex.ru/2.0/. Обязательные параметры: - `lang` — язык; - `load` — пакеты, которые необходимо загрузить. Дополнительные параметры: - `apikey` — API-ключ, полученный в [Кабинете Разработчика](https://developer.tech.yandex.ru); - `mode` — режим работы с API. По умолчанию `release` (код обфусцирован, ошибки API не генерируются); - `coordorder` — порядок координат. По умолчанию принимает значение `latlong` (широта, долгота); - `ns` — пространство имен. По умолчанию `ymaps`. | ```xml ... ``` URL API: https://api-maps.yandex.ru/2.1/. Обязательные параметры: - `apikey` — API-ключ. [Как получить ключ](https://yandex.com/dev/jsapi-v2-1/doc/ru/index.md); - `lang` — язык. Доступны те же параметры, что и в версии 2.0. Параметром `load` задаются [модули](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/dg/concepts/modules.md), которые необходимо загрузить. Данный параметр _не_ является обязательным. По умолчанию загружаются все компоненты API (`load=package.full`). Модульная система устроена таким образом, что функциональность подгружается в момент ее фактического использования. В большинстве случаев нет необходимости настраивать параметр `load`. || |# ### Создание карты {#create-map} #| || Версия 2.0 | Версия 2.1 || || ```javascript // Создание экземпляра карты // и его привязка к // контейнеру с id="YMapsID". var myMap = new ymaps.Map("YMapsID", { // Центр карты. center: [55.76, 37.64], // Коэффициент масштабирования. zoom: 10, // Тип карты. type: "yandex#satellite" }); ``` По умолчанию карта создается без элементов управления. | ```javascript // Создание экземпляра карты // и его привязка к // контейнеру с id="YMapsID". var myMap = new ymaps.Map("YMapsID", { center: [55.76, 37.64], zoom: 10, type: "yandex#satellite", // Карта будет создана без // элементов управления. controls: [] }); ``` По умолчанию карта создается со стандартными элементами управления: поиск по карте, выбор типа карты, полноэкранный режим, ползунок масштаба, геолокация и кнопка "Пробки". Если необходимо создать карту без элементов управления, следует в ее конструкторе в поле `controls` передать пустой массив. Как добавить на карту необходимые элементы управления см. в разделе [Элементы управления](#add-controls). || |# ### Поведения карты {#map-behaviors} #| || Версия 2.0 | Версия 2.1 || || По умолчанию включены следующие поведения: 'drag', 'multiTouch', 'dblClickZoom', 'rightMouseButtonMagnifier'. | По умолчанию включены те же поведения, что и в версии 2.0, а также 'scrollZoom'. || |# ### Геообъекты {#geoobjects} **Задание стиля метки** #| || Версия 2.0 | Версия 2.1 || || ```javascript // Метка с одним из стандартных значков. var myPlacemark = new ymaps.Placemark( // Координаты метки. [55.8, 37.6], // Данные метки. {}, // Опции метки. { preset: 'twirl#greenIcon' } ); // Создание метки с собственным значком. var myPlacemark2 = new ymaps.Placemark([55.8, 37.6], {}, { // Свое изображение иконки метки. iconImageHref: '/path/to/icon.png', // Размеры метки. iconImageSize: [30, 42], // Смещение левого верхнего угла иконки // относительно ее "ножки". iconImageOffset: [-3, -42] }); ``` Меткам можно задавать цвета только из предоставленного набора. | ```javascript // Метка с одним из стандартных значков. // Список стандартных стилей приведен // в справочнике в разделе // option.preset.storage. var myPlacemark = new ymaps.Placemark( [55.8, 37.6], {}, { preset: 'islands#greenCircleIcon' }); // Создание метки с собственным значком. var myPlacemark2 = new ymaps.Placemark([55.8, 37.6], {}, { // Один из двух стандартных макетов // меток со значком-картинкой: // - default#image - без содержимого; // - default#imageWithContent - с текстовым // содержимым в значке. iconLayout: 'default#image', iconImageHref: '/path/to/icon.png', iconImageSize: [20, 30], iconImageOffset: [-10, -20] }); ``` При задании своего значка иконки нужно задавать опцию `layout: 'default#image'`. Метки имеют векторное представление, поэтому для их иконок можно задавать произвольные цвета (кроме меток, растягивающихся под контент). Обратите внимание, что в браузере IE8 данная возможность не поддерживается (иконки будут стандартного голубого цвета). ```javascript // Создание метки произвольного цвета. var myPlacemark = new ymaps.Placemark([55.8, 37.6], {}, { // Стиль метки в виде круга. preset: 'islands#circleIcon', // Цвет метки. Опция iconColor // может быть задана совместно // с опцией preset, если // последняя не принимает // значение 'stretchyIcon'. iconColor: '#00000' }); ``` || |# **Создание собственного макета геообъекта** #| || Версия 2.0 | Версия 2.1 || || ```javascript var myIconContentLayout = ymaps.templateLayoutFactory.createClass('
'}); var squarePlacemark = new ymaps.Placemark( [55.725118, 37.682145], { hintContent: 'Метка с прямоугольным макетом' }, { iconLayout: myIconContentLayout } ); ``` При добавлении геообъектов на карту происходит добавление соответствующих элементов в DOM-дерево. Они добавляются поверх контейнера, на котором реализуется подписка события карты. Таким образом, события, происходящие на геообъекте, отслеживаются на уровне DOM. | ```javascript var myIconContentLayout = ymaps.templateLayoutFactory.createClass('
'); var squarePlacemark = new ymaps.Placemark([55.725118, 37.682145], { hintContent: 'Метка с прямоугольным макетом' }, { iconLayout: myIconContentLayout, // Описываем фигуру активной // области "Прямоугольник". iconShape: {type: 'Rectangle', // Прямоугольник описывается // в виде двух точек: // верхней левой и нижней правой. coordinates: [[-25, -25], [25, 25]]} }); ``` При добавлении геообъектов на карту соответствующие элементы добавляются в DOM-дерево под слой, на котором реализуется подписка на события карты. Это означает, что на DOM уровне события геообъектов не отслеживаются. Интерактивность геообъектов реализуется за счет активных областей, которые привязаны к слою событий. Для геообъектов со стандартным макетом активные области определяются автоматически. При задании собственного макета геообъекта необходимо самостоятельно указать форму активной области с помощью опции `iconShape`. В ее полях указываются тип геометрии, которую принимает активная область (например, прямоугольник или круг), а также описание ее контура (для круга, например, это координаты его центра и длина радиуса в пикселях). Подробный пример задания фигуры активной области можно посмотреть в [песочнице](http://api.yandex.ru/maps/jsbox/2.1/placemark_shape). || |# ### Кластеризация {#clusterer} **Балун и хинт кластера** #| || Версия 2.0 | Версия 2.1 || || ```javascript cluster.balloon.open(); ``` Для каждого кластера создается менеджер балуна в поле balloon. | ```javascript clusterer.balloon.open(clusterPlacemark); clusterer.hint.open(clusterPlacemark); ``` Создается один менеджер балуна/хинта в поле balloon/hint кластеризатора. || |# **Работа с объектами кластеризатора после их добавления на карту** #| || Версия 2.0 | Версия 2.1 || || ```javascript var placemarks = [ new ymaps.Placemark([44, 55]), new ymaps.Placemark([34, 45]) ]; clusterer.add(placemarks); clusterer.events.add('objectsaddtomap', function () { // Получим данные о состоянии объекта // внутри кластера. var geoObjectState = clusterer.getObjectState(placemarks[1]); // Проверяем, находится ли объект // в видимой области карты. if (geoObjectState.isShown) { // Если объект попадает в кластер, // открываем балун кластера с нужным выбранным объектом. if (geoObjectState.isClustered) { geoObjectState.cluster.state.set('activeObject', placemarks[1]); geoObjectState.cluster.balloon.open() } else { // Если объект не попал в кластер, // открываем его собственный балун. placemarks[1].balloon.open(); } } }); ``` Поскольку по умолчанию объекты добавляются асинхронно, обработку данных можно делать только после события, сигнализирующего об окончании добавления на карту дочерних объектов кластеризатора. | ```javascript var placemarks = [ new ymaps.Placemark([44, 55]), new ymaps.Placemark([34, 45]) ]; clusterer.add(placemarks); // Получим данные о состоянии объекта // внутри кластера. var geoObjectState = clusterer.getObjectState(placemarks[1]); // Проверяем, находится ли объект // в видимой области карты. if (geoObjectState.isShown) { // Если объект попадает в кластер, // открываем балун кластера с нужным // выбранным объектом. if (geoObjectState.isClustered) { geoObjectState.cluster.state.set('activeObject', placemarks[1]); clusterer.balloon.open(geoObjectState.cluster); } else { // Если объект не попал в кластер, // открываем его собственный балун. placemarks[1].balloon.open(); } } ``` Дочерние объекты кластеризатора (кластеры и метки, не попавшие ни в один кластер) добавляются на карту синхронно. || |# **Изменение цвета иконки кластера** #| || Версия 2.0 | Версия 2.1 || || ```javascript var options =ymaps.option.presetStorage.get('twirl#redClusterIcons'); cluster.options.set({ icons: options.clusterIcons, iconContentLayout: options.clusterContentLayout }); ``` Для изменения цвета иконки кластера необходимо задать ему следующие опции: - `icons` — массив ссылок на изображения значков (маленьких, средних и больших); - `iconContentLayout` — макет содержимого метки кластера. Также управлять цветом кластеров можно с помощью опции `preset`, в которой указывается ключ необходимого стиля. Данная опция может быть задана только для всего кластеризатора. При этом цвет будет задан для иконок всех его кластеров. | ```javascript cluster.options.set('preset', 'islands#redClusterIcons'); ``` Изменить цвет иконки кластера можно с помощью опции `preset`, в которой указывается ключ необходимого стиля. || |# **Указание опций для объектов в составе кластера** #| || Версия 2.0 | Версия 2.1 || || ```javascript clusterer.options.set({ clusterBalloonLayout: myClusterBalloonLayout, balloonLayout: myPlacemarkBalloonLayout }); ``` Опции, задаваемые через кластеризатор, применяются ко всем его дочерним объектам: как к одиночным меткам (не вошедших ни в один кластер), так и к меткам кластеров. Если необходимо задать опции только меткам кластеров, то название опции следует указывать с префиксом «cluster». Однако, если требуется повлиять только на одиночные метки, то так или иначе необходимо задать опции как для одиночных меток, так и для меток кластеров. | ```javascript clusterer.options.set({ clusterBalloonLayout: myClusterBalloonLayout, geoObjectBalloonLayout: myPlacemarkBalloonLayout }); ``` Все опции для дочерних объектов кластеризатора задаются с соответствующими префиксами: для меток кластеров c префиксом «cluster», для одиночных меток — с префиксом «geoObject». Таким образом, опции дочерних объектов не зависят друг от друга. || |# ### Элементы управления картой {#controls} **Доступные элементы управления** #| || Версия 2.0 | Версия 2.1 || || - control.Button - control.Group - control.ListBox - control.ListBoxItem - control.ListBoxSeparator - control.MapTools - control.MiniMap - control.RadioGroup - control.RollupButton - control.RouteEditor - control.ScaleLine - control.SearchControl - control.SmallZoomControl - control.ToolBar - control.ToolBarSeparator - control.TrafficControl - control.TypeSelector - control.ZoomControl | - control.Button - control.ListBox - control.ListBoxItem - control.RouteEditor - control.RulerControl - control.SearchControl - control.TrafficControl - control.TypeSelector - control.ZoomControl **Добавлены новые элементы управления:** - control.FullscreenControl — полноэкранный режим - control.GeolocationControl — геолокация **Больше не поддерживаются:** - control.Group - control.ListBoxSeparator - control.MapTools - control.MiniMap - control.RadioGroup - control.RollupButton - control.ScaleLine - control.SmallZoomControl - control.ToolBar - control.ToolBarSeparator || |# **Добавление элементов управления на карту** #| || Версия 2.0 | Версия 2.1 || || ```javascript // Добавление стандартного набора кнопок. myMap.controls.add("mapTools") // Добавление кнопки изменения // масштаба. .add("zoomControl") // Добавление списка типов карты. .add("typeSelector"); ``` | ```javascript // Первый способ задания элементов // управления — через конструктор // карты при ее создании. var myMap1 = new ymaps.Map("YMapsID", { center: [55.76, 37.64], zoom: 10, controls: ['zoomControl', 'searchControl'] }); // Второй способ — через поле controls // после создания карты. myMap1.controls.add('typeSelector'); // Если необходимо создать карту // без элементов управления, // следует в ее конструкторе // передать в поле `controls` // пустой массив. var myMap2 = new ymaps.Map("YMapsID", { center: [55.76, 37.64], zoom: 10, controls: [] }); ``` По умолчанию карта создается со стандартными элементами управления: поиск по карте, выбор типа карты, полноэкранный режим, ползунок масштаба, геолокация и кнопка "Пробки". Необходимые элементы управления могут быть заданы двумя способами: так же, как и в версии 2.0, и через конструктор карты при ее создании. {% note warning %} При попытке добавить элементы управления с одинаковыми ключами возникнет ошибка. Например, к ошибке приведет следующий код: ```javascript // По умолчанию карта создастся // со стандартными элементами // управления. var myMap = new ymaps.Map("YMapsID", { center: [55.76, 37.64], zoom: 10 }); // Возникнет ошибка, поскольку // ползунок масштаба уже добавлен // на карту по умолчанию. myMap.controls.add('zoomControl'); ``` {% endnote %} Если необходимо создать карту без элементов управления, следует в ее конструкторе передать в поле `controls` пустой массив. Элементы управления адаптивны, т. е. умеют подстраиваться под размер карты и размер экрана. Например, при больших размерах карты на элементах управления показывается и подпись, и иконка; при средних — только подпись; при маленьких — только иконка. Подробнее см. в разделе руководства разработчика [Элементы управления](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/dg/concepts/controls/about.md). || |# **Позиционирование элементов управления** #| || Версия 2.0 | Версия 2.1 || || ```javascript myMap.controls .add('zoomControl', { left: 5, top: 5 }) .add('typeSelector') .add('mapTools', { left: 35, top: 5 }); ``` | ```javascript myMap.controls // Элемент управления будет располагаться // в правом верхнем углу с указанными // отступами. .add('zoomControl', { float: 'none', position: {top: 5, right: 10} }) // Элемент управления будет расположен // в левом верхнем углу. .add('traffic', { float: left }); ``` Элементы управления могут размещаться поверх карты двумя способами, которые можно регулировать с помощью опции `float`: - выстраиваться в ряд в верхнем правом или верхнем левом углу карты (`float`: '`right`' или float: 'left'); - располагаться в произвольной точке привязки относительно любого из углов карты (float: 'none') путем задания опции `position`, содержащей отступы в пикселах от краев карты. || |# ### Балун {#balloon} #| || Версия 2.0 | Версия 2.1 || || ```javascript var myPlacemark = new ymaps.Placemark([55.76, 37.64], { balloonContent: 'Я балун' }); ``` | ```javascript var myPlacemark = new ymaps.Placemark([55.76, 37.64], { balloonContent: 'Я балун' }, { balloonPanelMaxMapArea: 0 }); ``` Если карта имеет маленькие размеры, то балун отображается в виде панели в нижней части карты. Если необходимо отобразить балун в качестве всплывающего окна над меткой, необходимо задать опцию `balloonPanelMaxMapArea: 0`. || |# **Балун, выходящий за пределы карты** #| || Версия 2.0 | Версия 2.1 || || ```javascript var myPlacemark = new ymaps.Placemark([55.76, 37.64], { balloonContent: 'Я вышел за границы карты' }, { // Балун лежит в контейнере // 'movableOuters' // и выходит за пределы карты. balloonPane: 'movableOuters', balloonShadowPane: 'movableOuters' }); ``` В приведенном фрагменте кода перемещение точки привязки балуна (то есть его «ножки») не отслеживается, поэтому балун будет отображен даже в том случае, когда он полностью выйдет за границы карты. Для того чтобы балун отображался за пределами карты с тенью, необходимо задать опцию `balloonShadowPane: 'movableOuters'`. | ```javascript var myPlacemark = new ymaps.Placemark([55.76, 37.64], { balloonContent: 'Я вышел за границы карты' }, { balloonPane: 'outerBalloon' }); ``` В приведенном примере балун отображается, даже если точка его привязки не попадает в область видимости карты. В песочнице подробно рассмотрен [пример](http://api.yandex.ru/maps/jsbox/2.1/balloon_out_of_map), в котором реализовано слежение за перемещением точки привязки балуна относительно пределов карты. || |# ### Оверлеи {#overlays} **Метод getOverlay** #| || Версия 2.0 | Версия 2.1 || || Возвращает оверлей сущности (геообъекта, балуна или хинта) либо null. Не поддерживает работу в асинхронном режиме.| Является асинхронным. Возвращает объект-обещание, который подтверждается объектом оверлея в момент его фактического создания, либо отклоняется с передачей соответствующей ошибки. || |# **Методы, возвращающие макет (getLayout, getShadowLayout и т. д.)** #| || Версия 2.0 | Версия 2.1 || || Являются синхронными. Возвращают макет сущности (элемента управления, геообъекта, балуна или хинта). | Являются асинхронными. Возвращают объект-обещание, который подтверждается макетом в момент его фактического создания, либо отклоняется с передачей соответствующей ошибки.|| |# ## Переход с версии 1.x {#update-1.x} Данный раздел содержит примеры кода для выполнения основных операций с JavaScript API Яндекс Карт версий 1.1 и 2.1. [Подключение API](#load-api-1.x) [Создание карты](#create-map-1.x) [Параметры карты](#map-param-1.x) [Поведения карты](#map-behaviors-1.x) [Добавление геообъектов на карту](#geoobjects-1.x) [Коллекции](#collections-1.x) [Элементы управления картой](#controls-1.x) [События](#events-1.x) [Геопоиск](#geocode-1.x) [Маршрутизатор](#router-1.x) ### Подключение API {#load-api-1.x} #| || Версия 1.1 | Версия 2.1 || || ```xml ... ``` URL API: https://api-maps.yandex.ru/1.1/index.xml. Загруженный API включает в себя библиотеку jQuery. | ```xml ... ``` URL API: https://api-maps.yandex.ru/2.1/. Доступные параметры: - `apikey` - API-ключ (обязательный параметр) [Как получить ключ](https://yandex.com/dev/jsapi-v2-1/doc/ru/index.md); - `lang` - язык (обязательный параметр); - `load` - модули, которые необходимо загрузить; - `mode` - режим работы с API. По умолчанию `release` (код обфусцирован, ошибки API не генерируются); - `coordorder` - порядок координат. По умолчанию принимает значение `latlong` (широта, долгота); - `ns` - пространство имен. По умолчанию `ymaps`. API не включает в себя библиотеку jQuery и допускает модульную загрузку (минимизация трафика). || |# ### Создание карты {#create-map-1.x} #| || Версия 1.1 | Версия 2.1 || || ```javascript /* Создание экземпляра карты и его привязка к контейнеру с id="YMapsID" */ var myMap = new YMaps.Map(YMaps.jQuery("#YMapsID")[0]); // Установка для карты ее центра, // типа и масштаба myMap.setCenter( // Центр карты new YMaps.GeoPoint(37.64, 55.76), // Коэффициент масштабирования 10, // Тип карты YMaps.MapType.SATELLITE ) ``` Центр и коэффициент масштабирования карты задаются после ее инициализации. | ```javascript /* Создание экземпляра карты и его привязка к контейнеру с id="YMapsID" */ var myMap = new ymaps.Map("YMapsID", { // Центр карты center: [55.76, 37.64], // Коэффициент масштабирования zoom: 10, // Тип карты type: "yandex#satellite" }); ``` Центр и коэффициент масштабирования карты задаются при ее инициализации. По умолчанию карта создастся со стандартными элементами управления. || |# ### Параметры карты {#map-param-1.x} **Изменение области просмотра карты** #| || Версия 1.1 | Версия 2.1 || || ```javascript myMap.setBounds(new YMaps.GeoBounds( /* Координаты юго-западного угла области просмотра карты */ new YMaps.GeoPoint(0, 0), /* Координаты северо-восточного угла области просмотра карты */ new YMaps.GeoPoint(40, 40); ) ) ``` | ```javascript myMap.setBounds([ /* Координаты юго-западного угла области просмотра карты */ [0, 0], /* Координаты северо-восточного угла области просмотра карты */ [40, 40] ], { // Включить проверку доступного // диапазона масштабов (исключает // возможность попасть в "серые тайлы") checkZoomRange: true, // Можно анимировать перемещение карты duration: 500 } ) ``` || |# **Плавное перемещение центра карты** #| || Версия 1.1 | Версия 2.1 || || ```javascript myMap.panTo( // Координаты нового центра карты new YMaps.GeoPoint(37.609,55.753), { /* Опции перемещения: разрешить уменьшать и затем увеличивать зум карты при перемещении между точками */ flying: true } ) ``` | ```javascript myMap.panTo( // Координаты нового центра карты [55.753, 37.609], { /* Опции перемещения: разрешить уменьшать и затем увеличивать зум карты при перемещении между точками */ flying: true } ) ``` || |# **Получение максимального и минимального масштабов карты** #| || Версия 1.1 | Версия 2.1 || || ```javascript /* Определение максимального значения коэффициента масштабирования для заданной области просмотра карты */ var maxZoom = myMap.getMaxZoom( new YMaps.GeoBounds( new YMaps.GeoPoint(0, 0), new YMaps.GeoPoint(40, 40) ) ); /* Определение минимального значения коэффициента масштабирования для заданной области просмотра карты */ var minZoom = myMap.getMinZoom( new YMaps.GeoBounds( new YMaps.GeoPoint(0, 0), new YMaps.GeoPoint(40, 40) ) ); ``` Получение максимального и минимального значений коэффициентов масштабирования - синхронная операция (все необходимые данные загружаются при подключении API). Максимальное и минимальное значения коэффициентов масштабирования определяются для заданной области просмотра карты. | ```javascript /* Определение максимального и минимального значений коэффициентов масштабирования (производится для центра карты) */ myMap.zoomRange.get( /* Координаты точки, в которой определяются значения коэффициентов масштабирования */ [55.8,37.6] ).then(function (zoomRange) { // zoomRange[0] - минимальный масштаб // zoomRange[1] - максимальный масштаб ... }); // Альтернативный вариант: можно получать // диапазон масштабов, не создавая карту ymaps.getZoomRange( // Тип карты 'yandex#map', /* Координаты точки, в которой определяются значения коэффициентов масштабирования */ [55.8,37.6] ).then(function (zoomRange) { // zoomRange[0] - минимальный масштаб // zoomRange[1] - максимальный масштаб ... }); ``` Получение максимального и минимального значений коэффициентов масштабирования - асинхронная операция (при вызове метода формируется запрос к серверу и возвращается объект-[обещание](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md)). Максимальное и минимальное значения коэффициентов масштабирования определяются для заданной точки карты. || |# ### Поведения карты {#map-behaviors-1.x} **Включение поведений карты** #| || Версия 1.1 | Версия 2.1 || || ```javascript // После создания карты включаем нужные поведения myMap.enableRuler(); myMap.enableScrollZoom(); ``` Включать поведения карты можно только после ее инициализации. | ```javascript /* При создании карты помимо поведений "по умолчанию" включаем еще дополнительные поведения (ruler) */ var myMap = new ymaps.Map("map", { center: [59.93, 30.31], zoom: 10, behaviors: ["default", "ruler"] }); // Включаем поведения после создания карты myMap.behaviors.enable("routeEditor"); ``` Включать поведения карты можно как при ее создании, так и после. || |# **Отключение поведений карты** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Отключаем поведения только после создания карты myMap.disableDragging(); myMap.disableScrollZoom(); ``` Поведения карты отключаются после ее инициализации. | ```javascript /* При инициализации карты отключаем все поведения, кроме scrollZoom */ var myMap = new ymaps.Map("map", { center: [59.93, 30.31], zoom: 10, behaviors: ["scrollZoom"] }); // Отключаем поведение после инициализации карты myMap.behaviors.disable("scrollZoom"); ``` Отключать поведения карты можно как при ее инициализации, так и после. || |# ### Добавление геообъектов на карту {#geoobjects-1.x} #| || Версия 1.1 | Версия 2.1 || || ```javascript myMap.addOverlay(geoObject) ``` Все геообъекты добавляются на карту с помощью метода `addOverlay()`. | ```javascript myMap.geoObjects.add(geoObject); ``` Все геообъекты добавляются на карту через глобальную коллекцию `map.geoObjects` с помощью метода `add()`. || |# **Метка** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Создание метки var myPlacemark = new YMaps.Placemark( // Координаты метки new YMaps.GeoPoint(37.6, 55.8), { /* Опции метки: - флаг перетаскивания метки */ draggable: true, /* - показывать значок метки при открытии балуна */ hideIcon: false } ); // Задание контента значка метки myPlacemark.name = "Москва"; // Задание контента балуна myPlacemark.description = "Столица России"; // Добавление метки на карту myMap.addOverlay(myPlacemark); ``` | ```javascript // Создание метки var myPlacemark = new ymaps.Placemark( // Координаты метки [55.8, 37.6], { /* Свойства метки: - контент значка метки */ iconContent: "Москва", // - контент балуна метки balloonContent: "Столица России" }, { /* Опции метки: - флаг перетаскивания метки */ draggable: true, /* - показывать значок метки при открытии балуна */ hideIconOnBalloonOpen: false } ); // Добавление метки на карту myMap.geoObjects.add(myPlacemark); ``` || |# **Изменение значка метки** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Метка с одним из стандартных значков var myPlacemark = new YMaps.Placemark( // Координаты метки new YMaps.GeoPoint(37.6, 55.8), // Опции метки { style: 'default#greenPoint' } ); // Задание собственного значка метки var myStyle = new YMaps.Style(); myStyle.iconStyle = new YMaps.IconStyle(); // URL значка myStyle.iconStyle.href = '/path/to/icon.png'; // Размер значка myStyle.iconStyle.size = new YMaps.Point(18, 29); // Положение "ножки" значка myStyle.iconStyle.offset = new YMaps.Point(-9, -29); // Создание метки с нестандартным значком var myPlacemark2 = new YMaps.Placemark( // Координаты метки new YMaps.GeoPoint(37.6, 55.8), // Опции метки { style: myStyle } ); ``` | ```javascript // Метка с одним из стандартных значков var myPlacemark = new ymaps.Placemark( // Координаты метки [55.8, 37.6], // Данные метки {}, // Опции метки { preset: 'islands#greenCircleIcon' } ); // Создание метки с нестандартным значком var myPlacemark2 = new ymaps.Placemark( // Координаты метки [55.8, 37.6], // Данные метки {}, // Опции метки { // Один из двух стандартных макетов // меток со значком-картинкой: // - default#image - без содержимого // - default#imageWithContent - с текстовым // - содержимым в значке iconLayout: 'default#image', // URL значка iconImageHref: '/path/to/icon.png', // Размер значка iconImageSize: [20, 30], // Положение "ножки" значка iconImageOffset: [-10, -20] } ); ``` || |# **Балун** #| || Версия 1.1 | Версия 2.1 || || ```javascript myMap.openBalloon( // Координаты балуна new YMaps.GeoPoint(37.6, 55.7), // Контент балуна "Москва", { /* Опции балуна: - балун имеет кнопку закрытия */ hasCloseButton: true } ); ``` | ```javascript myMap.balloon.open( // Координаты балуна [55.76, 37.64], { /* Свойства балуна: - контент балуна */ content: "Москва" }, { /* Опции балуна: - балун имеет кнопку закрытия */ closeButton: true } ); ``` || |# **Всплывающая подсказка** #| || Версия 1.1 | Версия 2.1 || || ```javascript myMap.hint.show( // Координаты подсказки myMap.converter.coordinatesToLocalPixels(myMap.getCenter()), // Контент подсказки "Москва", { /* Опции подсказки: - задержка показа хинта */ showTimeout: 2000 } ) ``` Позиция всплывающей подсказки задается локальными пиксельными координатами. | ```javascript myMap.hint.open( // Координаты подсказки myMap.getCenter(), // Контент подсказки "Москва", { /* Опции подсказки: - задержка показа хинта */ showTimeout: 2000 } ) ``` Позиция всплывающей подсказки задается в географических координатах. || |# **Ломаная линия** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Создание ломаной линии var myPolyline = new YMaps.Polyline( // Координаты линии [ new YMaps.GeoPoint(37.7, 55.7), new YMaps.GeoPoint(37.7, 55.8), new YMaps.GeoPoint(37.8, 55.8), new YMaps.GeoPoint(37.8, 55.7), new YMaps.GeoPoint(37.7, 55.7) ], { /* Опции линии: - отключение кнопки закрытия балуна */ hasCloseButton: false } ); // Создание стиля для ломанной var s = new YMaps.Style(); s.lineStyle = new YMaps.LineStyle(); // Цвет и прозрачность линии s.lineStyle.strokeColor = "0000FF55"; // Ширина линии s.lineStyle.strokeWidth = "5"; // Добавление стиля в хранилище стилей карты YMaps.Styles.add("example#CustomLine", s); // Задание стиля для ломаной myLine.setStyle("example#CustomLine"); // Установка контента балуна ломаной myPolyline.setBalloonContent("Ломаная линия"); // Добавление линии на карту myMap.addOverlay(myPolyline); ``` | ```javascript // Создание ломаной линии var myPolyline = new ymaps.Polyline([ // Координаты вершин ломаной [55.80, 37.30], [55.80, 37.40], [55.70, 37.30], [55.70, 37.40] ], { /* Свойства линии: - балун ломаной */ balloonContent: "Ломаная линия" }, { /* Опции линии: - отключение кнопки закрытия балуна */ balloonCloseButton: false, // - цвет и прозрачность линии strokeColor: "0000FF55", // - ширина линии strokeWidth: 5 } ); // Добавление линии на карту myMap.geoObjects.add(myPolyline); ``` || |# **Многоугольник** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Создание многоугольника var myPolygon = new YMaps.Polygon([ // Координаты многоугольника new YMaps.GeoPoint(37.7, 55.7), new YMaps.GeoPoint(37.7, 55.8), new YMaps.GeoPoint(37.8, 55.8), new YMaps.GeoPoint(37.8, 55.7) ] ), // Создание стиля многоугольника style = new YMaps.Style(); style.polygonStyle = new YMaps.PolygonStyle(); // Флаг использования заливки style.polygonStyle.fill = true; // Флаг отрисовки контурной линии style.polygonStyle.outline = true; // Ширина линии style.polygonStyle.strokeWidth = 10; // Цвет и прозрачность линии style.polygonStyle.strokeColor = "ffff0088"; // Цвет и прозрачность заливки style.polygonStyle.fillColor = "ff000055"; // Задание стиля для многоугольника myPolygon.setStyle(style); // Задание контента всплывающей подсказки многоугольника myPolygon.setHintContent = ("Многоугольник"); // Добавление многоугольника на карту myMap.addOverlay(myPolygon); ``` Если координаты первой и последней вершин многоугольника не совпадают, то при его отрисовке эти вершины будут автоматически соединены. | ```javascript // Создание многоугольника var myPolygon = new ymaps.Polygon([ // Координаты многоугольника [ [55.75, 37.50], [55.76, 37.60], [55.80, 37.70], [55.69, 37.72] ] ], { /* Свойства многоугольника: - контент хинта */ hintContent: "Многоугольник" }, { /* Опции многоугольника: - флаг использования заливки */ fill: true, // - флаг отрисовки контурной линии stroke: true, // - ширина линии strokeWidth: 5, // - цвет и прозрачность линии strokeColor: "ffff0088", // - цвет и прозрачность заливки fillColor: "ff000055" }); // Добавление многоугольника на карту myMap.geoObjects.add(myPolygon); ``` Если у многоугольника координаты первой и последней вершин не совпадают, то при создании этого многоугольника добавится еще одна вершина, совпадающая с первой. || |# ### Коллекции {#collections-1.x} **Создание коллекции** #| || Версия 1.1 | Версия 2.1 || || ```javascript var myCollection = new YMaps.GeoObjectCollection(); ``` | ```javascript var myCollection = new ymaps.GeoObjectCollection(); ``` || |# **Отображение элементов коллекции на карте** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Создание метки var myPlacemark = new YMaps.Placemark(new YMaps.GeoPoint(37.64, 55.76)); // Добавление объекта (метки) в коллекцию myCollection.add(myPlacemark); // Добавление коллекции на карту myMap.addOverlay(myCollection); ``` | ```javascript // Создание метки var myPlacemark = new ymaps.Placemark([55.8,37.6]); // Добавление объекта (метки) в коллекцию myCollection.add(myPlacemark); // Добавление коллекции на карту myMap.geoObjects.add(myCollection); ``` || |# **Удаление элементов из коллекции** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Удаление одного элемента из коллекции myCollection.remove(myPlacemark); // Удаление всех элементов из коллекции myCollection.removeAll(); ``` | ```javascript // Удаление одного элемента из коллекции myCollection.remove(myPlacemark); // Удаление всех элементов из коллекции myCollection.removeAll(); ``` || |# **Задание стиля для элементов коллекции** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Задание стиля для коллекции // при ее создании var myCollection = new YMaps.GeoObjectCollection("default#greenPoint"); // Задание стиля коллекции после // ее создания myCollecton.setStyle("default#redPoint") ``` | ```javascript // Задание стиля для коллекции // при ее создании var myCollection = new ymaps.GeoObjectCollection({}, { preset: "twirl#greenIcon" }); // Задание стиля коллекции // после ее создания myCollection.options.set("preset", "twirl#redIcon"); ``` || |# ### Элементы управления картой {#controls-1.x} **Добавление элементов управления на карту** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Добавление стандартного набора кнопок myMap.addControl(new YMaps.ToolBar()); // Добавление кнопки изменения масштаба myMap.addControl(new YMaps.Zoom()); // Добавление списка типов карты myMap.addControl(new YMaps.TypeControl()); ``` | Стандартный набор элементов управления создается автоматически при создании карты. || |# ### События {#events-1.x} **Добавление обработчика события карты** #| || Версия 1.1 | Версия 2.1 || || ```javascript /* При щелчке на карте показывается балун со значениями координат в месте клика */ YMaps.Events.observe(myMap, myMap.Events.Click, function (myMap, mEvent) { myMap.openBalloon( // Позиция балуна mEvent.getGeoPoint(), // Контент балуна "Значение: " + mEvent.getGeoPoint() ); }); ``` | ```javascript /* При щелчке на карте показывается балун со значениями координат в месте клика */ myMap.events.add("click", function(e) { myMap.balloon.open( // Позиция балуна e.get("coords"), { // Свойства балуна: // контент балуна contentBody: "Значение: " + e.get("coords") } ) }); ``` || |# **Удаление обработчика события** #| || Версия 1.1 | Версия 2.1 || || ```javascript /* Удаление обработчика события после того, как событие произошло */ var myEventListener = YMaps.Events.observe(map, map.Events.Click, function (map, mEvent) { alert("Щелк!"); myEventListener.cleanup(); } ); ``` | ```javascript // Одноразовая подписка на событие var onClick = function() { alert("Щелк!"); myMap.events.once("click", onClick); }; myMap.events.add("click", onClick); ``` || |# ### Геопоиск {#geocode-1.x} **Прямое геокодирование** #| || Версия 1.1 | Версия 2.1 || || ```javascript var geocoder = new YMaps.Geocoder( /* Строка с адресом, который нужно геокодировать */ "Москва", { /* Опции поиска: - область поиска */ boundedBy: myMap.getBounds(), // - искать только в этой // области strictBounds: true, // - требуемое количество // результатов results: 1 }); /* Размещение полученной коллекции геообъектов на карте */ myMap.addOverlay(geocoder); ``` | ```javascript var myGeocoder = ymaps.geocode( /* Строка с адресом, который нужно геокодировать */ "Москва", { /* Опции поиска: - область поиска */ boundedBy: myMap.getBounds(), // - искать только в этой // области strictBounds: true, // - требуемое количество // результатов results: 1 }); /* После того как поиск вернул результат, вызывается callback-функция */ myGeocoder.then(function (res) { /* Размещение полученной коллекции геообъектов на карте */ myMap.geoObjects.add(res.geoObjects); }); ``` || |# **Обработка событий геокодера** #| || Версия 1.1 | Версия 2.1 || || ```javascript /* Добавление обработчика события "Load" (геокодирование успешно закончено) */ YMaps.Events.observe(geocoder, geocoder.Events.Load, function () { if (this.length()) { // Добавление первого полученного // объекта на карту myMap.addOverlay(this.get(0)); // Центрирование карты // на добавленном объекте myMap.panTo(this.get(0).getGeoPoint()) } else { alert("Ничего не найдено"); } } ) /* Добавление обработчика события "Fault" (при выполнении геокодирования произошла ошибка) */ YMaps.Events.observe(geocoder, geocoder.Events.Fault, function (error) { alert("Произошла ошибка: " + error.message) } ) ``` | ```javascript // Результат поиска передается // в callback-функцию myGeocoder.then( function (res) { if (res.geoObjects.getLength()) { // point - первый элемент коллекции // найденных объектов var point = res.geoObjects.get(0); // Добавление полученного элемента // на карту myMap.geoObjects.add(point); // Центрирование карты // на добавленном объекте myMap.panTo(point.geometry.getCoordinates()); } }, // Обработка ошибки function (error) { alert("Возникла ошибка: " + error.message); } ) ``` || |# ### Маршрутизатор {#router-1.x} **Создание маршрута** #| || Версия 1.1 | Версия 2.1 || || ```javascript var router = new YMaps.Router([ // Список точек, которые необходимо посетить 'Арбатская', 'Кропоткинская', // Метро 'Третьяковская' new YMaps.GeoPoint(37.62561,55.74062) ], // Кропоткинская — транзитная точка [1], { /* Опции маршрутизатора: - автоматически позиционировать карту */ viewAutoApply: true }); ``` Точки маршрута можно задавать, указав либо их координаты (объект класса `YMaps.GeoPoint`), либо адрес. | ```javascript var myRouter = ymaps.route([ // Список точек, которые необходимо // посетить 'Москва, метро Арбатская', { // Транзитная точка type: "viaPoint", point: "Москва, метро Кропоткинская" }, // метро "Третьяковская" [55.74062, 37.62561] ], { /* Опции маршрутизатора: - автоматически позиционировать карту */ mapStateAutoApply: true }); ``` Точки маршрута могут быть заданы в одном из следующих форматов: - адрес точки; - объект с полями `type` (тип точки) и `point` (адрес точки); - массив координат точки. || |# **Добавление маршрута на карту** #| || Версия 1.1 | Версия 2.1 || || ```javascript // Добавление маршрута на карту myMap.addOverlay(router); ``` | ```javascript /* После того как маршрут был построен, вызывается callback-функция */ myRouter.then(function(route) { // Добавление маршрута на карту myMap.geoObjects.add(route); }); ``` || |# **Обработка событий маршрутизатора** #| || Версия 1.1 | Версия 2.1 || || ```javascript /* Добавление обработчика события "Success" (успешное построение маршрута) */ YMaps.Events.observe(router, router.Events.Success, function() { // Задание текста для меток router.getWayPoint(0).setIconContent("А"); router.getWayPoint(1).setIconContent("Б"); // Добавление маршрута на карту myMap.addOverlay(router); }) /* Добавление обработчика события "Error" (неудачное построение маршрута) */ YMaps.Events.observe(router, router.Events.RouteError, function (link, num) { alert("Не удается проложить маршрут до точки " + num); }) ``` | ```javascript /* В случае успешного построение маршрута вызывается callback-функция */ myRouter.then(function(route) { /* Задание контента меток в начальной и конечной точках */ var points = route.getWayPoints(); points.get(0).properties.set("iconContent", "А"); points.get(1).properties.set("iconContent", "Б"); // Добавление маршрута на карту myMap.geoObjects.add(route); }, // Обработка ошибки function (error) { alert("Возникла ошибка: " + error.message); } ) ``` || |#