Документация
Справочник JavaScript API
2.1.65 (текущая версия)
collection
interactivityModel
Интерфейсы

Руководство по переходу на JSAPI 2.1

Руководство содержит примеры, демонстрирующие различия между JavaScript API версий 2.1 и 2.0, а также 2.1 и 1.x. В разделе рассматриваются только те операции с API, в которых нарушена обратная совместимость.

Переход с версии 2.0

В разделе приведены примеры работы с JavaScript API версий 2.0 и 2.1. Следует обратить внимание на выделенные фрагменты кода. К каждому из них приводится пояснение.

Подключение API

Версия 2.0Версия 2.1
<!DOCTYPE html>
  <head>
    <!-- Загружаем API -->
    <script src="https://api-maps.yandex.ru/2.0/?lang=ru_RU&load=package.standard" type="text/javascript"></script>
    <script type="text/javascript">
      // При успешной загрузке API выполняется
      // соответствующая функция.
      ymaps.ready(function () {
         …
      });
    </script>
   </head>
  ...
</html>

URL API: https://api-maps.yandex.ru/2.0/.

Обязательные параметры:

  • lang — язык;
  • load — пакеты, которые необходимо загрузить.

Дополнительные параметры:

  • key — API-ключ;
  • mode — режим работы с API. По умолчанию release (код обфусцирован, ошибки API не генерируются);
  • coordorder — порядок координат. По умолчанию принимает значение latlong (широта, долгота);
  • ns — пространство имен. По умолчанию ymaps.

<!DOCTYPE html>
  <head>
    <!-- Загружаем API -->
    <script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
    <script type="text/javascript">
      // При успешной загрузке API выполняется
      // соответствующая функция.
      ymaps.ready(function () {
         …
      });
    </script>
   </head>
  ...
</html>

URL API: https://api-maps.yandex.ru/2.1/.

Доступны те же параметры, что и в версии 2.0.

Параметром load задаются модули, которые необходимо загрузить. Данный параметр не является обязательным.

По умолчанию загружаются все компоненты API (load=package.full).

Модульная система устроена таким образом, что функциональность подгружается в момент ее фактического использования. В большинстве случаев нет необходимости настраивать параметр load.

Создание карты

Версия 2.0Версия 2.1
// Создание экземпляра карты и его привязка к
// контейнеру с id="YMapsID".
var myMap = new ymaps.Map("YMapsID", {
      // Центр карты.
      center: [55.76, 37.64],
      // Коэффициент масштабирования.
      zoom: 10,
      // Тип карты.
      type: "yandex#satellite"
    });

По умолчанию карта создается без элементов управления.

// Создание экземпляра карты и его привязка к
// контейнеру с id="YMapsID".
var myMap = new ymaps.Map("YMapsID", {
      center: [55.76, 37.64],
      zoom: 10,
      type: "yandex#satellite",
      // Карта будет создана без 
      // элементов управления. 
      controls: []
    });

По умолчанию карта создается со стандартными элементами управления: поиск по карте, выбор типа карты, полноэкранный режим, ползунок масштаба, геолокация и кнопка "Пробки".

Если необходимо создать карту без элементов управления, следует в ее конструкторе в поле controls передать пустой массив.

Как добавить на карту необходимые элементы управления см. в разделе Элементы управления.

Поведения карты

Версия 2.0Версия 2.1

По умолчанию включены следующие поведения: 'drag', 'multiTouch', 'dblClickZoom', 'rightMouseButtonMagnifier'.

По умолчанию включены те же поведения, что и в версии 2.0, а также 'scrollZoom'.

Геообъекты

Задание стиля метки

Версия 2.0Версия 2.1
// Метка с одним из стандартных значков.
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]
      }
    );

Меткам можно задавать цвета только из предоставленного набора.

// Метка с одним из стандартных значков.
// Список стандартных стилей приведен в справочнике
// в разделе 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 данная возможность не поддерживается (иконки будут стандартного голубого цвета).

