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

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

В 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 и затем эту коллекцию добавить в глобальную коллекцию геообъектов карты. После этого метки будут отображены на карте. Исключение составляют поведения, которые всегда добавляются сразу в глобальную коллекцию поведений карты и не объединяются в коллекции более низкого уровня.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Через кластеризатор можно задавать опции для меток и кластеров, входящих в него, а так же для их балунов и хинтов. Опции кластеров задаются с помощью префикса « cluster », а опции меток, входящих в кластеризатор, — с помощью префикса « geoObject ».

// Задание опций меток и кластеров через кластеризатор.
myClusterer.options.set({
    // Макет иконок кластеров, входящих в данный кластеризатор.
    clusterIconLayout: MyIconLayoutClass, 
    // Макет иконок меток кластеризатора.
    geoObjectIconLayout: /* ... */,
    // Содержимое балунов меток, входящих в кластеризатор.
    geoObjectBalloonContent: /* ... */
});

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

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