API jQuery UI - Fabrique de widgets
Catégorie
Utilisation de jQuery.widget( name [, base ], prototype )
Description :Créer des plugins jQuery avec état en utilisant la même abstraction que tous les widgets jQuery UI.
| Parameters | Type | Type |
|---|---|---|
| name | String | Le nom du widget à créer, y compris l'espace de noms. |
| base | Function() | Le widget de base dont hériter. Doit être un constructeur pouvant être instancié avec le mot-clé `new`. Par défaut : jQuery.Widget. |
| prototype | PlainObject | L'objet à utiliser comme prototype du widget. |
Vous pouvez utiliser$.Widgetun objet comme base dont hériter, ou vous pouvez explicitement créer un nouveau widget à partir de zéro en vous basant sur un contrôle jQuery UI existant ou tiers. Définir un widget avec le même nom pour hériter du widget de base vous permet même d'étendre le widget de manière appropriée.
jQuery UI contient de nombreux widgets avec état, le modèle d'utilisation est donc légèrement différent de celui des plugins jQuery classiques. Tous les widgets jQuery UI utilisent le même modèle, défini par la fabrique de widgets. Ainsi, une fois que vous avez appris à en utiliser un, vous savez comment utiliser les autres widgets.
Remarque : Ce chapitre utilise leWidget Progressbarcomme exemple de démonstration, mais la syntaxe s'applique à tous les widgets.
Initialisation
Afin de suivre l'état du widget, nous devons présenter le cycle de vie complet du widget. Le cycle de vie commence lorsque le widget est initialisé. Pour initialiser un widget, nous appelons simplement le plugin sur un ou plusieurs éléments.
$( "#elem" ).progressbar();
Cela initialise chaque élément de l'objet jQuery. Dans l'exemple ci-dessus, l'id de l'élément est `progressbar`."elem"。
Options
Parce queprogressbar()il est appelé sans arguments, le widget est initialisé avec les options par défaut. Nous pouvons passer un ensemble d'options lors de l'initialisation pour remplacer les options par défaut :
$( "#elem" ).progressbar({ value: 20 });
Nous pouvons passer autant d'options que nécessaire, et toutes les options que nous ne passons pas utilisent leurs valeurs par défaut.
Vous pouvez passer plusieurs arguments d'option, qui seront fusionnés en un seul objet (similaire à$.extend( true, target, object1, objectN )`$.extend`). Cela est utile pour surcharger certains paramètres pour toutes les instances et partager des options entre les instances :
var options = { modal: true, show: "slow" };
$( "#dialog1" ).dialog( options );
$( "#dialog2" ).dialog( options, { autoOpen: false });
Toutes les options passées lors de l'initialisation sont copiées en profondeur, ce qui garantit que les objets peuvent être modifiés plus tard sans affecter le widget. Les tableaux sont la seule exception ; ils sont référencés tels quels. Cette exception vise à prendre correctement en charge la liaison de données, où la source de données doit être une référence.
Les valeurs par défaut sont stockées dans les propriétés du widget, nous pouvons donc remplacer les valeurs définies par jQuery UI. Par exemple, après le paramètre suivant, toutes les futures instances de progressbar auront par défaut une valeur de 80 :
$.ui.progressbar.prototype.options.value = 80;
Les options font partie intégrante de l'état du widget, nous pouvons donc aussi définir des options après l'initialisation. Nous verrons la méthode option plus tard.
Méthodes
Maintenant que le widget a été initialisé, nous pouvons interroger son état ou effectuer des actions sur le widget. Toutes les actions après l'initialisation sont effectuées en appelant des méthodes. Pour appeler une méthode sur le widget, nous passons le nom de la méthode au plugin jQuery. Par exemple, pour appeler lavalue()la méthode `value`, nous pouvons utiliser :
$( "#elem" ).progressbar( "value" );
Si une méthode accepte des paramètres, nous pouvons les passer après le nom de la méthode. Par exemple, pour passer le paramètre `2` à la40àvalue()la méthode `value`, nous pouvons utiliser :
$( "#elem" ).progressbar( "value", 40 );
Comme les autres méthodes de jQuery, la plupart des méthodes de widget renvoient l'objet jQuery :
$( "#elem" ) .progressbar( "value", 90 ) .addClass( "almost-done" );
Chaque widget possède son propre ensemble de méthodes en fonction des fonctionnalités qu'il fournit. Cependant, certaines méthodes existent sur tous les widgets, elles sont expliquées en détail ci-dessous.
Événements
Tous les widgets ont des événements associés à leurs différents comportements pour vous notifier lorsque l'état change. Pour la plupart des widgets, lorsqu'un événement est déclenché, son nom est préfixé par la forme en minuscules du nom du widget. Par exemple, nous pouvons lier l'événementchange`change` du progressbar, qui est déclenché lorsque la valeur change.
$( "#elem" ).bind( "progressbarchange", function() {
alert( "The value has changed!" );
});
Chaque événement a une fonction de rappel correspondante, disponible en tant qu'option. Si nécessaire, nous pouvons nous connecter auchangerappel `change` du progressbar au lieu de lierprogressbarchangel'événement `change`.
$( "#elem" ).progressbar({
change: function() {
alert( "The value has changed!" );
}
});
Tous les widgets ont unchangeévénement `create`, qui est déclenché lors de l'instanciation.
Instanciation
L'instance du widget est stockée en utilisant le nom complet du widget comme clé dansjQuery.data()`data`. Par conséquent, vous pouvez utiliser le code suivant pour récupérer l'objet d'instance du widget Progressbar à partir d'un élément.
$( "#elem" ).data( "ui-progressbar" );
Le fait qu'un élément soit lié à un widget donné peut être détecté à l'aide du:datasélecteur `:ui-progressbar`.
$( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true $( "#elem" ).is( ":data( 'ui-draggable' )" ); // false
Vous pouvez également utiliser:datapour obtenir une liste de tous les éléments qui sont des instances d'un widget donné.
$( ":data( 'ui-progressbar' )" );
Propriétés
Tous les widgets ont les propriétés suivantes :
- defaultElement`defaultElement` : L'élément à utiliser lorsqu'aucun élément n'a été fourni lors de la construction de l'instance du widget. Par exemple, étant donné que le
defaultElementOui"<div>",$.ui.progressbar({ value: 50 })`defaultElement` de la barre de progression est un<div>`div` nouvellement créé, vous pouvez instancier une instance du widget Progressbar sans passer d'élément. - document`document` : Le document qui contient l'élément du widget.
documentUtile si vous devez interagir avec le widget dans un iframe. - element`element` : Un objet jQuery contenant l'élément utilisé pour instancier le widget. Si vous sélectionnez plusieurs éléments et appelez
.myWidget()`.progressbar()`, une instance de widget distincte sera créée pour chaque élément. Par conséquent, cette propriété contient toujours un élément. - namespace`namespace` : emplacement dans l'objet jQuery global où le prototype du widget est stocké. Par exemple,
"ui"denamespace`$.ui.draggable` indique que le prototype du widget est stocké dans$.ui。 - options`$.ui.draggable`. `options` : un objet contenant les options actuellement utilisées par le widget. Lors de l'instanciation, toutes les options fournies par l'utilisateur seront automatiquement fusionnées avec
$.myNamespace.myWidget.prototype.optionsles valeurs par défaut définies dans le prototype du widget. Les options spécifiées par l'utilisateur remplacent les valeurs par défaut. - uuid`uuid` : un entier unique représentant l'identifiant du widget.
- version`version` : la version sous forme de chaîne du widget. Pour les widgets jQuery UI, cette propriété est définie sur la version de jQuery UI utilisée par le widget. Les développeurs de plugins doivent définir explicitement cette propriété dans leurs prototypes.
- widgetEventPrefix`widgetEventPrefix` : le préfixe ajouté aux noms d'événements du widget. Par exemple,le widget Draggablede
widgetEventPrefixOui"drag", donc lors de la création d'un draggable, le nom de l'événement est"dragcreate"`dragcreate`. Par défaut, lewidgetEventPrefix`widgetEventPrefix` du widget est son nom.Remarque : cette propriété est obsolète et sera supprimée dans les versions futures. Les noms d'événements seront modifiés en widgetName:eventName (par exemple `progressbarcreate`)."draggable:create")。 - widgetFullName`widgetFullName` : le nom complet du widget, incluant l'espace de noms. Pour
$.widget( "myNamespace.myWidget", {} ),widgetFullNamela barre de progression, ce sera `ui-progressbar`."myNamespace-myWidget"。 - widgetName`name`: Le nom du widget. Pour
$.widget( "myNamespace.myWidget", {} ),widgetNamela barre de progression, ce sera `progressbar`."myWidget"。 - window`window`: La fenêtre qui contient l'élément du widget.
windowUtile si vous devez interagir avec le widget dans un iframe.
Utilisation du widget de base jQuery.Widget
Description :Le widget de base utilisé par la fabrique de widgets.
Navigation rapide
| Options | Méthodes | Événements |
|---|---|---|
| Options | Type | Description | Default |
|---|---|---|---|
| disabled | Boolean | Si défini surtrue`true`, le widget est désactivé.Exemples de code : Initialiser un widget avec l'option spécifiée
$( ".selector" ).widget({ disabled: true });
Obtenir ou définir l' // getter var disabled = $( ".selector" ).widget( "option", "disabled" ); // setter $( ".selector" ).widget( "option", "disabled", true ); |
false |
| hide | Boolean ou Number ou String ou Object | Si et comment utiliser une animation pour masquer l'élément. Plusieurs types sont pris en charge :
Exemples de code : Initialiser le widget avec le spécifié
$( ".selector" ).widget({ hide: { effect: "explode", duration: 1000 } });
Après l'initialisation, obtenir ou définir l'
// getter
var hide = $( ".selector" ).widget( "option", "hide" );
// setter
$( ".selector" ).widget( "option", "hide", { effect: "explode", duration: 1000 } );
|
null |
| show | Boolean ou Number ou String ou Object | Indique si l'élément doit être affiché avec une animation, et comment animer l'affichage. Prend en charge plusieurs types :
Exemples de code : Initialiser le widget avec le spécifié
$( ".selector" ).widget({ show: { effect: "blind", duration: 800 } });
Après l'initialisation, obtenir ou définir l'
// getter
var show = $( ".selector" ).widget( "option", "show" );
// setter
$( ".selector" ).widget( "option", "show", { effect: "blind", duration: 800 } );
|
null |
| Méthodes | Renvoie | Description |
|---|---|---|
| _create() | jQuery (plugin uniquement) | _create()est la méthode constructeur du widget. Elle ne prend aucun argument, maisthis.elementetthis.optionsest déjà défini.
Exemples de code : Définit la couleur d'arrière-plan de l'élément widget en fonction d'une option.
_create: function() {
this.element.css( "background-color", this.options.color );
}
|
| _delay( fn [, delay ] ) | Number | Appelle la fonction fournie après le délai spécifié. Maintientthisle contexte correct. EssentiellementsetTimeout()。utilise clearTimeout()renvoie l'identifiant du timeout.
Exemples de code : Après 100 millisecondes, sur le widget, appelez la méthode this._delay( this._foo, 100 ); |
| _destroy() | jQuery (plugin uniquement) | La méthode publiquedestroy()efface toutes les données publiques, les événements, etc. Elle représente le nettoyage personnalisé spécifique au widget._destroy()。
Exemples de code : Supprime une classe de l'élément du widget lorsque le widget est détruit.
_destroy: function() {
this.element.removeClass( "my-widget" );
}
|
| _focusable( element ) | jQuery (plugin uniquement) | Établit, lors de la mise au point sur un élément, laui-state-focusclasse à appliquer.element。
Exemples de code : Applique un style focusable à un groupe d'éléments au sein du widget : this._focusable( this.element.find( ".my-items" ) ); |
| _getCreateEventData() | Object | Tous les widgets déclenchentcreatedes événements. Par défaut, aucune donnée n'est fournie dans l'événement, mais cette méthode renvoie un objet qui est passé commecreatedonnées d'événement.
Exemples de code : vers
_getCreateEventData: function() {
return this.options;
}
|
| _getCreateOptions() | Object | Cette méthode permet au widget de définir une méthode personnalisée pour définir des options lors de l'initialisation. Les options fournies par l'utilisateur remplacent les options renvoyées par cette méthode, c'est-à-dire qu'elles remplacent les options par défaut.
Exemples de code : Rend l'attribut id de l'élément du widget disponible en tant qu'option.
_getCreateOptions: function() {
return { id: this.element.attr( "id" ) };
}
|
| _hide( element, option [, callback ] ) | jQuery (plugin uniquement) | Masque un élément à l'aide d'une méthode d'animation intégrée ou d'un effet personnalisé. Pour lesoptionvaleurs, voirhide。
Exemples de code : Passes
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 uniquement) | Établit, lors du survol d'un élément, leui-state-hoverclasse à appliquer.element. Les gestionnaires d'événements sont automatiquement nettoyés lors de la destruction.
Exemples de code : Lors du survol de l'élément, à tous les éléments à l'intérieur de l'élément, this._hoverable( this.element.find( "div" ) ); |
| _init() | jQuery (plugin uniquement) | Le concept d'initialisation d'un widget est différent de sa création. Chaque fois que le plugin est appelé sans arguments ou avec uniquement un hash d'options, le widget est initialisé. Cette méthode est incluse lors de la création du widget. Remarque : S'il y a des actions logiques à effectuer lorsque le widget est appelé avec succès sans arguments, l'initialisation ne peut être gérée qu'à ce moment.
Exemples de code : Si la
_init: function() {
if ( this.options.autoOpen ) {
this.open();
}
}
|
| _off( element, eventName ) | jQuery (plugin uniquement) | Dissocie les gestionnaires d'événements de l'élément spécifié.
Exemples de code : Dissocie tous les événements click de l'élément du widget. this._off( this.element, "click" ); |
| _on( [suppressDisabledCheck ] [, element ], handlers ) | jQuery (plugin uniquement) | La délégation via des sélecteurs dans le nom de l'événement est prise en charge, par exemple"click .foo"。_on()La méthode offre plusieurs avantages par rapport à la liaison directe d'événements :
Exemples de code : Empêche le comportement par défaut de tous les liens cliqués à l'intérieur de l'élément du widget.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
}
});
|
| _setOption( key, value ) | jQuery (plugin uniquement) | Pour chaque option individuelle, appelle la_setOptions()méthode. L'état du widget est mis à jour au fur et à mesure des modifications.
Exemples de code : Lorsque l'option du widget
_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 uniquement) | Lorsque laoption()méthode est appelée, quelle que soit la forme sous laquelle elle est appeléeoption(). Si vous devez modifier des gestionnaires gourmands en ressources en fonction de plusieurs changements d'option, redéfinir cette méthode est utile.
Exemples de code : Si l'option du widget
_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 uniquement) | Affiche un élément à l'aide d'une méthode d'animation intégrée ou d'un effet personnalisé. Pour lesoptionvaleurs possibles, voirshow。
Exemple de code : Passer une animation personnalisée
this._show( this.element, this.options.show, function() {
// Focus the element when it's fully visible.
this.focus();
}
|
| _super( [arg ] [, ... ] ) | jQuery (plugin uniquement) | Appelle la méthode du même nom sur le widget parent, avec les arguments spécifiés. Essentiellement,.call()。
Exemple de code : Gérer
_setOption: function( key, value ) {
if ( key === "title" ) {
this.element.find( "h3" ).text( value );
}
this._super( key, value );
}
|
| _superApply( arguments ) | jQuery (plugin uniquement) | 在父部件上调用同名方法,并传入一个参数数组。本质上,.apply()。
Exemple de code : Gérer
_setOption: function( key, value ) {
if ( key === "title" ) {
this.element.find( "h3" ).text( value );
}
this._superApply( arguments );
}
|
| _trigger( type [, event ] [, data ] ) | Boolean | 触发一个事件及其关联的回调。带有该名称的选项等同于作为回调调用的类型。 事件名称是由部件名称和类型组成的小写字符串。 注意:当提供 data 时,必须提供全部三个参数。如果未传入 event,则传入 如果默认行为被阻止,则返回
Exemple de code : Lorsqu'une touche est enfoncée, déclenchez le
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 uniquement) | Supprimer complètement la fonctionnalité du widget. Cela ramène l'élément à son état de pré-initialisation.
Exemple de code : Détruire le widget lorsque l'on clique sur n'importe quelle ancre du widget.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.destroy();
}
});
|
| disable() | jQuery (plugin uniquement) | Désactiver le widget.
Exemple de code : Désactiver le widget lorsque l'on clique sur n'importe quelle ancre du widget.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.disable();
}
});
|
| enable() | jQuery (plugin uniquement) | Activer le widget.
Exemple de code : Activer le widget lorsque l'on clique sur n'importe quelle ancre du widget.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.enable();
}
});
|
| option( optionName ) | Object | Obtient la valeur actuellement associée au paramètre spécifiéoptionNamevaleur associée.
Exemple de code : Obtenez la this.option( "width" ); |
| option() | PlainObject | Obtient un objet contenant des paires clé/valeur qui représentent le hash actuel des options du widget.
Exemple de code : Journalisez les paires clé/valeur de chaque option du widget pour le débogage.
var options = this.option();
for ( var key in options ) {
console.log( key, options[ key ] );
}
|
| option( optionName, value ) | jQuery (plugin uniquement) | Définit, avec la valeur spécifiée,optionNamela valeur de l'option du widget associée.
Exemple de code : Définissez l' this.option( "width", 500 ); |
| option( options ) | jQuery (plugin uniquement) | Définit une ou plusieurs options pour le widget.
Exemple de code : Définissez l'
this.option({
width: 500,
height: 500
});
|
| widget() | jQuery | Renvoie un objet contenant l'élément d'origine ou d'autres éléments générés associésjQueryobjet.
Exemple de code : Lorsque le widget est créé, placez une bordure rouge autour de l'élément d'origine du widget.
_create: function() {
this.widget().css( "border", "2px solid red" );
}
|
| Événements | Type | Description |
|---|---|---|
| create( event, ui ) | widgetcreate | Déclenché lorsque le widget est créé.
Remarque : Exemple de code : Initialisez le widget avec le callback create spécifié :
$( ".selector" ).widget({
create: function( event, ui ) {}
});
Liez un écouteur d'événement à l'événement widgetcreate :
$( ".selector" ).on( "widgetcreate", function( event, ui ) {} );
|