control.ListBox. Статьи

JavaScript API 2.0

control

control.ListBox

Расширяет control.Group.

Класс для создания элемента управления в виде раскрывающегося списка.

Конструктор

control.ListBox([params[, options]])

Параметры:


Параметр	Значение по умолчанию	Описание
params	—	Тип: Object Параметры элемента управления.
params.data	—	Тип: Object Данные.
params.data.title	—	Тип: String Заголовок списка.
params.items	—	Тип: IControl[] Пункты списка.
options	—	Тип: Object Опции элемента управления.
options.collapseTimeout	3000	Тип: Number Временной интервал, по истечении которого раскрытый список автоматически закрывается.
options.expandOnClick	true	Тип: Boolean Флаг, разрешающий автоматическое разворачивание/сворачивание списка по клику.
options.layout	—	Тип: Function\|String Макет элемента управления. В конструктор макета передается объект, содержащий поля: control - ссылка на элемент управления; options - менеджер опций элемента управления control.ListBox.options; data - менеджер данных элемента управления control.ListBox.data; state - менеджер состояния элемента управления control.ListBox.state. Макет меняет свой внешний вид на основе данных, состояния и опций элемента управления. Элемент управления, в свою очередь, реагирует на интерфейсные события макета и меняет значения полей control.ListBox.state в зависимости от полученных команд. (Тип: конструктор объекта, реализующий интерфейсы: IGroupControlLayout; IExpandableControlLayout. или ключ макета).
options.minWidth	0	Тип: Number Минимальная ширина выпадающего списка.
options.position	{ top: 5, left: 5 }	Тип: Object Положение элемента управления над картой. Задается в виде объекта со следующими полями: top - отступ от верхнего края контейнера карты в пикселах; right - отступ от правого края контейнера карты в пикселах; bottom - отступ от нижнего края контейнера карты в пикселах; left - отступ от левого края контейнера карты в пикселах. Если при этом заданы одновременно и top, и bottom, то значение bottom игнорируется. Аналогично, если заданы одновременно и left, и right, то значение right игнорируется. Если элемент управления добавляется в группу элементов (например, в тулбар или раскрывающийся список), то значение position не применяется.
options.visible	true	Тип: Boolean Признак того, что элемент управления отображается.


Параметр	Значение по умолчанию	Описание
params	—	Тип: Object Параметры элемента управления.
params.data	—	Тип: Object Данные.
params.data.title	—	Тип: String Заголовок списка.
params.items	—	Тип: IControl[] Пункты списка.
options	—	Тип: Object Опции элемента управления.
options.collapseTimeout	3000	Тип: Number Временной интервал, по истечении которого раскрытый список автоматически закрывается.
options.expandOnClick	true	Тип: Boolean Флаг, разрешающий автоматическое разворачивание/сворачивание списка по клику.
options.layout	—	Тип: Function\|String Макет элемента управления. В конструктор макета передается объект, содержащий поля: control - ссылка на элемент управления; options - менеджер опций элемента управления control.ListBox.options; data - менеджер данных элемента управления control.ListBox.data; state - менеджер состояния элемента управления control.ListBox.state. Макет меняет свой внешний вид на основе данных, состояния и опций элемента управления. Элемент управления, в свою очередь, реагирует на интерфейсные события макета и меняет значения полей control.ListBox.state в зависимости от полученных команд. (Тип: конструктор объекта, реализующий интерфейсы: IGroupControlLayout; IExpandableControlLayout. или ключ макета).
options.minWidth	0	Тип: Number Минимальная ширина выпадающего списка.
options.position	{ top: 5, left: 5 }	Тип: Object Положение элемента управления над картой. Задается в виде объекта со следующими полями: top - отступ от верхнего края контейнера карты в пикселах; right - отступ от правого края контейнера карты в пикселах; bottom - отступ от нижнего края контейнера карты в пикселах; left - отступ от левого края контейнера карты в пикселах. Если при этом заданы одновременно и top, и bottom, то значение bottom игнорируется. Аналогично, если заданы одновременно и left, и right, то значение right игнорируется. Если элемент управления добавляется в группу элементов (например, в тулбар или раскрывающийся список), то значение position не применяется.
options.visible	true	Тип: Boolean Признак того, что элемент управления отображается.

