Общие сведения

Внимание. Версия 2.0 устарела. Перейти к документации версии 2.1

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

Компоненты API реализованы в виде классов, функций, статических объектов и интерфейсов.

В API используется следующее соглашение: названия всех классов начинаются с заглавной буквы (Map, Balloon), при этом классы определяющие интерфейсы, начинаются с заглавной латинской буквы «I» (IGeoObject). Все остальные объекты принято именовать с маленькой буквы.

Пространства имен

Все компоненты API попадают в единое пространство имён (по умолчанию «ymaps»). Компоненты могут логически объединяться в подпространства имён второго и третьего уровней — например, ymaps.map.Hint, ymaps.map.Balloon.

Изменить пространство имен можно при загрузке API с помощью параметра ns (например, ns=myNameSpace).

Использование глобального пространства имен позволяет избежать «пересечения» в именах компонентов API Яндекс.Карт и пользовательском коде или сторонних библиотеках.

Верстка

При формировании интерактивной карты происходит динамическое формирование HTML-кода и внедрение его в DOM-дерево страницы, на которой размещена карта.

Там, где это целесообразно, в генерируемом коде используются не стандартные HTML-элементы (img, div и т. д.), а элемент ymaps. Кроме того, все стилевое оформление генерируемого API кода базируется на CSS-классах, имеющих префикс « ymaps- », а CSS API использует селекторы только этих классов. Это позволяет свести вероятность конфликтов верстки к минимуму. Если в HTML-коде пользователя не используется элемент ymaps, а пользовательские CSS-определения не содержат классов с префиксом « ymaps- », конфликтов верстки не будет. То есть CSS пользователя не будет влиять на отображение карты и ее элементов, а CSS API не будет влиять на верстку пользователя.

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

Иерархия объектов карты

Корневым элементом в иерархии объектов API является карта.

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

myMap.geoObjects.add(myGeoObject) — добавление объекта на карту,

myMap.geoObjects.remove(myGeoObject) — удаление объекта с карты.

Перед тем как добавить объекты в глобальные коллекции, их можно сначала объединить в коллекции ICollection. Например, метки (Placemark) можно объединить в коллекцию GeoObjectCollection и затем эту коллекцию добавить в глобальную коллекцию геообъектов карты. После этого метки будут отображены на карте. Исключение составляют поведения, которые всегда добавляются сразу в глобальную коллекцию поведений карты и не объединяются в коллекции более низкого уровня.

Также у карты есть две отдельные сущности — балун и хинт, которые не принадлежат глобальным коллекциям. На одну карту может быть добавлен только один балун (хинт).

Опции, данные и состояния

Среди свойств программных компонентов API можно выделить опции, данные и состояние, которые обычно обозначаются как options, data (или properties) и state соответственно.

Например, конструкторы классов Hint и control.TrafficControl выглядят следующим образом:

Hint (map, data, options)
control.TrafficControl (state)

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

Данные data (или properties) — это произвольные данные, которые содержат любую информацию об объекте (например, его название, текст балуна и хинта, длина маршрута или время проезда). Данные могут содержать в себе любые поля.

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

Опции, данные и состояние представляются в виде JavaScript-объекта, состоящего из набора пар «ключ:значение».

Описание Пример

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

При нажатии на метке открывается балун с содержимым balloonContent.

var data = {
        balloonContent: 'Hello Yandex!',
        hintContent: 'Метка',
        iconContent: '1'
    },
    options = {balloonHasCloseButton: true},
    myPlacemark = new ymaps.Placemark([48, 40], data, options);

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

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

При нажатии на метке открывается балун с содержимым balloonContent.

var data = {
        balloonContent: 'Hello Yandex!',
        hintContent: 'Метка',
        iconContent: '1'
    },
    options = {balloonHasCloseButton: true},
    myPlacemark = new ymaps.Placemark([48, 40], data, options);

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

Наследование опций

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

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

При задании опций объектам не через карту область действия этих опций сужается. Например, если задать опцию балуна через коллекцию геообъектов GeoObjectCollection и открыть балун через экземпляр класса карты (myMap.balloon.open()), то опция не будет применена.