// Создание метки произвольного цвета.
var myPlacemark = new ymaps.Placemark(
      [55.8, 37.6],
      {},
      {
        // Стиль метки в виде круга.
        preset: 'islands#circleIcon',
        // Цвет метки. Опция iconColor может быть 
        // задана совместно с опцией preset,
        // если последняя не принимает значение 'stretchyIcon'.
        iconColor: '#00000'
      }
    );

Создание собственного макета геообъекта

Версия 2.0Версия 2.1
var myIconContentLayout = ymaps.templateLayoutFactory.createClass('<div class="square_layout"></div>'});

var squarePlacemark = new ymaps.Placemark(        [55.725118, 37.682145], {
      hintContent: 'Метка с прямоугольным макетом'
      }, {
        iconLayout: myIconContentLayout
      }
    );

При добавлении геообъектов на карту происходит добавление соответствующих элементов в DOM-дерево. Они добавляются поверх контейнера, на котором реализуется подписка события карты. Таким образом, события, происходящие на геообъекте, отслеживаются на уровне DOM.

var myIconContentLayout = ymaps.templateLayoutFactory.createClass('<div class="square_layout"></div>');

var squarePlacemark = new ymaps.Placemark(        [55.725118, 37.682145], {
      hintContent: 'Метка с прямоугольным макетом'
      }, {
        iconLayout: myIconContentLayout,
        // Описываем фигуру активной области
        // "Прямоугольник".
        iconShape: {
          type: 'Rectangle',
          // Прямоугольник описывается в виде двух 
          // точек - верхней левой и нижней правой.
          coordinates: [
            [-25, -25], [25, 25]
          ]
        }
      }
    );

При добавлении геообъектов на карту соответствующие элементы добавляются в DOM-дерево под слой, на котором реализуется подписка на события карты. Это означает, что на DOM уровне события геообъектов не отслеживаются.

Интерактивность геообъектов реализуется за счет активных областей, которые привязаны к слою событий. Для геообъектов со стандартным макетом активные области определяются автоматически.

При задании собственного макета геообъекта необходимо самостоятельно указать форму активной области с помощью опции iconShape. В ее полях указываются тип геометрии, которую принимает активная область (например, прямоугольник или круг), а также описание ее контура (для круга, например, это координаты его центра и длина радиуса в пикселях).

Подробный пример задания фигуры активной области можно посмотреть в песочнице.

Кластеризация

Балун и хинт кластера

Версия 2.0Версия 2.1
cluster.balloon.open();

Для каждого кластера создается менеджер балуна в поле balloon.

clusterer.balloon.open(clusterPlacemark);
clusterer.hint.open(clusterPlacemark);

Создается один менеджер балуна/хинта в поле balloon/hint кластеризатора.

Работа с объектами кластеризатора после их добавления на карту

Версия 2.0Версия 2.1
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();
    }
  }
});

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

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
var options = ymaps.option.presetStorage.get('twirl#redClusterIcons');

cluster.options.set({
   icons: options.clusterIcons,
   iconContentLayout: options.clusterContentLayout
});

Для изменения цвета иконки кластера необходимо задать ему следующие опции:

  • icons — массив ссылок на изображения значков (маленьких, средних и больших);
  • iconContentLayout — макет содержимого метки кластера.

Также управлять цветом кластеров можно с помощью опции preset, в которой указывается ключ необходимого стиля. Данная опция может быть задана только для всего кластеризатора. При этом цвет будет задан для иконок всех его кластеров.

cluster.options.set('preset', 'islands#redClusterIcons');

Изменить цвет иконки кластера можно с помощью опции preset, в которой указывается ключ необходимого стиля.

Указание опций для объектов в составе кластера

Версия 2.0Версия 2.1
clusterer.options.set({
  clusterBalloonLayout: myClusterBalloonLayout,
  balloonLayout: myPlacemarkBalloonLayout
});

Опции, задаваемые через кластеризатор, применяются ко всем его дочерним объектам: как к одиночным меткам (не вошедших ни в один кластер), так и к меткам кластеров.

