【原创】jQuery1.8.2源码解析之jQuery.data

数据缓存，jQuery现在支持两种：

1. dom元素，数据存储在jQuery.cache中。

2.普通js对象，数据存储在该对象中。

 以下是源代码：

var rbrace = /^(?:\{.*\}|\[.*\])$/,
    rmultiDash = /([A-Z])/g;

// 首先是对jQuery对象自身的扩展
jQuery.extend({
    // 即jQuery.cache，负责存储dom元素的缓存数据
    cache: {},

    // removeData时，缓存的数据被清除，返回的当时对应的id，以便再利用
    deletedIds: [], 

    // Please use with caution
    // 将数据存储到jQuery.cache中时，需要唯一id，用它来维护
    uuid: 0,

    // Unique for each copy of jQuery on the page
    // Non-digits removed to match rinlinejQuery
    // 内部key（随即生成），之后会作为key添加到dom的属性集中，而key对应的value则是该dom对应的缓存对象
    expando: "jQuery" + ( jQuery.fn.jquery + Math.random() ).replace( /\D/g, "" ),

    // The following elements throw uncatchable exceptions if you
    // attempt to add expando properties to them.
    // 不能添加expando属性的dom
    // classid为'clsid:D27CDB6E-AE6D-11cf-96B8-444553540000'的object是可以的，比较特殊吧
    noData: {
        "embed": true,
        // Ban all objects except for Flash (which handle expandos)
        "object": "clsid:D27CDB6E-AE6D-11cf-96B8-444553540000",
        "applet": true
    },

    hasData: function( elem ) {
        elem = elem.nodeType ? jQuery.cache[ elem[jQuery.expando] ] : elem[ jQuery.expando ];
        return !!elem && !isEmptyDataObject( elem );
    },

    data: function( elem, name, data, pvt /* Internal Use Only */ ) {
        if ( !jQuery.acceptData( elem ) ) {
            return;
        }

        var thisCache, ret,
            internalKey = jQuery.expando,
            getByName = typeof name === "string",

            // We have to handle DOM nodes and JS objects differently because IE6-7
            // can't GC object references properly across the DOM-JS boundary
            // 也就是说dom元素和普通js对象要进行不同的处理
            // 原因好像是是垃圾回收不能正确处理添加到dom元素的引用
            isNode = elem.nodeType,

            // Only DOM nodes need the global jQuery cache; JS object data is
            // attached directly to the object so GC can occur automatically
            // dom元素我们借用全局jQuery.cache来存储数据
            // 普通的js对象则直接将数据存储到对象中，垃圾回收可以自动处理
            cache = isNode ? jQuery.cache : elem,

            // Only defining an ID for JS objects if its cache already exists allows
            // the code to shortcut on the same path as a DOM node with no cache
            // 1. 如果是dom元素，返回dom元素expando对应的id（值可能为undefined）
            // 2. 如果是普通js对象，分两种情况：
            //    2.1 如果js对象存在expando对应的值，即代表有缓存数据，则立即返回expando作为id
            //    2.2 如果没有对应值，则代表没有缓存数据，此时返回undefined
            // 也就是说如果id不为空，那么肯定是有存储数据过的
            id = isNode ? elem[ internalKey ] : elem[ internalKey ] && internalKey;

        // Avoid doing any more work than we need to when trying to get data on an
        // object that has no data at all
        // 如果id不存在（表示不存在缓存）
        // 或者id存在，但是缓存为空
        // 又或者此时数据是私有的（pvt为true，仅为内部使用，此时只操控到cache[id]这一层）
        // 又或者数据不是私有的，但是对应的数据（data）为空
        // 以上条件之一成立后，
        // 再加上，getByName && data === undefined(表示是取数据)这个条件，直接return就可以了，因为没有数据取
        // 如果getByName为false，那么将初始化缓存对象（也为后来可能的name为object或者function时，extend做准备）
        if ( (!id || !cache[id] || (!pvt && !cache[id].data)) && getByName && data === undefined ) {
            return;
        }
        // 如果id为空，表示dom元素或者普通js对象没有缓存
        if ( !id ) {
            // Only DOM nodes need a new unique ID for each element since their data
            // ends up in the global cache
            // dom元素需要唯一id，因为它的数据将存在全局的jQuery.cache中
            if ( isNode ) {
                elem[ internalKey ] = id = jQuery.deletedIds.pop() || ++jQuery.uuid;
            } else {
            // 普通js对象的id都是expando
                id = internalKey;
            }
        }

        // 如果缓存为空，则之前没有存储过数据，此时需要进行必要的初始化
        if ( !cache[ id ] ) {
            // 创建缓存对象（理解为一个存放键值对的集合）
            cache[ id ] = {};

            // Avoids exposing jQuery metadata on plain JS objects when the object
            // is serialized using JSON.stringify
            // 普通js对象需要在它的缓存对象中添加toJSON方法，其中jQuery.noop只是有个空函数，什么都不做
            // 这里的目的是：在使用JSON.stringify(elem)序列化该js对象时，使它的缓存对象不参与序列化（空函数返回空）
            // 而dom元素是无法使用JSON.stringify(dom)的，会报错Converting circular structure to JSON
            if ( !isNode ) {
                cache[ id ].toJSON = jQuery.noop;
            }
        }

        // An object can be passed to jQuery.data instead of a key/value pair; this gets
        // shallow copied over onto the existing cache
        // 就是说在适用jQuery.data()缓存数据时，除了传递key/value键值对外，还可以传递一个对象，或者一个函数（返回一个对象）
        // 这样的结果是：传递的对象将会被extend到缓存中去
        if ( typeof name === "object" || typeof name === "function" ) {
            if ( pvt ) {
                // 私有数据，这里我明白了大概pvt的用处
                // cache[id].data 对象是用来存储用户自定义数据
                // cache[id] 则存储的是系统内部数据，比如之前说的toJSON
                // pvt不为空，则处理用户自定义数据，定位到cache[id].data这一层
                // pvt为空，则处理系统内部数据，定位到cache[id]这一层
                cache[ id ] = jQuery.extend( cache[ id ], name );
            } else {
                cache[ id ].data = jQuery.extend( cache[ id ].data, name );
            }
        }

        thisCache = cache[ id ];

        // jQuery data() is stored in a separate object inside the object's internal data
        // cache in order to avoid key collisions between internal data and user-defined
        // data.
        // 就是说为了防止系统内部数据和用户自定义数据的key发生冲突，才将用户数据包在thisCache.data中，
        // 系统内部数据就是thisCache中
        if ( !pvt ) {
            if ( !thisCache.data ) {
                thisCache.data = {};
            }

            //此时thisCache指向真正的数据缓存（集合）
            thisCache = thisCache.data;
        }

        // 如果data不为undefined，则表示这是在设置数据（set），那么进行负值缓存操作
        // jQuery.camelCase( name )将name驼峰化
        if ( data !== undefined ) {
            thisCache[ jQuery.camelCase( name ) ] = data;
        }

        // Check for both converted-to-camel and non-converted data property names
        // If a data property was specified
        // 返回指定name的数据，包括取数据和设置数据，都会返回。
        if ( getByName ) {

            // First Try to find as-is property data
            // 首先尝试取数据
            ret = thisCache[ name ];

            // Test for null|undefined property data
            // 如果ret为null或者undefined，则尝试将name驼峰化再尝试取数据（因为有可能之前name就被驼峰化）
            if ( ret == null ) {
                // Try to find the camelCased property
                ret = thisCache[ jQuery.camelCase( name ) ];
            }
        } else {
            // 没有指定name，则返回整个缓存对象
            ret = thisCache;
        }
        //返回数据
        return ret;
    },

    removeData: function( elem, name, pvt /* Internal Use Only */ ) {
        if ( !jQuery.acceptData( elem ) ) {
            return;
        }

        var thisCache, i, l,

            isNode = elem.nodeType,

            // See jQuery.data for more information
            cache = isNode ? jQuery.cache : elem,
            id = isNode ? elem[ jQuery.expando ] : jQuery.expando;

        // If there is already no cache entry for this object, there is no
        // purpose in continuing
        // 没有缓存，直接退出
        if ( !cache[ id ] ) {
            return;
        }

        // 如果有传入name，那么删除指定name对应的数据
        // 否则删除所有缓存，后面的代码有这一步处理
        if ( name ) {
            // 这里还是一样，通过内部pvt指定缓存层级，用户自定义数据层和系统内部数据层
            thisCache = pvt ? cache[ id ] : cache[ id ].data;

            if ( thisCache ) {

                // Support array or space separated string names for data keys
                // 支持单个的key
                // 数组，多个key，如：[key1, key2, key3, ...]
                // 字符串，多个key，用空格隔开，如：'key1 key2 key3 ...'

                //不是数组的情况，最终转换为数组形式
                if ( !jQuery.isArray( name ) ) {

                    // try the string as a key before any manipulation
                    // 首先直接查找
                    if ( name in thisCache ) {
                        name = [ name ];        //转换成数组形式，便于后面统一操作
                    } else {

                        // split the camel cased version by spaces unless a key with the spaces exists
                        name = jQuery.camelCase( name );
                        // 驼峰化后再查找
                        if ( name in thisCache ) {
                            name = [ name ];
                        // 用字符串转换为数组
                        } else {
                            name = name.split(" ");
                        }
                    }
                }
                // 统一用数组进行删除操作
                // 有一个疑问就是，如果数组元素没有被驼峰化，应该会出错？！
                for ( i = 0, l = name.length; i < l; i++ ) {
                    // delete thisCache[ jQuery.camelCase(name[i]) ];
                    delete thisCache[ name[i] ];
                }

                // If there is no data left in the cache, we want to continue
                // and let the cache object itself get destroyed
                // 如果缓存不为空，则退出
                // 否则，需要进行下一步的清理工作，因为此时缓存为空了嘛
                if ( !( pvt ? isEmptyDataObject : jQuery.isEmptyObject )( thisCache ) ) {
                    return;
                }
            }
        }

        // See jQuery.data for more information
        if ( !pvt ) {
            // 去除data属性
            delete cache[ id ].data;

            // Don't destroy the parent cache unless the internal data object
            // had been the only thing left in it
            // 当data处理过后需要检测cache[id]，因为此时cache[id]可能处于空的状态（这里的所谓的空在isEmptyDataObject有说明）
            if ( !isEmptyDataObject( cache[ id ] ) ) {
                return;
            }
        }

        // Destroy the cache
        // 如果是dom元素，除了jQuery.cache清理完毕后，还要处理dom元素自身，因为绑定了一个id嘛
        if ( isNode ) {
            jQuery.cleanData( [ elem ], true );

        // Use delete when supported for expandos or `cache` is not a window per isWindow (#10080)
        } else if ( jQuery.support.deleteExpando || cache != cache.window ) {
            delete cache[ id ];

        // When all else fails, null
        } else {
            cache[ id ] = null;
        }
    },

    // For internal use only.
    // 内部适用，这里设置pvt为true，返回内部数据，定位到cache[id]这一层
    _data: function( elem, name, data ) {
        return jQuery.data( elem, name, data, true );
    },

    // A method for determining if a DOM node can handle the data expando
    // 根据上面的jQuery.noData属性判断dom该元素是否可以添加expando属性（即dom是否允许添加数据）
    // 其中，classid为'clsid:D27CDB6E-AE6D-11cf-96B8-444553540000'的object是可以的，比较特殊吧
    acceptData: function( elem ) {
        var noData = elem.nodeName && jQuery.noData[ elem.nodeName.toLowerCase() ];

        // nodes accept data unless otherwise specified; rejection can be conditional
        return !noData || noData !== true && elem.getAttribute("classid") === noData;
    }
});

