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; // UIオブジェクト
      }
  });
  

  
  

  イベントにバインドするには、上記のイベントタイプを指定します。
  例: change イベントにバインドする場合

  $(".selector").bind(
      "sortchange",
      function(event, ui) { ... }
  );
  

戻り値

• jQuery: jQueryオブジェクト

例

例1:Selectable要素を生成します。

/* --- CSS --- */
// placeholder のCSS
.placeholder {border:1px dotted blue; background-color: #afeeee; height: 5px;}

// ul要素を並び替え可能にする

$("#test_result ul").sortable({
    placeholder: "placeholder",      // placeholder に適用するCSSクラス(.は不要)
    connectWith: "#test_result ul"   // Sortable アイテムを相互に並び替え可能にする
});


// 無効 → 有効にする
$("#enable").click(function(){$("#test_result ul").sortable("enable");});
// 有効 → 無効にする

$("#disable").click(function(){$("#test_result ul").sortable("disable");});
// 並び替え機能を破棄する
$("#destroy").click(function(){$("#test_result ul").sortable("destroy");});


// リスト1 をシリアライズする。
$("#serialize_list1").click(function(){$("#view1").text($(".list1").sortable("serialize"));});

// リスト1 の並び替えを一つ前の状態に戻す。
$("#serialize_list1").click(function(){$(".list1").sortable("cancel");});
// リスト2 をシリアライズする。

$("#serialize_list1").click(function(){$("#view2").text($(".list2").sortable("serialize"));});

// リスト2 の並び替えを一つ前の状態に戻す。
$("#serialize_list1").click(function(){$(".list2").sortable("cancel");});

Sortable 要素に付与されるクラス

Sortable要素には、状態に応じて以下のクラスが設定されます。

クラス	状態
ui-sortable	並び替え機能 有効
ui-sortable-disabled	並び替え機能 無効

例）並び替え機能 無効状態の Sortable 要素

<Sortable要素 class="ui-sortable ui-sortable-disabled" />

ページトップヘ

ページトップヘ