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

# control.ListBox

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

Класс для создания элемента управления в виде раскрывающегося списка. Стандартный макет выпадающего списка изменяет свой внешний вид в зависимости от размеров карты. Если карта имеет большую ширину, то в заголовке выпадающего списка отображается текст. Если карта небольшого размера, то в заголовке списка отображается только иконка. Если для кнопки не задана иконка, то во всех состояниях будет отображаться текст и наоборот.

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

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

```javascript
control.ListBox([parameters])
```

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

#|
|| **Параметр** | **Значение по умолчанию** | **Описание**  ||
|| [`parameters`](#param-parameters) | — | Тип: Object

Параметры выпадающего списка. ||
|| [`parameters.data`](#param-parameters.data) | — | Тип: Object

Данные. ||
|| [`parameters.data.content`](#param-parameters.data.content) | — | Тип: String

Заголовок списка. ||
|| [`parameters.data.image`](#param-parameters.data.image) | — | Тип: String

URL иконки кнопки. Стандартный макет кнопки рассчитан на иконку размером 16x16 пикселей. ||
|| [`parameters.data.title`](#param-parameters.data.title) | — | Тип: String

Текст всплывающей подсказки, которая появляется при наведении на список курсора мыши. ||
|| [`parameters.items`](#param-parameters.items) | — | Тип: [IControl](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IControl.md)[]

Массив дочерних элементов списка. ||
|| [`parameters.options`](#param-parameters.options) | — | Тип: Object

Опции элемента управления. ||
|| [`parameters.options.adjustMapMargin`](#param-parameters.options.adjustMapMargin) | false | Тип: Boolean

Регистрирует ли элемент управления свои размеры в менеджере отступов карты [map.margin.Manager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/map.margin.Manager.md). ||
|| [`parameters.options.collapseOnBlur`](#param-parameters.options.collapseOnBlur) | true | Тип: Boolean

Флаг, включающий сворачивание списка, когда кнопка теряет фокус (например, когда пользователь кликнул на другом элементе страницы). ||
|| [`parameters.options.expandOnClick`](#param-parameters.options.expandOnClick) | true | Тип: Boolean

Флаг, разрешающий автоматическое разворачивание/сворачивание списка по клику. ||
|| [`parameters.options.float`](#param-parameters.options.float) | "right" | Тип: String

Сторона, по которой нужно выравнивать элемент управления. Может принимать три значения: "left", "right" или "none". При значении "left" или "right" элементы управления выстраиваются друг за другом, начиная от левого или правого края карты соответственно. При значении "none" элементы управления позиционируется только по значениям опций left, right, bottom, top относительно границ карты. Также смотрите описание опции position. ||
|| [`parameters.options.floatIndex`](#param-parameters.options.floatIndex) | 0 | Тип: Number

Приоритет расположения элемента управления. Элемент с максимальным приоритетом находится ближе к указанному в свойстве float краю карты. Не работает при float = "none". ||
|| [`parameters.options.layout`](#param-parameters.options.layout) | — | Тип: Function\|String

Конструктор макета элемента управления, реализующий интерфейсы [ISelectableControlLayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ISelectableControlLayout.md) и [IGroupControlLayout](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IGroupControlLayout.md) или ключ макета в хранилище [layout.storage](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/layout.storage.md). В конструктор макета передается объект, содержащий поля:
- control - ссылка на элемент управления;
- options - менеджер опций элемента управления control.ListBox.options;
- data - менеджер данных элемента управления [control.ListBox.data](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#data);
- state - менеджер состояния элемента управления [control.ListBox.state](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#state).
Макет меняет свой внешний вид на основе данных, состояния и опций элемента управления. Элемент управления, в свою очередь, реагирует на интерфейсные события макета и меняет значения полей [control.ListBox.state](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#state) в зависимости от полученных команд. ||
|| [`parameters.options.maxWidth`](#param-parameters.options.maxWidth) | 90 | Тип: Number\|Number[]

Максимальная ширина кнопки списка при различных состояниях. Если задано число, то считается, что кнопка имеет одинаковые максимальные размеры во всех состояниях. Если задан массив, то он будет трактоваться как максимальная ширина кнопки в различных состояниях - от меньшего к большему. Количество доступных состояний задается в экземпляре класса [control.Manager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.Manager.md) через опцию states. Этот класс обычно является полем [Map.controls](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Map.md#controls). По умолчанию у элементов управления есть три состояния - ['small', 'medium', 'large']. ||
|| [`parameters.options.popupFloat`](#param-parameters.options.popupFloat) | — | Тип: String

Сторона, по которой нужно выравнивать попап элемента управления. Может принимать два значения: "left" и "right". По умолчанию определяется согласно опции "float". ||
|| [`parameters.options.position`](#param-parameters.options.position) | — | Тип: Object

Объект, описывающий позицию элемента управления. При указании опции position значение опции float автоматически трактуется как "none". ||
|| [`parameters.options.position.bottom`](#param-parameters.options.position.bottom) | 'auto' | Тип: Number\|String

Положение относительно нижнего края карты. ||
|| [`parameters.options.position.left`](#param-parameters.options.position.left) | 'auto' | Тип: Number\|String

Положение относительно левого края карты. ||
|| [`parameters.options.position.right`](#param-parameters.options.position.right) | 'auto' | Тип: Number\|String

Положение относительно правого края карты. ||
|| [`parameters.options.position.top`](#param-parameters.options.position.top) | 'auto' | Тип: Number\|String

Положение относительно верхнего края карты. ||
|| [`parameters.options.visible`](#param-parameters.options.visible) | true | Тип: Boolean

Признак того, что элемент управления отображается. ||
|| [`parameters.state`](#param-parameters.state) | — | Тип: Object

Состояние выпадающего списка. ||
|| [`parameters.state.expanded`](#param-parameters.state.expanded) | false | Тип: Boolean

Признак, развернут ли список. ||
|#


**Примеры:** 

**1.**

```javascript
// Пример 1.
// Обработка нажатия на элементы списка.
var cityList = new ymaps.control.ListBox({
    data: {
        content: 'Выберите город'
    },
    items: [
        new ymaps.control.ListBoxItem('Москва'),
        new ymaps.control.ListBoxItem('Новосибирск'),
        new ymaps.control.ListBoxItem({options: {type: 'separator'}}),
        new ymaps.control.ListBoxItem('Нью-Йорк'),
    ]
});
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, { floatIndex: 0 });
```

**2.**

```javascript
// Пример 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" style="display: {% if state.expanded %}block{% else %}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({options: {layout: MyListBoxLayout}});
```

**3.**

```javascript
// Пример 3.
// Использование элемента управления ListBox в качестве фильтра
// для отображения объектов на карте (поддерживается мультивыбор).
// Объекты добавляются на карту с помощью ObjectManager.

// Создание выпадающего списка с 5 элементами.
var listBoxItems = ['Школа', 'Аптека', 'Магазин', 'Больница', 'Бар']
    .map(function(title) {
        return new ymaps.control.ListBoxItem({
            data: {
                content: title
            },
            state: {
                selected: true
            }
        });
    });

// Теперь создаем выпадающий список из 5 пунктов.
var listBoxControl = new ymaps.control.ListBox({
    data: {
        content: 'Filter',
        title: 'Filter'
    },
    items: listBoxItems,
    state: {
        // Указывает, что список расширен.
        expanded: true,
        filters: listBoxItems.reduce(function(filters, filter) {
            filters[filter.data.get('content')] = filter.isSelected();
            return filters;
        }, {})
    }
});

map.controls.add(listBoxControl);

// Добавление отслеживания к индикатору для проверки того, выбран ли элемент списка.
listBoxControl.events.add(['select', 'deselect'], function(e) {
    var listBoxItem = e.get('target');
    var filters = ymaps.util.extend({}, listBoxControl.state.get('filters'));
    filters[listBoxItem.data.get('content')] = listBoxItem.isSelected();
    listBoxControl.state.set('filters', filters);
});

// Отслеживание изменений в элементе управления.список.государственное поле.
var filterMonitor = new ymaps.Monitor(listBoxControl.state);

filterMonitor.add('filters', function(filters) {
    // Применение фильтра к ObjectManager.
    objectManager.setFilter(getFilterFunction(filters));
});

function getFilterFunction(categories){
    return function(obj){
        var content = obj.properties.balloonContent;
        return categories[content]
    }
}
```

## Поля {#properties-summary}

#|
|| **Имя** | **Тип** | **Описание** ||
|| [data](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#data) | [data.Manager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/data.Manager.md) | Данные выпадающего списка. Имена полей, доступных через метод data.Manager.get:
- content - заголовок выпадающего списка;
- title - текст всплывающей подсказки, которая появляется при наведении на список курсора мыши. ||
|| [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/IControl.md#options) | [IOptionManager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IOptionManager.md) | Менеджер опций.

Унаследовано от [IControl](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IControl.md#options). ||
|| [state](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#state) | [data.Manager](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/data.Manager.md) | Состояние выпадающего списка. Имена полей, доступных через метод data.Manager.get:
- expanded - признак, раскрыт ли список;
- size - размер, который в данный момент выставлен списку; ||
|#

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

#|
|| **Имя** | **Описание** ||
|| [add](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#event-add) | Произошло добавление дочернего объекта.

Унаследовано от [ICollection](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#event-add). ||
|| [click](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#event-click) | Щелчок по заголовку списка. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md). ||
|| [collapse](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#event-collapse) | Список закрыт. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md). ||
|| [expand](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#event-expand) | Список открыт. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md). ||
|| [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). ||
|| [parentchange](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IChild.md#event-parentchange) | Сменился родительский объект.

Поля данных:

- oldParent - старый родитель;
- newParent - новый родитель.

Унаследовано от [IChild](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IChild.md#event-parentchange). ||
|| [press](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#event-press) | Событие, сигнализирующее о том, что кнопка была нажата. В отличии от click генерируется только если состояние isEnabled == true. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md). ||
|| [remove](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#event-remove) | Произошло удаление дочернего объекта.

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

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

#|
|| **Имя** | **Возвращает** | **Описание** ||
|| [add](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#add)([object](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#add-param-object)) | [ICollection](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md) | Добавляет в коллекцию дочерний объект.

Унаследован от [ICollection](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#add). ||
|| [collapse](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#collapse)() | [control.ListBox](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md) | Сворачивает список. ||
|| [expand](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#expand)() | [control.ListBox](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md) | Раскрывает список. ||
|| [getIterator](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#getIterator)() | [IIterator](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IIterator.md) | Возвращает итератор по коллекции.

Унаследован от [ICollection](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#getIterator). ||
|| [getMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#getMap)() | [Map](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Map.md) | Возвращает ссылку на карту. ||
|| [getParent](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IControl.md#getParent)() | [IControlParent](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IControlParent.md)\|null | Возвращает ссылку на родительский объект или null, если родительский элемент не был установлен.

Унаследован от [IControl](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IControl.md#getParent). ||
|| [isExpanded](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md#isExpanded)() | Boolean | Возвращает признак того, находится ли контрол в развернутом состоянии. ||
|| [remove](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#remove)([object](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#remove-param-object)) | [ICollection](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md) | Удаляет из коллекции дочерний объект.

Унаследован от [ICollection](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/ICollection.md#remove). ||
|| [setParent](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IControl.md#setParent)([parent](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IControl.md#setParent-param-parent)) | [IChildOnMap](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IChildOnMap.md) | Устанавливает родительский объект. Если передать значение null, то элемент управления будет только удален из текущего родительского объекта.

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

## Описание полей {#field_detail}

### data {#data}

```javascript
{data.Manager} data
```

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

**Пример:** 

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

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

### state {#state}

```javascript
{data.Manager} state
```

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

**Пример:** 

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

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

### click {#click}

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

### collapse {#collapse}

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

### expand {#expand}

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

### press {#press}

Событие, сигнализирующее о том, что кнопка была нажата. В отличии от click генерируется только если состояние isEnabled == true. Экземпляр класса [Event](https://yandex.com.tr/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/Event.md).

## Описание методов {#method_detail}

### collapse {#collapse}

```javascript
{control.ListBox} collapse()
```

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

**Возвращает** ссылку на себя.

### expand {#expand}

```javascript
{control.ListBox} expand()
```

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

**Возвращает** ссылку на себя.

### getMap {#getMap}

```javascript
{Map} getMap()
```

**Возвращает** ссылку на карту.

### isExpanded {#isExpanded}

```javascript
{Boolean} isExpanded()
```

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

<!-- XLIFF_FARM_ZGFmMmFl_CACHING -->