jQuery源码分析之Callbacks方法

// String to Object flags format cache
// 我们暂且称flagsCache为行为标识符串信息集合，供jQuery.Callbacks函数使用
// flagCache存储信息格式如下：
// {'once':{'once':true},'once memory':{'once':true,'memory':true}}
// 其中key为行为标识符串，value为行为标识符串所包含的行为标识符的信息对象
// 行为标识符串是由空格隔开的多个行为标识符构成的字符串
// 行为标识符则是影响队列里的回调函数执行方式的字符串
var flagsCache = {};

// Convert String-formatted flags into Object-formatted ones and store in cache
// 将行为标识符串转换成对象存储到flagsCache中，供jQuery.Callbacks函数使用
function createFlags( flags ) {
var object = flagsCache[ flags ] = {},
i, length;
flags = flags.split( /\s+/ );
for ( i = 0, length = flags.length; i < length; i++ ) {
object[ flags[i] ] = true;
}
return object;
}

/*
* Create a callback list using the following parameters:
*flags:an optional list of space-separated flags that will change how
*the callback list behaves
* By default a callback list will act like an event callback list and can be
* "fired" multiple times.
* Possible flags:
*once:will ensure the callback list can only be fired once (like a Deferred)
*
*memory:  will keep track of previous values and will call any callback added
*  after the list has been fired right away with the latest "memorized"
*  values (like a Deferred)
*
*unique:  will ensure a callback can only be added once (no duplicate in the list)
*
*stopOnFalse: interrupt callings when a callback returns false
*/
//以上英文为jQuery自带API说明，现用自己的语言说明一下：
//该函数将创建用于管理回调函数列表的对象
//参数flags为行为标识字符串，是由空格隔开的多个行为标识符构成的字符串。
//默认情况下（即不传flags），则回调函数列表如同事件回调函数列表般执行。
//flags可能的值：
//(1)once：该行为标识符表示列表中的回调函数仅执行一次
//(2)memory：该行为标识符表示会将先前执行回调函数用到的值(context和args)放入栈中缓存
//(3)unique：该行为标识符表示确保放入列表中的回调函数唯一性
//(4)stopOnFalse：该行为标识符表示当执行列表中的回调函数返回false时将中断后面的回调函数执行
jQuery.Callbacks = function( flags ) {
// Convert flags from String-formatted to Object-formatted
// (we check in cache first)
// 获取行为标识符信息对象
flags = flags ? ( flagsCache[ flags ] || createFlags( flags ) ) : {};

var // Actual callback list
// 存放回调函数的列表
list = [],
// Stack of fire calls for repeatable lists
// 存放调用回调函数所需参数(context和args)放入队列中
stack = [],
// Last fire value (for non-forgettable lists)
// 缓存最近一次执行回调函数列表所用到的值(context和args)
memory,
// Flag to know if list is currently firing
// 标记是否回调函数列表正在执行
firing,
// First callback to fire (used internally by add and fireWith)
// 标记回调函数列表执行开始的下标值
firingStart,
// End of the loop when firing
// 标记回调函数列表执行结束的下标值
firingLength,
// Index of currently firing callback (modified by remove if needed)
// 标记回调函数列表正在执行的下标值
firingIndex,
// Add one or several callbacks to the list
// 向回调函数列表添加函数
add = function( args ) {
var i,
length,
elem,
type,
actual;
for ( i = 0, length = args.length; i < length; i++ ) {
elem = args[ i ];
type = jQuery.type( elem );
if ( type === "array" ) {
// Inspect recursively
// 若元素是数组，则递归，直到元素类型为方法时才放入列表中
add( elem );
} else if ( type === "function" ) {
// Add if not in unique mode and callback is not in
// 直到elem为方法时，
// 判断unique标识符是否传入，若是则需判断elem是否已存在列表中；
// 若非唯一，则执行将elem放入列表中。
if ( !flags.unique || !self.has( elem ) ) {
list.push( elem );
}
}
}
},
// Fire callbacks
// 执行回调函数列表
// context为上下文环境，必选
// args为传入回调函数参数，可选
fire = function( context, args ) {
args = args || [];
//判断memory标识符是否传入，
//如是则memory=[context, args],
//若非则memory=true
memory = !flags.memory || [ context, args ];
//标记列表正在执行
firing = true;
//标记列表执行正在执行的下标值
firingIndex = firingStart || 0;
//重置列表执行开始位的下标值
firingStart = 0;
//标记列表执行长度
firingLength = list.length;
for ( ; list && firingIndex < firingLength; firingIndex++ ) {
//需判断stopOnFalse标识符是否传入，
//如是则在执行回调函数返回false时中断列表后面的回调函数执行并标记memory=true
if ( list[ firingIndex ].apply( context, args ) === false && flags.stopOnFalse ) {
memory = true; // Mark as halted
break;
}
}
//标记列表执行完毕
firing = false;
if ( list ) {
//判断once行为标识符是否传入
if ( !flags.once ) {
//未传入once行为标识符则判断队列stack是否存值
if ( stack && stack.length ) {
//弹出队列的第一个元素作为调用回调函数列表所需参数(context和args)传入
memory = stack.shift();
self.fireWith( memory[ 0 ], memory[ 1 ] );
}
} else if ( memory === true ) {
//传入once行为标识符，并且memory=true。
//执行列表的回调函数后，memory=true只有两种情况：
//1、memory标识符未传入(即行为标识符串flags包含有memory)。
//2、stopOnFalse标识符传入(即行为标识符串(flags)包含有stopOnFalse)，
//并且执行列表回调函数时返回false。
//此时回调函数列表将被冻结使用，即后面对该列表任何操作都将失效。
self.disable();
} else {
//传入once行为标识符，则置空回调函数列表
list = [];
}
}
},
// Actual Callbacks object
// self为函数jQuery.Callbacks所要返回的对象，其实它是闭包。
// 函数外部是无法访问的函数jQuery.Callbacks内的变量和函数的。
// 为了能够提供外部操作回调函数列表，故将self对象返回。
// self对象的一些方法返回this的目的是为了能够链式调用，这是一个技巧。
self = {
// Add a callback or a collection of callbacks to the list
// 添加回调函数到列表中
add: function() {
if ( list ) {
var length = list.length;
//调用上面定义的add函数
add( arguments );
// Do we need to add the callbacks to the
// current firing batch?
// 判断回调函数列表是否正在执行
if ( firing ) {
//如是，则需将firingLength重置为添加元素后的列表长度
//新增的回调函数能够被执行到，具体原因见上面的函数fire实现
firingLength = list.length;
}
// 如非，则判断memory是否缓存有最近一次执行回调函数列表时所用的值(context和args)
else if ( memory && memory !== true ) {
// With memory, if we're not firing then
// we should call right away, unless previous
// firing was halted (stopOnFalse)
// 如是，则将回调函数列表执行的开始下标设置为新增的元素下标值，
// 并将memory缓存的两个值作为参数传给fire函数调用
firingStart = length;
fire( memory[ 0 ], memory[ 1 ] );
}
}
return this;
},
// Remove a callback from the list
// 移除指定回调函数列表中指定的元素
remove: function() {
if ( list ) {
var args = arguments,
argIndex = 0,
argLength = args.length;
for ( ; argIndex < argLength ; argIndex++ ) {
// 删除指定的元素值每次都需遍历一遍回调函数列表list
for ( var i = 0; i < list.length; i++ ) {
if ( args[ argIndex ] === list[ i ] ) {
// Handle firingIndex and firingLength
// 若回调函数列表正在执行中
// 则需相应的设置firingIndex和firingLength的值
if ( firing ) {
if ( i <= firingLength ) {
firingLength--;
if ( i <= firingIndex ) {
firingIndex--;
}
}
}
// Remove the element
// 由于执行splice列表的元素值将减1
// 所以当删除操作执行完后索引变量i也需减1
list.splice( i--, 1 );
// If we have some unicity property then
// we only need to do this once
// 判断unique行为标识符是否传入
// 如是则无需继续遍历查询需删除的元素是否在列表中
// 因为unique行为标识符已确保列表中元素的唯一性
// 这是一个技巧
if ( flags.unique ) {
break;
}
}
}
}
}
return this;
},
// Control if a given callback is in the list
// 检测是否回调函数队列中是否已包含有指定回调函数
has: function( fn ) {
if ( list ) {
var i = 0,
length = list.length;
for ( ; i < length; i++ ) {
if ( fn === list[ i ] ) {
return true;
}
}
}
return false;
},
// Remove all callbacks from the list
// 置空回调函数队列list
empty: function() {
list = [];
return this;
},
// Have the list do nothing anymore
// 调用次函数后，终结对回调函数列表的任何操作
disable: function() {
list = stack = memory = undefined;
return this;
},
// Is it disabled?
disabled: function() {
return !list;
},
// Lock the list in its current state
// 锁住回调函数列表的当前调用状态(context和args)
lock: function() {
stack = undefined;
if ( !memory || memory === true ) {
self.disable();
}
return this;
},
// Is it locked?
// 判定是否已锁住回调函数列表的当前调用状态(context和args)
locked: function() {
return !stack;
},
// Call all callbacks with the given context and arguments
// 使用指定的参数(context和args)调回调函数列表
fireWith: function( context, args ) {
if ( stack ) {
if ( firing ) {
//若回调函数列表正在执行
if ( !flags.once ) {
//若未传入once行为标识符
//由于回调函数列表正在执行，
//所以回调函数列表不能立即使用传入的参数(context和args)执行，
//需要将传入的参数(context和args)存入队列stack中。
//当回调函数列表执行完毕后，将会逐一使用队列stack中的值再执行回调函数列表，直到队列stack没有元素为止
//具体请参看fire函数
stack.push( [ context, args ] );
}
} else if ( !( flags.once && memory ) ) {
//若回调函数列表已执行完毕，则直接使用传入的参数(context和args)调用回调函数列表
fire( context, args );
}
}
return this;
},
// Call all the callbacks with the given arguments
// fire方法是fireWith的特殊化，将fire方法的调用对象即self本身作为context传入fireWith方法中
fire: function() {
self.fireWith( this, arguments );
return this;
},
// To know if the callbacks have already been called at least once
fired: function() {
return !!memory;
}
};
return self;
};