Документация
Справочник JavaScript API
2.1.50 (текущая версия)
collection
interactivityModel
Интерфейсы
2.1.52 (релиз-кандидат)
collection
interactivityModel
Интерфейсы

control.Button

Расширяет ICustomizable, ISelectableControl.

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

Конструктор | Поля | События | Методы

Конструктор

control.Button([parameters])

Параметры:

ПараметрЗначение по умолчаниюОписание
parameters

Тип: Object|String

Параметры кнопки или строка - содержимое кнопки в виде HTML.

parameters.data

Тип: Object

Данные кнопки.

parameters.data.content

Тип: String

Содержимое кнопки в виде HTML.

parameters.data.image

Тип: String

URL иконки кнопки. Стандартный макет кнопки рассчитан на иконку размером 16x16 пикселей.

parameters.data.title

Тип: String

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

parameters.options

Тип: Object

Опции кнопки.

parameters.options.adjustMapMargin false

Тип: Boolean

Регистрирует ли кнопка свои размеры в менеджере отступов карты map.margin.Manager.

parameters.options.float "right"

Тип: String

Сторона, по которой нужно выравнивать элемент управления. Может принимать три значения: "left", "right" или "none". При значении "left" или "right" элементы управления выстраиваются друг за другом, начиная от левого или правого края карты соответственно. При значении "none" элементы управления позиционируется только по значениям опций left, right, bottom, top относительно границ карты. Также смотрите описание опции position.

parameters.options.floatIndex 0

Тип: Number

Приоритет расположения элемента управления. Элемент с максимальным приоритетом находится ближе к указанному в свойстве float краю карты. Не работает при float = "none".

parameters.options.layout

Тип: ISelectableControlLayout|String

Конструктор макета элемента управления, реализующий интерфейс ISelectableControlLayout или ключ макета в хранилище layout.storage. В конструктор макета передается объект, содержащий поля:

  • control - ссылка на элемент управления;
  • options - менеджер опций элемента управления control.Button.options;
  • data - менеджер данных элемента управления control.Button.data;
  • state - менеджер состояния элемента управления control.Button.state.
Макет меняет свой внешний вид на основе данных, состояния и опций элемента управления. Элемент управления, в свою очередь, реагирует на интерфейсные события макета и меняет значения полей control.Button.state в зависимости от полученных команд.

parameters.options.maxWidth 90

Тип: Number[][]|Number[]

Максимальная ширина кнопки в различных состояниях. Если задано число, то считается, что кнопка имеет одинаковые максимальные размеры во всех состояниях. Если задан массив, то он будет трактоваться как максимальная ширина кнопки в различных состояниях - от меньшего к большему. Количество доступных состояний задается в экземпляре класса control.Manager через опцию states. Этот класс обычно является полем Map.controls. По умолчанию у элементов управления есть три состояния - ['small', 'medium', 'large'].

parameters.options.position

Тип: Object

Объект, описывающий позицию элемента управления. При указании опции position значение опции float автоматически трактуется как "none".

parameters.options.position.bottom 'auto'

Тип: Number|String

Положение относительно нижнего края карты.

parameters.options.position.left 'auto'

Тип: Number|String

Положение относительно левого края карты.

parameters.options.position.right 'auto'

Тип: Number|String

Положение относительно правого края карты.

parameters.options.position.top 'auto'

Тип: Number|String

Положение относительно верхнего края карты.

parameters.options.selectOnClick true

Тип: Boolean

Опция, описывающая поведение кнопки.

  • true — кнопка становится "нажатой" после клика, то есть меняется ее внешний вид и значение поля control.Button.state устанавливается в 'selected';
  • false - кнопка не меняет свой внешний вид и состояние после клика на нее.

parameters.options.size 'auto'

Тип: String

Параметр, отвечающий за внешний вид стандартного макета кнопки. Может принимать значения:

  • 'auto' - стандартный макет кнопки автоматически изменяет свой внешний вид в зависимости от размеров карты и от количества добавленных элементов управления;
  • 'small' - в макете кнопки отображается иконка, независимо от размера карты;
  • 'medium' - в макете кнопки отображается только текст, независимо от размера карты;
  • 'large' - в макете кнопки всегда отображается иконка и текст, независимо от размера карты.

parameters.options.visible true

Тип: Boolean

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

parameters.state

Тип: Object

Объект, описывающий состояние кнопки.

parameters.state.enabled true

Тип: Boolean

Признак, активна ли кнопка.

parameters.state.selected false

Тип: Boolean

Признак, нажата ли кнопка.

Примеры:

1.