Если необходимо задать опции только меткам кластеров, то название опции следует указывать с префиксом «cluster».

Однако, если требуется повлиять только на одиночные метки, то так или иначе необходимо задать опции как для одиночных меток, так и для меток кластеров.

clusterer.options.set({
  clusterBalloonLayout: myClusterBalloonLayout,
  geoObjectBalloonLayout: myPlacemarkBalloonLayout
});

Все опции для дочерних объектов кластеризатора задаются с соответствующими префиксами: для меток кластеров c префиксом «cluster», для одиночных меток — с префиксом «geoObject». Таким образом, опции дочерних объектов не зависят друг от друга.

Элементы управления картой

Доступные элементы управления

Версия 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
// Добавление стандартного набора кнопок.
myMap.controls.add("mapTools")
  // Добавление кнопки изменения масштаба.
  .add("zoomControl")
  // Добавление списка типов карты.
  .add("typeSelector");
// Первый способ задания элементов управления —
// — через конструктор карты при ее создании.
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, и через конструктор карты при ее создании.

Внимание! При попытке добавить элементы управления с одинаковыми ключами возникнет ошибка. Например, к ошибке приведет следующий код:
// По умолчанию карта создастся со стандартными
// элементами управления: поиск по карте,
// выбор типа карты, полноэкранный режим,
// ползунок масштаба, геолокация
// и кнопка "Пробки". 
var myMap = new ymaps.Map("YMapsID", {
      center: [55.76, 37.64],
      zoom: 10
    });

// Возникнет ошибка, поскольку ползунок масштаба
// уже добавлен на карту по умолчанию.
myMap.controls.add('zoomControl');

Если необходимо создать карту без элементов управления, следует в ее конструкторе передать в поле controls пустой массив.

Элементы управления адаптивны, т. е. умеют подстраиваться под размер карты и размер экрана. Например, при больших размерах карты на элементах управления показывается и подпись, и иконка; при средних — только подпись; при маленьких — только иконка.

Подробнее см. в разделе руководства разработчика Элементы управления.

Позиционирование элементов управления

Версия 2.0Версия 2.1
myMap.controls
  .add('zoomControl', { left: 5, top: 5 })
  .add('typeSelector')
  .add('mapTools', { left: 35, top: 5 });
myMap.controls
  // Элемент управления будет располагаться в 
  // правом верхнем углу с указанными отступами.
  .add('zoomControl', {
    float: 'none', 
    position: { 
      top: 5, 
      right: 10
    }
  })
  // Элемент управления будет расположен в левом верхнем углу.
  .add('traffic', { float: left });

Элементы управления могут размещаться поверх карты двумя способами, которые можно регулировать с помощью опции float:

  • выстраиваться в ряд в верхнем правом или верхнем левом углу карты (float: 'right' или float: 'left');
  • располагаться в произвольной точке привязки относительно любого из углов карты (float: 'none') путем задания опции position, содержащей отступы в пикселах от краев карты.

Балун

Версия 2.0Версия 2.1
var myPlacemark = new ymaps.Placemark([55.76, 37.64], {
      balloonContent: 'Я балун'
    });
var myPlacemark = new ymaps.Placemark([55.76, 37.64], {
      balloonContent: 'Я балун'
    }, {
      balloonPanelMaxMapArea: 0
    });

Если карта имеет маленькие размеры, то балун отображается в виде панели в нижней части карты. Если необходимо отобразить балун в качестве всплывающего окна над меткой, необходимо задать опцию balloonPanelMaxMapArea: 0.

Балун, выходящий за пределы карты

Версия 2.0Версия 2.1
var myPlacemark = new ymaps.Placemark([55.76, 37.64], {
      balloonContent: 'Я вышел за границы карты'
    }, {
      // Балун лежит в контейнере
      // 'movableOuters' (не в контейнере overlays)
      // и выходит за пределы карты.
      balloonPane: 'movableOuters',
      balloonShadowPane: 'movableOuters'
    });

В приведенном фрагменте кода перемещение точки привязки балуна (то есть его «ножки») не отслеживается, поэтому балун будет отображен даже в том случае, когда он полностью выйдет за границы карты.

