jquery ui widget 源码分析

jquery ui 的所有 组件都是基于一个简单，可重用的widget。

这个widget是jquery ui的核心部分，实用它能实现一致的API，创建有状态的插件，而无需关心插件的内部转换。

$.widget( name, base, prototype )

widget一共有2或3个参数。base为可选。

这里之所以把base放在第二个参数里，主要是因为这样写代码更直观一些。（因为后面的prototype 是个代码非常长的大对象）。

name：第一个参数是一个包含一个命名空间和组件名称的字符串，通过”.”来分割。
命名空间必须有，它指向widget prototype存储的全局jQuery对象。
如果命名空间没有，widget factory将会为你生成。widget name是插件函数和原型的真实名称，
比如： jQuery.widget( “demo.multi”, {…} ) 将会生成 jQuery.demo , jQuery.demo.multi , and jQuery.demo.multi.prototype .

base：第二个参数（可选）是 widget prototype继承于什么对象。
例如jQuery UI有一个“mouse”的插件，它可以作为其他的插件提供的基础。
为了实现这个所有的基于mouse的插件比如draggable,
droppable可以这么做： jQuery.widget( "ui.draggable", $.ui.mouse, {...} );
如果没有这个参数，widget默认继承自“base widget” jQuery.Widget（注意jQuery.widget 和 jQuery.Widget不同） 。

prototype：最后一个参数是一个对象文字，它会转化为所有widget实例的prototype。widget factory会生成属性链，连接到她继承的widget的prototype。一直到最基本的 jQuery.Widget。