Примеры:

// Пример 1.
// Обработка клика на элементах списка.
var cityList = new ymaps.control.ListBox({
        data: {
            title: 'Выбрать город'
        },
        items: [
            new ymaps.control.ListBoxItem({data: {content: 'Москва'}}),
            new ymaps.control.ListBoxItem({data: {content: 'Новосибирск'}}),
            new ymaps.control.ListBoxSeparator(),
            new ymaps.control.ListBoxItem({data: {content: 'Нью-Йорк'}}),
        ]
    });
cityList.get(0).events.add('click', function () {
    map.setCenter([55.752736, 37.606815]);
});
cityList.get(1).events.add('click', function () {
    map.setCenter([55.026366, 82.907803]);
});
cityList.get(3).events.add('click', function () {
    map.setCenter([40.695537, -73.97552]);
});
map.controls.add(cityList);

// Пример 2.
// Создание пользовательского списка.
// В примере используется jQuery, загруженный с http://yandex.st/jquery/1.6.4/jquery.min.js

// Выпадающий список по умолчанию реагирует на события 'click' и автоматически
// меняет состояние на развернутое или свернутое.
var MyListBoxLayout = ymaps.templateLayoutFactory.createClass(
        "<div id='my-listbox-header' >$[data.title]</div >" +
        // Этот элемент будет служить контейнером для дочерних элементов списка.
        "<div id='my-list-box' [if state.expanded]style='display: block;'[else]style='display: none;'[endif] >" +
        "</div >", {

        build: function() {
            MyListBoxLayout.superclass.build.call(this);
            this.childContainerElement = $('#my-list-box').get(0);
            // Каждый раз при перестроении будем генерировать событие,
            // сигнализирующее о смене контейнера для дочерних элементов.
            // Формат события описан в интерфейсе IGroupControlLayout.
            this.events.fire('childcontainerchange', {
                newChildContainerElement: this.childContainerElement,
                oldChildContainerElement: null
            });
        },

        // Переопределим метод, который требует интерфейс IGroupControlLayout.
        getChildContainerElement: function () {
            return this.childContainerElement;
        }
    }),
    // Создадим список и выставим созданный макет через опции.
    listBox = new ymaps.control.ListBox({}, {layout: MyListBoxLayout});

Поля


Имя	Тип	Описание
data	data.Manager	Данные выпадающего списка. Имена полей, доступных через метод data.Manager.get: title - заголовок выпадающего списка.
events	IEventManager	Менеджер событий. Унаследовано от IEventEmitter.
options	IOptionManager	Менеджер опций. Унаследовано от ICustomizable.
state	data.Manager	Состояние выпадающего списка. Имена полей, доступных через метод data.Manager.get: expanded - признак, раскрыт ли список.


Имя	Тип	Описание
data	data.Manager	Данные выпадающего списка. Имена полей, доступных через метод data.Manager.get: title - заголовок выпадающего списка.
events	IEventManager	Менеджер событий. Унаследовано от IEventEmitter.
options	IOptionManager	Менеджер опций. Унаследовано от ICustomizable.
state	data.Manager	Состояние выпадающего списка. Имена полей, доступных через метод data.Manager.get: expanded - признак, раскрыт ли список.

События


Имя	Описание
add	Произошло добавление дочернего объекта. Унаследовано от ICollection.
childcontainerchange	Изменение дом-элемента, в который добавляются дочерние элементы группы. Экземпляр класса Event. Имена полей, доступных через метод Event.get: newChildContainerElement - новый дом-элемент для дочерних элементов; oldChildContainerElement - старый элемент для дочерних элементов. Унаследовано от control.Group.
click	Щелчок по заголовку списка. Экземпляр класса Event.
collapse	Список закрыт. Экземпляр класса Event.
expand	Список открыт. Экземпляр класса Event.
mapchange	Сменилась карта. Поля данных: oldMap - старая карта; newMap - новая карта. Унаследовано от IParentOnMap.
optionschange	Изменение в опциях объекта. Унаследовано от ICustomizable.
parentchange	Сменился родительский объект. Поля данных: oldParent - старый родитель; newParent - новый родитель. Унаследовано от IChild.
remove	Произошло удаление дочернего объекта. Унаследовано от ICollection.


