Элементы управления

Элемент управления — визуальный объект, связанный с картой и предназначенный для взаимодействия с пользователем. В большинстве случаев элементы управления размещаются в области показа карты.

API карт включает в себя набор встроенных элементов управления (выбор типа карты, ползунок изменения масштаба и пр.) и предоставляет возможность определения собственных.

Компоненты, предназначенные для создания элементов управления, реализованы в виде классов, находящихся в пространстве имен control (например, control.Button).

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

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

var myMap = new ymaps.Map("map", {
    center: [59.93772, 30.313622],
    zoom: 8
});

// Создание экземпляра элемента управления
myMap.controls.add(
   new ymaps.control.ZoomControl()
);

// Обращение к конструктору класса элемента
// управления по ключу
myMap.controls.add('typeSelector');
 
var myMap = new ymaps.Map("map", {
    center: [59.93772, 30.313622],
    zoom: 8
});

// Создание экземпляра элемента управления
myMap.controls.add(
   new ymaps.control.ZoomControl()
);

// Обращение к конструктору класса элемента
// управления по ключу
myMap.controls.add('typeSelector');

Стандартные элементы управления

Элемент управления Описание

Стандартный набор кнопок

 Панель инструментов со стандартным набором кнопок: перетягивание карты (drag), увеличение выделенной области, измерение расстояний.

Пример

Добавление на карту панели инструментов со стандартным набором кнопок:

myMap.controls.add('mapTools');

или

myMap.controls.add(new ymaps.control.MapTools());
Редактор маршрута.

Пример

Добавление на карту редактора маршрута:

myMap.controls.add('routeEditor');
или
myMap.controls.add(new ymaps.control.RouteEditor());

Выбор типа карты

 Переключатель отображаемого типа карты.

Пример

Добавление на карту переключателя типа карты (в выпадающем списке будут отображены все допустимые типы):

myMap.controls.add('typeSelector');

Добавление на карту переключателя типа карты (в выпадающем списке будут отображены только указанные типы):

myMap.controls.add(new ymaps.control.TypeSelector(['yandex#map', 'yandex#publicMap']));

Ползунок масштаба

Изменение коэффициента масштабирования.

Две кнопки для увеличения/уменьшения коэффициента масштабирования на единицу и ползунок масштаба.

Пример

Добавление на карту панели изменения масштаба:

myMap.controls.add('zoomControl');

или

myMap.controls.add(new ymaps.control.ZoomControl());

Кнопки изменения масштаба

Изменение коэффициента масштабирования — компактный вариант.

Две кнопки, одна из которых увеличивает коэффициент масштабирования на единицу, вторая — уменьшает на единицу.

Пример

Добавление на карту кнопок изменения масштаба:

myMap.controls.add('smallZoomControl');

или

myMap.controls.add(new ymaps.control.SmallZoomControl());

Масштабная линейка

Отображает на карте масштабный отрезок и показывает его длину в используемых географических единицах измерениях.

Позволяет визуально оценить расстояние между объектами.

Пример

Добавление на карту масштабной линейки:

myMap.controls.add('scaleLine');

или

myMap.controls.add(new ymaps.control.ScaleLine());

Обзорная карта

Уменьшенная карта местности, коэффициент масштаб которой на заданное количество единиц меньше основного.

Тип обзорной карты может отличаться от типа основной карты.

Пример

Добавление обзорной карты:

myMap.controls.add('miniMap');

Добавление обзорной карты с заданными параметрами:

myMap.controls.add(new ymaps.control.MiniMap({type:'yandex#hybrid'},{zoomOffset: 3}));

Поиск по карте

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

Пример

Добавление на карту поисковой строки:

myMap.controls.add('searchControl');

Добавление на карту поисковой строки с заданными параметрами:

myMap.controls.add(new ymaps.control.SearchControl({provider: 'yandex#publicMap',  useMapBounds: true}));

Пробки

Отображение пробок на карте.

Позволяет включать/отключать отображение на карте слоя пробок.

Пример

Добавление на карту элемента управления «Пробки»:

myMap.controls.add('trafficControl');

Добавление на карту элемента управления «Пробки» с указанным источником пробок (будут показаны пробки «обычно»):

myMap.controls.add(new ymaps.control.TrafficControl({providerKey: 'traffic#archive'}));
Элемент управления Описание

Стандартный набор кнопок

 Панель инструментов со стандартным набором кнопок: перетягивание карты (drag), увеличение выделенной области, измерение расстояний.

Пример

Добавление на карту панели инструментов со стандартным набором кнопок:

myMap.controls.add('mapTools');

или

myMap.controls.add(new ymaps.control.MapTools());
Редактор маршрута.

Пример

Добавление на карту редактора маршрута:

myMap.controls.add('routeEditor');
или
myMap.controls.add(new ymaps.control.RouteEditor());

