# JQuery UI API. Руководство разработчика

JavaScript @ 07 Февраль 2010

Перевод официального руководства jQuery UI API Developer Guide.

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

ui.core.js предоставляет фабричный метод для создания классов виджетов.

$.widget(String name, Options prototype);

При вызове фабрики создается метод виджета, который используется для инициализации экземпляра  класса этого виджета и для взаимодействия с ним.

Помимо тех методов, которые передаются через параметр prototype, следующие методы  доступны для каждого экземпляра по-умолчанию:

  • destroy() — удаляет экземпляр из инкапсулирующего его элемента DOM;
  • getData/setData/data(String key[, String value]) — получает или устанавливает значения настроек (опций) для данного экземпляра;
  • enable() — устанавливает опцию disabled в «ложь», реализация которой осуществляется классом виджета;
  • disable() — устанавливает опцию disabled в «правда», реализация которой осуществляется классом виджета.

У каждого экземпляра доступны свойства:

  • options — настройки данного экземпляра виджета, обычно к значениям по-умолчанию добавляются установки заданные пользователем;
  • element — объект jQuery всегда содержащий единственный элемент DOM, к которому можно обратится как this.element[0].

Вы можете переопределить эти методы в вашем виджете. Если же вы хотите наследовать стандартные методы, просто добавив функциональности, сделайте это:

$.widget.prototype.methodToOverride.apply(this, arguments)

будет выполнен метод по умолчанию. Затем вы можете добавить свой собственный код.

Использование фабричного метода

$.widget("ui.mywidget", {
   _init: function() {
     // код инициализации виджета mywidget
     // вы можете использовать this.options
     if (this.options.hidden) {
       // ... и this.element
       this.element.hide();
     }
   },
   _doSomething: function() {
      // названия внутренних функций должны начинаться со знака подчеркивания
      // код управления виджетом
   },
   value: function() {
     // вычисляем некое значение и возвращаем его
     return this._calculate();
   },
   length: function() {
     return this._someOtherValue();
   },
   destroy: function() {
       $.widget.prototype.destroy.apply(this, arguments); // деструктор по-умолчанию
        // теперь прочие действия, специфичные для этого виджета
   }
 });
 $.extend($.ui.mywidget, {
   getter: "value length",
   defaults: {
     option1: "defaultValue",
     hidden: true
   }
 });

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

Сеттеры и Геттеры


При первоначальном инстанцировании виджета можно передавать те начальные настройки, которые программист хочет переопределить.

$("div").draggable({ helper: "clone", axis: "x" });

Таким образом для всех divов на странице вы добавите возможность перетаскивания — используя виджет draggable с настройками по умолчанию, кроме настроек helper и axis. После того как элемент будет создан, все остальные обращения по имени виджета, где первый параметр не является строкой, будут игнорироваться. Поэтому это способ не может быть использован после первоначального инстанцирования.

На этом этапе установка и получение значений производится посредством метода option виджета. Например, чтобы изменить ось перетаскивания на «y» нужно вызвать:

setData: function(key, value) {
},
getData: function(key) {
}

Виджетом будет вызвана функция $(…).data() которая запускает те события, которые необходимы для проверки, следует ли переопределить его поведение  по-умолчанию и вернет/установит это значение.

Внутренние функции & области видимости

jQuery.data / jQuery.fn.data

Разработчикам виджетов часто нужно создать так называемый «expando» на узле DOM, это означает что для хранения дополнительных данных используется сам DOM узел. Однако, это зачастую приводит к утечкам памяти.

jQuery имеет свой собственный способ борьбы с ними – функция data. Для каждого узла DOM создается уникальная строка, используя которую можно хранить данные  во внутреннем объекте, поэтому  циклические ссылки не создаются.

Экземпляр вашего виджета автоматически сохраняется фабричным методом  с ключом «widget» (замените widget названием вашего виджета):

this.element.data("draggable") === this;

или

$.data(this.element[0], "draggable") === this;

