Форум

Методология

Инструментарий

Платформа

Сообщество

desktop
touch-pad
touch-phone

events

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

Обзор

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

Класс Конструктор Описание
Event Event(
type {String},
target {Object})
Служит для создания объекта события, изменения и проверки его состояний.
Emitter - Служит для генерации событий и подписки на них.

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

Класс Имя Тип или возвращаемое значение Описание
Event type String Тип события.
result * Результат, возвращенный последним обработчиком события.
target Object Объект на котором возникло событие.
data * Данные, передаваемые как аргумент обработчику.
preventDefault() - Позволяет предотвратить выполнение стандартного действия предусмотренного для события.
isDefaultPrevented() Boolean Проверяет, было ли предотвращено выполнение стандартного действия, предусмотренного для события.
stopPropagation() - Позволяет остановить всплывание события.
isPropagationStopped() Boolean Проверяет, было ли остановлено всплывание события.
Emitter on(
type {String},
[data {Object}],
fn {Function},
[ {Object} ctx])
- Служит для подписки на событие определенного типа.
once(
type {String},
[data {Object}],
fn {Function},
[ctx {Object}])
- Служит для подписки на событие определенного типа. Обработчик выполняется единожды.
un(
type {String},
fn {Function},
[ctx {Object}])
- Служит для удаления подписки на событие определенного типа.
emit(
type {String|events:Event},
[data {Object}])
- Служит для генерации события.

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

Элемент Способы использования Описание
channels JS Предназначен для работы с именованными каналами событий.

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

Элемент Функция Тип возвращаемого значения Описание
channels channels(
[id {String}],
[drop {Boolean}])
Object|undefined Создает или удаляет именованный канал событий.

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

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

  • 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'

});
Instance methods:
on
once
un
emit
Object methods:
Event
Emitter
Class Event
Instance methods:
preventDefault
isDefaultPrevented
stopPropagation
isPropagationStopped
Members
type
target
data
Constructor
Class Emitter
Instance methods:
on
once
un
emit

Module events

Instance methods:

on(e, [data], fn, [ctx]):Emitter
description
Adds an event handler
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
ctx
Object
Handler context
once(e, [data], fn, [ctx]):Emitter
description
Adds a one time handler for the event. Handler is executed only the next time the event is fired, after which it is removed.
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
ctx
Object
Handler context
un([e], [fn], [ctx]):Emitter
description
Removes event handler or handlers
parameters
e
String
Event type
fn
Function
Handler
ctx
Object
Handler context
emit(e, [data]):Emitter
description
Fires event handlers
parameters
e
String, events:Event
Event
data
Object
Additional data

Object methods:

Event()
Emitter()

Class Event

Instance methods:

preventDefault()
description
Prevents default action
isDefaultPrevented():Boolean
description
Returns whether is default action prevented
stopPropagation()
description
Stops propagation
isPropagationStopped():Boolean
description
Returns whether is propagation stopped

Members

type()
description
Type
target()
description
Target
data()
description
Data

Constructor

parameters
type
String
target
Object

Class Emitter

Instance methods:

on(e, [data], fn, [ctx]):Emitter
description
Adds an event handler
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
ctx
Object
Handler context
once(e, [data], fn, [ctx]):Emitter
description
Adds a one time handler for the event. Handler is executed only the next time the event is fired, after which it is removed.
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
ctx
Object
Handler context
un([e], [fn], [ctx]):Emitter
description
Removes event handler or handlers
parameters
e
String
Event type
fn
Function
Handler
ctx
Object
Handler context
emit(e, [data]):Emitter
description
Fires event handlers
parameters
e
String, events:Event
Event
data
Object
Additional data

events__channels

Returns/destroys a named communication channel
parameters
id
String
Channel ID
drop
Boolean
Destroy the channel
returns
events:Emitter, undefined
Communication channel

events__observable

Creates new observable

Instance methods:

on(e, [data], fn, [fnCtx]):Observable
description
Adds an event handler
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
fnCtx
Object
Context
once(e, [data], fn, [fnCtx]):Observable
description
Adds an event handler
parameters
e
String
Event type
data
Object
Additional data that the handler gets as e.data
fn
Function
Handler
fnCtx
Object
Context
un([e], [fn], [fnCtx]):Observable
description
Removes event handler
parameters
e
String
Event type
fn
Function
Handler
fnCtx
Object
Context
parameters
emitter
events:Emitter
returns
Observable

events__observable_type_bem-dom

Creates new observable
parameters
bemEntity
i-bem-dom:Block, i-bem-dom:Elem, events:Emitter
returns
Observable