# Размеры и адаптив

SDK сам управляет размерами плеера: он берёт «натуральный» размер креатива из ответа ad-сервера и подгоняет его под доступное пространство в вёрстке. Этот документ объясняет, как именно работает ресайз и как им управлять.

## Как SDK выбирает размер

При первом креативе и при каждом ресайзе родительского блока SDK проделывает следующее:

1. **Берёт исходный размер креатива** — `width × height`, заданные на сервере.
2. **Определяет ограничивающий блок** — это родитель контейнера, в который SDK был смонтирован (или сам контейнер, если родителя нет).
3. **Если ширина ограничивающего блока меньше ширины креатива** или у блока явно задана `width`/`max-width` в стилях — SDK ужимает плеер по ширине ограничивающего блока, сохраняя aspect ratio креатива.
4. **Если у ограничивающего блока задана `height` или `max-height`** — высота плеера дополнительно ограничивается этим значением, ширина пересчитывается через aspect ratio.
5. **Иначе** — плеер занимает натуральные размеры креатива.

Между ресайзами и сменой креативов работает плавная CSS-анимация (`transition: width/height ease`). Отключить её — `disableAnimations: true` в конфиге.

Изменения размеров родительского блока отслеживаются через `ResizeObserver` — плеер автоматически перестраивается при ресайзе окна, изменении ориентации устройства или динамической вёрстке.

Алгоритм выше — для **inline-форматов** (`video`, `multiformat`, `carouselMultiformat`). Модалка живёт поверх страницы, бегущая строка фиксирует высоту — см. разделы ниже.

## Форматы, которые считаются иначе

### Бегущая строка (`RunningLine`)

Полоса занимает **всю ширину** ограничивающего блока. Высота не берётся из креатива:

| Ширина контейнера | Высота полосы |
|-------------------|---------------|
| ≥ 960 px          | 90 px         |
| < 960 px       | 60 px         |

Картинка масштабируется по высоте полосы и едет горизонтально. Задавать `height` контейнеру не нужно — достаточно ширины (например `width: 100%` или `max-width: 100%`).

### Карусель (`carouselMultiformat`)

Высота считается от ширины контейнера и aspect ratio слайда (`displayOptions.size`). Сколько слайдов видно в ряд — зависит от ширины: SDK уменьшает число колонок, пока на слайд не останется минимум **200 px** (плюс отступ между слайдами).

- На широких экранах (≥ 769 px) рисуются стрелки, «уши» соседнего слайда скрыты.
- На узких — свайп и peek соседнего слайда.
- Если включён заголовок блока (`useHeader`), над слайдами добавляется ещё ~48 px.

Контейнеру лучше задать `width: 100%` или `max-width: 100%`, как обычному баннеру. Фиксировать высоту карусели не нужно — она пересчитается сама.

### Модалка (`modalwindow`)

Модалка **не занимает место в потоке** контейнера. SDK монтируется в переданный `container`, но окно позиционируется `fixed` относительно viewport: нижняя шторка, карточка в углу или почти на весь экран — см. [Форматы](formats.md#modalwindow).

- На время показа блокируется скролл страницы; при закрытии `overflow` у `body` возвращается.
- `width`/`height` контейнера на размер окна почти не влияют: геометрию задаёт `displayOptions` и ширина viewport.
- Если у предков контейнера есть `transform`, `filter`, `perspective` или `contain`, SDK перенесёт iframe к `document.body`, чтобы overlay покрыл экран.

Резервировать `min-height` под модалку в вёрстке не нужно — иначе останется пустая дыра.

## Типовые сценарии

### Фиксированная ширина

```html
<div id="ad" style="width: 600px;"></div>
```

Плеер будет максимум 600 px шириной. Если креатив больше — он ужимается с сохранением пропорций. Если меньше — отображается в натуральную величину (не растягивается).

### Фиксированная высота

```html
<div id="ad" style="height: 400px;"></div>
```

Плеер ограничен по высоте. Ширина пересчитывается через aspect ratio креатива.

### Полная ширина родителя (responsive)

```html
<div id="ad" style="width: 100%;"></div>
```

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

### Без ограничений

```html
<div id="ad"></div>
```

Без `width`/`height`/`max-*` плеер примет натуральный размер креатива. Подходит для десктопа с местом «под креатив», но на узких экранах может вылезать за viewport — лучше задать хотя бы `max-width: 100%`.

### Внутри flex/grid

```html
<div style="display: flex;">
    <aside>...</aside>
    <div id="ad" style="flex: 1; min-width: 0;"></div>
</div>
```

Работает как «фиксированная ширина» — SDK подхватит реальную ширину flex-ячейки. **Не забудьте `min-width: 0`**, иначе flex-элемент не даст плееру ужаться.

## SPA / динамические контейнеры

`ResizeObserver` пересоздаётся при инициализации плеера. Если ваш SPA удаляет и пересоздаёт контейнер с тем же `id`, нужно вручную:

1. Вызвать `player.destroy()` перед удалением старого контейнера.
2. После маунта нового контейнера снова вызвать `window.MadsPlayer({...})`.

См. [Варианты интеграций](recipes.md).

## Что НЕ работает

- **CSS `aspect-ratio` на контейнере** — SDK сам управляет высотой и перепишет ваш `aspect-ratio`. Если нужно зафиксировать соотношение сторон, делайте это на родительском блоке через padding-trick или фиксированную высоту.
- **Трансформации (`transform: scale`)** — `ResizeObserver` отслеживает «layout-размер» контейнера, а не визуальный после трансформации. Плеер будет считать, что у него исходные размеры.
- **Контейнер `display: none`** — `clientWidth` будет 0, и SDK не сможет посчитать целевую ширину. Прячьте плеер через `visibility: hidden` или удаляйте через `destroy()`.

## FAQ

**Креатив выходит за пределы экрана на мобильном.**
Добавьте `max-width: 100%` контейнеру или его родителю — SDK ужмёт плеер.

**После ресайза окна плеер не подстраивается.**
Проверьте, что у родительского блока есть какое-либо ограничение (`width`, `max-width`, или хотя бы он сам не растягивается шире viewport). Без ограничения SDK считает, что ему можно занять натуральный размер.

**Плеер «прыгает» при смене креатива в multiformat.**
Это нормально для ленты с разными размерами креативов — между ними играет fade + width/height анимация. Если нужен мгновенный переход — `disableAnimations: true`.

**Хочу зафиксировать высоту, чтобы не было layout shift.**
Задайте контейнеру `min-height: <px>` под ожидаемый размер креатива. SDK не будет уменьшать высоту ниже, если креатив окажется меньше — но может увеличить, если креатив больше. Для `modalwindow` `min-height` не нужен: окно рисуется поверх страницы.