Описание

Раздел содержит формальное описание свойств и методов плагина

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

Инициализация плагина производиться автоматически при нажатии мыши или касании элемента, имеющего аттрибут data-toggle="snapper" или через вызов метода инициализации плагина

// Инициализация плагина jQuery.Snapper
$('.container').snapper(options)

Автоматическую привязку можно отключить вызвав

// Отключение автоматической инициализации jQuery.Snapper
$(document).off('.data-api.snapper')

или

// Отключение автоматической инициализации всех элементов Bootstrap
$(document).off('.data-api')

Получить плагина элемента после инициализации можно прочитав атрибут data-snapper.

// Запрос плагина от элемента
var snapper = $(element).data('snapper')

В процессе инициализации всем контейнерам присваивается класс snapper.

Параметры инициализации options:

Параметр Описание По умолчанию
inertia Время инерционного воздействия 200ms
speed Скорость анимации перемещения 200ms
taphold Длительность нажатия до захвата. Для захвата сразу при нажатии установите 0. 200ms
timeout Таймаут отпускания при отсутствии движения 2s
easing Метод инерционного замедления анимации ease-out
catch Ловушки. Отменяет проверку выхода за границы:
  • top сверху
  • right справа
  • bottom снизу
  • left слева
  • none нет
 none
out Метод выхода из контейнера:
  • remove удаление
  • cancel отмена
  • swap обмен
 remove

Параметры инициализации для элемента могут быть заданы через атрибуты data-(имя параметра), например:

<div data-toggle="snapper" data-out="top left">

Значение по умолчанию для плагина могут быть изменены установкой соответствующих значений прототипу конструктора $.snapper.prototype, например:

// Захватывать элемент сразу при нажатии
$.snapper.prototype.taphold = 0

События

В процессе перемещения и захвата плагин создает несколько событий, обработка которых может помочь отследить изменения в DOM-модели. События вызваются как контейнером-источником, так и контейниром-приемником.

Событие Описание Контейнер
drag Захват элемента. Созданный для item близнец twin прилип к мышке и движется к цели. источник
drop Бросание элемента. Событие в по очереди передается всем контейнера в поисках приемника. источник
snap Приемник захватил элемент item и переместил его к себе. приемник
done Завершена анимация (показ мультфильма о перемещении элементов) источник

Примером использования событий может быть расширение jQuery.Snapper.Storage, обрабатывающая изменения состава элементов контейнера

// Отбираем все контейнеры по классу snapper 
$(document).on('done.snapper  snap.snapper', '.snapper', function(event) {
        // Здесь получаем измененные данные по источнику и приемнику 
        var self = $(event.target), snapper = self.data('snapper');
        ...
    });    
});

Свойства

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

Свойство Описание Событие определения
item Захваченный элемент drag
twin Близнец захваченного элемента, двигающийся по экрану drag
point Координаты указателя при захвате drag
offset Исходные координаты элемента drag
from Индекс элемента в контейнере drag
moves Последние 4 перемещения элемента drag
prediction Расчитанные с учетом инерции движения координаты элемента в момент бросания drop
dest Плагин контейнера-приемника, захвативщего элемента snap
to Индекс элемента в контейнере-приемнике snap

Методы

Необходимость вызывать методы плагина напрямую как правило отсутствует. Описание приводится с целью дать представление о внутренней структуре плагина.

Метод Описание
state() Возвращает текущее состояние от момента касания до бросания элемента. Используется для определения действия в зависимости от внешнего события (автомат состояний)
startDrag(item, point) Захват и начало перемещения элемента item в точке point. Вызывает событие drag.
moveDrag(point) Перемещение элемента в точку point
stopDrag() Заверщенгие перемещения.Вызывает событие drop.
isCatch(direction) Проверка возможности захвата по направлению direction
fitIn(pos) Проверка на возможность захвата элемента с центром в позиции pos
toIndex(pos) Определение индекса захвата элемента с центром в позиции pos
make(source) Проверка на возможность захвата элемента у источника source и выполнение захвата одним из доступных методов.
shift() Перемещение элемента внутри контейнера.
transfer() Перемещение элемента в другой контейнер-приемник. После завершения перемещения на приемнике вызывает событие snap
swap() Обмен элемента с другим контейнером-приемником. После завершения перемещения на приемнике вызывает событие snap
cancel() Отмена перемещения элемента.
drop() Вызывается на контейнере-источнике, если ни один из контейнеров не захватил брошенный элемент.
remove() Удаление брошенного элемента из DOM-модели.
done() Завершение всех мультипликаций, очистка состояния плагина. Вызывает событие done

Состояния

Состояние плагина могут быть получены вызвом метода state(). Поведение плагина, его реакция на внешние события зависит от текущего состояния.

Описание состояний

Состояние Описание
idle Ожидание касания одного из элементов
hold Удержание нажатия на элементе
drag Перемещение захваченного элемента
next Ожидание следующего касания для IE10
drop Бросание элемента
snap Захват и перемещение элемента

Матрица переходов состояний

Событие Исходное состояние Конеченое состояние
Инициализация библиотеки idle
Нажатие клаваши мыши или касание элемента idle hold
Истекло время удержания после нажатия hold drag
idle idle
Истекло время удержания после касания пальцем или стилусом в IE10 hold next
idle idle
Движение мыши или пальца по экрану hold idle
drag drag
Отпускание клавиши мыши, прекращение касания или уход пальца с экрана, таймаут движения мыши next drag
drag drop
hold idle
Элемент брошен источником drop snap
Перемещение завершено snap idle