Выбор типа карты

 Переключатель отображаемого типа карты.

Пример

Добавление на карту переключателя типа карты (в выпадающем списке будут отображены все допустимые типы):

myMap.controls.add('typeSelector');

Добавление на карту переключателя типа карты (в выпадающем списке будут отображены только указанные типы):

myMap.controls.add(new ymaps.control.TypeSelector(['yandex#map', 'yandex#publicMap']));

Ползунок масштаба

Изменение коэффициента масштабирования.

Две кнопки для увеличения/уменьшения коэффициента масштабирования на единицу и ползунок масштаба.

Пример

Добавление на карту панели изменения масштаба:

myMap.controls.add('zoomControl');

или

myMap.controls.add(new ymaps.control.ZoomControl());

Кнопки изменения масштаба

Изменение коэффициента масштабирования — компактный вариант.

Две кнопки, одна из которых увеличивает коэффициент масштабирования на единицу, вторая — уменьшает на единицу.

Пример

Добавление на карту кнопок изменения масштаба:

myMap.controls.add('smallZoomControl');

или

myMap.controls.add(new ymaps.control.SmallZoomControl());

Масштабная линейка

Отображает на карте масштабный отрезок и показывает его длину в используемых географических единицах измерениях.

Позволяет визуально оценить расстояние между объектами.

Пример

Добавление на карту масштабной линейки:

myMap.controls.add('scaleLine');

или

myMap.controls.add(new ymaps.control.ScaleLine());

Обзорная карта

Уменьшенная карта местности, коэффициент масштаб которой на заданное количество единиц меньше основного.

Тип обзорной карты может отличаться от типа основной карты.

Пример

Добавление обзорной карты:

myMap.controls.add('miniMap');

Добавление обзорной карты с заданными параметрами:

myMap.controls.add(new ymaps.control.MiniMap({type:'yandex#hybrid'},{zoomOffset: 3}));

Поиск по карте

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

Пример

Добавление на карту поисковой строки:

myMap.controls.add('searchControl');

Добавление на карту поисковой строки с заданными параметрами:

myMap.controls.add(new ymaps.control.SearchControl({provider: 'yandex#publicMap',  useMapBounds: true}));

Пробки

Отображение пробок на карте.

Позволяет включать/отключать отображение на карте слоя пробок.

Пример

Добавление на карту элемента управления «Пробки»:

myMap.controls.add('trafficControl');

Добавление на карту элемента управления «Пробки» с указанным источником пробок (будут показаны пробки «обычно»):

myMap.controls.add(new ymaps.control.TrafficControl({providerKey: 'traffic#archive'}));

Пользовательские элементы управления

API предоставляет возможность создания собственных элементов управления, позволяющих выполнить произвольные действия.

Наиболее часто элементы управления реализуются в виде кнопок. Для создания кнопочного элемента управления предназначен класс control.Button.

Поддерживается два типа реакций на нажатие кнопки: после нажатия кнопка остается нажатой (поведение по умолчанию) или возвращается в исходное состояние. Тип реакции на нажатие задается опцией selectOnClick (true/false).

При нажатии на кнопку всегда генерируется событие click. Для кнопок, запоминающих свое состояние после нажатия, дополнительно генерируется событие select или deselect (в зависимости от того, в каком состоянии кнопка находилась в момент нажатия).
var myButton = new ymaps.control.Button('<b>Я<b>');
myButton.events
    .add('click', function () { alert('Щёлк'); })
    .add('select', function () { alert('Нажата'); })
    .add('deselect', function () { alert('Отжата'); });
myMap.controls.add(myButton);
 
var myButton = new ymaps.control.Button({
    data: {
        content: 'Или <em>Я</em>',
        title: 'отжимаюсь сама'
    }
}, {
    selectOnClick: false
   }
);
myButton.events
    .add('click', function () {
        alert('Щёлк'); });
myMap.controls.add(myButton);
 
var myButton = new ymaps.control.Button('<b>Я<b>');
myButton.events
    .add('click', function () { alert('Щёлк'); })
    .add('select', function () { alert('Нажата'); })
    .add('deselect', function () { alert('Отжата'); });
myMap.controls.add(myButton);
 
var myButton = new ymaps.control.Button({
    data: {
        content: 'Или <em>Я</em>',
        title: 'отжимаюсь сама'
    }
}, {
    selectOnClick: false
   }
);
myButton.events
    .add('click', function () {
        alert('Щёлк'); });
myMap.controls.add(myButton);

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

Для определения собственных элементов управления предназначен интерфейс IControl. Для элементов управления, которые могут находиться в только в двух состояниях удобно использовать интерфейс ISelectableControl, расширяющий IControl.

Составные элементы управления и группировка

API Яндекс.Карт включает в себя набор компонентов, позволяющих создавать составные элементы управления, визуально объединяя включенные в них элементы.

