Von ngx-sortablejs zu ng-hub-ui-sortable migrieren
ngx-sortablejs hat seit Dezember 2020 keine neue Version mehr. Dieser Leitfaden ordnet Direktive, Inputs und Outputs denen von ng-hub-ui-sortable zu, zeigt eine Liste vorher und nachher und nennt, was sich zur Laufzeit ändert. Die neuen Namen wurden am Quellcode der Bibliothek geprüft, die alten am veröffentlichten Paket 11.1.0.
1 · Warum wechseln
Die letzte Version von ngx-sortablejs, 11.1.0, erschien am 25. Dezember 2020. Sie deklariert Angular 11 als Peer-Abhängigkeit und ist im Format vor Ivy (View Engine) veröffentlicht, das Angular seit Version 16 nicht mehr unterstützt; eine aktuelle Angular-Anwendung kann sie daher nicht bauen.
Wenn Sie nur dieselbe Template-API auf einem aktuellen Angular brauchen, gibt es einen gepflegten Fork: @worktile/ngx-sortablejs, dessen Version 22.0.0 im September 2026 für Angular 22 erschien. Er behält Selektor, Input- und Output-Namen bei, sodass sich nur der Import ändert. Der Wechsel zu ng-hub-ui-sortable lohnt sich, wenn Sie zusätzlich Signal-Inputs, echte Outputs und die übrigen Neuerungen unten wollen, auf Kosten einer Überarbeitung jedes Templates, das die Direktive verwendet.
ng-hub-ui-sortable ist ein Fork dieses Forks. Es ist eine Standalone-Direktive mit Signal-Inputs, einem Input je SortableJS-Option, Outputs für die SortableJS-Callbacks, einem Schalter autoUpdateArray, Array-Hilfsfunktionen, Tastatursortierung und einem Provider provideSortable(). Es benötigt Angular 17.3 oder neuer.
2 · Installation und Import
Ersetzen Sie das Paket und registrieren Sie die Direktive. Globale Optionen wandern von SortablejsModule.forRoot() zu provideSortable(), und die Direktive wird in den Komponenten importiert, die sie verwenden.
Vorher
Nachher
sortablejs wird jetzt vom Paket selbst installiert. Behalten Sie @types/sortablejs in Ihrem Projekt: Die Bibliothek exportiert die SortableJS-Typen erneut, liefert sie aber nicht mit.
3 · API-Zuordnung
Alle öffentlichen Mitglieder von ngx-sortablejs 11.1.0 und was sie ersetzt.
| Vorher | Nachher | Hinweise |
|---|---|---|
SortablejsModule, SortablejsModule.forRoot(options) | SortableDirective, provideSortable(options) | Die Direktive ist standalone. SortableModule und SortableModule.forRoot(options) gibt es noch, sie sind aber veraltet; forRoot verlangt weiterhin sein Argument. |
[sortablejs]="items" | [hubSortable]="items" | Umbenannt. Akzeptiert ein Array, ein FormArray oder ein WritableSignal mit einem Array. |
[sortablejsOptions] | [options] | Weiterhin das komplette SortableJS-Optionsobjekt. Die 32 einzelnen Inputs (etwa [group], [handle], [animation]) überschreiben denselben Schlüssel darin. |
[sortablejsContainer] | [container] | Umbenannt. Wird weiterhin einmal bei der Initialisierung aufgelöst; ein Selektor ohne Treffer lässt die Direktive ohne Fehler inaktiv. |
[sortablejsCloneFunction] | [cloneFunction] | Umbenannt, gleiche Signatur. Wird nur bei Klon-Drags mit gebundenem Array und aktivem autoUpdateArray abgefragt. |
(sortablejsInit) | (init) | Dieselbe Sortable-Instanz, jetzt typisiert. Sie wird nach dem nächsten Rendering ausgelöst, nicht nach einem Timeout, und nie auf dem Server. |
onStart, onEnd, onAdd, onUpdate, onSort, onRemove, onFilter, onChange, onChoose, onUnchoose, onClone | (start), (end), (add), (update), (sortEvent), (remove), (filterEvent), (change), (choose), (unchoose), (clone) | Callbacks in [options] funktionieren weiter. Die Outputs sind neu. sort und filter tragen das Suffix Event, weil diese Namen bereits Inputs sind. |
onMove | onMove in [options], (move) | Ein Veto über onMove in [options] funktioniert weiter. Der Output (move) beobachtet nur: Ein Angular-Output kann kein false zurückgeben. |
SortablejsDirective | SortableDirective | Alle Inputs sind Signal-Inputs, Lesezugriffe werden also zu Aufrufen (options()), Schreibzugriffe sind nicht möglich. |
SortableData | SortableData | Gleicher Name, erweitert um ein WritableSignal. |
GLOBALS, SortablejsService | Kein Äquivalent | Nicht exportiert. Die Paketwurzel stellt nur Direktive, Modul, Array-Hilfsfunktionen, provideSortable, die Bindings-Klassen und die Typen bereit. |
SortablejsBindings, SortablejsBinding | SortableBindings, SortableBinding | Werden jetzt aus der Paketwurzel exportiert (zuvor war ein tiefer Import nötig). |
| — | [autoUpdateArray], [keyboardSorting], [keyboardMessages], moveItemInArray(), transferArrayItem(), copyArrayItem() | Neu: autoUpdateArray, keyboardSorting, keyboardMessages sowie die Hilfsfunktionen moveItemInArray, transferArrayItem und copyArrayItem, deren Grenzfälle sich leicht von denen des CDK unterscheiden. |
4 · Eine typische Verwendung, vorher und nachher
Eine sortierbare Aufgabenliste mit Ziehgriff: zuerst mit ngx-sortablejs, dann mit ng-hub-ui-sortable.
Vorher
Nachher
5 · Verhaltensunterschiede, die Sie prüfen sollten
Diese Unterschiede überraschen nach der Umbenennung am ehesten.
- Es gibt keinen Codemod, und ein einfaches Suchen und Ersetzen von sortablejs zerstört die längeren Attributnamen. Ersetzen Sie zuerst sortablejsOptions, sortablejsContainer und sortablejsCloneFunction und danach die einzelne Direktive.
- Optionen werden in drei Schichten zusammengeführt: global, dann [options], dann die einzelnen Inputs. [options]="{ animation: 150 }" zusammen mit [animation]="0" ergibt 0, ohne Warnung. Verwenden Sie pro Element nur einen Stil.
- Verlagern Sie die Drop-Validierung nicht von options.onMove auf den Output (move). Der Output kann eine Bewegung nicht abbrechen, sodass jedes verbotene Ablegen akzeptiert würde.
- Ein Callback in [options] und der passende Output am selben Element laufen beide, ein an beide gebundener Handler läuft also zweimal pro Event. Wählen Sie pro Event einen Kanal.
- Namen wie (change), (start), (end), (add), (remove) und (update) am Host-Element binden jetzt an die Outputs der Direktive, nicht an DOM-Events. Behandeln Sie jede bestehende Bindung als Neuschreibung und verlegen Sie native Listener auf ein umschließendes Element.
- Die Instanz wird außerhalb der Angular-Zone erstellt; Callbacks, die die Direktive nicht umschließt (Plugin-Callbacks, setData, store), lösen die Änderungserkennung daher nicht von selbst aus. Schreiben Sie ein Signal oder markieren Sie die View selbst.
- Die neuen Inputs haben kein Präfix, daher wird ein statisches Attribut wie draggable="false" am Host als Zeichenfolge "false" an die Option draggable übergeben, und nichts wird ziehbar. Setzen Sie die Direktive auf ein umschließendes Element, wenn ein Attribut kollidiert.
- Die Tastatursortierung ist standardmäßig aktiv: Jedes Element (oder sein Griff) wird zum Tab-Stopp, Eingabe- oder Leertaste nimmt es auf, die Pfeiltasten bewegen es. Mit [keyboardSorting]="false" schalten Sie sie ab.
6 · Dokumentation
Die vollständige Referenz der Direktive mit Live-Beispielen finden Sie auf der zugehörigen Dokumentationsseite: Dokumentation zu ng-hub-ui-sortable