jQuery UI API - Widget Factory

Code examples:

Initialize a widget with the specifieddisabled`disabled` option:

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

Get or set thedisabled`disabled` option after initialization:

// getter
var disabled = $( ".selector" ).widget( "option", "disabled" );
 
// setter
$( ".selector" ).widget( "option", "disabled", true );
    

Multiple types are supported:

• Boolean: When set tofalse`false`, no animation is used and the element is hidden immediately. When set totrue`true`, the element fades out with the default duration and default easing.
• Number: The element fades out with the specified duration and default easing.
• String: The element is hidden using the specified effect. The value can be a built-in jQuery animation method name, such as"slideUp"`slideUp`, or ajQuery UI effectname, such as"fold"For both of the above cases, the effect uses the default duration and the default easing.
• Object: If the value is an object, theneffect、delay、durationandeasingproperty is provided. Ifeffectproperty contains the name of a jQuery method, that method is used; otherwise, it is considered to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you can include those settings in the object, and they will be passed to the effect. Ifdurationoreasingis omitted, the default value is used. Ifeffectis omitted, then"fadeOut". Ifdelayis omitted, no delay is used.

Code examples:

Initialize the widget with the specifiedhideoption:

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

After initialization, get or set thehideoption:

// getter
var hide = $( ".selector" ).widget( "option", "hide" );
 
// setter
$( ".selector" ).widget( "option", "hide", { effect: "explode", duration: 1000 } );
    

Supports multiple types:

• Boolean: When set tofalse, no animation is used, and the element is displayed immediately. When set totrue, the element fades in using the default duration and default easing.
• Number: The element fades in using the specified duration and the default easing.
• String: The element will be displayed using the specified effect. The value can be the name of a built-in jQuery animation method, such as"slideDown", or it can be ajQuery UI effectname, such as"fold". For both of the above cases, the effect uses the default duration and default easing.
• Object: If the value is an object, theneffect、delay、durationandeasingproperty is provided. Ifeffectproperty contains the name of a jQuery method, that method is used; otherwise, it is considered to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you can include those settings in the object, and they will be passed to the effect. Ifdurationoreasingis omitted, the default value is used. Ifeffectis omitted, then"fadeIn". Ifdelayis omitted, no delay is used.

Code examples:

Initialize the widget with the specifiedshowoption:

$( ".selector" ).widget({ show: { effect: "blind", duration: 800 } });
    

After initialization, get or set theshowoption:

// getter
var show = $( ".selector" ).widget( "option", "show" );
 
// setter
$( ".selector" ).widget( "option", "show", { effect: "blind", duration: 800 } );
    

• This method accepts no arguments.

Code examples:

Sets the background color of the widget element based on an option.

_create: function() {
  this.element.css( "background-color", this.options.color );
}
    

• fn
  Type: Function() or String
  Description: The function to call. It can also be the name of a method on the widget.
• delay
  Type: Number
  Description: The number of milliseconds to wait before calling the function. Defaults to0。

Code examples:

After 100 milliseconds, on the widget, call the_foo()method.

this._delay( this._foo, 100 );
    

• This method accepts no arguments.

Code examples:

Removes a class from the widget's element when the widget is destroyed.

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

• element
  Type: jQuery
  Description: The element to apply the focusable behavior to.

Code examples:

Applies focusable styling to a group of elements within the widget:

this._focusable( this.element.find( ".my-items" ) );
    

• This method accepts no arguments.

Code examples:

towardcreateThe event handler passes the widget's options as an argument.

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

• This method accepts no arguments.

Code examples:

Makes the id attribute of the widget's element available as an option.

_getCreateOptions: function() {
  return { id: this.element.attr( "id" ) };
}
    

• element
  Type: jQuery
  Description: The element to hide.
• option
  Type: Object
  Description: Settings that define how to hide the element.
• callback
  Type: Function()
  Description: A callback to call after the element is completely hidden.

Code examples:

Passeshideoptions for the custom animation.

this._hide( this.element, this.options.hide, function() {
 
  // Remove the element from the DOM when it's fully hidden.
  $( this ).remove();
});
    

• element
  Type: jQuery
  Description: The element to apply the hoverable behavior to.

Code examples:

When hovering over the element, to all elements within the element,divapply hoverable styling.

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

Note: If there are logical actions to be performed when the widget is successfully called without arguments, initialization can only be handled at this time.