一旦你调用jQuery.widget，它会在jQuery prototype ( jQuery.fn )上生成一个新的可用方法对应于widget的名字，比如我们这个例子jQuery.fn.multi。 .fn方法是包含Dom元素的jquery对象和你生成的 widget prototyp实例的接口，为每一个jQuery对象生成一个新的widget的实例。

  1 /*!
  2  * jQuery UI Widget @VERSION
  3  * http://jqueryui.com
  4  *
  5  * Copyright 2014 jQuery Foundation and other contributors
  6  * Released under the MIT license.
  7  * http://jquery.org/license
  8  *
  9  * http://api.jqueryui.com/jQuery.widget/
 10  */
 11  
 12 //这里判定是否支持amd or cmd 模式
 13 (function(factory) {
 14     if (typeof define === "function" && define.amd) {
 15  
 16         // AMD. Register as an anonymous module.
 17         define(["jquery"], factory);
 18     } else {
 19  
 20         // Browser globals
 21         factory(jQuery);
 22     }
 23 }(function($) {
 24  
 25     var widget_uuid = 0,
 26         //插件的实例化数量
 27         widget_slice = Array.prototype.slice; //数组的slice方法，这里的作用是将参赛arguments 转为真正的数组
 28  
 29     //清除插件的数据及缓存
 30     $.cleanData = (function(orig) {
 31         return function(elems) {
 32             for (var i = 0, elem;
 33             (elem = elems[i]) != null; i++) {
 34                 try {
 35                     // 重写cleanData方法，调用后触发每个元素的remove事件
 36                     $(elem).triggerHandler("remove");
 37                     // http://bugs.jquery.com/ticket/8235
 38                 } catch (e) {}
 39             }
 40             orig(elems);
 41         };
 42     })($.cleanData);
 43  
 44     /**
 45      * widget工厂方法，用于创建插件
 46      * @param name 包含命名空间的插件名称，格式 xx.xxx
 47      * @param base 需要继承的ui组件
 48      * @param prototype 插件的实际代码
 49      * @returns {Function}
 50      */
 51     $.widget = function(name, base, prototype) {
 52         var fullName, //插件全称
 53         existingConstructor, //原有的构造函数
 54         constructor, //当前构造函数
 55         basePrototype, //父类的Prototype
 56         // proxiedPrototype allows the provided prototype to remain unmodified
 57         // so that it can be used as a mixin for multiple widgets (#8876)
 58         proxiedPrototype = {},
 59             //可调用父类方法_spuer的prototype对象,扩展于prototype
 60             namespace = name.split(".")[0];
 61  
 62         name = name.split(".")[1];
 63         fullName = namespace + "-" + name;
 64         //如果只有2个参数  base默认为Widget类，组件默认会继承base类的所有方法
 65         if (!prototype) {
 66             prototype = base;
 67             base = $.Widget;
 68         }
 69  
 70         //    console.log(base, $.Widget)
 71  
 72         // create selector for plugin
 73         //创建一个自定义的伪类选择器
 74         //如 $(':ui-menu') 则表示选择定义了ui-menu插件的元素
 75         $.expr[":"][fullName.toLowerCase()] = function(elem) {
 76             return !!$.data(elem, fullName);
 77         };
 78  
 79         // 判定命名空间对象是否存在，没有的话 则创建一个空对象
 80         $[namespace] = $[namespace] || {};
 81         //这里存一份旧版的插件，如果这个插件已经被使用或者定义了
 82         existingConstructor = $[namespace][name];
 83         //这个是插件实例化的主要部分
 84         //constructor存储了插件的实例，同时也创建了基于命名空间的对象
 85         //如$.ui.menu
 86         constructor = $[namespace][name] = function(options, element) {
 87             // allow instantiation without "new" keyword
 88             //允许直接调用命名空间上的方法来创建组件
 89             //比如：$.ui.menu({},'#id') 这种方式创建的话，默认没有new 实例化。因为_createWidget是prototype上的方法，需要new关键字来实例化
 90             //通过 调用 $.ui.menu 来实例化插件
 91             if (!this._createWidget) {
 92                 console.info(this)
 93                 return new constructor(options, element);
 94             }
 95  
 96             // allow instantiation without initializing for simple inheritance
 97             // must use "new" keyword (the code above always passes args)
 98             //如果存在参数，则说明是正常调用插件
 99             //_createWidget是创建插件的核心方法
100             if (arguments.length) {
101                 this._createWidget(options, element);
102             }
103         };
104         // extend with the existing constructor to carry over any static properties
105         //合并对象，将旧插件实例，及版本号、prototype合并到constructor
106         $.extend(constructor, existingConstructor, {
107  
108             version: prototype.version,
109             // copy the object used to create the prototype in case we need to
110             // redefine the widget later
111             //创建一个新的插件对象
112             //将插件实例暴露给外部，可用户修改及覆盖
113             _proto: $.extend({}, prototype),
114             // track widgets that inherit from this widget in case this widget is
115             // redefined after a widget inherits from it
116             _childConstructors: []
117         });
118  
119         //实例化父类 获取父类的  prototype
120         basePrototype = new base();
121         // we need to make the options hash a property directly on the new instance
122         // otherwise we'll modify the options hash on the prototype that we're
123         // inheriting from
124         //这里深复制一份options
125         basePrototype.options = $.widget.extend({}, basePrototype.options);
126         //在传入的ui原型中有方法调用this._super 和this.__superApply会调用到base上（最基类上）的方法
127         $.each(prototype, function(prop, value) {
128             //如果val不是function 则直接给对象赋值字符串
129             if (!$.isFunction(value)) {
130                 proxiedPrototype[prop] = value;
131                 return;
132             }
133             //如果val是function
134             proxiedPrototype[prop] = (function() {
135                 //两种调用父类函数的方法
136                 var _super = function() {
137                         //将当期实例调用父类的方法
138                         return base.prototype[prop].apply(this, arguments);
139                     },
140                     _superApply = function(args) {
141                         return base.prototype[prop].apply(this, args);
142                     };
143                 return function() {
144                     var __super = this._super,
145                         __superApply = this._superApply,
146                         returnValue;
147                     //                console.log(prop, value,this,this._super,'===')
148                     //                debugger;
149                     //在这里调用父类的函数
150                     this._super = _super;
151                     this._superApply = _superApply;
152  
153                     returnValue = value.apply(this, arguments);
154  
155                     this._super = __super;
156                     this._superApply = __superApply;
157                     //                console.log(this,value,returnValue,prop,'===')
158                     return returnValue;
159                 };
160             })();
161         });
162         //    console.info(proxiedPrototype)
163         //    debugger;
164         //这里是实例化获取的内容
165         constructor.prototype = $.widget.extend(basePrototype, {
166             // TODO: remove support for widgetEventPrefix
167             // always use the name + a colon as the prefix, e.g., draggable:start
168             // don't prefix for widgets that aren't DOM-based
169             widgetEventPrefix: existingConstructor ? (basePrototype.widgetEventPrefix || name) : name
170         }, proxiedPrototype, {
171             //重新把constructor指向 constructor 变量
172             constructor: constructor,
173             namespace: namespace,
174             widgetName: name,
175             widgetFullName: fullName
176         });
177  
178         // If this widget is being redefined then we need to find all widgets that
179         // are inheriting from it and redefine all of them so that they inherit from
180         // the new version of this widget. We're essentially trying to replace one
181         // level in the prototype chain.
182         //这里判定插件是否被使用了。一般来说，都不会被使用的。
183         //因为插件的开发者都是我们自己，呵呵
184         if (existingConstructor) {
185             $.each(existingConstructor._childConstructors, function(i, child) {
186                 var childPrototype = child.prototype;
187  
188                 // redefine the child widget using the same prototype that was
189                 // originally used, but inherit from the new version of the base
190                 $.widget(childPrototype.namespace + "." + childPrototype.widgetName, constructor, child._proto);
191             });
192             // remove the list of existing child constructors from the old constructor
193             // so the old child constructors can be garbage collected
194             delete existingConstructor._childConstructors;
195         } else {
196             //父类添加当前插件的实例 主要用于作用域链查找 不至于断层
197             base._childConstructors.push(constructor);
198         }
199  
200         //将此方法挂在jQuery对象上
201         $.widget.bridge(name, constructor);
202  
203         return constructor;
204     };
205  
206     //扩展jq的extend方法，实际上类似$.extend(true,..) 深复制
207     $.widget.extend = function(target) {
208         var input = widget_slice.call(arguments, 1),
209             inputIndex = 0,
210             inputLength = input.length,
211             key, value;
212         for (; inputIndex < inputLength; inputIndex++) {
213             for (key in input[inputIndex]) {
214                 value = input[inputIndex][key];
215                 if (input[inputIndex].hasOwnProperty(key) && value !== undefined) {
216                     // Clone objects
217                     if ($.isPlainObject(value)) {
218                         target[key] = $.isPlainObject(target[key]) ? $.widget.extend({}, target[key], value) :
219                         // Don't extend strings, arrays, etc. with objects
220                         $.widget.extend({}, value);
221                         // Copy everything else by reference
222                     } else {
223                         target[key] = value;
224                     }
225                 }
226             }
227         }
228         return target;
229     };
230  
231     //bridge 是设计模式的一种，这里将对象转为插件调用
232     $.widget.bridge = function(name, object) {
233         var fullName = object.prototype.widgetFullName || name;
234         //这里就是插件了
235         //这部分的实现主要做了几个工作，也是制作一个优雅的插件的主要代码
236         //1、初次实例化时将插件对象缓存在dom上，后续则可直接调用，避免在相同元素下widget的多实例化。简单的说，就是一个单例方法。
237         //2、合并用户提供的默认设置选项options
238         //3、可以通过调用插件时传递字符串来调用插件内的方法。如:$('#id').menu('hide') 实际就是实例插件并调用hide()方法。
239         //4、同时限制外部调用“_”下划线的私有方法
240         $.fn[name] = function(options) {
241             var isMethodCall = typeof options === "string",
242                 args = widget_slice.call(arguments, 1),
243                 returnValue = this;
244  
245             // allow multiple hashes to be passed on init.
246             //可以简单认为是$.extend(true,options,args[0],...),args可以是一个参数或是数组
247             options = !isMethodCall && args.length ? $.widget.extend.apply(null, [options].concat(args)) : options;
248             //这里对字符串和对象分别作处理
249             if (isMethodCall) {
250                 this.each(function() {
251                     var methodValue, instance = $.data(this, fullName);
252                     //如果传递的是instance则将this返回。
253                     if (options === "instance") {
254                         returnValue = instance;
255                         return false;
256                     }
257                     if (!instance) {
258                         return $.error("cannot call methods on " + name + " prior to initialization; " + "attempted to call method '" + options + "'");
259                     }
260                     //这里对私有方法的调用做了限制，直接调用会抛出异常事件
261                     if (!$.isFunction(instance[options]) || options.charAt(0) === "_") {
262                         return $.error("no such method '" + options + "' for " + name + " widget instance");
263                     }
264                     //这里是如果传递的是字符串，则调用字符串方法，并传递对应的参数.
265                     //比如插件有个方法hide(a,b); 有2个参数：a，b
266                     //则调用时$('#id').menu('hide',1,2);//1和2 分别就是参数a和b了。
267                     methodValue = instance[options].apply(instance, args);
268                     if (methodValue !== instance && methodValue !== undefined) {
269                         returnValue = methodValue && methodValue.jquery ? returnValue.pushStack(methodValue.get()) : methodValue;
270                         return false;
271                     }
272                 });
273             } else {
274                 this.each(function() {
275                     var instance = $.data(this, fullName);
276  
277                     if (instance) {
278                         instance.option(options || {});
279                         //这里每次都调用init方法
280                         if (instance._init) {
281                             instance._init();
282                         }
283                     } else {
284                         //缓存插件实例
285                         $.data(this, fullName, new object(options, this));
286                     }
287                 });
288             }
289  
290             return returnValue;
291         };
292     };
293  
294     //这里是真正的widget基类
295     $.Widget = function( /* options, element */ ) {};
296     $.Widget._childConstructors = [];
297  
298     $.Widget.prototype = {
299         widgetName: "widget",
300         //用来决定事件的名称和插件提供的callbacks的关联。
301         // 比如dialog有一个close的callback，当close的callback被执行的时候，一个dialogclose的事件被触发。
302         // 事件的名称和事件的prefix+callback的名称。widgetEventPrefix 默认就是控件的名称，但是如果事件需要不同的名称也可以被重写。
303         // 比如一个用户开始拖拽一个元素,我们不想使用draggablestart作为事件的名称，我们想使用dragstart，所以我们可以重写事件的prefix。
304         // 如果callback的名称和事件的prefix相同，事件的名称将不会是prefix。
305         // 它阻止像dragdrag一样的事件名称。
306         widgetEventPrefix: "",
307         defaultElement: "<div>",
308         //属性会在创建模块时被覆盖
309         options: {
310             disabled: false,
311  
312             // callbacks
313             create: null
314         },
315         _createWidget: function(options, element) {
316             element = $(element || this.defaultElement || this)[0];
317             this.element = $(element);
318             this.uuid = widget_uuid++;
319             this.eventNamespace = "." + this.widgetName + this.uuid;
320             this.options = $.widget.extend({}, this.options, this._getCreateOptions(), options);
321  
322             this.bindings = $();
323             this.hoverable = $();
324             this.focusable = $();
325  
326             if (element !== this) {
327                 //            debugger
328                 $.data(element, this.widgetFullName, this);
329                 this._on(true, this.element, {
330                     remove: function(event) {
331                         if (event.target === element) {
332                             this.destroy();
333                         }
334                     }
335                 });
336                 this.document = $(element.style ?
337                 // element within the document
338                 element.ownerDocument :
339                 // element is window or document
340                 element.document || element);
341                 this.window = $(this.document[0].defaultView || this.document[0].parentWindow);
342             }
343  
344             this._create();
345             //创建插件时，有个create的回调
346             this._trigger("create", null, this._getCreateEventData());
347             this._init();
348         },
349         _getCreateOptions: $.noop,
350         _getCreateEventData: $.noop,
351         _create: $.noop,
352         _init: $.noop,
353         //销毁模块：去除绑定事件、去除数据、去除样式、属性
354         destroy: function() {
355             this._destroy();
356             // we can probably remove the unbind calls in 2.0
357             // all event bindings should go through this._on()
358             this.element.unbind(this.eventNamespace).removeData(this.widgetFullName)
359             // support: jquery <1.6.3
360             // http://bugs.jquery.com/ticket/9413
361             .removeData($.camelCase(this.widgetFullName));
362             this.widget().unbind(this.eventNamespace).removeAttr("aria-disabled").removeClass(
363             this.widgetFullName + "-disabled " + "ui-state-disabled");
364  
365             // clean up events and states
366             this.bindings.unbind(this.eventNamespace);
367             this.hoverable.removeClass("ui-state-hover");
368             this.focusable.removeClass("ui-state-focus");
369         },
370         _destroy: $.noop,
371  
372         widget: function() {
373             return this.element;
374         },
375         //设置选项函数
376         option: function(key, value) {
377             var options = key,
378                 parts, curOption, i;
379  
380             if (arguments.length === 0) {
381                 // don't return a reference to the internal hash
382                 //返回一个新的对象，不是内部数据的引用
383                 return $.widget.extend({}, this.options);
384             }
385  
386             if (typeof key === "string") {
387                 // handle nested keys, e.g., "foo.bar" => { foo: { bar: ___ } }
388                 options = {};
389                 parts = key.split(".");
390                 key = parts.shift();
391                 if (parts.length) {
392                     curOption = options[key] = $.widget.extend({}, this.options[key]);
393                     for (i = 0; i < parts.length - 1; i++) {
394                         curOption[parts[i]] = curOption[parts[i]] || {};
395                         curOption = curOption[parts[i]];
396                     }
397                     key = parts.pop();
398                     if (arguments.length === 1) {
399                         return curOption[key] === undefined ? null : curOption[key];
400                     }
401                     curOption[key] = value;
402                 } else {
403                     if (arguments.length === 1) {
404                         return this.options[key] === undefined ? null : this.options[key];
405                     }
406                     options[key] = value;
407                 }
408             }
409  
410             this._setOptions(options);
411  
412             return this;
413         },
414         _setOptions: function(options) {
415             var key;
416  
417             for (key in options) {
418                 this._setOption(key, options[key]);
419             }
420  
421             return this;
422         },
423         _setOption: function(key, value) {
424             this.options[key] = value;
425  
426             if (key === "disabled") {
427                 this.widget().toggleClass(this.widgetFullName + "-disabled", !! value);
428  
429                 // If the widget is becoming disabled, then nothing is interactive
430                 if (value) {
431                     this.hoverable.removeClass("ui-state-hover");
432                     this.focusable.removeClass("ui-state-focus");
433                 }
434             }
435  
436             return this;
437         },
438  
439         enable: function() {
440             return this._setOptions({
441                 disabled: false
442             });
443         },
444         disable: function() {
445             return this._setOptions({
446                 disabled: true
447             });
448         },
449  
450         _on: function(suppressDisabledCheck, element, handlers) {
451             var delegateElement, instance = this;
452  
453             // no suppressDisabledCheck flag, shuffle arguments
454             if (typeof suppressDisabledCheck !== "boolean") {
455                 handlers = element;
456                 element = suppressDisabledCheck;
457                 suppressDisabledCheck = false;
458             }
459  
460             // no element argument, shuffle and use this.element
461             if (!handlers) {
462                 handlers = element;
463                 element = this.element;
464                 delegateElement = this.widget();
465             } else {
466                 // accept selectors, DOM elements
467                 element = delegateElement = $(element);
468                 this.bindings = this.bindings.add(element);
469             }
470  
471             $.each(handlers, function(event, handler) {
472                 function handlerProxy() {
473                     // allow widgets to customize the disabled handling
474                     // - disabled as an array instead of boolean
475                     // - disabled class as method for disabling individual parts
476                     if (!suppressDisabledCheck && (instance.options.disabled === true || $(this).hasClass("ui-state-disabled"))) {
477                         return;
478                     }
479                     return (typeof handler === "string" ? instance[handler] : handler).apply(instance, arguments);
480                 }
481  
482                 // copy the guid so direct unbinding works
483                 if (typeof handler !== "string") {
484                     handlerProxy.guid = handler.guid = handler.guid || handlerProxy.guid || $.guid++;
485                 }
486  
487                 var match = event.match(/^([\w:-]*)\s*(.*)$/),
488                     eventName = match[1] + instance.eventNamespace,
489                     selector = match[2];
490                 if (selector) {
491                     delegateElement.delegate(selector, eventName, handlerProxy);
492                 } else {
493                     element.bind(eventName, handlerProxy);
494                 }
495             });
496         },
497  
498         _off: function(element, eventName) {
499             eventName = (eventName || "").split(" ").join(this.eventNamespace + " ") + this.eventNamespace;
500             element.unbind(eventName).undelegate(eventName);
501         },
502  
503         _delay: function(handler, delay) {
504             function handlerProxy() {
505                 return (typeof handler === "string" ? instance[handler] : handler).apply(instance, arguments);
506             }
507             var instance = this;
508             return setTimeout(handlerProxy, delay || 0);
509         },
510  
511         _hoverable: function(element) {
512             this.hoverable = this.hoverable.add(element);
513             this._on(element, {
514                 mouseenter: function(event) {
515                     $(event.currentTarget).addClass("ui-state-hover");
516                 },
517                 mouseleave: function(event) {
518                     $(event.currentTarget).removeClass("ui-state-hover");
519                 }
520             });
521         },
522  
523         _focusable: function(element) {
524             this.focusable = this.focusable.add(element);
525             this._on(element, {
526                 focusin: function(event) {
527                     $(event.currentTarget).addClass("ui-state-focus");
528                 },
529                 focusout: function(event) {
530                     $(event.currentTarget).removeClass("ui-state-focus");
531                 }
532             });
533         },
534  
535         _trigger: function(type, event, data) {
536             var prop, orig, callback = this.options[type];
537  
538             data = data || {};
539             event = $.Event(event);
540             event.type = (type === this.widgetEventPrefix ? type : this.widgetEventPrefix + type).toLowerCase();
541             // the original event may come from any element
542             // so we need to reset the target on the new event
543             event.target = this.element[0];
544  
545             // copy original event properties over to the new event
546             orig = event.originalEvent;
547             if (orig) {
548                 for (prop in orig) {
549                     if (!(prop in event)) {
550                         event[prop] = orig[prop];
551                     }
552                 }
553             }
554  
555             this.element.trigger(event, data);
556             return !($.isFunction(callback) && callback.apply(this.element[0], [event].concat(data)) === false || event.isDefaultPrevented());
557         }
558     };
559  
560     $.each({
561         show: "fadeIn",
562         hide: "fadeOut"
563     }, function(method, defaultEffect) {
564         $.Widget.prototype["_" + method] = function(element, options, callback) {
565             if (typeof options === "string") {
566                 options = {
567                     effect: options
568                 };
569             }
570             var hasOptions, effectName = !options ? method : options === true || typeof options === "number" ? defaultEffect : options.effect || defaultEffect;
571             options = options || {};
572             if (typeof options === "number") {
573                 options = {
574                     duration: options
575                 };
576             }
577             hasOptions = !$.isEmptyObject(options);
578             options.complete = callback;
579             if (options.delay) {
580                 element.delay(options.delay);
581             }
582             if (hasOptions && $.effects && $.effects.effect[effectName]) {
583                 element[method](options);
584             } else if (effectName !== method && element[effectName]) {
585                 element[effectName](options.duration, options.easing, callback);
586             } else {
587                 element.queue(function(next) {
588                     $(this)[method]();
589                     if (callback) {
590                         callback.call(element[0]);
591                     }
592                     next();
593                 });
594             }
595         };
596     });
597  
598     return $.widget;
599  
600 }));