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

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

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

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

Переход с версии 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/?apikey=ваш API-ключ&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 — пакеты, которые необходимо загрузить.

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

  • apikey — API-ключ, полученный в Кабинете Разработчика;
  • mode — режим работы с API. По умолчанию release (код обфусцирован, ошибки API не генерируются);
  • coordorder — порядок координат. По умолчанию принимает значение latlong (широта, долгота);
  • ns — пространство имен. По умолчанию ymaps.
 
<!DOCTYPE html>
  <head>
    <!-- Загружаем API -->
    <script src="https://api-maps.yandex.ru/2.1/?apikey=ваш API-ключ&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'
    // и выходит за пределы карты.
    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

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

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

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

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

Коллекции

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

События

Геопоиск

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

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

Версия 1.1

Версия 2.1

 
<!DOCTYPE html>
  <head>
    <!-- Загружаем API-->
    <script src="https://api-maps.yandex.ru/1.1/index.xml" 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 включает в себя библиотеку jQuery.

 
<!DOCTYPE html>
  <head>
    <!-- Загружаем API-->
    <script src="https://api-maps.yandex.ru/2.1/?apikey=ваш API-ключ&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/.

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

  • apikey - API-ключ (обязательный параметр) Как получить ключ;
  • lang - язык (обязательный параметр);
  • 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);
  }
)
Предыдущая
Версии JavaScript API
Следующая
Теоретические сведения