Для того чтобы балун отображался за пределами карты с тенью, необходимо задать опцию balloonShadowPane: 'movableOuters'.

var myPlacemark = new ymaps.Placemark([55.76, 37.64], {
      balloonContent: 'Я вышел за границы карты'
    }, {
      balloonPane: 'outerBalloon'
    });

В приведенном примере балун отображается, даже если точка его привязки не попадает в область видимости карты. В песочнице подробно рассмотрен пример, в котором реализовано слежение за перемещением точки привязки балуна относительно пределов карты.

Оверлеи

Метод getOverlay

Версия 2.0Версия 2.1

Возвращает оверлей сущности (геообъекта, балуна или хинта) либо null. Не поддерживает работу в асинхронном режиме.

Является асинхронным. Возвращает объект-обещание, который подтверждается объектом оверлея в момент его фактического создания, либо отклоняется с передачей соответствующей ошибки.

Методы, возвращающие макет (getLayout, getShadowLayout и т. д.)

Версия 2.0Версия 2.1

Являются синхронными. Возвращают макет сущности (элемента управления, геообъекта, балуна или хинта).

Являются асинхронными. Возвращают объект-обещание, который подтверждается макетом в момент его фактического создания, либо отклоняется с передачей соответствующей ошибки.

Переход с версии 1.x

Данный раздел содержит примеры кода для выполнения основных операций с JavaScript API Яндекс.Карт версий 1.1 и 2.1.

Подключение API

Версия 1.1Версия 2.1
<!DOCTYPE html>
  <head>
    <!-- Загружаем API-->
    <script src="https://api-maps.yandex.ru/1.1/index.xml?key=API-ключ" type="text/javascript"></script>
    <script type="text/javascript">
      /* При успешной загрузке API выполняется             соответствующая функция */
      YMaps.jQuery(function () {
        …
      });
    </script>
  </head>
  ...
</html>

URL API: https://api-maps.yandex.ru/1.1/index.xml.

Обязательно передать API-ключ.

Загруженный API включает в себя библиотеку jQuery.

<!DOCTYPE html>
  <head>
    <!-- Загружаем API-->
    <script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
    <script type="text/javascript">
      /* При успешной загрузке API выполняется
         соответствующая функция */
      ymaps.ready(function () { 
        …
      });
    </script> 
  </head>
  ...
</html>

URL API: https://api-maps.yandex.ru/2.1/.

API-ключ не является обязательным.

Обязательным является параметр lang.

Доступные параметры:

  • lang - язык (обязательный параметр);
  • key - API-ключ;
  • load - модули, которые необходимо загрузить;
  • mode - режим работы с API. По умолчанию release (код обфусцирован, ошибки API не генерируются);
  • coordorder - порядок координат. По умолчанию принимает значение latlong (широта, долгота);
  • ns - пространство имен. По умолчанию ymaps.

API не включает в себя библиотеку jQuery и допускает модульную загрузку (минимизация трафика).

Создание карты

Версия 1.1Версия 2.1
/* Создание экземпляра карты и его привязка 
   к контейнеру с id="YMapsID" */
var myMap = new YMaps.Map(YMaps.jQuery("#YMapsID")[0]);

// Установка для карты ее центра, типа и масштаба
myMap.setCenter(
  // Центр карты    
  new YMaps.GeoPoint(37.64, 55.76), 
  // Коэффициент масштабирования
  10, 
  // Тип карты
  YMaps.MapType.SATELLITE
)

Центр и коэффициент масштабирования карты задаются после ее инициализации.

/* Создание экземпляра карты и его привязка 
   к контейнеру с id="YMapsID" */
var myMap = new ymaps.Map("YMapsID", {
      // Центр карты
      center: [55.76, 37.64],
      // Коэффициент масштабирования
      zoom: 10,
      // Тип карты
      type: "yandex#satellite"
    });

Центр и коэффициент масштабирования карты задаются при ее инициализации.