Имя	Описание
add	Произошло добавление дочернего объекта. Унаследовано от ICollection.
childcontainerchange	Изменение дом-элемента, в который добавляются дочерние элементы группы. Экземпляр класса Event. Имена полей, доступных через метод Event.get: newChildContainerElement - новый дом-элемент для дочерних элементов; oldChildContainerElement - старый элемент для дочерних элементов. Унаследовано от control.Group.
click	Щелчок по заголовку списка. Экземпляр класса Event.
collapse	Список закрыт. Экземпляр класса Event.
expand	Список открыт. Экземпляр класса Event.
mapchange	Сменилась карта. Поля данных: oldMap - старая карта; newMap - новая карта. Унаследовано от IParentOnMap.
optionschange	Изменение в опциях объекта. Унаследовано от ICustomizable.
parentchange	Сменился родительский объект. Поля данных: oldParent - старый родитель; newParent - новый родитель. Унаследовано от IChild.
remove	Произошло удаление дочернего объекта. Унаследовано от ICollection.

Методы


Имя	Возвращает	Описание
add(item[, positionIndex])	control.Group	Добавляет элемент управления в группу. Элемент можно добавлять, передав экземпляр класса, реализующего интерфейс IControl, или по ключу. Возожные значения ключей: "mapTools" - стандартный тулбар с кнопками "Навигация", "Выделение" и "Линейка" control.MapTools; "miniMap" - обзорная карта control.MiniMap; "scaleLine" - масштабный отрезок control.ScaleLine; "searchControl" - панель поиска control.SearchControl; "trafficControl" - панель пробок control.TrafficControl; "typeSelector" - панель переключения типа карты control.TypeSelector; "zoomControl" - ползунок масштаба control.ZoomControl; "smallZoomControl" - простой ползунок масштаба control.SmallZoomControl. Унаследован от control.Group.
collapse()		Сворачивает список.
each(callback[, context])	control.Group	Перебирает все элементы коллекции, вызывая для каждого функцию-обработчик. Унаследован от control.Group.
expand()		Раскрывает список.
filter(callback)	IChildOnMap[]	Функция для выборки дочерних элементов по условию. Унаследован от control.Group.
get()	IChildOnMap	Returns ссылку на объект контрола, добавленного по ключу или по индексу. Унаследован от control.Group.
getAll()	IChildOnMap[]	Returns массив дочерних элементов контрола. Унаследован от control.Group.
getChildElement(child)	HTMLElement	Возвращает для своего дочернего объекта HTML-элемент, в котором он должен размещаться. Унаследован от IControlParent.
getContainer()	HTMLElement	Returns контейнер, в который добавляются дочерние элементы контрола. Унаследован от control.Group.
getIterator()	IIterator	Returns итератор по коллекции. Унаследован от ICollection.
getLength()	Number	Returns количество дочерних элементов. Унаследован от control.Group.
getMap()	Map	Returns ссылку на карту. Унаследован от IParentOnMap.
getParent()	IControlParent	Returns ссылку на родительский объект. Унаследован от IControl.
indexOf(childToFind)	Integer	Returns индекс дочернего элемента в группе. Унаследован от control.Group.
isExpanded()	Boolean	Returns признак того, находится ли контрол в развернутом состоянии.
remove(item)	control.Group	Удаляет элемент управления из группы. Унаследован от control.Group.
removeAll()	control.Group	Удаляет все дочерние элементы из группы. Унаследован от control.Group.
setMinWidth(width)		Устанавливает ширину списка.
setParent(parent)	IChildOnMap	Устанавливает родительский объект. Унаследован от IControl.
setTitle(html)		Задает новый заголовок раскрывающегося списка.


