jQuery функция $.Callbacks()

Определение и применение

jQuery фабричная функция $.Callbacks() возвращает многоцелевой объект (Callbacks), который обеспечивает мощный способ управления списками обратного вызова. Другими словами фабричная функция $.Callbacks() создает экземпляр объекта Callbacks.

Объект Callbacks поддерживает добавление, удаление, запуск и отключение обратных вызовов, в настоящее время этот объект используется внутри такой популярной функции как $.ajax() и объекта Deferred. Объект Callbacks подходит, например, для того, чтобы определить функциональность для новых компонентов.

jQuery синтаксис:

// без параметра
let myCallbacksObject = $.Callbacks()

// с указанием одного, или нескольких строковых значений (флагов)
let myCallbacksObject = $.Callbacks( flag )
let myCallbacksObject = $.Callbacks( flag flag )

flag - String

Добавлен в версии jQuery

Значения параметров

Пример использования

Использование функции без параметра

В этом примере мы рассмотрим базовое использование функции $.Callbacks() без параметра:

// возвращаем объект Callbacks и инициализируем переменную этим значением
let myCallbacks = $.Callbacks();

// создаем функцию и инициализируем переменную этим значением
const fn = function( value ) {
	console.log( "fn - " + value );
};

// создаем массив, содержащий две стрелочные функции и инициализируем переменную этим значением
const arr = [(val) => console.log("arrFn1 - " + val), (val) => console.log("arrFn2 - " + val)];

// добаляем функцию обратного вызова в список обратных вызовов объекта
myCallbacks.add( fn ); 
 
// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello" );

// вывод в консоль (срабатывает одна функция):
fn1 -  hello

// добаляем массив функций обратного вызова в список обратных вызовов объекта
myCallbacks.add( arr );

// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello world" );

// вывод в консоль (срабатывает три функции):
fn - hello world
arrFn1 - hello world
arrFn2 - hello world

В этом примере мы рассмотрели базовое использование функции $.Callbacks(), которую мы вызвали без параметра и возвратили объект Callbacks. После этого инициализировали две переменные, первая содержит функцию, а вторая массив функций. С помощью метода .add() объекта Callbacks мы добавили функцию в список обратных вызовов объекта Callbacks, и с помощью метода .fire() этого объекта вызываем все ранее добавленные функции обратного вызова с заданным аргументом. В результате чего мы вывели в консоль текстовое сообщение.

После этого с помощью метода .add() объекта Callbacks мы добавили массив функций в список обратных вызовов объекта Callbacks, и с помощью метода .fire() этого объекта вызываем все ранее добавленные функции обратного вызова с заданным аргументом. В результате чего мы вывели в консоль три текстовых сообщения, таким образом уже три функции из нашего списка были вызваны.

Использование функции с параметром once

В этом примере мы рассмотрим использование функции $.Callbacks() с параметром once:

// возвращаем объект Callbacks и инициализируем переменную этим значением
let myCallbacks = $.Callbacks("once"); // указываем параметр со значением once

// создаем стрелочную функцию и инициализируем переменную этим значением
const fn = (val) => console.log(val);

// добаляем функцию обратного вызова в список обратных вызовов объекта
myCallbacks.add( fn ); 
 
// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello" );

// вывод в консоль (срабатывает одна функция):
hello

// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello" );
// вывод в консоль не произойдет (функция из списка обратных вызовов не будет вызвана)

// если после этого добавить новую функцию и вызвать её, то вызова так же не произойдет
const fn2 = (val) => console.log("Вторая " + val);
myCallbacks.add( fn2 );
myCallbacks.fire( "hello" );
// вывод в консоль не произойдет (функция из списка обратных вызовов не будет вызвана)

Главной особенностью флага once является то, что список обратного вызова может быть запущен только один раз. Если после первого его запуска добавить в него какую-либо функцию и попытаться запустить этот список, то ничего из этого не выйдет.

Использование функции с параметром memory

В этом примере мы рассмотрим использование функции $.Callbacks() с параметром memory:

// возвращаем объект Callbacks и инициализируем переменную этим значением
let myCallbacks = $.Callbacks("memory"); // указываем параметр со значением memory

// создаем стрелочную функцию и инициализируем переменную этим значением
const fn = (val) => console.log(val);
const fn2 = (val) => console.log("Вторая " + val);

