Sortable
解説
要素をマウスでドラッグして、入れ替えられるようにします。
書式
jQuery_Object.sortable([options]);
依存ファイル
- jquery.ui.core.js
- jquery.ui.widget.js
- jquery.ui.mouse.js
- jquery.ui.sortable.js
引数
-
optionsオプション
関数
String: "destroy"、 "disable"、"enable"、"option"、"widget"、"serialize"、"toArray"、"refresh"、"refreshPositions"、"cancel" のいずれか。
値 | 書式 | 説明 |
"destroy" |
sortable("destroy") |
Sortable 機能を完全に破棄します。 |
"disable" |
sortable("disable") |
Sortable 機能を一時的に無効にします。 |
"enable" |
sortable("enable") |
Sortable 機能を有効にします。 |
"option" |
sortable("option", optionName, [value]) |
Sortable 機能のオプションを設定します。
optionName に、オプション名を指定します。
value に、オプション値を指定します。
(value を指定した場合は、オプションを設定するsetterとして、value を指定しない場合は、オプションを取得するgetterとして動作します。)
|
"option" |
sortable("option", options) |
Sortable 機能のオプションを設定します。
options に、オプションを指定します。(キーと値のハッシュ)
|
"widget" |
sortable("widget") |
Sortable 要素を返します。(ui-sortable クラスが設定された要素)
|
"serialize" |
sortable("serialize" [options]) |
並べ替えた順番で、Sortable アイテムに設定されたIDから、フォーム送信やajax送信できるようにシリアライズします。
リクエスト送信時に、URLに追加可能なハッシュを、並べ変えた要素の順番で生成します。
IDに、"-"(ハイフン)、"="(等号)、"_"(アンダースコア)があるかどうかを判別し、その文字で分割してハッシュ文字列を生成します。
例) 並べ替えた要素のIDが、 item-1, item-3, item-4, item-2 の場合
item[]=1&item[]=3&item[]=4&item[]=2
第2引数には、このメソッドの動作オプションを指定することができます。
プロパティ | 説明 |
key | 送信するキー文字列。 例えは "list" を指定すれば、"list[]=x" の形式でハッシュが生成されます。 |
attribute | id ではなく、別の属性値からハッシュを生成したい場合に、属性名を指定します。 |
expression |
分割する正規表現を指定します。
例:"#" で分割したい場合
|
|
"toArray" |
sortable("toArray") |
Sortable アイテムのIDの配列を返します。
例) Sortable アイテムのIDが、 item-1, item-3, item-4, item-2 の場合
["item-1", "item-3", "item-4", "item-2"]
|
"refresh" |
sortable("refresh") |
Sortable 要素を更新します。Sortable アイテムに変更があった場合に呼び出します。
|
"refreshPositions" |
sortable("refreshPositions") |
Sortable 要素のキャッシュされた位置情報を更新します。
内部で自動的に呼び出されますので、通常は使用しません。
|
"cancel" |
sortable("cancel") |
一つ前に行った並べ替えをキャンセルし、位置を元に戻します。
|
オプション
Object: 指定したオプションで、要素に Sortable 機能を追加します。(キーと値のハッシュ)
プロパティ | 型 | 初期値 | 説明 |
disabled |
Boolean |
false |
並べ替え機能の有効(false)、無効(true)を設定します。Sortable 機能の初期値として設定できます。 |
appendTo |
String |
"parent" |
helperのコンテナとして使用する要素を指定します。指定しない場合、helperは Sortable 要素と同じコンテナを使用します。
|
axis |
String |
false (制限なし) |
ドラッグできる方向を制限します。"x"を指定すると横方向、"y"を指定すると縦方向です。
|
cancel |
Selector |
":input,button" |
指定した要素を掴んでも、並び替えできないようにします。
|
connectWith |
Selector |
false |
他の Sortable 要素に、 Sortable アイテムを移動できるようにします。
このオプションは、一方向です。connectWith で指定した先の要素に Sortable アイテムを移動すると、元のSortable 要素に戻すことはできません。
双方向にしたい場合は、それぞれの Sortable 要素でお互いを参照するように connectWith オプションを指定します。
|
containment |
Element, String, Selector |
false |
ドラッグの範囲を制限します。指定した要素内でのみドラッグが可能になります。
"parent"(親要素内)、"document"(ドキュメント内)、 DOM要素、jQueryセレクタを指定できます。
|
cursor |
String |
"auto" |
ドラッグ中のカーソルを指定します。CSSの cursor プロパティの値が指定できます。
|
cursorAt |
Object |
false |
ドラッグ中のカーソルの位置を指定します。要素に対するカーソルのtop, left, right, bottomを、ハッシュで指定することができます。
|
delay |
Integer |
0 |
並び替えを開始するまでの時間をミリ秒で指定します。
|
distance |
Integer |
1 |
指定されたpixelを超えたところまで引きずらないと、並び替えが開始されないようにします。
|
dropOnEmpty |
Boolean |
true |
false を指定すると、Sortable 要素の内容が空の場合は、ドロップできなくなります。
|
forceHelperSize |
Boolean |
false |
true を指定すると、 helper の大きさを強制的に保持します。
|
forcePlaceholderSize |
Boolean |
false |
true を指定すると、 placeholder の大きさを強制的に保持します。
(placeholder とは、並び替え要素のドラッグ中に自動的に挿入される空白の領域です。)
|
grid |
Array [Integer x, Integer y] |
false |
指定したx, y座標毎にsnap(吸い付き)します。
|
handle |
Selector, Element |
false |
指定した要素をクリックして並び替えを開始するようにします。
|
helper |
String, Function |
"original" |
ドラッグ中の表示方法を指定します。
"clone"を指定すると、要素を複製して表示するghosting エフェクトが適用されます。
"original"を指定すると、ドラッグ要素をマウスカーソルに合わせて動かします。
また、DOM要素を返す関数オブジェクトを指定して、独自のエフェクトを設定することができます。
|
items |
Selector |
"> *" |
Sortable アイテムを指定します。デフォルトでは、Sortable 要素の子要素です。
|
opacity |
Float |
false |
ドラッグ中の不透明度を指定します。
|
placeholder |
String |
false |
placeholder に適用する CSS クラスを指定します。
(placeholder とは、並び替え要素のドラッグ中に自動的に挿入される空白の領域です。)
|
revert |
Boolean, Integer |
false |
trueを指定すると、スムーズなアニメーションをしながら並べ替え先へ移動します。
数値を指定した場合は、その時間(ms)でアニメーションします。
|
scroll |
Boolean |
true |
trueを指定すると、並び替え中に表示領域を出た場合、ウィンドウを自動的にスクロールします。
|
scrollSensitivity |
Integer |
20 |
スクロールを開始する表示領域の端からの距離をpixelで指定します。
この距離は、Sortable 要素ではなくマウスカーソルとの距離です。
|
scrollSpeed |
Integer |
20 |
scrollSensitivityオプションで指定した距離に入った時の、スクロール速度を指定します。
|
tolerance |
String |
"intersect" |
並び替えが起きる条件を指定します。
パラメータ | 意味 |
"intersect" | 交差した (並び替え要素が半分以上入った場合) |
"pointer" | ポインタが入った |
|
zIndex |
Integer |
1000 |
Sortable 要素の重ね合わせの順序を数値で指定します。数値が大きいほど、手前に表示されます。
|
イベント
プロパティ | イベントタイプ | 説明 |
start |
sortstart |
並び替えが開始されたときに呼び出されます。
|
sort |
sort |
並び替え中に呼び出されます。
|
change |
sortchange |
並び替え中に、DOM要素の位置が変更されたときに呼び出されます。
|
beforeStop |
sortbeforestop |
並び替えが終了し、placeholder もしくは helper が、まだ有効なときに呼び出されます。
|
stop |
sortstop |
並び替えが終了したときに呼び出されます。
|
update |
sortupdate |
並び替えが終了し、DOM要素の位置が変更されたときに呼び出されます。
|
receive |
sortreceive |
他の Sortable 要素からアイテムを受け取ったときに呼び出されます。
|
remove |
sortremove |
他の Sortable 要素に Sortable アイテムを移動し、自分のSortable 要素から削除されたときに呼び出されます。
|
over |
sortover |
並べ替えアイテムが Sortable 要素に入ったときに呼び出されます。
|
out |
sortout |
並べ替えアイテムが Sortable 要素から出たときに呼び出されます。
|
activate |
sortdeactivate |
関連付けられている Sortable 要素の Sortableアイテムのドラッグが開始したときに呼び出されます。
|
deactivate |
sortdeactivate |
関連付けられている Sortable 要素の、Sortable アイテムのドラッグが終了したときに呼び出されます。
|
イベントハンドラには2つの引数が渡されます。
第1引数は、イベントオブジェクトです。
第2引数には、以下のプロパティを持ったオブジェクトが渡されます。
プロパティ | 説明 |
helper | helper オブジェクトです。 |
placeholder | placeholder オブジェクトです。 |
position | Sortable アイテムの位置です。 top, left プロパティを持ちます。 |
originalPosition | Sortable アイテムの元の位置です。 top, left プロパティを持ちます。 |
offset | Sortable アイテムの絶対位置です。 top, left プロパティを持ちます。 |
item | 現在ドラッグ中の要素です。 |
sender | Sortable アイテムの移動元の Sortable 要素です。 (他の Sortable 要素から、Sortable アイテムを受け取ったときのみ設定されます。) |
例: change イベントハンドラの設定
$(".selector").sortable({
change: function(event, ui) {
event;
ui;
}
});
イベントにバインドするには、上記のイベントタイプを指定します。
例: change イベントにバインドする場合
$(".selector").bind(
"sortchange",
function(event, ui) { ... }
);
戻り値
例
例1:Selectable要素を生成します。
.placeholder {border:1px dotted blue; background-color: #afeeee; height: 5px;}
$("#test_result ul").sortable({
placeholder: "placeholder",
connectWith: "#test_result ul"
});
$("#enable").click(function(){$("#test_result ul").sortable("enable");});
$("#disable").click(function(){$("#test_result ul").sortable("disable");});
$("#destroy").click(function(){$("#test_result ul").sortable("destroy");});
$("#serialize_list1").click(function(){$("#view1").text($(".list1").sortable("serialize"));});
$("#serialize_list1").click(function(){$(".list1").sortable("cancel");});
$("#serialize_list1").click(function(){$("#view2").text($(".list2").sortable("serialize"));});
$("#serialize_list1").click(function(){$(".list2").sortable("cancel");});
Sortable 要素に付与されるクラス
Sortable要素には、状態に応じて以下のクラスが設定されます。
クラス | 状態 |
ui-sortable | 並び替え機能 有効 |
ui-sortable-disabled | 並び替え機能 無効 |
例)並び替え機能 無効状態の Sortable 要素
<Sortable要素 class="ui-sortable ui-sortable-disabled" />
|
|