Введение

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

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

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

<head>
...
    <script src="https://api-maps.yandex.ru/2.0-stable/?apikey=ваш API-ключ&load=package.full&lang=ru-RU" type="text/javascript"></script>
...
</head>

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

<script src="https://api-maps.yandex.ru/2.0/?apikey=ваш API-ключ&lang=ru-RU&load=package.controls,package.geoObjects" type="text/javascript"></script>

В первом примере были подключены все компоненты API, во втором - только пакеты package.controls и package.geoObjects. Набор загружаемых пакетов задается параметром load.

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

<script src="https://api-maps.yandex.ru/2.0/?apikey=ваш API-ключ&lang=ru-RU&load=package.clusters" type="text/javascript"></script>
<script type="text/javascript">
  if (window.location.pathname == '/special-page') {
      // Для этой страницы нужны балун и хинт
      ymaps.load(['balloon', 'hint']);
  }
</script>

В приведенном примере загрузка пакетов, содержащих компоненты балуна и хинта будут загружены функцией ymaps.load только на странице /special-page.

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

<script src="https://api-maps.yandex.ru/2.0/?apikey=ваш API-ключ&lang=ru-RU&load=map&ns=myNamespace" type="text/javascript"></script>
<script type="text/javascript">
  if (window.location.pathname == '/special-page') {
    // Для этой страницы нужны балун и хинт
    myNamespace.load(['balloon', 'hint']);
  }
</script>

Карта

Основным компонентом 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.0/?apikey=ваш API-ключ&load=package.full&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('drag');

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(
  // Геокодер возвращает результаты в виде упорядоченной коллекции GeoObjectArray
  function (res) {
    // Восьмой результат
    map.geoObjects.add (res.geoObjects.get(7));
  }
)

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

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

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

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

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

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

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

// Ползунок изменения масштаба
myMap.controls.add('zoomControl', {right : '35px'});
// Выбор типа карты
map.controls.add(new ymaps.control.TypeSelector());

Координаты

Базовой системой координат JavaScript API является глобальная пиксельная система координат. В этой системе каждая точка реального мира проецируется на бесконечную пиксельную плоскость. Каждому коэффициенту масштабирования соответствует своя пиксельная плоскость, на нулевом масштабе эта плоскость имеет размер 256x256 пикселей. Для каждого коэффициента масштабирования точка реального мира будет иметь различные глобальные пиксельные координаты.

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

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

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

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

<script src="https://api-maps.yandex.ru/2.0/?apikey=ваш API-ключ&coordorder=longlat&..." type="text/javascript"></script>

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