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" の形式でハッシュが生成されます。
    attributeid ではなく、別の属性値からハッシュを生成したい場合に、属性名を指定します。
    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引数には、以下のプロパティを持ったオブジェクトが渡されます。

    プロパティ説明
    helperhelper オブジェクトです。
    placeholderplaceholder オブジェクトです。
    positionSortable アイテムの位置です。
    top, left プロパティを持ちます。
    originalPositionSortable アイテムの元の位置です。
    top, left プロパティを持ちます。
    offsetSortable アイテムの絶対位置です。
    top, left プロパティを持ちます。
    item現在ドラッグ中の要素です。
    senderSortable アイテムの移動元の 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");});



リスト1

  • リスト1 [ id="fruits1-1" ] みかん
  • リスト1 [ id="fruits1-2" ] りんご
  • リスト1 [ id="fruits1-3" ] もも
  • リスト1 [ id="fruits1-4" ] かき
  • リスト1 [ id="fruits1-5" ] いちご

リスト2

  • リスト2 [ id="fruits2-1" ] メロン
  • リスト2 [ id="fruits2-2" ] キウィ
  • リスト2 [ id="fruits2-3" ] パイナップル
  • リスト2 [ id="fruits2-4" ] グレープフルーツ
  • リスト2 [ id="fruits2-5" ] オレンジ

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

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

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

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

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