events

Блок предоставляет набор JS-классов, реализующий механизмы работы с событиями.

Обзор

Классы, предоставляемые блоком

Свойства и методы объекта класса

Элементы блока

Функции предоставляемые элементами блока

Публичные технологии блока

Блок реализован в технологиях:

• vanilla.js

Описание

Класс Event

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

Принимаемые аргументы:

• type {String} – тип события. Обязательный аргумент.
• target {Object} – объект (источник) на котором событие возникло. Обязательный аргумент.

Возвращаемое значение: Event. Объект события.

Свойства и методы объекта класса

Свойство type

Тип: String.

Тип события.

modules.require(['events'], function(events) {

    var myevent = new events.Event('myevent', this);
    console.log(myevent.type); // 'myevent'

});

Свойство target

Тип: Object.

Объект, на котором возникло событие.

Свойство result

Тип: *.

Содержит данные, возвращаемые последней функцией-обработчиком события.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();
    myEmitter.on('myevent', function() { return 'hi-hi-hi'; });

    var myEvent = new events.Event('myevent');
    myEmitter.emit(myEvent)

    console.log(myEvent.result);    // 'hi-hi-hi'
});

Свойство data

Тип: *.

Содержит данные, передаваемые функции-обработчику события в качестве аргумента.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();
    myEmitter.on('myevent', 'my-data', function(e) { console.log(e.data); });

    myEmitter.emit('myevent'); // my-data
});

Метод preventDefault

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

Не принимает аргументов.

Не имеет возвращаемого значения.

Метод isDefaultPrevented

Позволяет проверить было ли предотвращено выполнение стандартного действия для события.

Не принимает аргументов.

Возвращаемое значение: Boolean. В случае, если выполнение стандартного действия было предотвращено – true.

Метод stopPropagation

Позволяет остановить всплывание события.

Не принимает аргументов.

Не имеет возвращаемого значения.

Метод isPropagationStopped

Позволяет проверить, было ли остановлено всплывание события.

Не принимает аргументов.

Возвращаемое значение: Boolean. В случае, если всплывание события было остановлено – true.

Класс Emitter

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

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

});

Свойства и методы объекта класса

Метод on

Служит для подписки на событие определенного типа.

Принимаемые аргументы:

• type {String} – тип события, на которое производится подписка. Обязательный аргумент.
• [data {Object}] – дополнительные данные, доступные обработчику как значение поля e.data объекта события.
• fn {Function} – функция-обработчик, вызываемая для события. Обязательный аргумент.
• [ctx {Object}] – контекст функции-обработчика.

Возвращает объект this.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on('myevent', function() { console.log('foo'); });
    myEmitter.emit('myevent'); // 'foo'
});

Кроме того, значением аргумента type могут быть:

• несколько типов событий, перечисленных через пробел – чтобы установить для них общую функцию-обработчик;

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on('myevent1 myevent2', function(e) { console.log(e.type) });

    myEmitter.emit('myevent1'); // 'myevent1'
    myEmitter.emit('myevent2'); // 'myevent2'
});

• хеш вида { 'событие-1' : обработчик-1, ... , 'событие-n' : обработчик-n } – чтобы установить сразу несколько обработчиков для разных типов событий;

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on({
        myevent1 : function(e) { console.log(e.type) },
        myevent2 : function(e) { console.log(e.type) }
    });  

    myEmitter.emit('myevent1'); // 'myevent1'
    myEmitter.emit('myevent2'); // 'myevent2'
});

Сказанное выше верно и для методов once и un.

Метод once

Идентичен методу on, но выполняется единожды – после первого события подписка удаляется.

Принимаемые аргументы:

• type {String} – тип события, на которое производится подписка. Обязательный аргумент.
• [data {Object}] – дополнительные данные, доступные как значение поля e.data объекта события.
• fn {Function} – функция-обработчик, вызываемая для события. Обязательный аргумент.
• [ctx {Object}] – контекст функции-обработчика.

Возвращает объект this.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on('myevent', function() { console.log('foo') });

    myEmitter.emit('myevent'); // 'foo'
    myEmitter.emit('myevent'); // обработчик не вызывается
});

Метод un

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

Принимаемые аргументы:

• type {String} – тип события, подписка на которое удаляется. Обязательный аргумент.
• [fn {Function}] – удаляемый обработчик.
• [ctx {Object}] – контекст обработчика.

Метод возвращает ссылку на объект this.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter(),
        shout = function() { console.log('foo') };

    myEmitter.on('myevent', shout);
    myEmitter.emit('myevent'); // 'foo'

    myEmitter.un('myevent', shout);
    myEmitter.emit('myevent'); // обработчик не вызывается
});

Метод emit

Служит для генерации события.

Метод вызывает все функции-обработчики, заданные для события.

Принимаемые аргументы:

• type {String|events:Event} – генерируемое событие в виде строки или готового объекта события. Обязательный аргумент.
• [data {Object}] – дополнительные данные, доступные как второй аргумент функции-обработчика.

Возвращает объект this.

modules.require(['events'], function(events) {

    var myEmitter = new events.Emitter();

    myEmitter.on('myevent', function(e, data) { console.log(data) });
    myEmitter.emit('myevent', 'ololo');  // 'ololo'
});

Статические методы класса

Набор и сигнатуры статических методов идентичны набору и сигнатурам методов объекта, инстанцируемого классом.

Элемент channels блока events

Элемент channels блока events предназначен для работы с именованными каналами событий. Именные каналы позволяют организовать работу с событиями, используя шаблон проектирования «наблюдатель» (также известный как Publisher-subscriber).

Элемент реализует функцию, позволяющую:

• получить ссылку на именной канал по id;
• получить ссылку на стандартный канал;
• удалить канал – стандартный или по id.

Принимаемые аргументы:

• [id {String}] – Идентификатор канала. Если не задан будет использоваться канал по умолчанию ('default').
• [drop {Boolean}] – Логический флаг, указывающий (в значении true) на необходимость удалить канал. По умолчанию false.

Возвращаемое значение:

• Object. Объект «класса» Emitter – именной канал.
• undefined. В случае если функция была вызвана с параметром drop в значении true.

Пример:

modules.require(['events__channels'], function(channels) {

var myChannel = channels('my-channel');
myChannel.on('test', function(e, data) { console.log(data.foo) });

myChannel.emit('test', { foo : 'bar' }); // 'bar'

});