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

Макеты и шаблоны

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

Чтобы изменить/задать внешний вид отображаемого объекта необходимо изменить/задать связанный с ним макет. Объекты связываются со своими макетами с помощью соответствующих опций.

var myPlacemark = new ymaps.Placemark(
    [55.8, 37.6],
    {},
    {balloonContentLayout: MyBalloonContentLayoutClass}
    // MyBalloonContentLayoutClass — класс макета балуна.
);

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

Примечание. Реализация собственного макета «с нуля» на основе интерфейса ILayout является относительно трудоемкой задачей, решение которой выходит за рамки данного руководства. Однако в песочнице можно ознакомиться с примером, демонстрирующим реализацию данной задачи.

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

Шаблон представляет собой HTML-код, в который могут быть включены подстановки. Для создания макетов с помощью языка шаблонов предназначена фабрика макетов — статический объект templateLayoutFactory. Этот объект имеет единственный метод createClass, в который передается код шаблона.

var MyBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(
    '<div class="my-layout"><h3>Макет</h3><p>Создан на основе шаблона.</p></div>' 
);

Часто возникает необходимость использовать данные объекта в связанном с ним макете. Например, вывести название метки в ее балуне.

Шаблоны имеют доступ к некоторым полям родительского объекта. В большинстве случаев доступны значения полей data (либо properties), options и state. Значения этих полей могут быть использованы в т. н. подстановках. Типы возможных подстановок описаны в спецификации объекта templateLayoutFactory.

Примечание. В API поддерживается базовый синтаксис языков шаблонов Twig/Django Templates.

var myPlacemark = new ymaps.Placemark(
    [55.8, 37.6],
    {
        name: 'Москва',
        description: 'Столица. Много людей.',
        metro: true
    },
    {balloonContentLayout: MyBalloonContentLayoutClass}
);
var MyBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(
    '<h3>{{ properties.name }}</h3>' +
    '<p>Описание: {{ properties.description }}</p>' +
    '<p>Население: {{ properties.population|default:"неизвестно" }}</p>' +
    '<p>Метрополитен: {% if properties.metro %}да{% else %}нет{% endif %}</p>'
);

Макеты можно размещать в специальном хранилище layout.storage и в дальнейшем извлекать их оттуда по ключу.

var myBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(...);
ymaps.layout.storage.add('my#simplestBCLayout', MyBalloonContentLayoutClass);
var myPlacemark = new ymaps.Placemark(
    ...
    {balloonContentLayout:  'my#simplestBCLayout'}
);

Шаблоны могут включать в себя определенные ранее макеты. В приведенных примерах переопределяется макет содержимого балуна, который изначально включает в себя три макета: для заголовка, тела и нижнего колонтитула.

Для включения в шаблон макета используются подстановки вида {% include 'ключ макета в хранилище' %} и {% include options.optionName %}.

var MyBalloonContentLayoutClass = ymaps.templateLayoutFactory.createClass(
    '{% include options.balloonContentLayout %}<p>...</p>{% include 'my#simplestBCLayout' %}' 
);

Интерактивность геообъектов

При добавлении геообъектов на карту их соответствующие DOM-элементы размещаются под слоем, на котором реализуется подписка на DOM-события. Это означает, что события геообъектов карты не отслеживаются на уровне DOM.

Интерактивность геообъектов реализуется за счет активных областей, суть которых заключается в следующем. Для каждого геообъекта задается его представление в виде простейшей геометрической фигуры: круга, прямоугольника или многоугольника. Эти фигуры, или активные области, определяют участки на карте, которые будут интерактивными. Когда в какой-нибудь точке карты происходит DOM-событие, выполняется проверка на попадание данной точки в активную область.

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

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

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]
          ]
        }
      }
    );

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