Список классов для создания составных элементов приведен в таблице.

Элемент управления Описание

Горизонтальная панель

Панель инструментов, элементы которых расположены горизонтально.

Чаще всего на горизонтальной панели размещаются кнопки.

Классы:

control.ToolBar — контейнер элементов;

control.ToolBarSeparator — разделитель элементов панели.

Пример

var myToolBar = new ymaps.control.ToolBar();
myToolBar.add(new ymaps.control.Button('Красный'))
    .add(new ymaps.control.Button('Жёлтый'))
    .add(new ymaps.control.ToolBarSeparator())
    .add(new ymaps.control.Button('Зелёный'));

myMap.controls.add(myToolBar);

Панель переключаемых элементов

Панель элементов, каждый из которых может находиться только в двух состояниях (ISelectableControl).

Класс control.RadioGroup.

Пример

var myRadioGroup = new ymaps.control.RadioGroup({
    items: [
        new ymaps.control.Button('Наше'),
        new ymaps.control.Button('Маяк'),
        new ymaps.control.Button('Европа +')
    ]
});

myMap.controls.add(myRadioGroup);

Раскрывающаяся панель

Панель элементов, вертикально раскрывающаяся при наведении курсора на первый элемент.

Класс control.RollupButton.

Пример

var myRollupButton = new ymaps.control.RollupButton({
    items: [
        new ymaps.control.Button('Раз'),
        new ymaps.control.Button('Два'),
        new ymaps.control.Button('Три')
    ]
});

myMap.controls.add(myRollupButton);

Выпадающий список

Выпадающий список.

Классы:

control.ListBox — контейнер элементов;

control.ListBoxItem — элемент списка;

control.ListBoxSeparator — разделитель элементов списка.

Пример

var myListBox = new ymaps.control.ListBox({
  data: {
    content: 'Выбрать город'
  },
  items: [
    new ymaps.control.ListBoxItem('Москва'),
    new ymaps.control.ListBoxItem('Новосибирск'),
    new ymaps.control.ListBoxSeparator(),
    new ymaps.control.ListBoxItem('Нью-Йорк')
  ]
});

myMap.controls.add(myListBox);
Элемент управления Описание

Горизонтальная панель

Панель инструментов, элементы которых расположены горизонтально.

Чаще всего на горизонтальной панели размещаются кнопки.

Классы:

control.ToolBar — контейнер элементов;

control.ToolBarSeparator — разделитель элементов панели.

Пример

var myToolBar = new ymaps.control.ToolBar();
myToolBar.add(new ymaps.control.Button('Красный'))
    .add(new ymaps.control.Button('Жёлтый'))
    .add(new ymaps.control.ToolBarSeparator())
    .add(new ymaps.control.Button('Зелёный'));

myMap.controls.add(myToolBar);

Панель переключаемых элементов

Панель элементов, каждый из которых может находиться только в двух состояниях (ISelectableControl).

Класс control.RadioGroup.

Пример

var myRadioGroup = new ymaps.control.RadioGroup({
    items: [
        new ymaps.control.Button('Наше'),
        new ymaps.control.Button('Маяк'),
        new ymaps.control.Button('Европа +')
    ]
});

myMap.controls.add(myRadioGroup);

Раскрывающаяся панель

Панель элементов, вертикально раскрывающаяся при наведении курсора на первый элемент.

Класс control.RollupButton.

Пример

var myRollupButton = new ymaps.control.RollupButton({
    items: [
        new ymaps.control.Button('Раз'),
        new ymaps.control.Button('Два'),
        new ymaps.control.Button('Три')
    ]
});

myMap.controls.add(myRollupButton);

Выпадающий список

Выпадающий список.

Классы:

control.ListBox — контейнер элементов;

control.ListBoxItem — элемент списка;

control.ListBoxSeparator — разделитель элементов списка.

Пример

var myListBox = new ymaps.control.ListBox({
  data: {
    content: 'Выбрать город'
  },
  items: [
    new ymaps.control.ListBoxItem('Москва'),
    new ymaps.control.ListBoxItem('Новосибирск'),
    new ymaps.control.ListBoxSeparator(),
    new ymaps.control.ListBoxItem('Нью-Йорк')
  ]
});

myMap.controls.add(myListBox);
В общем случае для группировки элементов управления предназначен класс control.Group (все приведенные в таблице составные элементы его наследуют). С его помощью можно задавать общие для всех элементов группы свойства и проводить групповые операции над ними.
var myControlGroup = new ymaps.control.Group({
    items: [
        new ymaps.control.Button('Первый'),
        new ymaps.control.Button('Второй'),
        new ymaps.control.Button('Расчет окончен')
    ]
}, {selectOnClick: false});

myControlGroup.events.add(['click'], function (e) {
    alert(e.get('target').data.get('content'));
});