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

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

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

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

  1. Подключение API
  2. Создание карты
  3. Поведения карты
  4. Геообъекты
  5. Кластеризация
  6. Элементы управления картой
  7. Балун
  8. Оверлеи

Подключение 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'
    // и выходит за пределы карты.
    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);
  }
)