// 接下来是对jQuery对象（$(selector)）的扩展
jQuery.fn.extend({
    data: function( key, value ) {
        var parts, part, attr, name, l,
            elem = this[0],
            i = 0,
            data = null;

        // Gets all values
        // 如果为连key的值都未指定，那么返回的所有数据
        // 如：$dom.data();
        if ( key === undefined ) {
            if ( this.length ) {
                // 先从jquery缓存中取出所有数据
                data = jQuery.data( elem );

                // 对于元素节点而言，数据可以来自两个地方：
                // 1. jQuery.cache缓存中，之前手动存进去的，如：$dom.data('data1', value1);
                // 2. 来自html标签的以data-开头的属性，之后该属性的数据也会被存储到jQuery.cache缓存中，
                //    （属性名采用驼峰的形式）避免每次都要去html标签里去匹配并取值
                //    如：<div data-data-first="{a:1,b:2}" data-data-second="hello">hello world</div>
                //    当使用$dom.data()时，会获取到：
                // {
                //     dataFirst : {
                //         a : 1,
                //         b : 2
                //     }
                //     dataSecond : 'hello world'
                // }

                // 通过缓存中的内部属性parsedAttrs，分析html标签属性所带的数据是否被解析过（即存到jQuery过缓存中）
                // 解析过了，那么这里就没必要再解析一遍了，上面一步就已经取到数据了
                if ( elem.nodeType === 1 && !jQuery._data( elem, "parsedAttrs" ) ) {
                    attr = elem.attributes;
                    // 遍历dom节点的属性列表
                    for ( l = attr.length; i < l; i++ ) {
                        name = attr[i].name;
                        // 对于属性名以data-开头的属性进行取值存储操作
                        if ( name.indexOf( "data-" ) === 0 ) {
                            // 首先name去除data-,并将剩余的字符驼峰化
                            name = jQuery.camelCase( name.substring(5) );

                            dataAttr( elem, name, data[ name ] );
                        }
                    }
                    // 标记html标签上的数据已经解析过
                    jQuery._data( elem, "parsedAttrs", true );
                }
            }

            return data;
        }

        // Sets multiple values
        // 传递对象（键值对）作为data缓存，此时是对jQuery对象列表进行each操作
        if ( typeof key === "object" ) {
            return this.each(function() {
                jQuery.data( this, key );
            });
        }

        parts = key.split( ".", 2 );
        parts[1] = parts[1] ? "." + parts[1] : "";
        part = parts[1] + "!";

        return jQuery.access( this, function( value ) {

            if ( value === undefined ) {
                data = this.triggerHandler( "getData" + part, [ parts[0] ] );

                // Try to fetch any internally stored data first
                if ( data === undefined && elem ) {
                    // 首先从jQuery缓存中获取
                    data = jQuery.data( elem, key );
                    // 再从html标签里面获取（可见标签数据的优先级高）
                    data = dataAttr( elem, key, data );
                }

                return data === undefined && parts[1] ?
                    this.data( parts[0] ) :
                    data;
            }

            parts[1] = value;
            this.each(function() {
                var self = jQuery( this );

                self.triggerHandler( "setData" + part, parts );
                jQuery.data( this, key, value );
                self.triggerHandler( "changeData" + part, parts );
            });
        }, null, value, arguments.length > 1, null, false );
    },

    removeData: function( key ) {
        return this.each(function() {
            jQuery.removeData( this, key );
        });
    }
});