Экземпляр также используется UI фреймворком для отслеживания, инстанцирован ли виджет на данном конкретном узле. UI позволяет инстанцировать виджет более чем один раз на узел, поэтому для удаления ссылки с экземпляром виджета, используйте:

$.removeData("myWidgetName")

Более подробную информацию о использовании функции data см. jQuery API .data().

jQuery.fn

jQuery.fn является общим пространством имен плагинов. Лишь одна функция UI виджета представлена в этом пространстве имен — единая функция-акцептор перегруженная различными способами использования (это делается автоматически при использовании фабрики виджетов).

Возьмем функцию $.draggable() в качестве примера:

  • $.draggable() — создает новый экземпляр jQuery.ui.draggable;
  • $.draggable({...}) — создает новый экземпляр jQuery.ui.draggable c использованием опциональных настроек;
  • $.draggable("disable", [args]) — вызывает метод jQuery.ui.draggable.disable с дополнительными аргументами.

jQuery.ui

В этом пространстве имен хранится функция-конструктор виджета.  Все виджеты должны хранить только одну функцию в этом пространстве имен, поэтому рекомендуется работать с прототипами и экземплярами (при использовании фабрики виджетов это делается автоматически).

jQuery.fn.bind

В UI виджетах функция bind jQuery используется двумя способами:

  • для связывания функции обратного вызова (callback) с пользовательскими событиями: $(..).bind("drag")
  • для связывания пользовательских геттеров и сеттеров для получения/изменения настроек (см. Сеттеры и Геттеры на этой странице)

Стиль оформления кода

Отступы

Для отступов используйте символ табуляции. Это делает работу гораздо проще, потому что вы можете задать свой собственный размер табуляции в вашем редактор, если ширина отступов окажется слишком большой.  В случае если используются отступы пробелами, это не так легко изменить. Кроме того, не добавляйте отступы для пустых строк.

Соответствие стандартам

Обратные вызовы

Пожалуйста, подумайте о возможности обратного вызова где это можно. Они должны быть названы ближе к jQuery стилю, а не как в DOM. Draggable, например, имеет следующие функции обратного вызова:

  • start
  • drag
  • stop

которые связываются вот так:

{
  start: function(event, ui){},
  drag: function(event, ui){},
  stop: function(event, ui){}
}

Вместо того чтобы использовать свои собственные функции, для их вызова, фабрика виджетов предоставляет метод:

this._trigger(type, event, uiHash)

где type — имя события, event — событие браузера, а uiHash должен быть объектом хранящим ваши собственные пары ключ / значение, что вы хотите передать в функцию обратного вызова.

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

Производные от других классов

Все виджеты, связанные с взаимодействием с мышью используют другой класс — класс взаимодействия с мышью (jquery.ui.mouse.js). По существу он обрабатывает все события (mousedown, mouseup, mousemove) и связывания, и вы можете использовать приватные функции обратного вызова, чтобы потом сделать что-то с новым положение мыши (перемещение элементов, например).

Посмотрите на реализацию производных от draggable / resizable говорящую саму за себя.

Кодирование

Убедитесь, что все ваши файлы в кодировке UTF-8.  Очень неприятно исправлять ошибки кодировки, если три человека делают коммит одного и того же файла в трёх различных кодировках.

Документация

Javadoc блоки

Пожалуйста, не генерируйте Javadoc блоки для Ваших функций и классов. Документация должна быть написана на странице планирования плагина на Dev & Planning wiki.

Inline комментарии

Помещайте inline комментарий перед строкой которые они комментируют и пробел между двойным слешем и текстом комментария.

Коментируйте «почему», а не «как». «Как» обеспечивает код. Документируйте вещи, которые не очевидны из кода.

// только левая кнопка начинает перетаскивание
if (e.which != 1)
  return true;

В этом примере, трудно догадаться, для чего используется данное условие (пока вы не узнаете, как  работает свойство e.which), так что объяснение здесь бы не помешало.

Сочетания клавиш

«The DHTML Style Guide Working Group (DSGWG) создал рекомендацию для сочетаний клавиш, которые будут использоваться в виджетах веб-сайтов» DHTML Style Guide.

Tags: , ,

Leave a Reply