JqueryUI - 小部件工厂

早些时候,在 jQuery 中编写自定义控件的唯一方法是扩展 $.fn 命名空间。 这适用于简单的小部件。 假设您构建更多有状态的小部件,它很快就会变得很麻烦。 为了帮助构建小部件的过程,在 jQuery UI 中引入了小部件工厂,它删除了通常与管理小部件相关联的大部分样板。

jQueryUI Widget Factory 只是一个函数($.widget),它将一个字符串名称和一个对象作为参数,并创建一个 jQuery 插件和一个"类"来封装其功能。

语法

以下是 jQueryUI Widget Factory 方法的语法 −

jQuery.widget( name [, base ], prototype )

name − 它是一个字符串,包含要创建的小部件的名称空间小部件名称(以点分隔)。

base − The base widget to inherit from. This must be a constructor that can be instantiated with the `new` keyword. Defaults to jQuery.Widget.

prototype − 用作小部件继承自的原型的对象。 例如,jQuery UI 有一个"mouse"鼠标插件,其余的交互插件都基于该插件。为了实现这一点,draggable, droppable, 等都像这样继承自鼠标插件: jQuery.widget( "ui.draggable", $.ui.mouse, {...} ); 如果不提供此参数,小部件将直接继承自"基础小部件"jQuery.Widget(注意小写"w"jQuery.widget 和大写"W"jQuery.Widget 之间的区别)。


基础小部件

Base widget是widget factory使用的widget。

选项

下表列出了可与基本小部件一起使用的不同选项

序号 选项 & 说明
1 disabledhide

如果设置为 true,此选项将禁用小部件。 默认情况下,它的值为 false

Option - disabledhide

如果设置为 true,此选项将禁用小部件。 默认情况下,它的值为 false

示例

$( ".selector" ).widget({ disabled: true });
2 hide

此选项确定如何为元素的隐藏设置动画。 默认情况下,它的值为 null

Option - hide

此选项确定如何为元素的隐藏设置动画。 默认情况下,它的值为 null

这可以是类型 −

  • Boolean − 如果设置为 false 则不会使用动画。 如果设置为 true,元素将以默认持续时间和默认缓动淡出。

  • Number − 该元素将以指定的持续时间和默认的缓动淡出。

  • String − 该元素将使用指定的效果隐藏。

  • Object − 如果该值是一个对象,则可以提供 effect、delay、durationeasing 属性。

示例

$( ".selector" ).widget({ hide: { effect: "explode", duration: 1000 } });
3 show

此选项确定如何为元素的显示设置动画。 默认情况下,它的值为 null

Option - show

此选项确定如何为元素的显示设置动画。 默认情况下,它的值为 null

这可以是类型 −

  • Boolean − 如果设置为 false,则不会使用动画来显示元素。 如果设置为 true,元素将以默认持续时间和默认缓动淡入。

  • Number − 该元素将以指定的持续时间和默认的缓动淡入。

  • String − 该元素将使用指定的效果显示。

  • Object − 如果该值是一个对象,则可以提供 effect、delay、durationeasing 属性。

示例

$( ".selector" ).widget({ show: { effect: "explode", duration: 1000 } });

方法

下表列出了可与基本小部件一起使用的不同方法

序号 操作 & 说明
1 _create()

此方法是小部件的构造函数。 没有参数,但 this.elementthis.options 已经设置。

Action - _create()

此操作完全破坏了元素的手风琴功能。 元素返回到它们的预初始化状态。 此方法是小部件的构造函数。 没有参数,但 this.elementthis.options 已经设置。

示例

_create: function() {
   this.element.css( "background-color", this.options.color );
}
2 _delay( fn [, delay ] )

此方法在指定延迟后调用提供的函数。 返回用于 clearTimeout() 的超时 ID。

Action - _delay( fn [, delay ] )

此方法在指定延迟后调用提供的函数。 返回用于 clearTimeout() 的超时 ID。