Имя	Возвращает	Описание
add(item[, positionIndex])	control.Group	Добавляет элемент управления в группу. Элемент можно добавлять, передав экземпляр класса, реализующего интерфейс IControl, или по ключу. Возожные значения ключей: "mapTools" - стандартный тулбар с кнопками "Навигация", "Выделение" и "Линейка" control.MapTools; "miniMap" - обзорная карта control.MiniMap; "scaleLine" - масштабный отрезок control.ScaleLine; "searchControl" - панель поиска control.SearchControl; "trafficControl" - панель пробок control.TrafficControl; "typeSelector" - панель переключения типа карты control.TypeSelector; "zoomControl" - ползунок масштаба control.ZoomControl; "smallZoomControl" - простой ползунок масштаба control.SmallZoomControl. Унаследован от control.Group.
collapse()		Сворачивает список.
each(callback[, context])	control.Group	Перебирает все элементы коллекции, вызывая для каждого функцию-обработчик. Унаследован от control.Group.
expand()		Раскрывает список.
filter(callback)	IChildOnMap[]	Функция для выборки дочерних элементов по условию. Унаследован от control.Group.
get()	IChildOnMap	Returns ссылку на объект контрола, добавленного по ключу или по индексу. Унаследован от control.Group.
getAll()	IChildOnMap[]	Returns массив дочерних элементов контрола. Унаследован от control.Group.
getChildElement(child)	HTMLElement	Возвращает для своего дочернего объекта HTML-элемент, в котором он должен размещаться. Унаследован от IControlParent.
getContainer()	HTMLElement	Returns контейнер, в который добавляются дочерние элементы контрола. Унаследован от control.Group.
getIterator()	IIterator	Returns итератор по коллекции. Унаследован от ICollection.
getLength()	Number	Returns количество дочерних элементов. Унаследован от control.Group.
getMap()	Map	Returns ссылку на карту. Унаследован от IParentOnMap.
getParent()	IControlParent	Returns ссылку на родительский объект. Унаследован от IControl.
indexOf(childToFind)	Integer	Returns индекс дочернего элемента в группе. Унаследован от control.Group.
isExpanded()	Boolean	Returns признак того, находится ли контрол в развернутом состоянии.
remove(item)	control.Group	Удаляет элемент управления из группы. Унаследован от control.Group.
removeAll()	control.Group	Удаляет все дочерние элементы из группы. Унаследован от control.Group.
setMinWidth(width)		Устанавливает ширину списка.
setParent(parent)	IChildOnMap	Устанавливает родительский объект. Унаследован от IControl.
setTitle(html)		Задает новый заголовок раскрывающегося списка.

Описание полей

data

{data.Manager} data

Данные выпадающего списка. Имена полей, доступных через метод data.Manager.get:

title - заголовок выпадающего списка.

Пример:

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

// Создадим группу слушателей событий.
var listBoxListener = listBox.events.group()
    .add('expand', function () {
        listBox.data.set('title', 'Список развернут');   
    })
    .add('collapse', function () {
        listBox.data.set('title', 'Список свернут');
    });
map.controls.add(listBox, {top: 10, left: 10});
// ...
map.controls.remove(listBox);
// После удаления элемента с карты удалим слушателей.
listBoxListener.removeAll();

state

{data.Manager} state

Состояние выпадающего списка. Имена полей, доступных через метод data.Manager.get:

expanded - признак, раскрыт ли список.

Пример:

// Создадим и добавим на карту список, который изначально открыт.
var listBox = new ymaps.control.ListBox();
listBox.state.set('expanded', true);
map.controls.add(listBox);

Описание событий

click

Щелчок по заголовку списка. Экземпляр класса Event.

collapse

Список закрыт. Экземпляр класса Event.

expand

Список открыт. Экземпляр класса Event.

Описание методов

collapse

{} collapse()

Сворачивает список.

expand

{} expand()

Раскрывает список.

isExpanded

{Boolean} isExpanded()

Returns признак того, находится ли контрол в развернутом состоянии.

setMinWidth

{} setMinWidth(width)

Устанавливает ширину списка.

Параметры:


Параметр	Значение по умолчанию	Описание
width *	—	Тип: Number Ширина списка.

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

setTitle

{} setTitle(html)

Задает новый заголовок раскрывающегося списка.

Параметры:


Параметр	Значение по умолчанию	Описание
html *	—	Тип: String Заголовок.

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

Была ли статья полезна?

Расскажите, что вам не понравилось в статье: