Балуны

• Введение
• Основы
  • Балун
  • Группы балунов
  • Менеджер балунов
• Класс балуна DG.Balloons.Common
  • Конструктор
  • Методы
    • Получить идентификатор балуна
    • Скрыть балун
    • Показать балун
    • Получить географическое положение балуна
    • Установить географическое положение балуна
    • Получить содержимое балуна
    • Установить содержимое балуна
    • Получить содержимое header-а балуна
    • Установить содержимое header-а балуна
    • Получить содержимое footer-а балуна
    • Установить содержимое footer-а балуна
    • Получить размер области содержимого балуна
    • Установить размер области содержимого балуна
    • Включить возможность перетаскивания
    • Отключить возможность перетаскивания
    • Перерисовать балун
    • Проверить показан ли в данный момент балун на карте или нет.
• Класс менеджера балунов DG.Balloons
  • Методы управления группами балунов
    • Создать группу
    • Удалить группу
    • Получить список имен групп
    • Получить уже созданный объект группы по ее имени
    • Получить имя группы по умолчанию
    • Получить объект группы по умолчанию
  • Методы управления балунами
    • Добавить балун
    • Удалить балун
    • Получить список всех балунов
    • Получить балун по его идентификатору
    • Удалить все балуны
• Класс группы балунов DG.BalloonGroup
  • Методы
    • Добавить балун в группу
    • Удалить балун из группы
    • Получить список всех балунов в группе
    • Получить балун по его порядковому номеру в группе
    • Удалить все балуны из группы
    • Скрыть группу
    • Отобразить группу
    • Получить количество балунов в группе
    • Проверить наличие балуна в группе
    • Получить порядковый номер балуна в группе
    • Выполнить операцию для каждого балуна в группе
    • Получить имя группы

Введение

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

Предполагается, что вы уже ознакомились с разделами «Быстрый старт» и «Карта».

Основы

Балун

Рассмотрим пример создания балуна:

// Создаем балун в Новосибирске с текстом приветствия: 
var myBalloon = new DG.Balloons.Common({ 
    // Местоположение, на которое указывает балун: 
    geoPoint: new DG.GeoPoint(82.9278, 55.0289),
    // Текст внутри балуна: 
    contentHtml: 'Привет!<br/>Хорошего настроения :)'
 }); 
// Добавим балун на карту:
myMap.balloons.add(myBalloon);

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

В результате мы увидим балун на карте для точки с координатами: долгота — 82.9278, широта — 55.0289.

В дальнейшем мы рассмотрим класс DG.Balloons.Common подробнее.

Группы балунов

Каждый балун должен принадлежать определенной группе. Это дает возможность выполнять групповые операции.

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

Если разделение на группы не требуется, группы по умолчанию должно быть достаточно. Группу по умолчанию удалить нельзя, поэтому можно смело полагаться, что она есть всегда.

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

Менеджер балунов

Менеджер отвечает за управление группами. А группы, в свою очередь, управляют балунами. При этом, для удобства, часть методов по работе с балунами есть также и в менеджере.

Менеджер балунов доступен как свойство balloons объекта карты:

// Инициализируем объект карты:
var myMap = new DG.Map("myMapId");
// Менеджер балунов:
myMap.balloons;

Любые операции с балунами в менеджере сразу же отображаются на карте.

Класс балуна DG.Balloons.Common

Ниже мы подробно рассмотрим конструктор и все методы класса балунов. Для наглядности допустим, что myBalloon — объект балуна.

Описание методов представляет собой действие (что делает метод, для чего он нужен?) и название метода. Вместе с тем, представлены дополнительно параметры, возвращаемое значение метода и особенности, если таковые имеются.

Конструктор

Параметры:

Имя	Тип	Обязательный	Описание
options.contentHtml	String	Да	Содержимое балуна. Произвольный HTML-код.
options.geoPoint	DG.GeoPoint	Да	Географическое положение точки, на которую указывает балун.
options.headerContentHtml	String	Нет	Содержимое header-а балуна. Произвольный HTML-код.
options.footerContentHtml	String	Нет	Содержимое footer-а балуна. Произвольный HTML-код.
options.isClosed	Boolean	Нет	Показывать ли «крестик» в правом верхнем углу балуна, кликнув по которому пользователь может закрыть балун. По умолчанию isClosed равен true — «крестик» показывается.
options.killWhenClose	Boolean	Нет	Параметр отвечает за то, действительно ли удаляется балун при клике по «крестику» или просто скрывается. При удалении, в отличии от скрытия, балуны будут удаляться как с карты, так и из группы балунов. Если балунов не очень много и они могут часто открываться/закрываться, рекомендуется их просто скрывать — это будет работает быстрее. По умолчанию, killWhenClose равен false — балуны не удаляются.
options.closeCallback	Function	Нет	Функция, которая вызывается при попытке пользователя закрыть балун (клике по «крестику»). При этом если определяем эту функцию, то поведение «крестика» по умолчанию мы сбрасываем. Поэтому если внутри нашей функции мы хотим закрыть балун, нужно явно это сделать, например, с помощью функции: myBalloon.hide(), где myBalloon — объект балуна.
options.contentSize	DG.Size	Нет	Фиксированный размер содержимого балуна. По умолчанию (т.е. когда options.contentSize не передан) размер балуна автоматически подстраивается под размер содержимого. Если параметр передан, ширина у объекта DG.Size должна быть не менее 87 пикселей.
options.adjustMapCenterToBalloon	Boolean	Нет	Параметр отвечает за то, будет ли изменён центр карты в случае, если балун находится за пределами видимой области. По умолчанию, adjustMapCenterToBalloon равен true — центр карты будет смещён так, чтобы балун попал в видимую область карты. False — центр карты смещён не будет и балун останется за пределами видимой области.
options.draggable	Boolean	Нет	Давать ли возможность пользователю перетаскивать балун. По умолчанию draggable равен false.
options.dragStartCallback	Function	Нет	Обработчик начала таскания балуна. В качестве аргумента принимает объект балуна. Активируется только при указанной опции draggable: true.
options.dragStopCallback	Function	Нет	Обработчик завершения таскания балуна. В качестве аргумента принимает объект балуна. Активируется только при указанной опции draggable: true.
options.fixedRelativePosition	Boolean	Нет	Зафиксировать ли относительное расположение ножки и области содержащей контент балуна при драге карты.
options.maxContentHeight	Number	Нет	Максимальная высота балуна в пикселях, когда размер балуна автоматически подстраивается под размер содержимого (т.е. когда options.contentSize не передан). По умолчанию, высота балуна не ограничена. Если по ошибке указаны одновременно и options.contentSize, и options.maxContentHeight, то последний - игнорируется.
options.maxContentWidth	Number	Нет	Максимальная ширина балуна в пикселях, когда размер балуна автоматически подстраивается под размер содержимого (т.е. когда options.contentSize не передан). По умолчанию, ширина ограничена значением 850 пикселей. Допустимые значения от 87 до 850 пикселей. Если по ошибке указаны одновременно и options.contentSize, и options.maxContentWidth, то последний - игнорируется.
options.maxHeaderHeight	Number	Нет	Максимальная высота header-а балуна в пикселях. Если содержимое не помещается в header, тогда оно будет обрезано. По умолчанию, высота header-а не ограничена.
options.maxFooterHeight	Number	Нет	Максимальная высота footer-а балуна в пикселях. Если содержимое не помещается в footer, тогда оно будет обрезано. По умолчанию, высота footer-а не ограничена.

Пример:

// Объект опций:
var options = {
    // Местоположение, на которое указывает балун: 
    geoPoint: new DG.GeoPoint(82.927810142519,55.028936234826), 
    // Текст внутри балуна: 
    contentHtml: 'Привет!<br/>Хорошего настроения :)'
};
// Класс балунов принимает единственный параметр - options
var balloon = new DG.Balloons.Common(options);

Методы

Получить идентификатор балуна

myBalloon.getId()

Возвращает:

Тип	Описание
String	Возвращает уникальный идентификатор балуна, который генерируется в момент его создания.

Скрыть балун

myBalloon.hide()

Показать балун

myBalloon.show()

Получить географическое положение балуна

myBalloon.getPosition()

Возвращает:

Тип	Описание
DG.GeoPoint	Географическое положение балуна

Установить географическое положение балуна

myBalloon.setPosition(geoPoint)

Параметры:

Имя	Тип	Обязательный	Описание
geoPoint	DG.GeoPoint	Да	Географическое положение балуна.

Получить содержимое балуна

myBalloon.getContent()

Возвращает:

Тип	Описание
String	Содержимое балуна.

Установить содержимое балуна

myBalloon.setContent(content)

Параметры:

Имя	Тип	Обязательный	Описание
content	String	Да	Содержимое балуна. Произвольный HTML-код.

Получить содержимое header-а балуна

myBalloon.getHeaderContent()

Возвращает:

Тип	Описание
String	Содержимое header-а балуна.

Установить содержимое header-а балуна

myBalloon.setHeaderContent(content)

Параметры:

Имя	Тип	Обязательный	Описание
content	String	Да	Содержимое header-а балуна. Произвольный HTML-код.

Ниже приведен пример установки текста header-а и footer-а балуна.

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

Получить содержимое footer-а балуна

myBalloon.getFooterContent()

Возвращает:

Тип	Описание
String	Содержимое footer-а балуна.

Установить содержимое footer-а балуна

myBalloon.setFooterContent(content)

Параметры:

Имя	Тип	Обязательный	Описание
content	String	Да	Содержимое footer-а балуна. Произвольный HTML-код.

Ниже приведен пример установки текста header-а и footer-а балуна.

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

Получить размер области содержимого балуна

myBalloon.getSize()

Возвращает:

Тип	Описание
DG.Size | Null	Размер области содержимого балуна.

Установить размер области содержимого балуна

myBalloon.setSize(size)

Параметры:

Имя	Тип	Обязательный	Описание
size	DG.Size	Да	Размер области содержимого балуна. Ширина у объекта DG.Size должна быть не менее 87 пикселей.

Включить возможность перетаскивания

myBalloon.enableDraggable()

Отключить возможность перетаскивания

myBalloon.disableDraggable()

Перерисовать балун

myBalloon.redraw()

Если содержимое балуна было изменено в обход метода setContent, необходимо вызвать данный метод redraw. Например, если мы скрыли какой-нибудь html-элемент внутри балуна.

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

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

myBalloon.isVisible()

Возвращает:

Тип	Описание
Boolean	true — если балун показан, false — если балун скрыт.

Класс менеджера балунов DG.Balloons

Менеджер отвечает за управление группами. А группы, в свою очередь, управляют балунами. Для удобства часть методов по работе с балунами есть также и в менеджере.

Ниже мы подробно рассмотрим все методы класса менеджера. Для наглядности допустим, что myMap — объект карты.

Описание методов представляет собой действие (что делает метод, для чего он нужен?) и название метода. Вместе с тем представлены дополнительно параметры, возвращаемое значение метода и особенности, если таковые имеются.

Создать менеджер балунов явно через ключевое слово new нельзя. Он автоматически доступен как свойство balloons объекта карты.

Методы управления группами балунов

Создать группу

myMap.balloons.createGroup(groupName)

Параметры:

Имя	Тип	Обязательный	Описание
groupName	String	Да	Название группы. Должно быть уникальным.

Возвращает:

Тип	Описание
DG.BalloonGroup	Экземпляр класс DG.BalloonGroup.

Удалить группу

myMap.balloons.removeGroup(groupName)

Параметры:

Имя	Тип	Обязательный	Описание
groupName	String	Да	Название группы.

Возвращает:

Тип	Описание
Boolean	Возвращает true при успешном удалении группы, в противном случае — false.

Получить список имен групп

myMap.balloons.getAllGroupsNames()

Возвращает:

Тип	Описание
Array	Список имен групп. Массив строк.

Получить уже созданный объект группы по ее имени

myMap.balloons.getGroup(groupName)

Параметры:

Имя	Тип	Обязательный	Описание
groupName	String	Да	Название группы.

Возвращает:

Тип	Описание
DG.BalloonGroup | Null	Экземпляр класса DG.BalloonGroup, который уже был создан с помощью метода myMap.balloons.createGroup. Если запросить у метода несуществующую группу, возвращает null.

Получить имя группы по умолчанию

myMap.balloons.getDefaultGroupName()

Возвращает:

Тип	Описание
String	Название группы по умолчанию, которая есть всегда.

Получить объект группы по умолчанию

myMap.balloons.getDefaultGroup()

Возвращает:

Тип	Описание
DG.BalloonGroup	Объект группы по умолчанию, который есть всегда.

Особенности:

Фактически данный метод, является короткой записью выражения:

myMap.balloons.getGroup(myMap.balloons.getDefaultGroupName())

Методы управления балунами

Рассмотрим часть методов по работе с балунами, которую можно выполнить в менеджере. Если требуются более сложные операции, их можно выполнить средствами объекта группы.

Добавить балун

myMap.balloons.add(item, groupName)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Balloons.Common	Да	Балун. Экземпляр класса DG.Balloons.Common.
groupName	String	Нет	Название группы. Если параметр не передан, балун будет добавлен в группу по умолчанию. Если название группы новое, автоматически будет создана новая группа с переданным именем. Ограничение: нельзя добавлять один и тот же балун дважды, во-первых, в одну группу, а во-вторых, в несколько групп сразу.

Удалить балун

myMap.balloons.remove(item)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Balloons.Common | String	Да	Может быть либо объектом балуна, либо его идентификатором. Для получения идентификатора у балуна есть метод getId().

Получить список всех балунов

myMap.balloons.getAll()

Возвращает:

Тип	Описание
Array	Массив, состоящий из экземпляров класса DG.Balloons.Common.

Получить балун по его идентификатору

myMap.balloons.get(id)

Параметры:

Имя	Тип	Обязательный	Описание
id	String	Да	Идентификатор балуна. Для его получения у балуна есть метод getId().

Возвращает:

Тип	Описание
DG.Balloons.Common	Экземпляр класса DG.Balloons.Common.

Удалить все балуны

myMap.balloons.removeAll()

Особенности:

При этом, хоть все балуны и удаляются, группы остаются не тронутыми.

Класс группы балунов DG.BalloonGroup

Объект группы предоставляет наиболее полный арсенал методов для управления балунами.

Ниже мы подробно рассмотрим все методы класса группы балунов. Для наглядности допустим, что myGroup — объект группы.

Описание методов представляет собой действие (что делает метод, для чего он нужен?) и название метода. Вместе с тем представлены дополнительно параметры, возвращаемое значение метода и особенности, если таковые имеются.

Создать группу балунов явно через ключевое слово new нельзя. Правильно это делать с помощью метода createGroup менеджера балунов.

Методы

Добавить балун в группу

myGroup.add(item, index)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Balloons.Common	Да	Балун. Экземпляр класса DG.Balloons.Common.
index	Number	Нет	Порядковый номер добавляемого балуна в группе. При этом нумерация балунов начинается с нуля. Если параметр не передан, балун будет добавлен в конец группы. Ограничение: значение должно быть целым неотрицательным числом не превышающим текущее количество балунов в группе. Таким образом обеспечивается непрерывная нумерация элементов в группе.

Удалить балун из группы

myGroup.remove(item)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Balloons.Common	Да	Балун. Экземпляр класса DG.Balloons.Common.

Получить список всех балунов в группе

myGroup.getAll()

Возвращает:

Тип	Описание
Array	Массив, состоящий из экземпляров класса DG.Balloons.Common.

Получить балун по его порядковому номеру в группе

myGroup.get(index)

Параметры:

Имя	Тип	Обязательный	Описание
index	Number	Да	Порядковый номер балуна в группе. Для его получения у группы есть метод indexOf(item).

Возвращает:

Тип	Описание
DG.Balloons.Common	Экземпляр класса DG.Balloons.Common.

Удалить все балуны из группы

myGroup.removeAll()

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

Скрыть группу

myGroup.hide()

При этом все балуны становятся невидимыми. Более того, при добавлении новых балунов они также остаются невидимыми.

Отобразить группу

myGroup.show()

Отменяет действие метода myGroup.hide(), все балуны становятся видимыми.

Получить количество балунов в группе

myGroup.length()

Возвращает:

Тип	Описание
Number	Возвращает количество балунов в группе.

Проверить наличие балуна в группе

myGroup.contains(item)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Balloons.Common | String	Да	Экземпляр класса DG.Balloons.Common или ID балуна.

Возвращает:

Тип	Описание
Boollean	Возвращает true, если балун содержится в группе. В противном случае — false.

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

myGroup.indexOf(item)

Параметры:

Имя	Тип	Обязательный	Описание
item	DG.Balloons.Common | String	Да	Экземпляр класса DG.Balloons.Common или ID балуна.

Возвращает:

Тип	Описание
Number | null	Возвращает порядковый номер балуна в группе. Нумерация начинается с нуля. Если балуна нет в группе, возвращает null.

Выполнить операцию для каждого балуна в группе

myGroup.forEach(callback, context)

Параметры:

Имя	Тип	Обязательный	Описание
callback	Function	Да	Сallback-функция, вызываемая для каждого элемента в группе. Функция вызывается со следующими параметрами callback(balloon, index, group), где: balloon — текущий балун, index — порядковый номер текущего балуна (нумерация начинается с нуля), group — объект группы myGroup.
context	Object	Нет	Контекст выполнения callback-функции. Другими словами, что будет скрываться за ключевым словом this внутри callback-функции. Если параметр не передан, по умолчанию this равен глобальному объекту window.

Получить имя группы

myGroup.getName()

Возвращает:

Тип	Описание
String	Возвращает имя группы, которое задается в конструкторе группы при ее создании.