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

Введение

JavaScript API Яндекс.Карт представляет собой набор JavaScript-компонентов, предназначенных для создания интерактивных карт. Компоненты размещены на серверах Яндекса и доступны для использования сразу после их загрузки на страницу.

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

Подключение API производится стандартным образом с помощью загрузки внешнего JavaScript-файла, содержащего компоненты API.

Внимание! API доступен по протоколу HTTPS.

<head>
...
    <script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
...
</head>

Могут быть загружены как все компоненты API, так и отдельные модули. Это позволяет регулировать объем трафика, передаваемого клиентскому приложению.

<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU&load=Map" type="text/javascript"></script>

В первом примере были подключены все компоненты API, во втором — модуль Map, содержащий только функциональность показа собственно карты. Набор загружаемых модулей задается параметром load.

При этом API поддерживает загрузку компонентов «по требованию», т. е. их можно загрузить в тот момент, когда в них возникнет необходимость.

<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU&load=Placemark" type="text/javascript"></script>
<script type="text/javascript">
  if (!ymaps.Map) {
    ymaps.modules.require('Map, Placemark', function (Map, Placemark) {
         // Добавляем в глобальную область видимости класс вручную, так как при использовании метода require модульной системы этого не происходит.
        ymaps.Map = Map;
        var myMap = new ymaps.Map('map', { 
              center: [55.76, 37.64], 
              zoom: 10    
            }),
            // Класс Placemark не добавлен в публичную область видимости.
            placemark = new Placemark([55.55, 37.00]);
        myMap.geoObjects.add(placemark);
    })
    /* Метка не будет создана, поскольку класс Placemark не включен в ymaps.
    var newPlacemark = new ymaps.Placemark([55.50, 37.00]); 
    */
}
</script>

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

По умолчанию все компоненты JavaScript API принадлежат пространству имен ymaps. Изменить пространство имен можно с помощью параметра ns.

<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU&load=Map&ns=myNamespace" type="text/javascript">

Если указать в качестве параметра ns пустую строку, то функциональность API вообще не попадёт в публичную область видимости и будет передана в качестве аргумента в указанную функцию-обработчик:

<script>
  function myFunction (ymaps) {
    var myMap = new ymaps.Map({
          center: [55.733835, 37.588227],
          zoom: 4
        });
  }
</script>
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU&ns=&onload=myFunction" type="text/javascript">

Карта

Основным компонентом API является карта, которая может быть размещена в любом блочном HTML-элементе и всегда имеет прямоугольную форму.

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

<head>
<script type="text/javascript">
  var myMap = new ymaps.Map('myMap', {
        // центр и коэффициент масштабирования однозначно
        // определяют область картографирования
        center: [55.76, 37.64],
        zoom: 7
      });
</script>
</head>
<body>
  <!-- Область показа карты -->
  <div id="myMap" style="width: 600px; height: 300px"></div>
</body>

API предоставляет три встроенных типа карт: схема, спутник и гибрид. Тип карты реализуется в виде одного или нескольких наложенных друг на друга слоев. Существует возможность определения новых типов карт с помощью создания собственных слоев и/или комбинирования встроенных. Если при создании карты тип не указан (как в предыдущем примере), используется тип «схема».

<script type="text/javascript">
  var myMap = new ymaps.Map('myMap', {
        center: [55.76, 37.64],
        zoom: 7,
        // встроенный тип карты "спутник".
        type: 'yandex#satellite'
      });
</script>

Надписи на карте могут быть отображены на различных языках. Язык надписей задается при подключении API параметром lang, в который передается локаль в виде <language>_<region> в соответствии с RFC-3066.

<head>
...
  <script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
...
</head>

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

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

var myMap = new ymaps.Map('myMap', {
      center: [55.76, 37.64],
      zoom: 10,
      behaviors: ['ruler', 'scrollZoom'],
    });
// Отключаем перетаскивание карты мышью.
myMap.behaviors.disable('ruler');

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

Объекты на карте

На карте может быть размещено произвольное количество геообъектов - программных компонентов, описывающих географические объекты реального мира. Геообъект характеризуется своей геометрией, которая определяется геометрическим типом (точка, многоугольник и пр.) и координатами географического объекта.

var myGeoObject = new ymaps.GeoObject({
      // Тип геометрии - точка.
      type: 'Point',
      // Координаты точки.
      coordinates: [55.8, 37.8]
    });
myMap.geoObjects.add(myGeoObject);

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

// Соответствует геообъекту с типом геометрии "точка" (type: "Point")
var myPlacemark = new  ymaps.Placemark([55.8, 37.6]);
myMap.geoObjects.add(myPlacemark);

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

var myCollection = new ymaps.GeoObjectCollection ({},
      // Все объекты коллекции можно будет перемещать с помощью мыши.
      { geoObjectDraggable: true }
    );
myCollection.add(myGeoObject);
myCollection.add(myPlacemark);
myMap.geoObjects.add(myCollection);

ymaps.geocode('деревня Ивановка').then(
  // Геокодер возвращает результаты в виде коллекции
  function (res) {
    // Восьмой результат
    myMap.geoObjects.add(res.geoObjects.get(7));
  }
)

Помимо коллекций, существует также специальный объект — кластеризатор, позволяющий группировать геообъекты в кластеры. Обычно это применяется в том случае, если на каких-то масштабах маркеры геообъектов накладываются друг на друга. В этом случае удобно вместо множества маркеров использовать один — маркер кластера. При увеличении масштаба кластер визуально распадается на отдельные маркеры и/или другие кластеры.

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

Карта имеет один балун и один хинт, каждый из которых размещается в точке с заданными координатами.

myMap.hint.open(myMap.getCenter(), 'Центр карты');

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

var myPlacemark = new ymaps.Placemark([48, 40], {balloonContent: 'Мой <strong>балун</strong>'});
myPlacemark.balloon.open();

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

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

// Ползунок изменения масштаба
myMap.controls.add('zoomControl', {
    float: 'none',
    position: { left: 10, top: 44 }
});

// Выбор типа карты
myMap.controls.add(new ymaps.control.TypeSelector());

Координаты

Базовой системой координат JavaScript API является глобальная пиксельная система координат. В этой системе каждая точка реального мира проецируется на бесконечную пиксельную плоскость. На начальном (нулевом) масштабе карта мира попадает в область 256х256 пикселей. При увеличении уровня масштабирования на 1 размер "карта мира" удваивается.

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

API включает в себя встроенную поддержку стандартных географических координат и декартовой системы. Для географических координат API предоставляет две проекции: эллиптическую (согласно WGS-84) и сферическую проекции Меркатора. Первая используется в API Яндекс.Карт по умолчанию, вторая часто применяется в сторонних геосервисах.

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

Географические координаты можно указывать как в виде [широта, долгота], так и в обратной последовательности [долгота, широта]. Порядок следования задается параметром coordorder при подключении API.

<script src="https://api-maps.yandex.ru/2.1/?coordorder=longlat&..." type="text/javascript"></script>

Если этот параметр не задан, географические координаты интерпретируются как заданные в виде [широта, долгота], что соответствует значению latlong параметра coordorder.