По умолчанию карта создастся со стандартными элементами управления.

Параметры карты

Изменение области просмотра карты

Версия 1.1Версия 2.1
myMap.setBounds(new YMaps.GeoBounds(
  /* Координаты юго-западного угла области просмотра
     карты */
  new YMaps.GeoPoint(0, 0), 
  /* Координаты северо-восточного угла области просмотра 
       карты */
  new YMaps.GeoPoint(40, 40);
  )
)
myMap.setBounds([
  /* Координаты юго-западного угла области просмотра
     карты */
  [0, 0],
  /* Координаты северо-восточного угла области
       просмотра карты */
  [40, 40]
  ], {
      // Включить проверку доступного
      // диапазона масштабов (исключает
      // возможность попасть в "серые тайлы")
      checkZoomRange: true,
      // Можно анимировать перемещение карты
      duration: 500
  }
)

Плавное перемещение центра карты

Версия 1.1Версия 2.1
myMap.panTo(
  // Координаты нового центра карты
  new YMaps.GeoPoint(37.609,55.753), {
    /* Опции перемещения:
       разрешить уменьшать и затем увеличивать
       зум карты при перемещении между точками  */   
    flying: true
  }
)
myMap.panTo(
  // Координаты нового центра карты
  [55.753, 37.609], {
    /* Опции перемещения:
       разрешить уменьшать и затем увеличивать зум
       карты при перемещении между точками 
     */
    flying: true
  }
)

Получение максимального и минимального масштабов карты

Версия 1.1Версия 2.1
/* Определение максимального значения коэффициента
   масштабирования для заданной области просмотра
   карты */
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).

Максимальное и минимальное значения коэффициентов масштабирования определяются для заданной области просмотра карты.

/* Определение максимального и минимального 
   значений коэффициентов масштабирования
  (производится для центра карты) */
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] - максимальный масштаб
    ...
});
                

Получение максимального и минимального значений коэффициентов масштабирования - асинхронная операция (при вызове метода формируется запрос к серверу и возвращается объект-обещание).

Максимальное и минимальное значения коэффициентов масштабирования определяются для заданной точки карты.

Поведения карты

Включение поведений карты

Версия 1.1Версия 2.1
// После создания карты включаем нужные поведения
myMap.enableRuler();
myMap.enableScrollZoom();

Включать поведения карты можно только после ее инициализации.

/* При создании карты помимо поведений "по умолчанию"
   включаем еще дополнительные поведения (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
// Отключаем поведения только после создания карты
myMap.disableDragging();
myMap.disableScrollZoom();

Поведения карты отключаются после ее инициализации.

/* При инициализации карты отключаем все поведения, 
   кроме scrollZoom */
var myMap = new ymaps.Map("map", {
      center: [59.93, 30.31],
      zoom: 10,
      behaviors: ["scrollZoom"]
    });

// Отключаем поведение после инициализации карты
myMap.behaviors.disable("scrollZoom");

Отключать поведения карты можно как при ее инициализации, так и после.

Добавление геообъектов на карту

Версия 1.1Версия 2.1
myMap.addOverlay(geoObject)

Все геообъекты добавляются на карту с помощью метода addOverlay().

myMap.geoObjects.add(geoObject);

Все геообъекты добавляются на карту через глобальную коллекцию map.geoObjects с помощью метода add().

Метка

Версия 1.1Версия 2.1
// Создание метки 
var myPlacemark = new YMaps.Placemark(
      // Координаты метки
      new YMaps.GeoPoint(37.6, 55.8), {
        /* Опции метки:
           - флаг перетаскивания метки */
        draggable: true,
        /* - показывать значок метки 
             при открытии балуна */
        hideIcon: false
      }
    );

// Задание контента значка метки
myPlacemark.name = "Москва";
// Задание контента балуна
myPlacemark.description = "Столица России";

