jQuery UI Как использовать фабрику виджетов
Мы создадим индикатор выполнения. Как показано в примере ниже, это можно сделать, вызвавjQuery.widget()чтобы добиться этого; этот вызов принимает два параметра: один — имя создаваемого плагина, а другой — объектный литерал, содержащий функции, поддерживающие плагин. При вызове плагина создаётся новый экземпляр плагина, и все функции будут выполняться в контексте этого экземпляра. Это отличается от стандартных плагинов jQuery двумя важными моментами. Во-первых, контекст — это объект, а не элемент DOM. Во-вторых, контекст всегда является одним объектом, а не коллекцией.
$.widget( "custom.progressbar", {
_create: function() {
var progress = this.options.value + "%";
this.element
.addClass( "progressbar" )
.text( progress );
}
});
Имя плагина должно содержать пространство имён. В этом примере мы используемcustomпространство имён. Вы можете создать пространство имён только на один уровень в глубину, поэтомуcustom.progressbarявляется допустимым именем плагина, тогда какvery.custom.progressbarне является допустимым именем плагина.
Мы видим, что Widget Factory предоставляет нам два свойства.this.elementявляется объектом jQuery, содержащим один элемент. Если наш плагин вызывается для объекта jQuery, содержащего несколько элементов, для каждого элемента будет создан отдельный экземпляр плагина, и каждый экземпляр будет иметь свой собственныйthis.element. Второе свойство,this.options, представляет собой хеш пар ключ/значение, содержащий все параметры плагина. Эти параметры можно передать плагину следующим образом:
$( "<div></div>" )
.appendTo( "body" )
.progressbar({ value: 20 });
Когда мы вызываемjQuery.widget(), он расширяет jQuery, добавляя функции вjQuery.fn(система, используемая для создания стандартных плагинов). Имена добавленных функций основаны на имени, которое вы передаёте вjQuery.widget()без пространства имён — "progressbar". Параметры, переданные плагину, — это значения, установленные в экземпляре плагина. Как показано в примере ниже, мы можем указать значения по умолчанию для любого параметра. При проектировании вашего API вы должны ясно понимать наиболее распространённые сценарии использования вашего плагина, чтобы вы могли задать подходящие значения по умолчанию и гарантировать, что все параметры действительно необязательны.
$.widget( "custom.progressbar", {
// Default options.
options: {
value: 0
},
_create: function() {
var progress = this.options.value + "%";
this.element
.addClass( "progressbar" )
.text( progress );
}
});
Вызов методов плагина
Теперь, когда мы можем инициализировать наш индикатор выполнения, мы будем выполнять действия, вызывая методы у экземпляра плагина. Чтобы определить метод плагина, мы просто ссылаемся на функцию в объекте, который передаём вjQuery.widget()этот объект. Мы также можем определять «приватные» методы, добавляя символ подчёркивания перед именем функции.
$.widget( "custom.progressbar", {
options: {
value: 0
},
_create: function() {
var progress = this.options.value + "%";
this.element
.addClass( "progressbar" )
.text( progress );
},
// Create a public method.
value: function( value ) {
// No value passed, act as a getter.
if ( value === undefined ) {
return this.options.value;
}
// Value passed, act as a setter.
this.options.value = this._constrain( value );
var progress = this.options.value + "%";
this.element.text( progress );
},
// Create a private method.
_constrain: function( value ) {
if ( value > 100 ) {
value = 100;
}
if ( value < 0 ) {
value = 0;
}
return value;
}
});
Чтобы вызвать метод у экземпляра плагина, можно передать имя метода в jQuery-плагин. Если вызываемый метод принимает параметры, вы просто передаёте эти параметры после имени метода.
Примечание:Методы выполняются путём передачи имени метода в ту же функцию jQuery, которая использовалась для инициализации плагина. Это сделано, чтобы предотвратить загрязнение пространства имён jQuery, сохраняя при этом цепочку методов. Позже в этой главе мы увидим другие варианты использования, которые выглядят более естественно.
var bar = $( "<div></div>" )
.appendTo( "body" )
.progressbar({ value: 20 });
// Get the current value.
alert( bar.progressbar( "value" ) );
// Update the value.
bar.progressbar( "value", 50 );
// Get the current value again.
alert( bar.progressbar( "value" ) );
Использование опций
option()Метод автоматически предоставляется плагину.option()Метод позволяет получать и задавать опции после инициализации. Этот метод работает как jQuery-.css()и.attr()метод: можно передать только имя, чтобы использовать его как геттер, передать имя и значение, чтобы использовать его как сеттер, или передать хеш пар ключ/значение, чтобы задать несколько значений. При использовании в качестве геттера плагин вернёт текущее значение опции, соответствующей переданному имени. При использовании в качестве сеттера, у плагина_setOptionметод будет вызван для каждой задаваемой опции. Мы можем указать_setOptionметод в нашем плагине, чтобы реагировать на изменения опций. Для действий, которые должны выполняться независимо при изменении опции, мы можем переопределить_setOptions。
$.widget( "custom.progressbar", {
options: {
value: 0
},
_create: function() {
this.options.value = this._constrain(this.options.value);
this.element.addClass( "progressbar" );
this.refresh();
},
_setOption: function( key, value ) {
if ( key === "value" ) {
value = this._constrain( value );
}
this._super( key, value );
},
_setOptions: function( options ) {
this._super( options );
this.refresh();
},
refresh: function() {
var progress = this.options.value + "%";
this.element.text( progress );
},
_constrain: function( value ) {
if ( value > 100 ) {
value = 100;
}
if ( value < 0 ) {
value = 0;
}
return value;
}
});
Добавление обратных вызовов
Самый простой способ расширить плагин — добавить обратные вызовы, чтобы пользователи могли реагировать на изменение состояния плагина. В примере ниже мы увидим, как добавить обратный вызов к индикатору выполнения, когда прогресс достигает 100%._trigger()Метод принимает три параметра: имя обратного вызова, объект события jQuery, который запускает обратный вызов, и хеш данных, связанный с событием. Имя обратного вызова — единственный обязательный параметр, но остальные параметры очень полезны для пользователей, которые хотят реализовать пользовательскую функциональность в плагине. Например, если мы создаем плагин с возможностью перетаскивания, мы можем передать событие mousemove при запуске обратного вызова перетаскивания, что позволит пользователям реагировать на перетаскивание на основе координат x/y, предоставленных объектом события. Обратите внимание, что событие, передаваемое в_trigger()должно быть событием jQuery, а не нативным событием браузера.
$.widget( "custom.progressbar", {
options: {
value: 0
},
_create: function() {
this.options.value = this._constrain(this.options.value);
this.element.addClass( "progressbar" );
this.refresh();
},
_setOption: function( key, value ) {
if ( key === "value" ) {
value = this._constrain( value );
}
this._super( key, value );
},
_setOptions: function( options ) {
this._super( options );
this.refresh();
},
refresh: function() {
var progress = this.options.value + "%";
this.element.text( progress );
if ( this.options.value == 100 ) {
this._trigger( "complete", null, { value: 100 } );
}
},
_constrain: function( value ) {
if ( value > 100 ) {
value = 100;
}
if ( value < 0 ) {
value = 0;
}
return value;
}
});
Функции обратного вызова по сути являются просто дополнительными опциями, поэтому вы можете получать и задавать их так же, как любую другую опцию. Всякий раз, когда выполняется обратный вызов, запускается соответствующее событие. Тип события определяется путем конкатенации имени плагина и имени обратного вызова. И обратные вызовы, и события принимают одни и те же два параметра: объект события и хеш данных, связанный с событием, как показано в примере ниже.
Вашему плагину может потребоваться включить функциональность, которая не позволяет пользователям использовать его. Чтобы добиться этого, лучше всего создать отменяемый обратный вызов. Пользователи могут отменить обратный вызов или связанное с ним событие так же, как они отменили бы любое нативное событие, вызвавevent.preventDefault()или вернувfalseчтобы добиться этого. Если пользователь отменяет обратный вызов,_trigger()метод вернетfalse, поэтому вы можете реализовать соответствующую функциональность внутри плагина.
var bar = $( "<div></div>" )
.appendTo( "body" )
.progressbar({
complete: function( event, data ) {
alert( "Callbacks are great!" );
}
})
.bind( "progressbarcomplete", function( event, data ) {
alert( "Events bubble and support many handlers for extreme flexibility." );
alert( "The progress bar value is " + data.value );
});
bar.progressbar( "option", "value", 100 );
Под капотом
Теперь, когда мы увидели, как использовать Widget Factory для создания плагина, давайте посмотрим, как это на самом деле работает. Когда вы вызываетеjQuery.widget(), будет создана функция-конструктор для плагина, и переданный вами объект станет прототипом для экземпляров плагина. Вся функциональность, автоматически добавляемая плагину, происходит от базового прототипа виджета, который определён какjQuery.Widget.prototype. При создании экземпляра плагина используйтеjQuery.data, чтобы сохранить его в исходном DOM-элементе, с именем плагина в качестве ключа.
Поскольку экземпляр плагина напрямую связан с DOM-элементом, вы можете получить доступ к экземпляру плагина напрямую, не используя методы плагина. Это позволяет вызывать методы непосредственно у экземпляра плагина, не передавая имя метода в виде строки, а также напрямую обращаться к свойствам плагина.
var bar = $( "<div></div>" )
.appendTo( "body" )
.progressbar()
.data( "progressbar" );
// Call a method directly on the plugin instance.
bar.option( "value", 50 );
// Access properties on the plugin instance.
alert( bar.options.value );
Вы также можете создать экземпляр без использования методов плагина, вызвав конструктор напрямую с параметрами и элементом:
var bar = $.custom.progressbar( {}, $( "<div></div>" ).appendTo( "body") );
// Same result as before.
alert( bar.options.value );
Расширение прототипа плагина
Наибольшее преимущество наличия у плагина конструктора и прототипа в том, что плагин легко расширять. Добавляя или изменяя методы в прототипе плагина, мы можем изменить поведение всех экземпляров плагина. Например, если мы хотим добавить в индикатор выполнения метод для сброса прогресса до 0%, мы можем добавить этот метод в прототип, и его можно будет вызывать у всех экземпляров плагина.
$.custom.progressbar.prototype.reset = function() {
this._setOption( "value", 0 );
};
Дополнительные сведения о расширении виджетов и о том, как создать совершенно новый виджет на основе существующего виджета, см.Расширение виджетов с помощью фабрики виджетов。
Очистка
В некоторых случаях полезно позволить пользователям применить плагин, а затем отменить его применение. Вы можете сделать это с помощью_destroy()-метод. В_destroy()-методе, вы должны отменить всё, что плагин сделал во время инициализации и последующего использования._destroy()вызывается через.destroy()метод. Этот.destroy()метод автоматически вызывается, когда элемент, привязанный к экземпляру плагина, удаляется из DOM, поэтому это можно использовать для сборки мусора. Базовый.destroy()метод также обрабатывает некоторые общие операции очистки, такие как удаление ссылки на экземпляр из DOM-элемента виджета, отвязка всех событий в пространстве имен виджета от элемента и отвязка всех событий, добавленных с помощью_bind()добавленные события.
$.widget( "custom.progressbar", {
options: {
value: 0
},
_create: function() {
this.options.value = this._constrain(this.options.value);
this.element.addClass( "progressbar" );
this.refresh();
},
_setOption: function( key, value ) {
if ( key === "value" ) {
value = this._constrain( value );
}
this._super( key, value );
},
_setOptions: function( options ) {
this._super( options );
this.refresh();
},
refresh: function() {
var progress = this.options.value + "%";
this.element.text( progress );
if ( this.options.value == 100 ) {
this._trigger( "complete", null, { value: 100 } );
}
},
_constrain: function( value ) {
if ( value > 100 ) {
value = 100;
}
if ( value < 0 ) {
value = 0;
}
return value;
},
_destroy: function() {
this.element
.removeClass( "progressbar" )
.text( "" );
}
});
Заключительные замечания
Фабрика виджетов — это лишь один из способов создания плагинов с состоянием. Существует несколько других моделей, которые вы можете использовать, каждая со своими преимуществами и недостатками. Фабрика виджетов решает многие распространенные проблемы и значительно повышает эффективность, а также значительно улучшает повторное использование кода, что делает ее подходящей для jQuery UI и других плагинов с состоянием.
Обратите внимание, что в этой главе мы использовалиcustomпространство имен. Этоuiпространство имен зарезервировано для официальных плагинов jQuery UI. При создании собственных плагинов вы должны создать собственное пространство имен. Это делает более понятным, откуда происходит плагин и к какой области он относится.