Фабрика виджетов

Вы можете создавать новые виджеты с нуля, используя только объект $.Widget в качестве базового для наследования, или вы можете явно унаследовать от существующих виджетов jQuery UI или сторонних виджетов. Определение виджета с тем же именем, что и у наследователя, даже позволяет расширять виджеты на месте.

jQuery UI содержит множество виджетов, которые сохраняют состояние и, следовательно, имеют немного другой порядок использования, чем обычные плагины jQuery. Все виджеты jQuery UI используют одни и те же шаблоны, которые определены фабрикой виджетов. Поэтому, если вы научитесь использовать один виджет, вы сможете использовать все.

Ищете учебные материалы о фабрике виджетов? Посмотрите статьи на сайте jQuery Learning Center.

Примечание: Эта документация показывает примеры, использующие виджет progressbar, но синтаксис одинаков для каждого виджета.

Инициализация

Для отслеживания состояния виджета необходимо ввести полный жизненный цикл виджета. Жизненный цикл начинается, когда виджет инициализируется. Чтобы инициализировать виджет, просто вызовите плагин на одном или нескольких элементах.

$( "#elem" ).progressbar();

Это инициализирует каждый элемент в объекте jQuery, в этом случае элемент с идентификатором "elem".

Параметры

Поскольку progressbar() был вызван без параметров, виджет был инициализирован со своими значениями по умолчанию. Мы можем передать набор параметров во время инициализации, чтобы переопределить значения по умолчанию:

$( "#elem" ).progressbar({ value: 20 });

Мы можем передать столько или так мало параметров, сколько хотим во время инициализации. Любые параметры, которые мы не передаём, просто будут использовать свои значения по умолчанию.

Вы можете передать несколько аргументов параметров. Эти аргументы будут объединены в один объект (подобно $.extend( true, target, object1, objectN )). Это полезно для совместного использования параметров между экземплярами, одновременно переопределяя некоторые свойства для каждого из них:

var options = { modal: true, show: "slow" };
$( "#dialog1" ).dialog( options );
$( "#dialog2" ).dialog( options, { autoOpen: false });

Все параметры, передаваемые при инициализации, глубоко копируются, чтобы гарантировать, что объекты можно изменять позже, не влияя на виджет. Массивы являются единственным исключением, они ссылаются как есть. Это исключение используется для поддержки привязки данных, где источник данных должен храниться как ссылка.

Значения по умолчанию хранятся в прототипе виджета, поэтому у нас есть возможность переопределить значения, установленные jQuery UI. Например, после выполнения следующего действия все будущие экземпляры progressbar по умолчанию будут иметь значение 80:

$.ui.progressbar.prototype.options.value = 80;

Параметры являются частью состояния виджета, поэтому мы можем задавать параметры и после инициализации. Мы увидим это позже с методом опций.

Методы

Теперь, когда виджет инициализирован, мы можем запросить его состояние или выполнить действия с виджетом. Все действия после инициализации выполняются в виде вызова метода. Чтобы вызвать метод виджета, мы передаём имя метода в плагин jQuery. Например, чтобы вызвать метод value() для нашего виджета progressbar, мы бы использовали:

$( "#elem" ).progressbar( "value" );

Если метод принимает параметры, мы можем передать их после имени метода. Например, чтобы передать параметр 40 методу value(), мы можем использовать:

$( "#elem" ).progressbar( "value", 40 );

Так же, как и другие методы в jQuery, большинство методов виджетов возвращают объект jQuery для цепочки.

$( "#elem" )
  .progressbar( "value", 90 )
  .addClass( "almost-done" );

Каждый виджет будет иметь свой набор методов, основанных на функциональности, которую предоставляет виджет. Однако есть несколько методов, которые существуют во всех виджетах, которые документированы ниже.

События

Все виджеты имеют события, связанные с их различным поведением, чтобы уведомить вас, когда состояние изменяется. Для большинства виджетов, когда события срабатывают, имена имеют префикс имени виджета и преобразуются в нижний регистр. Например, мы можем привязаться к событию change progressbar, которое срабатывает всякий раз, когда значение изменяется.