// Добавление метки на карту
myMap.addOverlay(myPlacemark); 
// Создание метки 
var myPlacemark = new ymaps.Placemark(
      // Координаты метки
      [55.8, 37.6], {
        /* Свойства метки:
           - контент значка метки */
        iconContent: "Москва",
        // - контент балуна метки
        balloonContent: "Столица России"
      }, {
        /* Опции метки:
           - флаг перетаскивания метки */
        draggable: true,
        /* - показывать значок метки 
             при открытии балуна */
        hideIconOnBalloonOpen: false
      }
    );

// Добавление метки на карту
myMap.geoObjects.add(myPlacemark);

Изменение значка метки

Версия 1.1Версия 2.1
// Метка с одним из стандартных значков
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
      }    
    );
// Метка с одним из стандартных значков
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
myMap.openBalloon(
  // Координаты балуна
  new YMaps.GeoPoint(37.6, 55.7),
  // Контент балуна
  "Москва", {
    /* Опции балуна:
       - балун имеет кнопку закрытия */
    hasCloseButton: true
  }
);
myMap.balloon.open(
  // Координаты балуна
  [55.76, 37.64], {
    /* Свойства балуна:
       - контент балуна */
    content: "Москва"
  }, {
    /* Опции балуна:
       - балун имеет кнопку закрытия */ 
    closeButton: true
  }
);

Всплывающая подсказка

Версия 1.1Версия 2.1
myMap.hint.show(
  // Координаты подсказки
  myMap.converter.coordinatesToLocalPixels(myMap.getCenter()), 
  // Контент подсказки
  "Москва", {
    /* Опции подсказки:
       - задержка показа хинта */
    showTimeout: 2000
  }
)

Позиция всплывающей подсказки задается локальными пиксельными координатами.

myMap.hint.open(
  // Координаты подсказки
  myMap.getCenter(), 
  // Контент подсказки
  "Москва", { 
    /* Опции подсказки:
       - задержка показа хинта */
    showTimeout: 2000
  }
)

Позиция всплывающей подсказки задаётся в географических координатах.

Ломаная линия

Версия 1.1Версия 2.1
// Создание ломаной линии 
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);
// Создание ломаной линии
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
// Создание многоугольника
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);

Если координаты первой и последней вершин многоугольника не совпадают, то при его отрисовке эти вершины будут автоматически соединены.

// Создание многоугольника
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);

Если у многоугольника координаты первой и последней вершин не совпадают, то при создании этого многоугольника добавится еще одна вершина, совпадающая с первой.

Коллекции

Создание коллекции

Версия 1.1Версия 2.1
var myCollection = new YMaps.GeoObjectCollection();
var myCollection = new ymaps.GeoObjectCollection();

Отображение элементов коллекции на карте

Версия 1.1Версия 2.1
// Создание метки
var myPlacemark = new YMaps.Placemark(new YMaps.GeoPoint(37.64, 55.76));

// Добавление объекта (метки) в коллекцию
myCollection.add(myPlacemark);

// Добавление коллекции на карту
myMap.addOverlay(myCollection);
// Создание метки 
var myPlacemark = new ymaps.Placemark([55.8,37.6]);

// Добавление объекта (метки) в коллекцию
myCollection.add(myPlacemark);

// Добавление коллекции на карту
myMap.geoObjects.add(myCollection);

Удаление элементов из коллекции

Версия 1.1Версия 2.1
// Удаление одного элемента из коллекции
myCollection.remove(myPlacemark);

// Удаление всех элементов из коллекции
myCollection.removeAll();
// Удаление одного элемента из коллекции
myCollection.remove(myPlacemark);

// Удаление всех элементов из коллекции
myCollection.removeAll();

Задание стиля для элементов коллекции

Версия 1.1Версия 2.1
// Задание стиля для коллекции при ее создании
var myCollection = new YMaps.GeoObjectCollection("default#greenPoint"); 

// Задание стиля коллекции после ее создания
myCollecton.setStyle("default#redPoint")
// Задание стиля для коллекции при ее создании
var myCollection = new ymaps.GeoObjectCollection({}, {
      preset: "twirl#greenIcon" 
    });

// Задание стиля коллекции после ее создания
myCollection.options.set("preset", "twirl#redIcon");

