jQuery UI API - Widget Factory
Категория
Использование jQuery.widget( name [, base ], prototype )
Описание:Создавайте stateful-плагины jQuery, используя ту же абстракцию, что и все виджеты jQuery UI.
| Parameters | Type | Type |
|---|---|---|
| name | String | Имя создаваемого виджета, включая пространство имён. |
| base | Function() | Базовый виджет, от которого наследуются. Должен быть конструктором, который можно создать с помощью ключевого слова `new`. По умолчанию — jQuery.Widget. |
| prototype | PlainObject | Объект, используемый в качестве прототипа виджета. |
Вы можете использовать$.Widgetобъект в качестве базы для наследования, или вы можете явно создать новый виджет с нуля на основе существующего элемента управления jQuery UI или стороннего производителя. Определение виджета с тем же именем для наследования базового виджета даже позволяет вам соответствующим образом расширить виджет.
jQuery UI содержит множество stateful-виджетов, поэтому шаблон использования немного отличается от типичных плагинов jQuery. Все виджеты jQuery UI используют один и тот же шаблон, определённый Widget Factory. Поэтому, как только вы научитесь использовать один, вы будете знать, как использовать остальные виджеты.
Примечание: в этой главе в качестве демонстрационного примера используетсявиджет Progressbar, но синтаксис применим к каждому виджету.
Инициализация
Чтобы отслеживать состояние виджета, мы должны рассмотреть полный жизненный цикл виджета. Жизненный цикл начинается при инициализации виджета. Чтобы инициализировать виджет, мы просто вызываем плагин для одного или нескольких элементов.
$( "#elem" ).progressbar();
Это инициализирует каждый элемент в объекте jQuery. В приведённом выше примере id элемента — `progressbar`."elem"。
Параметры
Потому чтоprogressbar()при вызове без аргументов виджет инициализируется с параметрами по умолчанию. Мы можем передать набор параметров при инициализации, чтобы переопределить параметры по умолчанию:
$( "#elem" ).progressbar({ value: 20 });
Мы можем передать столько параметров, сколько нужно, а любые непереданные параметры используют свои значения по умолчанию.
Можно передать несколько аргументов-параметров, которые будут объединены в один объект (аналогично$.extend( true, target, object1, objectN )`$.extend`). Это полезно для переопределения некоторых настроек для всех экземпляров и совместного использования параметров между экземплярами:
var options = { modal: true, show: "slow" };
$( "#dialog1" ).dialog( options );
$( "#dialog2" ).dialog( options, { autoOpen: false });
Все параметры, переданные при инициализации, глубоко копируются, что гарантирует возможность изменять объекты позже без влияния на виджет. Массивы — единственное исключение; они передаются по ссылке как есть. Это исключение необходимо для правильной поддержки привязки данных, где источник данных должен быть ссылкой.
Значения по умолчанию хранятся в свойствах виджета, поэтому мы можем переопределить значения, заданные jQuery UI. Например, после следующей настройки все будущие экземпляры progressbar по умолчанию будут иметь значение 80:
$.ui.progressbar.prototype.options.value = 80;
Параметры являются неотъемлемой частью состояния виджета, поэтому мы также можем задавать параметры после инициализации. Позже мы увидим метод option.
Методы
Теперь, когда виджет инициализирован, мы можем запрашивать его состояние или выполнять действия над виджетом. Все действия после инициализации выполняются путём вызова методов. Чтобы вызвать метод у виджета, мы передаём имя метода в плагин jQuery. Например, чтобы вызватьvalue()метод `value`, мы можем использовать:
$( "#elem" ).progressbar( "value" );
Если метод принимает параметры, мы можем передать их после имени метода. Например, чтобы передать параметр `2` в40вvalue()метод `value`, мы можем использовать:
$( "#elem" ).progressbar( "value", 40 );
Как и другие методы в jQuery, большинство методов виджетов возвращают объект jQuery:
$( "#elem" ) .progressbar( "value", 90 ) .addClass( "almost-done" );
Каждый виджет имеет собственный набор методов, основанный на функциональности, предоставляемой виджетом. Однако есть некоторые методы, которые существуют у всех виджетов; они подробно объяснены ниже.
Events
Все виджеты имеют события, связанные с различными аспектами их поведения, чтобы уведомлять вас при изменении состояния. Для большинства виджетов, когда событие срабатывает, его имя имеет префикс в виде имени виджета в нижнем регистре. Например, мы можем привязать у виджета progressbarchangeсобытие `change`, которое срабатывает при изменении значения.
$( "#elem" ).bind( "progressbarchange", function() {
alert( "The value has changed!" );
});
У каждого события есть соответствующий обратный вызов, который доступен как опция. При необходимости мы можем использовать у виджета progressbarchangeобратный вызов `change` вместо привязкиprogressbarchangeсобытия `change`.
$( "#elem" ).progressbar({
change: function() {
alert( "The value has changed!" );
}
});
У всех виджетов естьchangeсобытие `create`, которое срабатывает при создании экземпляра.
Создание экземпляра
Экземпляр виджета хранится с использованием полного имени виджета в качестве ключа вjQuery.data()`data`. Поэтому вы можете использовать следующий код, чтобы получить объект экземпляра виджета Progressbar из элемента.
$( "#elem" ).data( "ui-progressbar" );
Привязан ли элемент к данному виджету, можно определить с помощью:dataселектора `:ui-progressbar`.
$( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true $( "#elem" ).is( ":data( 'ui-draggable' )" ); // false
Вы также можете использовать:dataчтобы получить список всех элементов, которые являются экземплярами данного виджета.
$( ":data( 'ui-progressbar' )" );
Свойства
Все виджеты имеют следующие свойства:
- defaultElement`defaultElement`: Элемент, который используется, когда при создании экземпляра виджета не был предоставлен элемент. Например, поскольку у progressbar
defaultElementДа"<div>",$.ui.progressbar({ value: 50 })`defaultElement` — это только что созданный<div>`div`, вы можете создать экземпляр виджета progressbar, не передавая элемент. - document`document`: Документ, который содержит элемент виджета.
documentПолезно, если вам нужно взаимодействовать с виджетом внутри iframe. - element`element`: Объект jQuery, содержащий элемент, использованный для создания экземпляра виджета. Если вы выбираете несколько элементов и вызываете
.myWidget()`.progressbar()`, для каждого элемента будет создан отдельный экземпляр виджета. Поэтому это свойство всегда содержит один элемент. - namespace`namespace`: место в глобальном объекте jQuery, где хранится прототип виджета. Например,
"ui"изnamespace`$.ui.draggable` указывает, что прототип виджета хранится в$.ui。 - options`$.ui.draggable`. `options`: объект, содержащий параметры, которые в данный момент использует виджет. При создании экземпляра все параметры, предоставленные пользователем, автоматически объединяются с
$.myNamespace.myWidget.prototype.optionsзначениями по умолчанию, определёнными в прототипе виджета. Пользовательские параметры переопределяют значения по умолчанию. - uuid`uuid`: уникальное целое число, представляющее идентификатор виджета.
- version`version`: строковая версия виджета. Для виджетов jQuery UI это свойство устанавливается в версию jQuery UI, используемую виджетом. Разработчики плагинов должны явно задавать это свойство в своих прототипах.
- widgetEventPrefix`widgetEventPrefix`: префикс, добавляемый к именам событий виджета. Например,Виджет Draggableиз
widgetEventPrefixДа"drag", поэтому при создании draggable имя события —"dragcreate"`dragcreate`. По умолчанию у виджетаwidgetEventPrefix`widgetEventPrefix` — это его имя.Примечание: это свойство устарело и будет удалено в будущих версиях. Имена событий будут изменены на widgetName:eventName (например, `progressbarcreate`)."draggable:create")。 - widgetFullName`widgetFullName`: полное имя виджета, включая пространство имён. Для
$.widget( "myNamespace.myWidget", {} ),widgetFullNameprogressbar, это будет `ui-progressbar`."myNamespace-myWidget"。 - widgetName`name`: Имя виджета. Для
$.widget( "myNamespace.myWidget", {} ),widgetNameprogressbar, это будет `progressbar`."myWidget"。 - window`window`: Окно, содержащее элемент виджета.
windowПолезно, если вам нужно взаимодействовать с виджетом внутри iframe.
Использование базового виджета jQuery.Widget
Описание:Базовый виджет, используемый фабрикой виджетов.
Быстрая навигация
| Параметры | Методы | Events |
|---|---|---|
| Параметры | Type | Описание | Default |
|---|---|---|---|
| disabled | Boolean | Если установлено значениеtrue`true`, виджет отключен.Примеры кода: Инициализация виджета с указанным
$( ".selector" ).widget({ disabled: true });
Получить или задать // getter var disabled = $( ".selector" ).widget( "option", "disabled" ); // setter $( ".selector" ).widget( "option", "disabled", true ); |
false |
| hide | Boolean, Number, String или Object | Определяет, использовать ли анимацию для скрытия элемента и каким образом. Поддерживается несколько типов:
Примеры кода: Инициализировать виджет с указанным
$( ".selector" ).widget({ hide: { effect: "explode", duration: 1000 } });
После инициализации получите или задайте
// getter
var hide = $( ".selector" ).widget( "option", "hide" );
// setter
$( ".selector" ).widget( "option", "hide", { effect: "explode", duration: 1000 } );
|
null |
| show | Boolean, Number, String или Object | Определяет, отображать ли элемент с анимацией и как анимировать отображение. Поддерживает несколько типов:
Примеры кода: Инициализировать виджет с указанным
$( ".selector" ).widget({ show: { effect: "blind", duration: 800 } });
После инициализации получите или задайте
// getter
var show = $( ".selector" ).widget( "option", "show" );
// setter
$( ".selector" ).widget( "option", "show", { effect: "blind", duration: 800 } );
|
null |
| Методы | Возвращает | Описание |
|---|---|---|
| _create() | jQuery (только плагин) | _create()метод является конструктором виджета. Он не принимает аргументов, ноthis.elementиthis.optionsуже установлен.
Примеры кода: Устанавливает цвет фона элемента виджета на основе опции.
_create: function() {
this.element.css( "background-color", this.options.color );
}
|
| _delay( fn [, delay ] ) | Number | Вызывает предоставленную функцию после указанной задержки. Сохраняетthisправильный контекст. По сутиsetTimeout()。использует clearTimeout()возвращает ID тайм-аута.
Примеры кода: Через 100 миллисекунд вызовите у виджета this._delay( this._foo, 100 ); |
| _destroy() | jQuery (только плагин) | Публичныйdestroy()метод очищает все публичные данные, события и т. д. Он представляет собой пользовательскую очистку, специфичную для виджета._destroy()。
Примеры кода: Удаляет класс из элемента виджета при уничтожении виджета.
_destroy: function() {
this.element.removeClass( "my-widget" );
}
|
| _focusable( element ) | jQuery (только плагин) | Устанавливает, при фокусировке на элементе,ui-state-focusкласс, который нужно применить.element。
Примеры кода: Применяет стили фокусируемости к группе элементов внутри виджета: this._focusable( this.element.find( ".my-items" ) ); |
| _getCreateEventData() | Object | Все виджеты генерируютcreateсобытия. По умолчанию в событии не передаются данные, но этот метод возвращает объект, который передается какcreateданные события.
Примеры кода: в направлении
_getCreateEventData: function() {
return this.options;
}
|
| _getCreateOptions() | Object | Этот метод позволяет виджету определить пользовательский метод для определения параметров во время инициализации. Параметры, предоставленные пользователем, переопределяют параметры, возвращаемые этим методом, то есть переопределяют параметры по умолчанию.
Примеры кода: Делает атрибут id элемента виджета доступным в качестве параметра.
_getCreateOptions: function() {
return { id: this.element.attr( "id" ) };
}
|
| _hide( element, option [, callback ] ) | jQuery (только плагин) | Скрывает элемент с помощью встроенного метода анимации или пользовательского эффекта. Для возможныхoptionзначений, см.hide。
Примеры кода: Передаёт
this._hide( this.element, this.options.hide, function() {
// Remove the element from the DOM when it's fully hidden.
$( this ).remove();
});
|
| _hoverable( element ) | jQuery (только плагин) | Устанавливает при наведении курсора на элементui-state-hoverкласс, который нужно применить.element. Обработчики событий автоматически удаляются при уничтожении.
Примеры кода: При наведении курсора на элемент, ко всем элементам внутри элемента, this._hoverable( this.element.find( "div" ) ); |
| _init() | jQuery (только плагин) | Понятие инициализации виджета отличается от создания. Когда плагин вызывается без аргументов или только с хешем параметров, виджет инициализируется. Этот метод включается при создании виджета. Примечание: Если при успешном вызове виджета без аргументов должны выполняться логические действия, инициализация может быть обработана только в этот момент.
Примеры кода: Если
_init: function() {
if ( this.options.autoOpen ) {
this.open();
}
}
|
| _off( element, eventName ) | jQuery (только плагин) | Отвязывает обработчики событий от указанного элемента.
Примеры кода: Отвязывает все события click от элемента виджета. this._off( this.element, "click" ); |
| _on( [suppressDisabledCheck ] [, element ], handlers ) | jQuery (только плагин) | Поддерживается делегирование через селекторы внутри имени события, например"click .foo"。_on()Метод даёт несколько преимуществ по сравнению с прямой привязкой событий:
Примеры кода: Предотвращает поведение по умолчанию для всех нажатых ссылок внутри элемента виджета.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
}
});
|
| _setOption( key, value ) | jQuery (только плагин) | Для каждой отдельной опции вызывает_setOptions()метод. Состояние виджета обновляется по мере внесения изменений.
Примеры кода: Когда у виджета
_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 (только плагин) | Когда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();
}
}
|
| _show( element, option [, callback ] ) | jQuery (только плагин) | Показывает элемент с помощью встроенного метода анимации или пользовательского эффекта. Для возможныхoptionзначений, см.show。
Пример кода: Передайте пользовательскую анимацию
this._show( this.element, this.options.show, function() {
// Focus the element when it's fully visible.
this.focus();
}
|
| _super( [arg ] [, ... ] ) | jQuery (только плагин) | Вызывает метод с тем же именем у родительского виджета с любыми указанными аргументами. По сути,.call()。
Пример кода: Handle
_setOption: function( key, value ) {
if ( key === "title" ) {
this.element.find( "h3" ).text( value );
}
this._super( key, value );
}
|
| _superApply( arguments ) | jQuery (только плагин) | Вызывает метод с тем же именем у родительского виджета, передавая массив аргументов. По сути,.apply()。
Пример кода: Handle
_setOption: function( key, value ) {
if ( key === "title" ) {
this.element.find( "h3" ).text( value );
}
this._superApply( arguments );
}
|
| _trigger( type [, event ] [, data ] ) | Boolean | Вызывает событие и связанную с ним функцию обратного вызова. Опция с таким именем эквивалентна типу, вызываемому в качестве функции обратного вызова. Имя события — это строка в нижнем регистре, состоящая из имени виджета и типа. Примечание: когда data указан, необходимо указать все три параметра. Если event не передан, передайте Если поведение по умолчанию предотвращено, возвращается
Пример кода: Когда нажата клавиша, вызвать
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 (только плагин) | Полностью удалить функциональность виджета. Это возвращает элемент в состояние до инициализации.
Пример кода: Уничтожить виджет при щелчке по любому якорю виджета.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.destroy();
}
});
|
| disable() | jQuery (только плагин) | Отключить виджет.
Пример кода: Отключить виджет при щелчке по любому якорю виджета.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.disable();
}
});
|
| enable() | jQuery (только плагин) | Включить виджет.
Пример кода: Включить виджет при щелчке по любому якорю виджета.
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.enable();
}
});
|
| option( optionName ) | Object | Получает значение, связанное в данный момент с указаннымoptionNameсвязанное значение.
Пример кода: Получить this.option( "width" ); |
| option() | PlainObject | Получает объект, содержащий пары ключ/значение, которые представляют текущий хеш параметров виджета.
Пример кода: Запишите в журнал пары ключ/значение каждой опции виджета для отладки.
var options = this.option();
for ( var key in options ) {
console.log( key, options[ key ] );
}
|
| option( optionName, value ) | jQuery (только плагин) | Устанавливает с указаннымoptionNameзначением связанной опции виджета.
Пример кода: Установите this.option( "width", 500 ); |
| option( options ) | jQuery (только плагин) | Установите одну или несколько опций для виджета.
Пример кода: Установите
this.option({
width: 500,
height: 500
});
|
| widget() | jQuery | Возвращает объект, содержащий исходный элемент или другие связанные сгенерированные элементыjQueryобъект.
Пример кода: При создании виджета поместите красную рамку вокруг исходного элемента виджета.
_create: function() {
this.widget().css( "border", "2px solid red" );
}
|
| Events | Type | Описание |
|---|---|---|
| create( event, ui ) | widgetcreate | Срабатывает при создании виджета.
Примечание: Пример кода: Инициализируйте виджет с указанной функцией обратного вызова create:
$( ".selector" ).widget({
create: function( event, ui ) {}
});
Привяжите обработчик события к событию widgetcreate:
$( ".selector" ).on( "widgetcreate", function( event, ui ) {} );
|