Группируемые элементы

Материал из JQuery

Перейти к: навигация, поиск

Sortable


Описание
Свойства
Методы
События

Плагин Sortable позволяет научить группу элементов страницы меняться друг с другом местами, при перетаскивании их мышью. Плагин применяется не к самим группируемым элементам, а к обрамляющему их элементу (если нужно сделать группируемыми элементы списка li, то применить плагин нужно к содержащему их ul-элементу). Обрамляющий элемент автоматически получают класс ui-sortable.

Перетаскиваемые элементы генерируют несколько новых типов событий (см. вкладку События). Обработчики этих событий будут получать 2 параметра: стандартный объект события от браузера и дополнительный объект (назовем его ui) со следующими полями:

ui.helper — вспомогательный элемент (helper) в форме объекта jQuery. Подробности об этом элементе можно узнать в описании свойства helper.
ui.position — позиция перемещаемого helper-элемента относительно ближайшего родителя c заданным типом позиционирования (css-свойство position равно relative или absolute или fixed).
ui.offset — позиция перемещаемого helper-элемента относительно начала документа.
ui.item — перемещаемый в данный момент элемент.
ui.placeholder — элемент, заполняющий вакантное пространство (placeholder), если он определен.
ui.sender — sortable-элемент, в котором был взят группируемый элемент (это свойство доступно, только если вы перемещаете элемент из одной группы в другую).

↓ Имя свойства :типы значений (значение по умолчанию)
disabled:boolean(false)
Останавливает\возобновляет возможности плагина.
// ------- Работа со свойством disabled---------
// в момент установки draggable на элемент
$("selector").sortable({ disabled: true });
 
//получение значения disabled 
var disabled = $("selector").sortable( "option", "disabled" );
//изменение значения disabled
$("selector").sortable( "option", "disabled", true );
appendTo:element,селектор('parent')
Этот параметр определяет в какой элемент страницы будет помещен вспомогательный элемент (helper, см. одноименное свойство ниже), в случае, если helper не равен "original". По умолчанию, вспомогательный элемент помещается туда же, где находится перемещаемый элемент. appendTo может быть задан DOM-элементом или селектором, по которому будет осуществлен поиск элемента.
// ------- Работа со свойством appendTo ---------
// в момент установки sortable на элемент
$("selector").sortable({ appendTo: "#someId" });
 
//получение значения appendTo
var el = $("selector").sortable( "option", "appendTo" );
//изменение значения appendTo
$("selector").sortable( "option", "appendTo", "#someId" );
axis:string,false(false)
Этот параметр определяет в каком направлении можно будет перемещать элемент. Возможные значения 'x', 'y' и false (только по вертикали, только по горизонтали или в любом).
// ------- Работа со свойством axis ---------
// в момент установки sortable на элемент
$("selector").sortable({ axis: "x" });
 
//получение значения axis
var axis = $("selector").sortable( "option", "axis" );
//изменение значения axis
$(".selector").sortable( "option", "axis", "y" );
cancel:селектор('input,option')
Параметр cancel определяет, какие элементы нельзя перетаскивать.
// ------- Работа со свойством cancel ---------
// в момент установки sortable на элемент
$("selector").sortable({ cancel: "button" });
 
//получение значения cancel
var cancel = $("selector").sortable( "option", "cancel" );
//изменение значения cancel
$("selector").sortable( "option", "cancel", "button" );
connectWith:селектор,false(false)
В этом параметре можно указать другие sortable-наборы, из которых можно перетаскивать элементы в данный набор.
// ------- Работа со свойством connectWith ---------
// в момент установки sortable на элемент
$("selector").sortable({ connectWith:"ul#myList" });
 
//получение значения connectWith
var connectWith = $("selector").sortable( "option", "connectWith" );
//изменение значения connectWith
$("selector").sortable( "option", "connectWith", "ul#myList" );
Параметр containment определяет ограничения на перемещение элемента при перетаскивании. По умолчанию их нет, но они могут быть заданы областью какого-либо элемента (например с помощью селекторов или строк 'parent', 'document', 'window' и др.).
// ------- Работа со свойством containment ---------
// в момент установки sortable на элемент
$("selector").sortable({ containment:"parent" });
 
//получение значения containment
var containment = $("selector").sortable( "option", "containment" );
//изменение значения containment
$("selector").sortable( "option", "containment", "parent" );
cursor:string('auto')
Определяет значение css-свойства cursor (вид курсора) для группируемых элементов.
// ------- Работа со свойством cursor ---------
// в момент установки sortable на элемент
$("selector").sortable({ cursor:"pointer" });
 
//получение значения cursor
var cursor = $("selector").sortable( "option", "cursor" );
//изменение значения cursor
$("selector").sortable( "option", "cursor", "pointer" );
cursorAt:object(false)
С помощью этого свойства можно задать координаты на перемещаемом элементе, в которых окажется курсор при его перетаскивании (см. пример "Расположение курсора" плагина draggable).
// ------- Работа со свойством cursorAt ---------
// в момент установки sortable на элемент
$("selector").sortable({ cursorAt:{left:5, top:5} });
 
//получение значения cursorAt
var cursorAt = $("selector").sortable( "option", "cursorAt" );
//изменение значения cursorAt
$("selector").sortable( "option", "cursorAt", {right:5, bottom:5} );
delay:integer(0)
Параметр delay определяет задержку (в миллисекундах) перед началом перемещения элемента. Это может быть защитой от нежелательного перетаскивания элемента, если пользователь случайно потянет элемент.
// ------- Работа со свойством delay ---------
// в момент установки sortable на элемент
$("selector").sortable({ delay:500 });
 
//получение значения delay
var delay = $("selector").sortable( "option", "delay" );
//изменение значения delay
$("selector").sortable( "option", "delay", 500 );
distance:integer(1)
Этот параметр определяет расстояние (в пикселях), на которое нужно потянуть элемент, что бы он "оторвался" от своего первоначального положения. Это может быть защитой от нежелательного перетаскивания элемента, если пользователь случайно потянет элемент.
// ------- Работа со свойством distance ---------
// в момент установки sortable на элемент
$("selector").sortable({ distance:15 });
 
//получение значения distance
var distance = $("selector").sortable( "option", "distance" );
//изменение значения distance
$("selector").sortable( "option", "distance", 15 );
dropOnEmpty:boolean(true)
Если этот параметр равен false, то из текущего набора sortable-элементов нельзя будет переносить элементы в другие наборы, если в них нет ни одного элемента (см. пример "Работа с пустыми списками" выше).
// ------- Работа со свойством dropOnEmpty ---------
// в момент установки sortable на элемент
$("selector").sortable({ dropOnEmpty:true });
 
//получение значения dropOnEmpty
var dropOnEmpty = $("selector").sortable( "option", "dropOnEmpty" );
//изменение значения dropOnEmpty
$("selector").sortable( "option", "dropOnEmpty", true );
forceHelperSize:boolean(false)
If true, forces the helper to have a size.
// ------- Работа со свойством forceHelperSize ---------
// в момент установки sortable на элемент
$("selector").sortable({ forceHelperSize:true });
 
//получение значения forceHelperSize
var forceHelperSize = $("selector").sortable( "option", "forceHelperSize" );
//изменение значения forceHelperSize
$("selector").sortable( "option", "forceHelperSize", true );
forcePlaceholderSize:boolean(false)
If true, forces the placeholder to have a size.
// ------- Работа со свойством forcePlaceholderSize ---------
// в момент установки sortable на элемент
$("selector").sortable({ forcePlaceholderSize:true });
 
//получение значения forcePlaceholderSize
var forcePlaceholderSize = $("selector").sortable( "option", "forcePlaceholderSize" );
//изменение значения forcePlaceholderSize
$("selector").sortable( "option", "forcePlaceholderSize", true );
grid:array,false(false)
С помощью grid можно задать в пикселях размер шага перемещения элемента (горизонтального и вертикального отдельно). См. пример "Магнитные края" плагина Draggable.
// ------- Работа со свойством grid ---------
// в момент установки sortable на элемент
$("selector").sortable({ grid:[10,10] });
 
//получение значения grid
var grid = $("selector").sortable( "option", "grid" );
//изменение значения grid
$("selector").sortable( "option", "grid", [10,10] );
Позволяет указать, какие элементы, находящиеся внутри группируемого элемента, можно "схватить" для перетаскивания последнего. Параметр может быть задан с помощью DOM-элемента или селектора, по которому его можно найти. См. пример "Области захвата" плагина Draggable.
// ------- Работа со свойством handle ---------
// в момент установки sortable на элемент
$(".selector").sortable({ handle:'h2' });
 
//получение значения handle
var handle = $(".selector").sortable( "option", "handle" );
//изменение значения handle
$(".selector").sortable( "option", "handle", 'h2' );
helper:string,функция('original')
Определяет, какой элемент будет перемещаться в момент перетаскивания на самом деле: сам элемент (значение 'original'), его клон (значение 'clone') или какой то другой элемент (в этом случае, параметру helper необходимо присвоить функцию, которая бы возвращала нужный DOM-элемент).
// ------- Работа со свойством helper ---------
// в момент установки sortable на элемент
$(".selector").sortable({ helper:'clone' });
 
//получение значения helper
var helper = $(".selector").sortable( "option", "helper" );
//изменение значения helper
$(".selector").sortable( "option", "helper", 'clone' );
itemsселектор("> *")
Плагин Sortable примененный к элементу страницы, делает всех его прямых потомков группируемыми. Если необходимо, чтобы группируемыми стали лишь некоторые элементы, укажите соответствующий им селектор в параметре items (см. пример "Пассивные элементы" выше).
// ------- Работа со свойством items ---------
// в момент установки sortable на элемент
$(".selector").sortable({ items:true });
 
//получение значения items
var items = $(".selector").sortable( "option", "items" );
//изменение значения items
$(".selector").sortable( "option", "items", true );
opacity:float,false(false)
Параметр opacity отвечает за уровень прозрачности элемента в момент его перемещения. Напомним, что он принимает значения от 0 до 1 (от полной прозрачности, до полной видимости).
// ------- Работа со свойством opacity ---------
// в момент установки sortable на элемент
$("selector").sortable({ opacity:0.5 });
 
//получение значения opacity
var opacity = $("selector").sortable( "option", "opacity" );
//изменение значения opacity
$("selector").sortable( "option", "opacity", 0.5 );
placeholder:string,false(false)
При перетаскивании группируемого элемента, соседние элементы перемещаются, оставляя текущее вакантное место пустым. Для его оформления можно указать в параметре placeholder нужный класс.
// ------- Работа со свойством placeholder ---------
// в момент установки sortable на элемент
$("selector").sortable({ placeholder:"someClass" });
 
//получение значения placeholder
var placeholder = $("selector").sortable( "option", "placeholder" );
//изменение значения placeholder
$("selector").sortable( "option", "placeholder", "someClass" );
revert:boolean,integer(false)
Если этот параметр равен true, то при отпускании перетаскиваемого элемента, он вернется на место, с которого был взят. В этом параметре можно так же указать целое число, которое будет использовано как время (в миллисекундах) возвращения элемента в исходную позицию.
// ------- Работа со свойством revert ---------
// в момент установки sortable на элемент
$("selector").sortable({ revert:true });
 
//получение значения revert
var revert = $("selector").sortable( "option", "revert" );
//изменение значения revert
$("selector").sortable( "option", "revert", true );
scroll:boolean(true)
Присвоив этому параметру значение true, вы включите автоскроллинг. В этом случае, при попытке перетащить элемент за пределы ближайшего прокручиваемого родителя, последний начнет прокручиваться автоматически. Смотри так же параметры scrollSensitivity и scrollSpeed.
// ------- Работа со свойством scroll ---------
// в момент установки sortable на элемент
$("selector").sortable({ scroll:false });
 
//получение значения scroll
var scroll = $("selector").sortable( "option", "scroll" );
//изменение значения scroll
$("selector").sortable( "option", "scroll", false );
scrollSensitivity:integer(20)
Определяет расстояние (в пикселях) на котором должен находиться перетаскиваемый элемент от границы его ближайшего скроллируемого предка, для включения автоскроллинг (см. свойство scroll).
// ------- Работа со свойством scrollSensitivity ---------
// в момент установки sortable на элемент
$("selector").sortable({ scrollSensitivity:100 });
 
//получение значения scrollSensitivity
var scrollSensitivity = $("selector").sortable( "option", "scrollSensitivity" );
//изменение значения scrollSensitivity
$("selector").sortable( "option", "scrollSensitivity", 100 );
scrollSpeed:integer(20)
Определяет скорость выполнения автоскроллинга (см. свойство scroll).
// ------- Работа со свойством scrollSpeed ---------
// в момент установки sortable на элемент
$(".selector").sortable({ scrollSpeed:40 });
 
//получение значения scrollSpeed
var scrollSpeed = $(".selector").sortable( "option", "scrollSpeed" );
//изменение значения scrollSpeed
$(".selector").sortable( "option", "scrollSpeed", 40 );
tolerance:string('intersect')
С помощью этого свойства можно указать режим определения позиции перетаскиваемого элемента. Возможные значения:
intersect — перетаскиваемый элемент считается находящимся на следующей позиции, если он находится над ней более чем наполовину.
pointer — ..., если курсор находится в этой позиции.
// ------- Работа со свойством tolerance ---------
// в момент установки sortable на элемент
$("selector").sortable({ tolerance:"pointer" });
 
//получение значения tolerance
var tolerance = $("selector").sortable( "option", "tolerance" );
//изменение значения tolerance
$("selector").sortable( "option", "tolerance", "pointer" );
zIndex:integer(1000)
С помощью этого параметра можно указать значение css-свойства z-index перетаскиваемого элемента.
// ------- Работа со свойством zIndex ---------
// в момент установки sortable на элемент
$(".selector").sortable({ zIndex:5 });
 
//получение значения zIndex
var zIndex = $(".selector").sortable( "option", "zIndex" );
//изменение значения zIndex
$(".selector").sortable( "option", "zIndex", 5 );

↓ Способ вызова
.sortable("destroy") 
Удаляет всю функциональность плагина sortable с выбранных элементов.
.sortable("disable") 
Останавливает работу плагина sortable на выбранных элементах. Для возобновления, необходимо воспользоваться методом .sortable("enable").
.sortable("enable") 
Возобновляет работу плагина sortable на выбранных элементах (например, после того, как она была остановлена с помощью .sortable("disable")).
.sortable("option", optionName, [value]) 
Этот метод позволяет изменять/получать свойства плагина sortable. Если необходимо изменить сразу несколько свойств, воспользуйтесь следующей формой этой функции — .sortable("option", options), где options это объект в формате {optionName1:value1, optionName2:value2, ...}.
.sortable("widget") 
Возвращает те из выбранных элементов, которые являются перетаскиваемыми.
.sortable("serialize", [options]) 
Метод возвращает строку, в которой будут перечислены идентификаторы группируемых элементов. Строка будет иметь формат url-параметров, поэтому, ее удобно использовать для отправки на сервер данных о наборе группируемых объектов.

Чтобы идентификатор элемента попал в этот список, он должен соответствовать формату "somename_number" (например "item_1", "item_2", ...). Возвращаемая строка при этом будет выглядеть так "somename[]=number1&somename[]=number2" (для предыдущего примера "item[]=1&item[]=2..."). Кроме нижнего подчеркивания, в качестве разделителя можно использовать знаки дефис и равно (т.е. "item-1" или "item=1").

Для изменения работы метода можно указывать следующие настройки: 'key' (в возвращаемой строке, вместо somename[] будет указывать это значение), 'attribute' (в возвращаемой строке будут указаны не id элементов, а заданные атрибуты) and 'expression' (собственное регулярное выражение для разбиения id или других атрибутов).

<body>
  <ul id="sortable">
    <li id="it_1">Item 1</li>
    <li id="it_2">Item 2</li>
    <li id="it_3">Item 3</li>
  </ul>
 
  <script>
    alert(
      $( "#sortable" ).sortable() // сделает список группируемым
      .sortable("serialize") // вернет строку с id всех группируемых элементов
    );
  </script>
</body>

В итоге, будет выведено сообщение "it[]=1&it[]=2&it[]=3".

.sortable("toArray") 
Метод возвращает массив, в котором будут перечислены идентификаторы группируемых элементов.
<body>
  <ul id="sortable">
    <li id="it1">Item 1</li>
    <li id="it2">Item 2</li>
    <li id="it3">Item 3</li>
  </ul>
 
  <script>
    alert(
      $( "#sortable" ).sortable() // сделает список группируемым
      .sortable("toArray") // вернет массив с id всех группируемых элементов
    );
  </script>
</body>

В результате будет возвращен массив ["it1", "it2", "it3"].

.sortable("refresh") 
Инициирует обновления кеша, в котором хранится состав текущего группируемого набора. Обычно это делается автоматически, после изменения состава (удаления/добавления новых группируемых элементов).
.sortable("refreshPositions") 
Инициирует обновления кеша, в котором хранятся позиции всех элементов текущего группируемого набора. Обычно это делается автоматически после перестановки элементов или изменения состава текущего набора.
.sortable("cancel") 
Отменяет последнюю перестановку в группируемом наборе (включая перенос элемента из одного набора в другой. В этом случае, нужно вызывать метод на наборе, из которого был взят элемент. К нему можно обратиться из набора, получившего новый элемент, с помощью кода $(ui.sender).sortable('cancel')).

↓ Внутреннее имя события :внешнее имя
create:sortcreate
Событие create происходит в момент инициализации sortable на элементе.
// обработка события create
$("selector").sortable({
   create: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortcreate", function(event, ui){ ... });
start:sortstart
Событие start происходит в момент начала перетаскивания элемента.
// обработка события start
$("selector").sortable({
   start: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortstart", function(event, ui){ ... });
sort:sort
Событие sort происходит при каждом движении (изменении координат) перетаскиваемого элемента.
// обработка события sort
$("selector").sortable({
   sort: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sort", function(event, ui){ ... });
change:sortchange
Событие change происходит во время перетаскивания группируемого элемента, в моменты смены вакантной позиции (места, на которое встанет перетаскиваемый элемент, если его отпустить в данный момент).
// обработка события change
$("selector").sortable({
   change: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "change", function(event, ui){ ... });
beforeStop:sortbeforestop
Это событие происходит после отпускания перетаскиваемого элемента, но до удаления вспомогательных элементов (helper и placeholder).
// обработка события beforeStop
$("selector").sortable({
   beforeStop: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortbeforestop", function(event, ui){ ... });
stop:sortstop
Событие происходит после отпускания перетаскиваемого элемента.
// обработка события stop
$("selector").sortable({
   stop: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortstop", function(event, ui){ ... });
update:sortupdate
Событие происходит после отпускания перетаскиваемого элемента, в случае, если порядок группируемых элементов поменялся.
// обработка события update
$("selector").sortable({
   update: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortupdate", function(event, ui){ ... });
receive:sortreceive
Это событие происходит, когда в набор группируемых элементов помешают элемент из другого (связанного) набора.
// обработка события receive
$("selector").sortable({
   receive: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortreceive", function(event, ui){ ... });
over:sortover
Это событие происходит, если элемент из связанного группируемого набора оказывается над текущим набором. Это событие произойдет и в случае, если схватить элемент из текущего набора, перетащить его в область связного набора и не отпуская возвратить обратно в зону текущего набора (однако, это поведение не указано в документации и возможно является ошибочным, поэтому может быть и исправлено в будущем).
// обработка события over
$("selector").sortable({
   over: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortover", function(event, ui){ ... });
out:sortout
Судя по документации, это событие должно происходить в случае, если элемент из текущего группируемого набора, окажется над областью другого (связанного) набора. Но на деле, это событие происходит по довольно запутанному принципу.
// обработка события out
$("selector").sortable({
   out: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortout", function(event, ui){ ... });
activate:sortactivate
Это событие срабатывает в начале перетаскивания элемента, находящегося в текущем или связанном наборе.
// обработка события activate
$("selector").sortable({
   activate: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortactivate", function(event, ui){ ... });
deactivate:sortdeactivate
Это событие срабатывает при завершении перетаскивания элемента, находящегося в текущем или связанном наборе.
// обработка события deactivate
$("selector").sortable({
   deactivate: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "sortdeactivate", function(event, ui){ ... });