蒙国造博客

jQuery封装插件开发入门教程

扩展jQuery插件和方法的作用是非常强大的,它可以节省大量开发时间。这篇文章将概述jQuery插件开发的基本知识,最佳做法和常见的陷阱。

入门

编写一个jQuery插件开始于,给jQuery.fn加入​​新的功能属性,这个属性的名称就是插件的名称

jQuery.fn.myPlugin = function(){

  //你自己的插件代码

};

在JQuery中,jQuery.fnjQuery.prototype的简写。那么,用户非常喜欢的$符号哪里去了? 它仍然存在,但是,为了避免和其他JavaScript库冲突,我们最好将jQuery传递给一个自我执行的封闭程序,jQuery在此程序中映射为$符号,这样可以避免$号被其他库覆写。

(function ($) {
    $.fn.m​​yPlugin = function () {
        //你自己的插件代码
    };
})(jQuery);
 在这个封闭程序中,我们可以无限制的使用$符号来表示jQuery函数。

环境

现在,我们可以开始编写实际的插件代码。 但是,在这之前,我们必须得对插件所处的环境有个概念。
在插件的范围里, this关键字代表了这个插件将要执行的jQuery对象,所以不需要用$(this)引用jQuery对象,这是多余的,直接使用this即可。但是,在其他包含callback的jQuery函数中,this关键字代表了原生的DOM元素,是需要用$(this)的,如下所示。

(function ($) {
    $.fn.m​​yPlugin = function () {

        //此处直接使用this即可,没有必要将this包在$号中,如 $(this),因为this已经是一个jQuery对象,
        //加上$反而是多余的, $(this) 已经等同于 $($('#element')); 了

        this.fadeIn('normal', function () {

            //此处callback函数中this关键字代表一个DOM元素,就需要使用$(this)来引用这一元素

        });
    };
})(jQuery);

$('#element').myPlugin();

基础知识

现在,我们理解了jQuery插件的基础知识,让我们写一个插件,做一些事情。

(function ($) {
    $.fn.m​​axHeight = function () {
        var max = 0;
        this.each(function () {
            max = Math.max(max, $(this).height());
        });
        return max;
    };
})(jQuery);

var tallest = $('div').maxHeight(); //返回高度最大的div元素的高度

这是一个简单的插件,利用.height()返回页面中高度最大的div元素的高度。

 

链式调用

很多时候,一个插件的意图仅仅是以某种方式修改收集的元素,并把它们传递给链中的下一个方法。 这是jQuery的设计之美,是jQuery如此受欢迎的原因之一。 因此,要保持一个插件的chainability,你必须确保你的插件返回this关键字。

(function ($) {
    $.fn.lockDimensions = function (type) {
        return this.each(function () {

            var $this = $(this);

            if (!type || type == 'width') {
                $this.width($this.width());
            }

            if (!type || type == 'height') {
                $this.height($this.height());
            }
        });
    };
})(jQuery);

$('div').lockDimensions('width').CSS('color', 'red');

这段代码中,并不是用 each() 在选择器的每个元素上运行代码。each() 调用的函数的局部作用域中,可以通过 this 来引用每个被单独处理的元素,也就是说,可以通过 $(this) 来引用它的jQuery对象。这里我们用 $this 变量存储jQuery对象,就不用每次调用函数的时候都使用 $(this),这是个很好的实践。还有要注意的是,我们将会对每个单独方法都使用 each(),这样到时我们就可以返回我们需要的值,而不是一个jQuery对象。

本例中,插件返回 this 关键字,它保持了链式调用,这样jQuery收集的元素可以继续被jQuery方法(如.css)控制。 因此,如果插件不是返回固定的变量值,应该总是在其作用范围内返回 this 关键字。 此外,你可能会推断,传递给插件的参数将会在插件的作用范围内被传递。 因此,在前面的例子,字符串'width'变成了插件的类型参数。

默认值和选项

对于比较复杂的插件,或者提供了许多定制选项的插件,最好可以拓展默认配置,可以通过$.extend()实现。

(function ($) {
    $.fn.tooltip = function (options) {

        //默认值
        var defaults = {
            'location': 'top',
            'background-color': 'blue'
        }
        //用options拓展默认选项,defaults中同名对象的值,会被options的值覆盖
        var settings = $.extend({}, defaults, options);

        return this.each(function () {

            // Tooltip插件代码

        });
    };
})(jQuery);

$('div').tooltip({
    'location': 'left'
});

在这个例子中,调用tooltip插件时,覆写了默认设置中的location选项,background-color选项保持默认值,所以最终被调用的设定值相当于:

var settings = {
    'location': 'left',
    'background-color': 'blue'
}

这是一个很灵活的方式,提供一个高度可配置的插件,而无需开发人员定义所有可用的选项。

命名空间

正确使用命名空间是插件开发的一个重要部分。如果命名空间使用正确,可以极大降低插件被其他插件、或同一页上的其他代码覆盖的几率。 命名空间也使得插件人员开发更容易,因为它可以更好地跟踪你的方法、事件和数据。

插件方法

一个基本的函数可能在某些情况下良好地工作,但是稍微复杂一点的插件就需要提供各种各样的方法和私有函数。你可能会使用不同的命名空间去为你的插件提供各种方法,但是最好不要让你的源代码因为多余的命名空间而变得混乱。在任何情况下,一个单独的插件不应该在jQuery.fn对象里有多个命名空间。