$( "#elem" ).bind( "progressbarchange", function() {
  alert( "The value has changed!" );
});

Каждое событие имеет соответствующую функцию обратного вызова, которая представлена в качестве параметра. Мы можем подключиться к функции обратного вызова change progressbar вместо привязки к событию progressbarchange, если хотим.

$( "#elem" ).progressbar({
  change: function() {
    alert( "The value has changed!" );
  }
});

Все виджеты имеют событие create, которое срабатывает при создании экземпляра.

Экземпляр

Экземпляр виджета можно получить из данного элемента с помощью метода instance().

$( "#elem" ).progressbar( "instance" );

Если метод instance() вызывается на элементе, который не связан с виджетом, возвращается undefined.

$( "#not-a-progressbar" ).progressbar( "instance" ); // undefined

Экземпляр хранится с помощью jQuery.data() с полным именем виджета в качестве ключа. Следовательно, селектор :data также может определить, привязан ли к элементу данный виджет.

$( "#elem" ).is( ":data('ui-progressbar')" ); // true
$( "#elem" ).is( ":data('ui-draggable')" ); // false

В отличие от instance(), :data можно использовать, даже если виджет, для которого проверяется, ещё не загружен.

$( "#elem" ).nonExistentWidget( "instance" ); // TypeError
$( "#elem" ).is( ":data('ui-nonExistentWidget')" ); // false

Вы также можете использовать :data для получения списка всех элементов, являющихся экземплярами данного виджета.

$( ":data('ui-progressbar')" );

Свойства

Все виджеты имеют следующий набор свойств:

• defaultElement: Элемент, используемый, когда экземпляр виджета создаётся без предоставления элемента. Например, так как defaultElement - это "<div>, $.ui.progressbar({ value: 50 }) создаёт экземпляр виджета progressbar на только что созданном <div>.
• document: Объект jQuery, содержащий document, в котором находится элемент виджета. Полезно, если вам нужно взаимодействовать с виджетами во фреймах.
• element: Объект jQuery, содержащий элемент, используемый для создания виджета. Если вы выбираете несколько элементов и вызываете .myWidget(), для каждого элемента будет создан отдельный экземпляр виджета. Поэтому это свойство всегда будет содержать один элемент.
• namespace: Местоположение в глобальном объекте jQuery, где хранится прототип виджета. Например, namespace "ui" указывает, что прототип виджета хранится в $.ui.
• options: Объект, содержащий параметры, которые в данный момент используются виджетом. При создании экземпляра любые параметры, предоставленные пользователем, автоматически будут объединены со значениями по умолчанию, определёнными в $.myNamespace.myWidget.prototype.options. Параметры, указанные пользователем, переопределяют значения по умолчанию.
• uuid: Уникальный целочисленный идентификатор виджета.
• version: Строковая версия виджета. Для виджетов jQuery UI это будет версия jQuery UI, которую использует виджет. Разработчики виджетов должны явно установить это свойство в своём прототипе.
• widgetEventPrefix: Префикс, добавляемый к имени событий, сгенерированных этим виджетом. Например, widgetEventPrefix виджета draggable - это "drag", поэтому при создании виджета draggable имя события, сгенерированного, - это "dragcreate". По умолчанию widgetEventPrefix виджета - это его имя. Примечание: Это свойство устарело и будет удалено в будущих версиях. Имена событий будут изменены на widgetName:eventName (например, "draggable:create").
• widgetFullName: Полное имя виджета, включая пространство имён. Для $.widget( "myNamespace.myWidget", {} ), widgetFullName будет "myNamespace-myWidget".
• widgetName: Имя виджета. Для $.widget( "myNamespace.myWidget", {} ), widgetName будет "myWidget".
• window: Объект jQuery, содержащий window, в котором находится элемент виджета. Полезно, если вам нужно взаимодействовать с виджетами во фреймах.