示例

this._delay( this._foo, 100 );
3 _destroy()

公共 public destroy() 方法清除所有公共数据、事件等,然后委托给此 _destroy() 方法进行自定义、特定于小部件的清除。

Action - _destroy()

公共 public destroy() 方法清除所有公共数据、事件等,然后委托给此 _destroy() 方法进行自定义、特定于小部件的清除。

示例

_destroy: function() {
   this.element.removeClass( "my-widget" );
}
4 _focusable( element )

此方法设置元素以在焦点上应用 ui-state-focus 类。 事件处理程序在销毁时自动清理。

Action - _focusable( element )

此方法设置元素以在焦点上应用 ui-state-focus 类。 事件处理程序在销毁时自动清理。

示例

_create: function() {
   this._focusable( this.element.find( ".my-items" ) );
}
5 _getCreateEventData()

所有小部件都会触发 create 事件。 默认情况下,事件中不提供任何数据,但此方法可以返回一个对象,该对象将作为创建事件的数据传递。

Action - _getCreateEventData()

所有小部件都会触发 create 事件。 默认情况下,事件中不提供任何数据,但此方法可以返回一个对象,该对象将作为创建事件的数据传递。

示例

_getCreateEventData: function() {
   return this.options;
}
6 _getCreateOptions()

此方法允许小部件定义一个自定义方法,用于在实例化期间定义选项。 用户提供的选项会覆盖此方法返回的选项,后者会覆盖默认选项。

Action - _getCreateOptions()

此方法允许小部件定义一个自定义方法,用于在实例化期间定义选项。 用户提供的选项会覆盖此方法返回的选项,后者会覆盖默认选项。

示例

_getCreateOptions: function() {
   return { id: this.element.attr( "id" ) };
}
7 _hide( element, option [, callback ] )

此方法使用内置动画方法或使用自定义效果立即隐藏元素。 有关可能的选项值,请参阅隐藏选项。

Action - _hide( element, option [, callback ] )

此方法使用内置动画方法或使用自定义效果立即隐藏元素。 有关可能的选项值,请参阅隐藏选项。

示例

this._hide( this.element, this.options.hide, function() {
   $( this ).remove();
});
8 _hoverable( element )

此方法设置元素以在悬停时应用 ui-state-hover 类。 事件处理程序在销毁时自动清理。

Action - _hoverable( element )

此方法设置元素以在悬停时应用 ui-state-hover 类。 事件处理程序在销毁时自动清理。

示例

this._hoverable( this.element.find( "div" ) );
9 _init()

任何时候在不带参数或仅带选项散列的情况下调用插件时,都会初始化小部件; 这包括创建小部件的时间。

Action - _init()

任何时候在不带参数或仅带选项散列的情况下调用插件时,都会初始化小部件; 这包括创建小部件的时间。

示例

_init: function() {
   if ( this.options.autoOpen ) {
      this.open();
   }
}
10 _off( element, eventName )

此方法从指定元素解除绑定事件处理程序。

Action - _off( element, eventName )

此方法从指定元素解除绑定事件处理程序。

示例

this._off( this.element, "click" );
11 _on( [suppressDisabledCheck ] [, element ], handlers )

将事件处理程序绑定到指定的元素。 通过事件名称中的选择器支持委派,例如"click .foo"。

Action - _on( [suppressDisabledCheck ] [, element ], handlers )

>将事件处理程序绑定到指定的元素。 通过事件名称中的选择器支持委派,例如"click .foo"。

示例

this._on( this.element, {
   "click a": function( event ) {
      event.preventDefault();
   }
});
12 _setOption( key, value )

此方法从每个单独选项的 _setOptions() 方法调用。 小部件状态应根据更改进行更新。

Action - _setOption( key, value )

此方法从每个单独选项的 _setOptions() 方法调用。 小部件状态应根据更改进行更新。

示例