// добаляем функцию обратного вызова в список обратных вызовов объекта
myCallbacks.add( fn ); 
 
// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello" );

// вывод в консоль (срабатывает одна функция):
hello

// добаляем функцию обратного вызова в список обратных вызовов объекта
myCallbacks.add( fn2 ); 

// вызов функции происходит сразу после добавления (с запомненным значением):
Вторая hello

// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello" );

// вывод в консоль (срабатывает одна функция):
hello 
Вторая hello

Главной особенностью флага memory является то, что он отслеживает предыдущие значения и вызовет любой обратный вызов, добавленный после того как список обратного вызова был вызван с последними "запомненными" значениями.

Использование функции с параметром unique

В этом примере мы рассмотрим использование функции $.Callbacks() с параметром unique:

// возвращаем объект Callbacks и инициализируем переменную этим значением
let myCallbacks = $.Callbacks(); // без параметра
let myCallbacks2 = $.Callbacks("unique"); // указываем параметр со значением once

// создаем стрелочную функцию и инициализируем переменную этим значением
const fn = (val) => console.log(val);

// добаляем функции обратного вызова в список обратных вызовов объекта
myCallbacks.add( fn ); 
myCallbacks.add( fn ); // повторяем добавление функции

// добаляем функции обратного вызова в список обратных вызовов объекта
myCallbacks2.add( fn );
myCallbacks2.add( fn ); // повторяем добавление функции
 
// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello" );
// вывод в консоль (срабатывает две функции):
hello
hello

// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks2.fire( "hello" );

// вывод в консоль (срабатывает одна функция):
hello

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

Использование функции с параметром stopOnFalse

В этом примере мы рассмотрим использование функции $.Callbacks() с параметром stopOnFalse:

// возвращаем объект Callbacks и инициализируем переменную этим значением
let myCallbacks = $.Callbacks(); // без параметра
let myCallbacks2 = $.Callbacks("stopOnFalse"); // указываем параметр со значением stopOnFalse

// создаем стрелочную функцию и инициализируем переменную этим значением
const arr = [(val) => {console.log("1 " + val); return true},
                      (val) => {console.log("2 " + val); return false},
                      (val) => {console.log("3 " + val); return true}];

// добаляем функции обратного вызова в список обратных вызовов объекта
myCallbacks.add( arr ); 
myCallbacks2.add( arr ); 
 
// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello" );
// вывод в консоль (срабатывают три функции):
1 hello
2 hello
3 hello

// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks2.fire( "hello" );

// вывод в консоль (срабатывают две функции):
1 hello
2 hello

Главной особенностью флага stopOnFalse является то, что обрытные вызовы будут прерваны, когда один из обратных вызов возвращает значение false.

Использование нескольких значений в параметре

В этом примере мы рассмотрим использование функции $.Callbacks() с параметром, который содержит несколько значений, перечисленных через пробел:

let myCallbacks = $.Callbacks("unique memory"); // указываем параметр со значением unique memory

// создаем стрелочную функцию и инициализируем переменную этим значением
const fn = (val) => console.log("1 " + val);
const fn2 = (val) => console.log("2 " + val);

// добаляем функции обратного вызова в список обратных вызовов объекта
myCallbacks.add( fn ); 

// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello" );

// вывод в консоль (срабатывает одна функция):
1 hello

// повторяем добавление функции fn
myCallbacks.add( fn ); 
// немедленный вывод в консоль не произойдет (функция уже добавлялась)

myCallbacks.add( fn2 );

// вызов функции происходит сразу после добавления (с запомненным значением):
2 hello

// вызываем все ранее добавленные функции обратного вызова с заданным аргументом
myCallbacks.fire( "hello" );
 
// вывод в консоль (срабатывают две функции):
1 hello
2 hello

Для информации, комбинации флагов "unique memory" функции $.Callbacks() используются во внутреннем механизме таких методов объекта Deferred как .done() (добавляет обработчик или обработчики, которые будут вызваны при изменении состояния объекта Deferred на resolved - успешное выполнение) и .fail() (добавляет обработчик или обработчики, которые будут вызваны при изменении состояния объекта Deferred на rejected - выполнение отклонено).