jQuery UI API - Widget Factory
Categoría
Uso de jQuery.widget( name [, base ], prototype )
Descripción:Cree complementos (plugins) de jQuery con estado utilizando la misma abstracción que todos los widgets de jQuery UI.
| Parámetros | Tipo | Tipo |
|---|---|---|
| name | String | El nombre del widget a crear, incluido el espacio de nombres. |
| base | Function() | El widget base a heredar. Debe ser un constructor que pueda instanciarse con la palabra clave `new`. El valor predeterminado es jQuery.Widget. |
| prototype | PlainObject | El objeto que se utilizará como prototipo del widget. |
Puede usar$.Widgetel objeto como base para heredar, o puede crear explícitamente un nuevo widget desde cero basándose en un widget existente de jQuery UI o de terceros. Definir un widget con el mismo nombre para heredar del widget base incluso le permite extender el widget de manera adecuada.
jQuery UI incluye muchos widgets que mantienen estado, por lo que tienen un patrón de uso ligeramente diferente al de los complementos típicos de jQuery. Todos los widgets de jQuery UI utilizan el mismo patrón, definido por el Widget Factory. Por lo tanto, si aprende a usar uno, sabrá cómo usar los demás widgets.
Nota: este capítulo utilizael widget de barra de progreso (Progressbar Widget)como ejemplo de demostración, pero la sintaxis se aplica a todos los widgets.
Inicialización
Para rastrear el estado del widget, debemos presentar el ciclo de vida completo del widget. El ciclo de vida comienza cuando se inicializa el widget. Para inicializar un widget, simplemente llamamos al complemento en uno o más elementos.
$( "#elem" ).progressbar();
Esto inicializará cada elemento del objeto jQuery. En el ejemplo anterior, el elemento con id"elem"。
Opciones
Debido a queprogressbar()al llamarse sin argumentos, el widget se inicializa con las opciones predeterminadas. Podemos pasar un conjunto de opciones en la inicialización para sobrescribir las predeterminadas:
$( "#elem" ).progressbar({ value: 20 });
Podemos pasar tantas opciones como necesitemos; cualquier opción que no pasemos utilizará su valor predeterminado.
Puede pasar múltiples argumentos de opciones, que se fusionarán en un solo objeto (similar a$.extend( true, target, object1, objectN )). Esto es útil para sobrescribir algunas configuraciones para todas las instancias y compartir opciones entre instancias:
var options = { modal: true, show: "slow" };
$( "#dialog1" ).dialog( options );
$( "#dialog2" ).dialog( options, { autoOpen: false });
Todas las opciones pasadas en la inicialización son copias profundas, lo que garantiza que los objetos puedan modificarse posteriormente sin afectar al widget. La única excepción son los arreglos, que se referencian tal cual. Esta excepción existe para admitir adecuadamente el enlace de datos, donde la fuente de datos debe pasarse por referencia.
Los valores predeterminados se almacenan en las propiedades del widget, por lo que podemos sobrescribir los valores establecidos por jQuery UI. Por ejemplo, después de la siguiente configuración, todas las futuras instancias de la barra de progreso tendrán como valor predeterminado 80:
$.ui.progressbar.prototype.options.value = 80;
Las opciones son una parte integral del estado del widget, por lo que también podemos establecer opciones después de la inicialización. Veremos el método `option` más adelante.
Métodos
Ahora que el widget está inicializado, podemos consultar su estado o realizar acciones en él. Todas las acciones posteriores a la inicialización se ejecutan como llamadas a métodos. Para llamar a un método en un widget, pasamos el nombre del método al complemento de jQuery. Por ejemplo, para llamar al métodovalue(), podemos utilizar:
$( "#elem" ).progressbar( "value" );
Si el método acepta parámetros, podemos pasarlos después del nombre del método. Por ejemplo, para pasar el parámetro40llegarvalue()al método, podemos usar:
$( "#elem" ).progressbar( "value", 40 );
Al igual que otros métodos en jQuery, la mayoría de los métodos de widget devuelven un objeto jQuery:
$( "#elem" ) .progressbar( "value", 90 ) .addClass( "almost-done" );
Cada widget tiene su propio conjunto de métodos, basado en la funcionalidad que proporciona. Sin embargo, hay algunos métodos que existen en todos los widgets, como se detalla a continuación.
Eventos
Todos los widgets tienen eventos asociados con sus diversos comportamientos para notificarle cuando cambia el estado. En la mayoría de los widgets, cuando se dispara un evento, el nombre lleva como prefijo el nombre del widget en minúsculas. Por ejemplo, podemos vincular el eventochangede la barra de progreso, que se dispara cuando cambia el valor.
$( "#elem" ).bind( "progressbarchange", function() {
alert( "The value has changed!" );
});
Cada evento tiene una devolución de llamada (callback) correspondiente, que se expone como una opción. Si es necesario, podemos usar la devolución de llamadachangede la barra de progreso en lugar de vincular el eventoprogressbarchange.
$( "#elem" ).progressbar({
change: function() {
alert( "The value has changed!" );
}
});
Todos los widgets tienen un eventochangeque se dispara en el momento de la instanciación.
Instanciación
La instancia del widget se almacena usando la clave con el nombre completo del widget enjQuery.data(). Por lo tanto, puede usar el siguiente código para recuperar el objeto de instancia del widget de barra de progreso desde el elemento.
$( "#elem" ).data( "ui-progressbar" );
Para saber si un elemento tiene vinculado un widget determinado, puede usar:datael selector para comprobarlo.
$( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true $( "#elem" ).is( ":data( 'ui-draggable' )" ); // false
También puede usar:datapara obtener una lista de todos los elementos que son instancias de un widget determinado.
$( ":data( 'ui-progressbar' )" );
Propiedades
Todos los widgets tienen las siguientes propiedades:
- defaultElement: el elemento que se utilizará cuando no se proporcione un elemento al construir la instancia del widget. Por ejemplo, como el
defaultElementSí"<div>",$.ui.progressbar({ value: 50 })de la barra de progreso se instancia en un nuevo<div>, se crea una instancia del widget de barra de progreso sobre él. - document: el documento que contiene el elemento del widget.
documentÚtil si necesita interactuar con el widget dentro de un marco (iframe). - element: un objeto jQuery que contiene el elemento utilizado para instanciar el widget. Si selecciona varios elementos y llama a
.myWidget(), se creará una instancia de widget separada para cada elemento. Por lo tanto, esta propiedad siempre contiene un elemento. - namespace: la ubicación global del objeto jQuery donde se almacena el prototipo del widget. Por ejemplo,
"ui"denamespaceindica que el prototipo del widget se almacena en$.ui。 - options: un objeto que contiene las opciones actuales del widget. Durante la instanciación, cualquier opción proporcionada por el usuario se fusiona automáticamente con
$.myNamespace.myWidget.prototype.optionslos valores predeterminados definidos en . Las opciones especificadas por el usuario sobrescriben los valores predeterminados. - uuid: un entero único que representa el identificador del control.
- version: la versión de cadena del widget. Para los widgets de jQuery UI, esta propiedad se establece con la versión de jQuery UI que utiliza el widget. Los desarrolladores de complementos deben establecer esta propiedad explícitamente en sus prototipos.
- widgetEventPrefix: el prefijo que se agrega a los nombres de los eventos del widget. Por ejemplo,el widget arrastrable (Draggable Widget)de
widgetEventPrefixSí"drag", por lo que al crear un draggable, el nombre del evento es"dragcreate". De manera predeterminada, elwidgetEventPrefixdel widget es su nombre.Nota: esta propiedad está en desuso y se eliminará en versiones futuras. Los nombres de eventos se cambiarán a widgetName:eventName (por ejemplo,"draggable:create")。 - widgetFullName: el nombre completo del widget, incluido el espacio de nombres. Para
$.widget( "myNamespace.myWidget", {} ),widgetFullNameserá"myNamespace-myWidget"。 - widgetName: el nombre del widget. Para
$.widget( "myNamespace.myWidget", {} ),widgetNameserá"myWidget"。 - window: el documento que contiene el elemento del widget.
window. Útil si necesita interactuar con el widget dentro de un marco (iframe).
Uso del widget base jQuery.Widget
Descripción:El widget base utilizado por el Widget Factory.
Navegación rápida
| Opciones | Métodos | Eventos |
|---|---|---|
| Opciones | Tipo | Descripción | Valor predeterminado |
|---|---|---|---|
| disabled | Boolean | Si se establece entrue, el widget queda deshabilitado.Ejemplo de código: Inicialice el widget con la opción
$( ".selector" ).widget({ disabled: true });
Después de la inicialización, obtenga o establezca la opción // getter var disabled = $( ".selector" ).widget( "option", "disabled" ); // setter $( ".selector" ).widget( "option", "disabled", true ); |
false |
| hide | Boolean, Number, String u Object | Si se debe ocultar el elemento con animación y cómo hacerlo. Admite varios tipos:
Ejemplo de código: Inicializar el widget con la opción
$( ".selector" ).widget({ hide: { effect: "explode", duration: 1000 } });
Después de la inicialización, obtener o establecer la opción
// getter
var hide = $( ".selector" ).widget( "option", "hide" );
// setter
$( ".selector" ).widget( "option", "hide", { effect: "explode", duration: 1000 } );
|
null |
| show | Boolean, Number, String u Object | Si se usa animación para mostrar el elemento y cómo animarlo. Se admiten varios tipos:
Ejemplo de código: Inicializar el widget con la opción
$( ".selector" ).widget({ show: { effect: "blind", duration: 800 } });
Después de la inicialización, obtener o establecer la opción
// getter
var show = $( ".selector" ).widget( "option", "show" );
// setter
$( ".selector" ).widget( "option", "show", { effect: "blind", duration: 800 } );
|
null |
| Método | Devuelve | Descripción |
|---|---|---|
| _create() | jQuery (plugin only) | _create()El método es el constructor del widget. No tiene parámetros, perothis.elementythis.optionsya está establecido.
Ejemplo de código: Establece el color de fondo del elemento del widget basándose en una opción.
_create: function() {
this.element.css( "background-color", this.options.color );
}
|
| _delay( fn [, delay ] ) | Number | Llama a la función proporcionada después del retraso especificado. Mantienethisel contexto correcto. Es esencialmentesetTimeout()。usando clearTimeout()Devuelve el ID de tiempo de espera.
Ejemplo de código: Después de 100 milisegundos, en el widget, llama al this._delay( this._foo, 100 ); |
| _destroy() | jQuery (plugin only) | El método públicodestroy()limpia todos los datos, eventos, etc. públicos. Representa la personalización, el widget específico y la limpieza._destroy()。
Ejemplo de código: Elimina una clase del elemento del widget cuando el widget es destruido.
_destroy: function() {
this.element.removeClass( "my-widget" );
}
|
| _focusable( element ) | jQuery (plugin only) | Establece la que se aplicará cuando el elemento reciba el focoui-state-focusclase.element。
Ejemplo de código: Aplica el estilo focusable a un grupo de elementos dentro del widget: this._focusable( this.element.find( ".my-items" ) ); |
| _getCreateEventData() | Object | Todos los widgets disparan elcreateevento. De forma predeterminada, no se proporcionan datos en el evento, pero este método devuelve un objeto que se pasa comocreatelos datos del evento se pasan.
Ejemplo de código: hacia
_getCreateEventData: function() {
return this.options;
}
|
| _getCreateOptions() | Object | Este método permite al widget definir un método personalizado para definir opciones durante la inicialización. Las opciones proporcionadas por el usuario sobrescriben las opciones devueltas por este método, es decir, sobrescriben las opciones predeterminadas.
Ejemplo de código: Hace que el atributo id del elemento del widget esté disponible como opción.
_getCreateOptions: function() {
return { id: this.element.attr( "id" ) };
}
|
| _hide( element, option [, callback ] ) | jQuery (plugin only) | Oculta un elemento utilizando los métodos de animación integrados o efectos personalizados. Para conocer los posiblesoptionvalores, consultehide。
Ejemplo de código: Para una animación personalizada, pase las
this._hide( this.element, this.options.hide, function() {
// Remove the element from the DOM when it's fully hidden.
$( this ).remove();
});
|
| _hoverable( element ) | jQuery (plugin only) | Establece la que se aplicará cuando se pase el cursor sobre el elementoui-state-hoverclase.element. El manejador de eventos se limpia automáticamente al destruir.
Ejemplo de código: Cuando se pasa el cursor sobre el elemento, a todos los this._hoverable( this.element.find( "div" ) ); |
| _init() | jQuery (plugin only) | La noción de inicialización del widget es diferente de la creación. En cualquier momento, llamar al plugin sin parámetros o solo con un hash de opciones inicializa el widget. Este método se incluye cuando se crea el widget. Nota: Si hay acciones lógicas que deben ejecutarse cuando el widget se llama exitosamente sin parámetros, la inicialización solo puede manejarlas en ese momento.
Ejemplo de código: Si se establece
_init: function() {
if ( this.options.autoOpen ) {
this.open();
}
}
|
| _off( element, eventName ) | jQuery (plugin only) | Desvincula los manejadores de eventos del elemento especificado.
Ejemplo de código: Desvincula todos los eventos click del elemento del widget. this._off( this.element, "click" ); |
| _on( [suppressDisabledCheck ] [, element ], handlers ) | jQuery (plugin only) | La delegación se admite mediante selectores dentro del nombre del evento, por ejemplo"click .foo"。_on()El método proporciona algunos beneficios de la vinculación directa de eventos:
Ejemplo de código: Previene el comportamiento predeterminado de todos los enlaces en los que se hace clic dentro del elemento del widget.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
}
});
|
| _setOption( key, value ) | jQuery (plugin only) | Para cada opción individual, llama al_setOptions()método. El estado del widget se actualiza a medida que cambia.
Ejemplo de código: Cuando la
_setOption: function( key, value ) {
if ( key === "width" ) {
this.element.width( value );
}
if ( key === "height" ) {
this.element.height( value );
}
this._super( key, value );
}
|
| _setOptions( options ) | jQuery (plugin only) | Cuando se llama aloption()método, se invoca sin importar de qué forma se llame aoption(). Si necesita cambiar el procesamiento intensivo según los cambios de múltiples opciones, es útil sobrescribir este método.
Ejemplo de código: Si la
_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();
}
}
|
| _show( element, option [, callback ] ) | jQuery (plugin only) | Muestra un elemento utilizando los métodos de animación integrados o efectos personalizados. Para conocer los posiblesoptionvalores, consulteshow。
Código de ejemplo: Pasar para animaciones personalizadas
this._show( this.element, this.options.show, function() {
// Focus the element when it's fully visible.
this.focus();
}
|
| _super( [arg ] [, ... ] ) | jQuery (plugin only) | Llama al método del mismo nombre desde el widget padre, con los argumentos especificados. En esencia,.call()。
Código de ejemplo: Manejar
_setOption: function( key, value ) {
if ( key === "title" ) {
this.element.find( "h3" ).text( value );
}
this._super( key, value );
}
|
| _superApply( arguments ) | jQuery (plugin only) | Llama al método del mismo nombre desde el widget padre, con una matriz de argumentos. En esencia,.apply()。
Código de ejemplo: Manejar
_setOption: function( key, value ) {
if ( key === "title" ) {
this.element.find( "h3" ).text( value );
}
this._superApply( arguments );
}
|
| _trigger( type [, event ] [, data ] ) | Boolean | Desencadena un evento y sus devoluciones de llamada asociadas. La opción con ese nombre es igual al tipo que se invoca como devolución de llamada. El nombre del evento es una cadena en minúsculas del nombre del widget y del tipo. Nota: cuando se proporcionan datos, debe proporcionar los tres argumentos. Si no se pasa ningún evento, pase Si se previene el comportamiento predeterminado, devuelve
Código de ejemplo: Cuando se presiona una tecla, se desencadena
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()
});
}
});
|
| destroy() | jQuery (plugin only) | Elimina por completo la funcionalidad del widget. Esto devuelve el elemento a su estado previo a la inicialización.
Código de ejemplo: Destruye el widget cuando se hace clic en cualquier ancla del widget.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.destroy();
}
});
|
| disable() | jQuery (plugin only) | Deshabilita el widget.
Código de ejemplo: Deshabilita el widget cuando se hace clic en cualquier ancla del widget.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.disable();
}
});
|
| enable() | jQuery (plugin only) | Habilita el widget.
Código de ejemplo: Habilita el widget cuando se hace clic en cualquier ancla del widget.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.enable();
}
});
|
| option( optionName ) | Object | Obtiene el valor actual asociado con laoptionNameopción especificada.
Código de ejemplo: Obtener this.option( "width" ); |
| option() | PlainObject | Obtiene un objeto que contiene pares clave/valor que representan el hash de opciones actual del widget.
Código de ejemplo: Registra los pares clave/valor de cada opción del widget, para depuración.
var options = this.option();
for ( var key in options ) {
console.log( key, options[ key ] );
}
|
| option( optionName, value ) | jQuery (plugin only) | Establece el valor asociado con laoptionNameTipo: String
Establecer la opción como this.option( "width", 500 ); |
| option( options ) | jQuery (plugin only) | Establece una o más opciones para el widget.
Código de ejemplo: Establecer
this.option({
width: 500,
height: 500
});
|
| widget() | jQuery | Devuelve un objeto que contiene el elemento original u otros elementos generados relacionadosjQueryobjeto.
Código de ejemplo: Cuando se crea el widget, coloca un borde rojo alrededor del elemento original del widget.
_create: function() {
this.widget().css( "border", "2px solid red" );
}
|
| Eventos | Tipo | Descripción |
|---|---|---|
| create( event, ui ) | widgetcreate | Se desencadena cuando se crea el widget.
Nota: Código de ejemplo: Inicializa el widget con el callback create especificado:
$( ".selector" ).widget({
create: function( event, ui ) {}
});
Vincula un detector de eventos al evento widgetcreate:
$( ".selector" ).on( "widgetcreate", function( event, ui ) {} );
|