_setOption: function( key, value ) {
   if ( key === "width" ) {
      this.element.width( value );
   }
   if ( key === "height" ) {
      this.element.height( value );
   }
   this._super( key, value );
}
13 _setOptions( options )

只要调用 option() 方法,就会调用此方法,而不管调用 option() 方法的形式如何。

Action - _setOptions( options )

只要调用 option() 方法,就会调用此方法,而不管调用 option() 方法的形式如何。

示例

_setOptions: function( options ) {
   var that = this,
   resize = false;
   $.each( options, function( key, value ) {
      that._setOption( key, value );
      if ( key === "height" || key === "width" ) {
         resize = true;
      }
   });
   if ( resize ) {
      this.resize();
   }
}
14 _show( element, option [, callback ] )

使用内置动画方法或使用自定义效果立即显示元素。 有关可能的选项值,请参阅显示选项。

Action - _show( element, option [, callback ] )

使用内置动画方法或使用自定义效果立即显示元素。 有关可能的选项值,请参阅显示选项。

示例

_this._show( this.element, this.options.show, function() {
   // Focus the element when it's fully visible.
   this.focus();
}
15 _super( [arg ] [, ... ] )

此方法使用任何指定的参数从父窗口小部件调用同名方法。 本质上是.call()。

Action - _super( [arg ] [, ... ] )

此方法使用任何指定的参数从父窗口小部件调用同名方法。 本质上是.call()。

示例

_setOption: function( key, value ) {
   if ( key === "title" ) {
      this.element.find( "h3" ).text( value );
   }
   this._super( key, value );
}
16 _superApply( arguments )

使用参数数组从父小部件调用同名方法。

Action - _superApply( arguments )

使用参数数组从父小部件调用同名方法。

示例

_setOption: function( key, value ) {
   if ( key === "title" ) {
      this.element.find( "h3" ).text( value );
   }
   this._superApply( arguments );
}
17 _trigger( type [, event ] [, data ] )

此方法触发一个事件及其关联的回调。 名称等于 type 的选项作为回调调用。

Action - _trigger( type [, event ] [, data ] )

此方法触发一个事件及其关联的回调。 名称等于 type 的选项作为回调调用。

示例

this._on( this.element, {
   keydown: function( event ) {
      // Pass the original event so that the custom search event has
      // useful information, such as keyCode
      this._trigger( "search", event, {
         // Pass additional information unique to this event
         value: this.element.val()
      });
   }
});
18 destroy()

此方法完全删除了小部件功能。 这会将元素返回到其预初始化状态。

Action - destroy()

此方法完全删除了小部件功能。 这会将元素返回到其预初始化状态。

示例

this._on( this.element, {
   "click a": function( event ) {
      event.preventDefault();
      this.destroy();
   }
});
19 disable()

此方法禁用小部件。

Action - disable()

此方法禁用小部件。

示例

this._on( this.element, {
   "click a": function( event ) {
      event.preventDefault();
      this.disable();
   }
});
20 enable()

此方法启用小部件。

Action - enable()

此方法启用小部件。

示例

this._on( this.element, {
   "click a": function( event ) {
      event.preventDefault();
      this.enable();
   }
});
21 option( optionName )

此方法获取当前与指定的 optionName 关联的值。

Action - option( optionName )

此方法获取当前与指定的 optionName 关联的值。

示例

this.option( "width" );
22 option()

此方法获取一个对象,该对象包含表示当前小部件选项哈希的键/值对。

Action - option()

此方法获取一个对象,该对象包含表示当前小部件选项哈希的键/值对。

示例

var options = this.option();
for ( var key in options ) {
   console.log( key, options[ key ] );
}
23 option( optionName, value )

此方法设置与指定选项名称关联的小部件选项的值。

Action - option( optionName, value )

此方法设置与指定选项名称关联的小部件选项的值。

示例

this.option( "width", 500 );
24 option( options )

此方法为小部件设置一个或多个选项。

Action - option( options )

此方法为小部件设置一个或多个选项。

示例

this.option({
   width: 500,
   height: 500
});
25 widget()

此方法返回包含原始元素或其他相关生成元素的 jQuery 对象。

Action - widget()

此方法返回包含原始元素或其他相关生成元素的 jQuery 对象。

示例

_create: function() {
   this.widget().css( "border", "2px solid red" );
}

事件

序号 事件方法 & 说明
1 create( event, ui )

创建小部件时会触发此事件。

Event - create( event, ui )

创建小部件时会触发此事件。 其中eventEvent类型,uiObject类型。

语法

$( ".selector" ).widget({
   create: function( event, ui ) {}
});

jQueryUI 小部件工厂生命周期

jQueryUI 小部件工厂提供了一种面向对象的方式来管理小部件的生命周期。 这些生命周期活动包括 −

创建和销毁一个小部件:例如,

$( "#elem" ).progressbar();

更改小部件选项:例如

$( "#elem" ).progressbar({ value: 20 });

在子类小部件中进行"超级"调用:例如

$( "#elem" ).progressbar( "value" );
or 
$( "#elem" ).progressbar( "value", 40 );

事件通知:例如

$( "#elem" ).bind( "progressbarchange", function() {
   alert( "The value has changed!" );
});

示例

现在让我们在以下示例中创建一个自定义小部件。 我们将创建一个按钮小部件。 我们将在以下示例中看到如何在小部件中创建选项、方法和事件 −

创建自定义小部件

让我们首先创建一个简单的自定义小部件。

<!DOCTYPE html>
<html>
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Widget - Default functionality</title>
      <link rel = "stylesheet" href = "//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <script>
         $(function() {
            $.widget("iP.myButton", {
               _create: function() { 
                  this._button = $("<button>"); 
                  this._button.text("My first Widget Button");
                  this._button.width(this.options.width) 
                  this._button.css("background-color", this.options.color);    
                  this._button.css("position", "absolute");   
                  this._button.css("left", "100px");            
                  $(this.element).append(this._button);
               },
            });
            $("#button1").myButton();
         });
      </script>
   </head>
   
   <body>
      <div id = "button1"></div>
   </body>
</html>

让我们将上面的代码保存在一个 HTML 文件 widgetfactoryexample.htm 中,并在支持 javascript 的标准浏览器中打开它,您应该会看到以下输出 −

向自定义小部件添加选项

在前面的示例中,我们使用了_create 函数来创建自定义控件。 但用户一般都希望通过设置和修改选项来自定义控件。我们可以定义一个选项对象,它存储您定义的所有选项的默认值。 _setOption 函数用于此目的。 为用户设置的每个单独选项调用它。 这里我们设置按钮的 widthbackground-color

<!DOCTYPE html>
<html>
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Widget - Default functionality</title>
      <link rel = "stylesheet" href = "//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <script>
         $(function() {
            $.widget("iP.myButton", {
               _create: function() { 
                  this._button = $("<button>"); 
                  this._button.text("My first Widget Button");
                  this._button.width(this.options.width) 
                  this._button.css("background-color", this.options.color);    
                  this._button.css("position", "absolute");   
                  this._button.css("left", "100px");            
                  $(this.element).append(this._button);
               },
               _setOption: function(key, value) { 
                  switch (key) { 
                     case "width": 
                     this._button.width(value); 
                     break; 
                     case "color":
                     this._button.css("background-color",value);
                     break; 
                  } 
               },
            });
            $("#button2").myButton();
            $("#button2").myButton("option", {width:100,color:"#cedc98"});
         });
      </script>
   </head>
   
   <body>
      <div id = "button2"></div>
   </body>
</html>

让我们将上面的代码保存在一个 HTML 文件 widgetfactoryexample.htm 中,并在支持 javascript 的标准浏览器中打开它,您应该会看到以下输出 −

向自定义小部件添加方法

在下面的示例中,我们将添加用户可以使用的方法,这些方法很容易构建到框架中。 我们将编写一个 Move 方法,将按钮移动指定的水平距离。 为了让它工作,我们还需要在 _create 函数中设置 position 和 left 属性 −

this._button.css("position", "absolute");   
this._button.css("left", "100px");  

在此之后,用户现在可以以通常的 jQuery UI 方式调用您的方法 −

this._button.css("position", "absolute");   
this._button.css("left", "100px");  
$("button3").myButton("move", 200);
<!DOCTYPE html>
<html>
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Widget - Default functionality</title>
      <link rel = "stylesheet" href = "//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>

      <script>
         $(function() {
            $.widget("iP.myButton", {
               _create: function() { 
                  this._button = $("<button>"); 
                  this._button.text("My first Widget Button");
                  this._button.width(this.options.width) 
                  this._button.css("background-color", this.options.color);    
                  this._button.css("position", "absolute");   
                  this._button.css("left", "100px");            
                  $(this.element).append(this._button);
               },
         
               move: function(dx) { 
                  var x = dx + parseInt(this._button.css("left")); 
                  this._button.css("left", x); 
                  if(x>400) { this._trigger("outbounds",{},  {position:x}); }
               }
            });
            $("#button3").myButton();
            $("#button3").myButton("move", 200);
         });
      </script>
   </head>
   
   <body>
      <div id = "button3"></div>
   </body>
</html>

让我们将上面的代码保存在一个 HTML 文件 widgetfactoryexample.htm 中,并在支持 javascript 的标准浏览器中打开它,您应该会看到以下输出 −

向自定义小部件添加事件

在此示例中,我们将演示如何创建事件。 要创建一个事件,您所要做的就是使用 _trigger 方法。 第一个参数是事件的名称,第二个参数是您要传递的任何标准事件对象,第三个是您要传递的任何自定义事件对象。

这里我们在按钮移动超过 x=400 时触发一个事件。 您所要做的就是添加移动功能 −

if(x<400) { this._trigger("outbounds",{}, {position:x}); }

在这种情况下,该事件称为出站,并且一个空事件对象与一个自定义事件对象一起传递,该对象仅将位置作为其唯一属性提供。

整个移动函数是 −

move: function(dx) {
   var x = dx + parseInt(this._button.css("left")); 
   this._button.css("left", x); 
   if(x<400) { this._trigger("outbounds",{}, {position:x}); }
}

用户只需定义同名选项即可设置事件处理函数。

$("button4").myButton("option", {
   width: 100, 
   color: "red",
   outbounds:function(e,ui) {
      alert(ui.position);}
});
<!DOCTYPE html>
<html>
   <head>
      <meta charset = "utf-8">
      <title>jQuery UI Widget - Default functionality</title>
      <link rel = "stylesheet" href = "//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
      <script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
      <script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
      
      <script>
         $(function() {
            $.widget("iP.myButton", {
               _create: function() { 
                  this._button = $("<button>"); 
                  this._button.text("My first Widget Button");
                  this._button.width(this.options.width) 
                  this._button.css("background-color", this.options.color);    
                  this._button.css("position", "absolute");   
                  this._button.css("left", "100px");            
                  $(this.element).append(this._button);
               },
               move: function(dx) { 
                  var x = dx + parseInt(this._button.css("left")); 
                  this._button.css("left", x); 
                  if(x>400) { this._trigger("outbounds",{},  {position:x}); }
               }
            });
            $("#button4").myButton();
            $("#button4").on("mybuttonoutbounds", function(e, ui) {
               //alert("out");
            });
            $("#button4").myButton("move", 500);
         });
      </script>
   </head>
   
   <body>
      <div id = "button4"></div>
   </body>
</html>

让我们将上面的代码保存在一个 HTML 文件 widgetfactoryexample.htm 中并在支持 javascript 的标准浏览器中打开它,一个警告框打开。