---
metadata:
  - name: generator
    content: Diplodoc Platform v5.39.1
alternate:
  - https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/dg/concepts/layouts.md
  - https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/dg/concepts/layouts.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/jsapi-v2-1/doc/ru/llms.txt

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

Внешний вид любых отображаемых элементов (балун, хинт, метка и пр.) определяется с помощью _макетов_. Макет представляет из себя объект, реализующий интерфейс [ILayout](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayout.md), который генерирует код, отвечающий за конечное представление объекта. Макеты могут изменять DOM-дерево документа.

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

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

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

{% note info %}

Реализация собственного макета «с нуля» на основе интерфейса **ILayout** является относительно трудоемкой задачей, решение которой выходит за рамки данного руководства. Однако в песочнице можно ознакомиться с [примером](https://tech.yandex.ru/maps/jsbox/2.1/balloon_autopan), демонстрирующим реализацию данной задачи.

{% endnote %}

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

Шаблон представляет собой HTML-код, в который могут быть включены подстановки. Для создания макетов с помощью языка шаблонов предназначена фабрика макетов — статический объект [templateLayoutFactory](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/templateLayoutFactory.md). Этот объект имеет единственный метод [createClass](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/templateLayoutFactory.md#.createClass), в который передается код шаблона.

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

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

Шаблоны имеют доступ к некоторым полям родительского объекта. В большинстве случаев доступны значения полей `data` (либо `properties`), `options` и `state`. Значения этих полей могут быть использованы в т. н. подстановках. Типы возможных подстановок описаны в спецификации объекта [templateLayoutFactory](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/templateLayoutFactory.md).

{% note info %}

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

{% endnote %}

```javascript
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](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/layout.storage.md) и в дальнейшем извлекать их оттуда по ключу.

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

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

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

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

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

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

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

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

{% note info %}

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

{% endnote %}

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

В песочнице приведен более подробный [пример](http://api.yandex.ru/maps/jsbox/2.1/placemark_shape), который иллюстрирует работу с активными областями при задании макета геообъектов.