function dataAttr( elem, key, data ) {
    // If nothing was found internally, try to fetch any
    // data from the HTML5 data-* attribute
    // 如果data为空，且elem为元素节点，那么从标签的数据属性取数据（遵循html5）
    if ( data === undefined && elem.nodeType === 1 ) {
        // 将驼峰化转换成'-'连接的小写字符串
        var name = "data-" + key.replace( rmultiDash, "-$1" ).toLowerCase();
        // 获取dom上的对应属性
        data = elem.getAttribute( name );
        // 如果该属性存在，此时data为字符串，下面将进行根据数据类型进行数据的格式化
        if ( typeof data === "string" ) {
            try {
                // 布尔型
                data = data === "true" ? true :
                data === "false" ? false :
                // null
                data === "null" ? null :
                // Only convert to a number if it doesn't change the string
                // +data用来测试类型是否为数字
                +data + "" === data ? +data :
                // 对象和数组
                rbrace.test( data ) ? jQuery.parseJSON( data ) :
                    data;
            } catch( e ) {}

            // Make sure we set the data so it isn't changed later
            // 将格式化的数据存在jQuery.cache缓存。
            //（注意这里存的是jQuery.cache中，也就是说之前通过$dom.data()获取的对象，因为是引用，所以此时也是有值的）
            jQuery.data( elem, key, data );

        } else {
            // 如果该属性不存在，此时data为null，将其转换为undefined
            data = undefined;
        }
    }
    // 返回标签属性数据
    return data;
}

// checks a cache object for emptiness
// 内部使用，用于检测cache[id]这一层是否为空
// 其中，toJSON 不参与检测，也就是说只有它存在时，也算是空
// 其中，data 参与检测，如果data不为空，整个cache[id]则不为空
function isEmptyDataObject( obj ) {
    var name;
    for ( name in obj ) {

        // if the public data object is empty, the private is still empty
        // 对于data属性，需要额外判断data里面是否有数据
        // 如果没有，则data为空，那么跳过data，继续检测
        // 否则将在下面的返回false,表示不为空
        if ( name === "data" && jQuery.isEmptyObject( obj[name] ) ) {
            continue;
        }
        // toJSON 这个方法可以认为是是内置的，可以忽略它。
        // 如果不是toJSON 一律返回false，表示还有其他数据
        if ( name !== "toJSON" ) {
            return false;
        }
    }

    return true;
}