Балун

Балун - это всплывающее окно, в котором может быть показано любое HTML-содержимое. Одновременно на карте может быть показан только один балун (экземпляр класса YMaps.Balloon).

Показ балуна

Для объекта YMaps.Balloon нет необходимости вызывать конструктор, он создается автоматически при вызове конструктора карты и существует в единственном экземпляре. На карте может быть только один балун и все, что с ним можно сделать - это переместить его в другое место, изменить его содержимое или внешний вид.

Для того, чтобы показать балун используйте метод карты openBalloon(), на вход которого передайте координаты точки, где должен располагаться "хвостик" балуна и задайте HTML-содержимое балуна.

Например, чтобы разместить балун с надписью "Москва" над центром карты Москвы, используйте следующую строку:

map.openBalloon(new YMaps.GeoPoint(37.64, 55.76), "Москва");

Открыть пример в новом окне

Также балун можно показать для любых объектов-оверлеев, добавленных на карту.

// Создает метку и добавляет ее на карту
var placemark = new YMaps.Placemark(new YMaps.GeoPoint(37.64, 55.76));
placemark.name = "Имя метки";
placemark.description = "Описание метки";
map.addOverlay(placemark);

// Открывает балун
placemark.openBalloon();

Открыть пример в новом окне

Параметры балуна

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

  • hasCloseButton - флаг, указывающий должна ли быть у балуна кнопка закрытия (по умолчанию установлен в значение true);
  • mapAutoPan - флаг, указывающий, что при открытии балуна требуется автоматически сдвигать карту так, чтобы балун был виден целиком (по умолчанию установлен в значение true);
  • margin - величина минимального отступа балуна от границ карты (в пикселах);
  • maxHeight и maxWidth - максимальная высота и ширина балуна (в пикселах);
  • style - стиль балуна.

По умолчанию максимальная высота и ширина балуна определяются автоматически, исходя из размеров контейнера карты. Эти значения можно переопределить, задав параметры maxWidth и maxHeight.

Содержимое балуна

Содержимое балуна, открытого над объектом-оверлеем, форматируется в HTML с помощью шаблона. По умолчанию шаблон содержимого балуна имеет следующий вид:

<b>$[name]</b><div>$[description]</div>

Поля $[name] и $[description] заменяются на соответствующие значения из полей name и description объекта-оверлея.

В примере ниже создается метка, у которой заполнены поля name и description:

var placemark = new YMaps.Placemark(new YMaps.GeoPoint(37.64, 55.76));
placemark.name = "Имя метки";
placemark.description = "Описание метки";
map.addOverlay(placemark);

Если у этой метки открыть балун, то его содержимое будет таким:

<b>Имя метки</b><div>Описание метки</div>

Содержимым балуна могут быть любые HTML-конструкции. Чтобы поместить HTML-код в балун используйте метод setBalloonContent(), а чтобы получить его - метод getBalloonContent().

Примечание. Содержимое, помещенное в балун с помощью метода setBalloonContent(), имеет приоритет перед содержимым, созданным с помощью наложения текущего стиля содержимого балуна.
var placemark = new YMaps.Placemark(new YMaps.GeoPoint(37.64, 55.76));

// Задает информационные поля для метки
// При открытии балуна появится надпись:
// <b>Имя метки</b><div>Описание метки</div>
placemark.name = "Имя метки";
placemark.description = "Описание метки";

// Задает содержимое балуна наиболее приоритетным способом
placemark.setBalloonContent("<div>Новое описание метки</div>");

map.addOverlay(placemark);

// Открывает балун с надписью: <div>Новое описание метки</div>
placemark.openBalloon();

Задание стиля для содержимого балуна

Для того, чтобы изменить стиль отображения содержимого балуна на карте используйте класс YMaps.BalloonContentStyle.

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

var s = new YMaps.Style();
s.balloonContentStyle = new YMaps.BalloonContentStyle(
    new YMaps.Template("<div style=\"color:#0A0\">$[description]</div>")
);

var placemark = new YMaps.Placemark(new YMaps.GeoPoint(37.7,55.7), {style: s} );
placemark.description = "Добро пожаловать на Яндекс.Карты!";
map.addOverlay(placemark);    
placemark.openBalloon();

Открыть пример в новом окне

Также с помощью стилей можно полностью изменить внешний вид балуна, см. раздел Cтили, шаблоны и макеты.