ngx-sortablejs から ng-hub-ui-sortable への移行
ngx-sortablejs は 2020 年 12 月以降リリースされていません。このガイドでは、そのディレクティブ、input、output を ng-hub-ui-sortable のものに対応づけ、リストを移行前後で示し、実行時に変わる点を説明します。新しい名前はライブラリのソースで、古い名前は公開済みの 11.1.0 パッケージで確認しています。
1 · 移行する理由
ngx-sortablejs の最新版 11.1.0 は 2020 年 12 月 25 日に公開されました。peer 依存は Angular 11 で、Ivy 以前(View Engine)の形式で公開されています。Angular はバージョン 16 でこの形式のサポートをやめたため、現行の Angular アプリケーションではビルドできません。
現行の Angular で同じテンプレート API をそのまま使いたいだけなら、メンテナンスされているフォークがあります。@worktile/ngx-sortablejs で、22.0.0 が 2026 年 9 月に Angular 22 向けに公開されました。セレクター、input、output の名前は変わらないので、変更するのはインポートだけです。シグナル input や本物の output、以下のその他の追加機能も使いたい場合は ng-hub-ui-sortable が向いていますが、ディレクティブを使うすべてのテンプレートを書き換える必要があります。
ng-hub-ui-sortable はそのフォークからさらに派生したものです。シグナル input、SortableJS のオプションごとの input、SortableJS のコールバック用 output、autoUpdateArray スイッチ、配列ヘルパー、キーボードでの並べ替え、provideSortable() プロバイダーを備えたスタンドアロンのディレクティブです。Angular 17.3 以降が必要です。
2 · インストールとインポート
パッケージを入れ替え、ディレクティブを登録します。グローバルオプションは SortablejsModule.forRoot() から provideSortable() に移り、ディレクティブはそれを使うコンポーネントでインポートします。
移行前
移行後
sortablejs はパッケージ自身がインストールします。@types/sortablejs はプロジェクトに残してください。ライブラリは SortableJS の型を再エクスポートしますが、同梱はしていません。
3 · API の対応表
ngx-sortablejs 11.1.0 の公開メンバーすべてと、その置き換え先です。
| 移行前 | 移行後 | 備考 |
|---|---|---|
SortablejsModule, SortablejsModule.forRoot(options) | SortableDirective, provideSortable(options) | ディレクティブはスタンドアロンです。SortableModule と SortableModule.forRoot(options) は残っていますが非推奨で、forRoot は引き続き引数が必須です。 |
[sortablejs]="items" | [hubSortable]="items" | 名前が変わりました。配列、FormArray、配列を持つ WritableSignal を受け取れます。 |
[sortablejsOptions] | [options] | 引き続き SortableJS のオプションオブジェクト全体です。32 個の個別 input(たとえば [group]、[handle]、[animation])は、その中の同じキーより優先されます。 |
[sortablejsContainer] | [container] | 名前が変わりました。引き続き初期化時に一度だけ解決されます。一致しないセレクターを渡すと、エラーなしでディレクティブは何もしません。 |
[sortablejsCloneFunction] | [cloneFunction] | 名前が変わりました。シグネチャは同じです。配列がバインドされ autoUpdateArray が有効なクローンドラッグでのみ参照されます。 |
(sortablejsInit) | (init) | 同じ Sortable インスタンスで、型が付きました。タイムアウト後ではなく次の描画後に発火し、サーバー上では発火しません。 |
onStart, onEnd, onAdd, onUpdate, onSort, onRemove, onFilter, onChange, onChoose, onUnchoose, onClone | (start), (end), (add), (update), (sortEvent), (remove), (filterEvent), (change), (choose), (unchoose), (clone) | [options] 内のコールバックはそのまま動作します。output は新規です。sort と filter は、その名前がすでに input であるため Event という接尾辞が付きます。 |
onMove | onMove in [options], (move) | [options] の onMove による拒否は引き続き有効です。(move) output は監視専用で、Angular の output は false を返せません。 |
SortablejsDirective | SortableDirective | すべての input はシグナル input なので、読み取りは呼び出し(options())になり、書き込みはできません。 |
SortableData | SortableData | 名前は同じで、WritableSignal を受け取れるように拡張されました。 |
GLOBALS, SortablejsService | 対応するものなし | エクスポートされていません。パッケージのルートが公開するのは、ディレクティブ、モジュール、配列ヘルパー、provideSortable、バインディングのクラス、型だけです。 |
SortablejsBindings, SortablejsBinding | SortableBindings, SortableBinding | パッケージのルートからエクスポートされるようになりました(以前は深いインポートが必要でした)。 |
| — | [autoUpdateArray], [keyboardSorting], [keyboardMessages], moveItemInArray(), transferArrayItem(), copyArrayItem() | 新規: autoUpdateArray、keyboardSorting、keyboardMessages、および配列ヘルパーの moveItemInArray、transferArrayItem、copyArrayItem。エッジケースの挙動は CDK のものとわずかに異なります。 |
4 · 典型的な使い方(移行前と移行後)
ドラッグハンドル付きの並べ替え可能なタスクリストを、ngx-sortablejs と ng-hub-ui-sortable の順で示します。
移行前
移行後
5 · 確認すべき動作の違い
名前を置き換えたあとで特に戸惑いやすい違いです。
- コードモッドはなく、sortablejs の単純な検索置換では、より長い属性名が壊れます。先に sortablejsOptions、sortablejsContainer、sortablejsCloneFunction を置き換え、そのあとで単独のディレクティブを置き換えてください。
- オプションは 3 層でマージされます。グローバル、[options]、個別 input の順です。[options]="{ animation: 150 }" と [animation]="0" を併用すると、警告なしに 0 になります。1 つの要素では片方のスタイルに統一してください。
- ドロップの検証を options.onMove から (move) output に移さないでください。output は移動をキャンセルできないため、禁止されたドロップがすべて受け入れられてしまいます。
- 同じ要素で [options] のコールバックと対応する output の両方を設定すると両方が実行され、両方につないだハンドラーはイベントごとに 2 回動きます。イベントごとに経路は 1 つにしてください。
- ホスト要素の (change)、(start)、(end)、(add)、(remove)、(update) などは、DOM イベントではなくディレクティブの output にバインドされるようになりました。既存のバインディングは書き換えが必要なものとして扱い、ネイティブのリスナーは外側のラッパー要素に移してください。
- インスタンスは Angular ゾーンの外で作られるため、ディレクティブがラップしないコールバック(プラグインのコールバック、setData、store)だけでは変更検知が走りません。シグナルに書き込むか、ビューを自分でマークしてください。
- 新しい input には接頭辞がないため、ホストの draggable="false" のような静的属性は文字列 "false" として draggable オプションに渡され、何もドラッグできなくなります。属性が衝突する場合は、ディレクティブをラッパー要素に付けてください。
- キーボードでの並べ替えは既定で有効です。各項目(またはそのハンドル)が Tab 移動の対象になり、Enter または Space でつかみ、矢印キーで動かします。不要な場合は [keyboardSorting]="false" を指定してください。
6 · ドキュメント
ディレクティブの完全なリファレンスとライブ例は、専用のドキュメントページにあります。 ng-hub-ui-sortable のドキュメント