(function ($) {

    $.fn.tooltip = function (options) {
        // this
    };
    $.fn.tooltipShow = function () {
        // is
    };
    $.fn.tooltipHide = function () {
        // bad
    };
    $.fn.tooltipUpdate = function (content) {
        // !!!
    };

})(jQuery);

这是不鼓励的,这样会使$.fn命名空间混乱。要解决这个问题,应该收集对象文本中所有插件的方法,通过传递该方法的字符串名称给插件,以调用它们,如下。

(function ($) {
    var methods = {
        init: function (options) {
            // this
        },
        show: function () {
            // is
        },
        hide: function () {
            // good
        },
        update: function (content) {
            // !!!
        }
    };

    $.fn.tooltip = function () {
        // 获取传入的方法,切勿用function(method){}来实现,否则会毁掉一切
        // arguments对象用法参考:http://www.w3school.com.cn/js/pro_js_functions_arguments_object.asp
        var method = arguments[0];
        // 方法调用
        if (methods[method]) {
 
            // 如果存在,获取方法名
            method = methods[method];

            // 我们的方法是作为参数传入的,把它从参数列表中删除,因为调用方法时仅需JSON格式参数,并不需要它
            arguments = Array.prototype.slice.call(arguments, 1);

        } else if (typeof method === 'object' || !method) {

            // 如果没有传入方法名,则默认调用init方法,参数为arguments
            method = methods.init;
        } else {

            // 否则提示错误
            $.error('Method' + method + 'does not exist on jQuery.tooltip');
        }

        // 用apply方法来调用方法,并传入参数 
        return method.apply(this, arguments);
    };
})(jQuery);

// 调用init方法
$('div').tooltip();

// 调用init方法
$('div').tooltip({
    foo: 'bar'
});

// 调用hide方法
$('div').tooltip('hide');

// 调用update方法
$('div').tooltip('update', 'This is the new tooltip content!');

这种类型的插件架构允许您封装所有的方法在父包中,通过传递该方法的字符串名称和额外的此方法需要的参数来调用它们。 这种方法的封装和架构类型是jQuery插件社区的标准,它被无数的插件在使用,包括jQueryUI中的插件和widgets。其中, init方法可以如下:

    init: function(options) {

         // 在每个元素上执行方法
         return this.each(function() {
             var $this = $(this);

             // 默认值
             var defaults = {
                 'location': 'top',
                 'background-color': 'blue'
             }
 
             // 用options拓展默认选项
             var settings = $.extend({}, defaults, options);
 
             // 执行代码
 
        });
    },

 

持久性数据

有时你会想在插件中保存设置和信息,这时jQuery中的data()函数就可以派上用场了。它使用非常简单,首先它会尝试获取和元素相关的数据,如果数据不存在,它就会创造相应的数据并添加到元素上。一旦你使用了data()来为元素添加信息,请确认你已经记住,当不再需要数据的时候,用removeData()来删除相应的数据。 相对于使用不同变量名记录变量,使用单独的对象保存所有变量,并通过一个单独的命名空间读取这个对象,是一个更好的方法。

(function($) {
    var methods = {
        init: function(options) {
            return this.each(function() {
                var $this = $(this);

                // 尝试去获取settings,如果不存在,则返回“undefined”
                var settings = $this.data('pluginName');
 
               // 如果获取settings失败,则根据options和default创建它
                if(typeof(settings) == 'undefined') {
 
                    var defaults = {
                        propertyName: 'value',
                        onSomeEvent: function() {}
                    }
 
                    settings = $.extend({}, defaults, options);
                    // 保存我们新创建的settings
                    $this.data('pluginName', settings);
                } else {
                    // 如果我们获取了settings,则将它和options进行合并(这不是必须的,你可以选择不这样做)
                    settings = $.extend({}, settings, options);

                    // 如果你想每次都保存options,可以添加下面代码:
                    // $this.data('pluginName', settings);
                }
        
               // 执行代码
            });
        },
        destroy: function(options) {
            
            // 在每个元素中执行代码
            return $(this).each(function() {
                var $this = $(this);
 
                // 执行代码

                // 删除元素对应的数据
                $this.removeData('pluginName');
            });
        },
        val: function(options) {
            // 这里的代码通过.eq(0)来获取选择器中的第一个元素的,我们或获取它的HTML内容作为我们的返回值
            var someValue = this.eq(0).html();
            // 返回值
            return someValue;
        }
    };
 
    $.fn.pluginName = function() {
        var method = arguments[0];
 
        if(methods[method]) {
            method = methods[method];
            arguments = Array.prototype.slice.call(arguments, 1);
        } else if( typeof(method) == 'object' || !method ) {
            method = methods.init;
        } else {
            $.error( 'Method ' +  method + ' does not exist on jQuery.pluginName' );
            return this;
        }
 
        return method.apply(this, arguments);
 
    }
 
})(jQuery);

将数据通过命名空间封装在一个对象中,可以更容易的从一个集中的位置读取所有插件的属性。在上面的代码中,首先检验元素的数据是否存在。如果数据不存在,optionsdefault 会被合并,构建成一个新的settings,然后用data()保存在元素中。

总结和最佳做法

编写jQuery插件允许你做出库,将最有用的功能集成到可重用的代码,可以节省开发者的时间,使开发更高效。 开发jQuery插件时,要牢记:

 

参考资料

  1. jQuery插件开发入门:http://www.css88.com/archives/4821
  2. 怎样封装自己的jQuery插件:https://github.com/superbug/blog/issues/2
  3. 深入理解jQuery插件开发:http://blog.jobbole.com/30550/

 

退出移动版