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

# Balloon

Расширяет [IBalloon](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IBalloon.md), [Popup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Popup.md).

Балун — всплывающее облако, которое может отображать любое HTML-содержимое. Обычно балун существует на карте в единственном экземпляре, управление им происходит через специальные менеджеры (например, [карты](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/map.Balloon.md), [геообъектов](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/geoObject.Balloon.md), [слоев активных областей](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/hotspot.layer.Balloon.md) и т. д.). Не создавайте их самостоятельно, если в этом нет необходимости.

[Конструктор](#constructor-summary) | [Поля ](#properties-summary) | [События ](#events-summary) | [Методы ](#methods-summary)

## Конструктор {#constructor-summary}

```javascript
Balloon(map[, options])
```

**Параметры:**

#|
|| **Параметр** | **Значение по умолчанию** | **Описание** ||
|| [`map`](#param-map)[*](*star) |  — | Тип: [Map](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Map.md)

Ссылка на объект карты. ||
|| [`options`](#param-options) | — | Тип: Object

Опции. ||
|| [`options.autoPan`](#param-options.autoPan) | true | Тип: Boolean

Сдвигать карту, чтобы отобразить открывшийся балун. ||
|| [`options.autoPanCheckZoomRange`](#param-options.autoPanCheckZoomRange) | false | Тип: Boolean

Включает автомасштабирование при невозможности отобразить карту после перемещения на том же масштабе. ||
|| [`options.autoPanDuration`](#param-options.autoPanDuration) | 500 | Тип: Number

Длительность перемещения к точке балуна (в мс). ||
|| [`options.autoPanMargin`](#param-options.autoPanMargin) | 34 | Тип: Number\|Number[]

Отступ или отступы от краев видимой области карты при выполнении действия autoPan. Значение может быть задано в виде одного числа (равный отступ для всех сторон), в виде двух чисел (для вертикальные и горизонтальные отступы) и в виде четырех чисел (в порядке: верхний, правый, нижний и левый отступ). Следует иметь в виду, данное значение будет суммироваться со значением рассчитыванным в менеджере отступов [map.margin.Manager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/map.margin.Manager.md). ||
|| [`options.autoPanUseMapMargin`](#param-options.autoPanUseMapMargin) | true | Тип: Boolean

Нужно ли учитывать отступы карты [map.margin.Manager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/map.margin.Manager.md) при выполнении действия autoPan. ||
|| [`options.closeButton`](#param-options.closeButton) | true | Тип: Boolean

Флаг наличия кнопки закрытия. ||
|| [`options.closeTimeout`](#param-options.closeTimeout) | 700 | Тип: Number

Задержка закрытия (в мс). ||
|| [`options.contentLayout`](#param-options.contentLayout) | — | Тип: Function\|String

Макет для содержимого балуна. (Тип: конструктор объекта с интерфейсом [ILayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayout.md) или ключ макета). ||
|| [`options.interactivityModel`](#param-options.interactivityModel) | — | Тип: String

Ключ модели интерактивности. Доступные ключи и их значения перечислены в описании [interactivityModel.storage](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/interactivityModel.storage.md). ||
|| [`options.layout`](#param-options.layout) | islands#balloon | Тип: Function\|String

Внешний макет балуна. (Тип: конструктор объекта с интерфейсом [ILayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayout.md) или ключ макета). ||
|| [`options.maxHeight`](#param-options.maxHeight) | — | Тип: Number

Максимальная высота, в пикселах. ||
|| [`options.maxWidth`](#param-options.maxWidth) | — | Тип: Number

Максимальная ширина, в пикселах. ||
|| [`options.minHeight`](#param-options.minHeight) | — | Тип: Number

Минимальная высота, в пикселах. ||
|| [`options.minWidth`](#param-options.minWidth) | — | Тип: Number

Минимальная ширина, в пикселах. ||
|| [`options.offset`](#param-options.offset) | — | Тип: Number[]

Дополнительное смещение позиции относительно точки привязки. ||
|| [`options.openTimeout`](#param-options.openTimeout) | 150 | Тип: Number

Задержка открытия (в мс). ||
|| [`options.pane`](#param-options.pane) | 'balloon' | Тип: String

Ключ пейна, в который помещается оверлей балуна. ||
|| [`options.panelContentLayout`](#param-options.panelContentLayout) | null | Тип: Function\|String

Макет для содержимого балуна в режиме панели. Если опция не задана, то используется значение опции contentLayout. (Тип: конструктор объекта с интерфейсом [ILayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayout.md) или ключ макета). ||
|| [`options.panelMaxHeightRatio`](#param-options.panelMaxHeightRatio) | — | Тип: Number

Максимальная высота балуна-панели. Задаётся как коэфициент отношения к высоте карты: числом от 0 до 1. ||
|| [`options.panelMaxMapArea`](#param-options.panelMaxMapArea) | — | Тип: Number

Максимальная площадь карты, при которой балун будет отображаться в виде панели. Можно отключить режим панели, задав значение _0_, и наоборот, всегда отображать балун в виде панели, задав значение _Infinity_. ||
|| [`options.shadow`](#param-options.shadow) | true | Тип: Boolean

Флаг наличия тени. ||
|| [`options.shadowLayout`](#param-options.shadowLayout) | — | Тип: Function\|String

Макет тени. (Тип: конструктор объекта с интерфейсом [ILayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ILayout.md) или ключ макета). ||
|| [`options.shadowOffset`](#param-options.shadowOffset) | — | Тип: Number[]

Дополнительное смещение позиции тени относительно точки привязки. ||
|| [`options.zIndex`](#param-options.zIndex) | — | Тип: String

z-index балуна. ||
|#


\*\Обязательный параметр/опция.

**Пример:**

```javascript
// Создание независимого экземпляра балуна и отображение его в центре карты.
var balloon = new ymaps.Balloon(myMap);
// Здесь родительскими устанавливаются опции карты,
// где содержатся значения по умолчанию для обязательных опций.
balloon.options.setParent(myMap.options);
// Открываем балун в центре карты:
balloon.open(myMap.getCenter());
```
## Поля {#properties-summary}

#|
|| **Имя** | **Тип** | **Описание** ||
|| [events](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IEventEmitter.md#events) | [IEventManager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IEventManager.md) | Менеджер событий.

Унаследовано от [IEventEmitter](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IEventEmitter.md#events). ||
|| [options](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#options) | [IOptionManager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IOptionManager.md) | Менеджер опций.

Унаследовано от [ICustomizable](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#options). ||
|#

## События {#events-summary}

#|
|| **Имя** | **Описание** ||
|| [autopanbegin](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Balloon.md#event-autopanbegin) | Начало автоматического перемещения центра карты, вызванного методом autoPan. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md). ||
|| [autopanend](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Balloon.md#event-autopanend) | Окончание автоматического перемещения центра карты, вызванного методом autoPan. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md). ||
|| [beforeuserclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Balloon.md#event-beforeuserclose) | Событие, предшествующее событию [Balloon.userclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Balloon.md#event-userclose). Позволяет отменить пользовательское действие посредством вызова метода preventDefault. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md). ||
|| [close](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#event-close) | Закрытие инфо-объекта.

Унаследовано от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#event-close). ||
|| [open](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#event-open) | Открытие инфо-объекта.

Унаследовано от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#event-open). ||
|| [optionschange](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#event-optionschange) | Изменение в опциях объекта.

Унаследовано от [ICustomizable](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICustomizable.md#event-optionschange). ||
|| [userclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Balloon.md#event-userclose) | Закрытие балуна пользователем. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md). ||
|#

## Методы {#methods-summary}

#|
|| **Имя** | **Возвращает** | **Описание** ||
|| [autoPan](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IBalloon.md#autoPan)() | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md) | Перемещает карту таким образом, чтобы балун оказался видимым.

Унаследован от [IBalloon](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IBalloon.md#autoPan). ||
|| [close](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#close)(\[[force](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#close-param-force)\]) | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md) | Закрывает инфо-объект.

Унаследован от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#close). ||
|| [getData](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#getData)() | | Возвращает данные инфо-объекта.

Унаследован от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#getData). ||
|| [getOverlay](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#getOverlay)() | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md) | Возвращает объект-обещание вернуть оверлей.

Унаследован от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#getOverlay). ||
|| [getOverlaySync](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#getOverlaySync)() | [IOverlay](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IOverlay.md) | Возвращает оверлей, если тот существует.

Унаследован от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#getOverlaySync). ||
|| [getPosition](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#getPosition)() | | Возвращает координаты инфо-объекта.

Унаследован от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#getPosition). ||
|| [isOpen](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#isOpen)() | Boolean | Возвращает состояние инфо-объекта: открыт/закрыт.

Унаследован от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#isOpen). ||
|| [open](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#open)(\[[position](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#open-param-position)[, [data](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#open-param-data)]]) | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md) | Открывает инфо-объект в указанной позиции. Если инфо-объект уже открыт, перемещает его в указанную точку. Формат и суть координат определяется проекцией [IProjection](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IProjection.md), которая содержится в опциях.

Унаследован от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#open). ||
|| [setData](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#setData)([data](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#setData-param-data)) | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md) | Задаёт инфо-объекту новые данные.

Унаследован от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#setData). ||
|| [setPosition](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#setPosition)([position](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#setPosition-param-position)) | [vow.Promise](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md) | Задаёт инфо-объекту новую позицию.

Унаследован от [IPopup](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IPopup.md#setPosition). ||
|#

## Описание событий {#event_detail}

### autopanbegin {#event-autopanbegin}

Начало автоматического перемещения центра карты, вызванного методом autoPan. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md).

## autopanend {#event-autopanend}

Окончание автоматического перемещения центра карты, вызванного методом autoPan. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md).

## beforeuserclose {#event-beforeuserclose}

Событие, предшествующее событию [Balloon.userclose](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Balloon.md#event-userclose). Позволяет отменить пользовательское действие посредством вызова метода preventDefault. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md).

## userclose {#event-userclose}

Закрытие балуна пользователем. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md).

<!-- XLIFF_FARM_ODNiZmMw_CACHING -->

[*star]: Обязательный параметр.