Элементы управления картой

Добавление элементов управления на карту

Версия 1.1Версия 2.1
// Добавление стандартного набора кнопок
myMap.addControl(new YMaps.ToolBar());
// Добавление кнопки изменения масштаба
myMap.addControl(new YMaps.Zoom());
// Добавление списка типов карты
myMap.addControl(new YMaps.TypeControl());

Стандартный набор элементов управления создаётся автоматически при создании карты.

События

Добавление обработчика события карты

Версия 1.1Версия 2.1
/* При щелчке на карте показывается балун со 
   значениями координат в месте клика */
YMaps.Events.observe(myMap, myMap.Events.Click, function (myMap, mEvent) {
  myMap.openBalloon(
    // Позиция балуна
    mEvent.getGeoPoint(),
    // Контент балуна
    "Значение: " + mEvent.getGeoPoint()
  );
});
/* При щелчке на карте показывается балун со
   значениями координат в месте клика */
myMap.events.add("click", function(e) {
  myMap.balloon.open(
    // Позиция балуна
    e.get("coords"), {
      // Свойства балуна:
      // контент балуна
      contentBody: "Значение: " + e.get("coords")
    }
  )
});

Удаление обработчика события

Версия 1.1Версия 2.1
/* Удаление обработчика события после того, как
   событие произошло */
var myEventListener = YMaps.Events.observe(map, map.Events.Click, 
      function (map, mEvent) {
        alert("Щелк!");
        myEventListener.cleanup();
      }
    );
// Одноразовая подписка на событие
var onClick = function() {
      alert("Щелк!");
      myMap.events.once("click", onClick);
    };

myMap.events.add("click", onClick);

Геопоиск

Прямое геокодирование

Версия 1.1Версия 2.1
var geocoder = new YMaps.Geocoder(
      /* Строка с адресом, который нужно
         геокодировать */
      "Москва", {
        /* Опции поиска:
           - область поиска */
        boundedBy: myMap.getBounds(),
        // - искать только в этой области
        strictBounds: true,
        // - требуемое количество результатов
        results: 1
    });

/* Размещение полученной коллекции
   геообъектов на карте */
myMap.addOverlay(geocoder);
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
/* Добавление обработчика события "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)
  }
)
// Результат поиска передается в 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);
  }
)

Маршрутизатор

Создание маршрута

Версия 1.1Версия 2.1
var router = new YMaps.Router([
      // Список точек, которые необходимо посетить
      'Арбатская',
      'Кропоткинская',
      // Метро 'Третьяковская'
      new YMaps.GeoPoint(37.62561,55.74062)
    ],
    // Кропоткинская — транзитная точка
    [1], {
      /* Опции маршрутизатора: 
         - автоматически позиционировать карту */
      viewAutoApply: true 
    });

Точки маршрута можно задавать, указав либо их координаты (объект класса YMaps.GeoPoint), либо адрес.

var myRouter = ymaps.route([
      // Список точек, которые необходимо посетить
      'Москва, метро Арбатская', {
        // Кропоткинская — транзитная точка
        type: "viaPoint",                   
        point: "Москва, метро Кропоткинская"
      },
      [55.74062, 37.62561] // метро "Третьяковская"
    ], {
      /* Опции маршрутизатора:
         - автоматически позиционировать карту */
      mapStateAutoApply: true 
    });

Точки маршрута могут быть заданы в одном из следующих форматов:

  • адрес точки;
  • объект с полями type (тип точки) и point (адрес точки);
  • массив координат точки.

Добавление маршрута на карту

Версия 1.1Версия 2.1
// Добавление маршрута на карту
myMap.addOverlay(router);
/* После того, как маршрут был построен, вызывается
   callback-функция */ 
myRouter.then(function(route) {
  // Добавление маршрута на карту
  myMap.geoObjects.add(route);
});

Обработка событий маршрутизатора

Версия 1.1Версия 2.1
/* Добавление обработчика события "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);
})
/* В случае успешного построение маршрута вызывается
   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);
  }
)