• This method accepts no arguments.

Code examples:

If theautoOpenoption is set, then call theopen()method.

_init: function() {
  if ( this.options.autoOpen ) {
    this.open();
  }
}
    

• element
  Type: jQuery
  Description: The element to unbind event handlers from. Unlike the_on()method,_off()an element is required in the method.
• eventName
  Type: String
  Description: One or more space-separated event types.

Code examples:

Unbinds all click events from the widget's element.

this._off( this.element, "click" );
    

• Maintains the appropriatethiscontext within handlers.
• Automatically handles disabled widgets: if the widget is disabled or the event occurs on an element with theui-state-disabledclass, the event handler is not called. Can be overridden by thesuppressDisabledCheckparameter.
• Event handlers are automatically namespaced and automatically cleaned up on destroy.
• suppressDisabledCheck(default:false）
  Type: Boolean
  Description: Whether to bypass the disabled check.
• element
  Type: jQuery
  Description: The element to bind the event handlers to. If no element is provided,this.elementit is used for non-delegated events,the widget elementis used for delegated events.
• handlers
  Type: Object
  Description: A map in which string keys represent event types, optional selectors are used for delegation, and values represent the handler functions called for the events.

Code examples:

Prevents the default behavior of all clicked links within the widget element.

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

• key
  Type: String
  Description: The name of the option to set.
• value
  Type: Object
  Description: The value to set for the option.

Code examples:

When the widget'sheightorwidthoption changes, update the widget's element.

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

• options
  Type: Object
  Description: The value to set for the option.

Code examples:

If the widget'sheightorwidthoption changes, call theresizemethod.

_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();
  }
}
    

• element
  Type: jQuery
  Description: The element to show.
• option
  Type: Object
  Description: Settings that define how to show the element.
• callback
  Type: Function()
  Description: A callback to be called after the element is fully displayed.

Code example:

Pass a custom animationshowoption.

this._show( this.element, this.options.show, function() {
 
  // Focus the element when it's fully visible.
  this.focus();
}
    

• arg
  Type: Object
  Description: Zero or more arguments to pass to the parent widget's method.

Code example:

Handletitleoption updates, and call the parent widget's_setOption()to update the internal storage of the options.

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

• arguments
  Type: Array
  Description: An array of arguments to pass to the parent widget's method.

Code example:

Handletitleoption updates, and call the parent widget's_setOption()to update the internal storage of the options.

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

The event name is a lowercase string of the widget name and the type.

Note: When data is provided, you must provide all three parameters. If no event is passed, passnull。

If the default behavior is prevented, it returnsfalse, otherwise it returnstrue. When the handler returnsfalseor callsevent.preventDefault(), the default behavior is prevented.

• type
  Type: String
  Description:typeThe name should match the callback option. The full event type is generated automatically.
• event
  Type: Event
  Description: The original event that caused this event to occur, useful for providing context to listeners.
• data
  Type: Object
  Description: A data hash associated with the event.

Code example:

When a key is pressed, trigger thesearchevent.

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()
    });
  }
});
    

• This method accepts no arguments.

Code example:

Destroy the widget when any anchor of the widget is clicked.

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

• This method accepts no arguments.

Code example:

Disable the widget when any anchor of the widget is clicked.

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

• This method accepts no arguments.

Code example:

Enable the widget when any anchor of the widget is clicked.

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

• optionName
  Type: String
  Description: The name of the option to get.

Code example:

Get thewidthoption's value.

this.option( "width" );
    

• This method accepts no arguments.

Code example:

Log the key/value pairs of each widget option for debugging.

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

• optionName
  Type: String
  Description: The name of the option to set.
• value
  Type: Object
  Description: The value to set for the option.

Code example:

Set thewidthoption to500。

this.option( "width", 500 );
    

• options
  Type: Object
  Description: The option-value pairs to set.

Code example:

Set theheightandwidthoption to500。

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

• This method accepts no arguments.

Code example:

When the widget is created, place a red border around the widget's original element.

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

• event
  Type: Event
• ui
  Type: Object

Note:uiThe object is empty; it is included here for consistency with other events.

Code example:

Initialize the widget with the specified create callback:

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

Bind an event listener to the widgetcreate event:

$( ".selector" ).on( "widgetcreate", function( event, ui ) {} );