В API реализована поддержка заранее предустановленных наборов опций — т. н. пресетов (от англ. preset).

Для хранения пресетов существует специальное хранилище option.presetStorage, позволяющее поставить пресету в соответствие именованный ключ. Хранилище представляет собой статический объект, уже содержащий пресеты, которые могут использоваться (или используются) некоторыми компонентами API.

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

Метка с белой иконкой, растягивающейся под контент

var myPlacemark = new ymaps.Placemark(
    [55.7, 37.6],
    { iconContent: 'Пользуйтесь пресетами' },
    { preset: 'twirl#whiteStretchyIcon' } // Иконка будет белой и растянется под iconContent
);
Описание Пример

Метка с белой иконкой, растягивающейся под контент

var myPlacemark = new ymaps.Placemark(
    [55.7, 37.6],
    { iconContent: 'Пользуйтесь пресетами' },
    { preset: 'twirl#whiteStretchyIcon' } // Иконка будет белой и растянется под iconContent
);

Таким образом сослаться можно только на один пресет.

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

Список доступных пресетов можно посмотреть в справочнике.

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

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

// Задание опции метке через карту
myMap.options.set({
    geoObjectZIndexHover: 200 // z-index геообъекта при наведении на него указателя мыши
})

// Задание опции метке напрямую через объект Placemark
myMap.Placemark.options.set({
    zIndexHover: 100 // для этой метки значение опции будет 100
})

Использование префиксов в названиях опций

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

Поэтому для различия опций одинакового назначения в названиях этих опций используются префиксы (например, balloonLayout или iconLayout).

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

Ниже приведены примеры использования префиксов для опции layout при задании макета определенным объектам (меткам, балуну, хинту и кластерам).

Для задания макета объекту напрямую через этот объект (например, хинту карты) опция layout указывается без префикса:

myMap.hint.show([56, 37], {'Я хинт!'}, {
    layout: MyHintLayoutClass // макет хинта карты
});
При задании опций определенным объектам через их коллекции (то есть на уровне выше), нужно указывать соответствующие префиксы: icon, balloon, hint и т.д.:
// Задание макета геообъектам через их коллекции
myGeoObjectCollection.options.set({
    hintLayout: MyHintLayoutClass // макет хинтов всех геообъектов из данной коллекции
    balloonLayout: MyBalloonLayoutClass // макет балунов всех геообъектов из данной коллекции
    iconLayout: MyIconLayoutClass // макет иконок всех меток из данной коллекции
    ...
});

Через кластеризатор можно задавать опции для меток и кластеров, входящих в него, а так же для их балунов и хинтов. Поэтому для различия опций объектов, относящихся только к кластерам используется префикс « cluster ».

Примечание. Если через кластеризатор все опции заданы без префикса «cluster» , то эти опции применятся ко всем объектам кластеризатора, в том числе и к кластерам.
// Задание макета иконок меток и кластеров через кластеризатор
myClusterer.options.set({
    iconLayout: MyIconLayoutClass // макет иконок меток и кластеров, входящих в данный кластеризатитор
    balloonLayout: ... // макет балунов всех объектов кластеризатора
    clusterBalloonLayout: ... // макет балунов только кластеров
    ...
});

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

myMap.geoObjects.options.set({
    iconLayout: MyIconLayoutClass, // макет иконок всех объектов карты
    balloonLayout: MyBalloonLayoutClass, // макет балунов всех объектов карты
    clusterBalloonLayout: ... // макет балунов кластеров
    ...
});
При задании опций геообъектам, балуну и хинту через карту (то есть на самом верхнем уровне) помимо соответствующего определенному объекту префикса (icon, balloon и т.д.) нужно добавлять префикс geoObject:
// Задание опции объектам через глобальную коллекцию геообъектов
myMap.options.set({
    geoObjectIconLayout: MyIconLayoutClass, // макет всех меток на карте
    geoObjectBalloonLayout: MyBalloonLayoutClass, // макет балунов  геообъектов карты
    balloonLayout: ... // макет всех балунов карты
    geoObjectClusterBalloonLayout: ... // макет балунов кластеров
    ...
});