// Пример 1.
// Создание кнопки и добавление ее на карту.
var button = new ymaps.control.Button({
         data: {
             // Зададим иконку для кнопки
             image: 'images/button.jpg',
             // Текст на кнопке.
             content: 'Сохранить',
             // Текст всплывающей подсказки.
             title: 'Нажмите для сохранения маршрута'
         },
         options: {
             // Зададим опции для кнопки.
             selectOnClick: false,
             // Кнопка будет иметь три состояния - иконка, текст и иконка+текст.
             // Поэтому зададим три значения ширины кнопки для всех состояний.
             maxWidth: [30, 100, 150]
         }});
map.controls.add(button, { float: 'right', floatIndex: 100 });

2.

// Пример 2.
// Создание кнопки с пользовательским макетом
var button = new ymaps.control.Button({
        data: {
            content: 'Красная кнопка',
            title: 'Нажмите на кнопку'
        },
        options: {
            layout: ymaps.templateLayoutFactory.createClass(
                // Если кнопка не нажата, к ней применится css-стиль 'myButton'
                // Если кнопка нажата, к ней применятся css-стили 'myButton' и 'myButtonSelected'.
                "<div class='myButton {% if state.selected %}myButtonSelected{% endif %}' title='{{ data.title }}'>" +
                "{{ data.content }}" +
                "</div>"
            ),
            // Чтобы другие элементы управления корректно позиционировались по горизонтали,
            // нужно обязательно задать максимальную ширину для макета.
            maxWidth: 150
        }});
map.controls.add(button, { float: 'left', floatIndex: 0 });

// Можно задать позиционирование относительно краев карты. В этом случае
// значение опции maxWidth не влияет на позиционирование
// элементов управления.
map.controls.add(button, { float: 'none', position: {left: '5px', top: '5px'} });

Поля

ИмяТипОписание
datadata.Manager

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

  • image - иконка кнопки, если есть;
  • content - cодержимое кнопки в виде HTML;
  • title - текст всплывающей подсказки, которая появляется при наведении на кнопку курсора мыши.

eventsIEventManager

Менеджер событий.

Унаследовано от IEventEmitter.

optionsIOptionManager

Менеджер опций.

Унаследовано от IControl.

press

Событие, сигнализирующее о том, что кнопка была нажата. В отличии от click генерируется только если состояние isEnabled == true. Экземпляр класса Event.

statedata.Manager

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

  • selected - признак, нажата ли кнопка;
  • enabled - признак, активна ли кнопка;
  • size - размер, который в данный момент выставлен кнопке;

События

ИмяОписание
click

Нажатие на кнопку. Экземпляр класса Event.

deselect

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

Унаследовано от ISelectableControl.

disable

Элемент управления стал недоступным.

Унаследовано от ISelectableControl.

enable

Элемент управления стал доступным.

Унаследовано от ISelectableControl.

optionschange

Изменение в опциях объекта.

Унаследовано от ICustomizable.

parentchange

Сменился родительский объект.

Поля данных:

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

Унаследовано от IChild.

select

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

Унаследовано от ISelectableControl.

Методы

ИмяВозвращаетОписание
deselect()

Отменяет выбор элемента управления (выключает).

Унаследован от ISelectableControl.

disable()

Делает элемент управления недоступным (запрещены пользовательские действия).

Унаследован от ISelectableControl.

enable()

Делает элемент управления доступным (разрешены пользовательские действия).

Унаследован от ISelectableControl.

getMap()

Map

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

getParent()

IControlParent|null

Возвращает ссылку на родительский объект или null, если родительский элемент не был установлен.

Унаследован от IControl.

isEnabled()

Boolean

Возвращает true - элемент управления доступен, false - недоступен.

Унаследован от ISelectableControl.

isSelected()

Boolean

Возвращает true - элемент управления выбран, false - не выбран.

Унаследован от ISelectableControl.

select()

Выбирает (включает) элемент управления.

Унаследован от ISelectableControl.

setParent(parent)

IChildOnMap

Устанавливает родительский объект. Если передать значение null, то элемент управления будет только удален из текущего родительского объекта.

Унаследован от IControl.

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

data

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

  • image - иконка кнопки, если есть;
  • content - cодержимое кнопки в виде HTML;
  • title - текст всплывающей подсказки, которая появляется при наведении на кнопку курсора мыши.

press

press

Событие, сигнализирующее о том, что кнопка была нажата. В отличии от click генерируется только если состояние isEnabled == true. Экземпляр класса Event.

state

{data.Manager} state

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

  • selected - признак, нажата ли кнопка;
  • enabled - признак, активна ли кнопка;
  • size - размер, который в данный момент выставлен кнопке;

Пример:

var button = new ymaps.control.Button('Редактировать');
// Зададим состояние кнопки "нажата" -
// аналогично вызову метода button.select();
button.state.set('selected', true);

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

click

Нажатие на кнопку. Экземпляр класса Event.

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

getMap

{Map} getMap()

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