Migrar de ngx-sortablejs a ng-hub-ui-sortable
ngx-sortablejs no publica ninguna versión desde diciembre de 2020. Esta guía relaciona su directiva, inputs y outputs con los de ng-hub-ui-sortable, muestra una lista antes y después, e indica qué cambia en ejecución. Los nombres nuevos se han comprobado contra el código de la librería y los antiguos contra el paquete publicado 11.1.0.
1 · Por qué cambiar
La última versión de ngx-sortablejs, la 11.1.0, salió el 25 de diciembre de 2020. Declara Angular 11 como dependencia peer y está publicada en el formato anterior a Ivy (View Engine), que Angular dejó de admitir en la versión 16, así que una aplicación Angular actual no puede compilarla.
Si solo necesitas la misma API de plantilla en un Angular actual, existe un fork mantenido: @worktile/ngx-sortablejs, cuya 22.0.0 salió en septiembre de 2026 para Angular 22. Conserva los nombres de selector, inputs y outputs, así que solo cambia la importación. Pasar a ng-hub-ui-sortable compensa cuando además quieres inputs con signals, outputs reales y el resto de novedades de abajo, a costa de reescribir cada plantilla que use la directiva.
ng-hub-ui-sortable es un fork de ese fork. Es una directiva standalone con inputs con signals, un input por cada opción de SortableJS, outputs para los callbacks de SortableJS, un interruptor autoUpdateArray, utilidades para arrays, reordenación con teclado y un proveedor provideSortable(). Requiere Angular 17.3 o superior.
2 · Instalación e importación
Sustituye el paquete y registra la directiva. Las opciones globales pasan de SortablejsModule.forRoot() a provideSortable(), y la directiva se importa en los componentes que la usan.
Antes
Después
sortablejs ahora lo instala el propio paquete. Mantén @types/sortablejs en tu proyecto: la librería reexporta los tipos de SortableJS pero no los incluye.
3 · Equivalencias de API
Todos los miembros públicos de ngx-sortablejs 11.1.0 y lo que los sustituye.
| Antes | Después | Notas |
|---|---|---|
SortablejsModule, SortablejsModule.forRoot(options) | SortableDirective, provideSortable(options) | La directiva es standalone. SortableModule y SortableModule.forRoot(options) siguen existiendo pero están obsoletos; forRoot sigue exigiendo su argumento. |
[sortablejs]="items" | [hubSortable]="items" | Renombrado. Acepta un array, un FormArray o un WritableSignal que contenga un array. |
[sortablejsOptions] | [options] | Sigue siendo el objeto completo de opciones de SortableJS. Los 32 inputs individuales (por ejemplo [group], [handle], [animation]) prevalecen sobre la misma clave dentro de él. |
[sortablejsContainer] | [container] | Renombrado. Se sigue resolviendo una sola vez al inicializar; un selector sin coincidencias deja la directiva inactiva sin lanzar error. |
[sortablejsCloneFunction] | [cloneFunction] | Renombrado, misma firma. Solo se consulta en arrastres de clonado con un array enlazado y autoUpdateArray activo. |
(sortablejsInit) | (init) | La misma instancia de Sortable, ahora tipada. Se emite tras el siguiente renderizado, no tras un timeout, y nunca en el servidor. |
onStart, onEnd, onAdd, onUpdate, onSort, onRemove, onFilter, onChange, onChoose, onUnchoose, onClone | (start), (end), (add), (update), (sortEvent), (remove), (filterEvent), (change), (choose), (unchoose), (clone) | Los callbacks dentro de [options] siguen funcionando. Los outputs son nuevos. sort y filter llevan el sufijo Event porque esos nombres ya son inputs. |
onMove | onMove in [options], (move) | Un veto desde onMove en [options] sigue funcionando. El output (move) solo observa: un output de Angular no puede devolver false. |
SortablejsDirective | SortableDirective | Todos los inputs son inputs con signals, así que las lecturas pasan a ser llamadas (options()) y no se pueden escribir. |
SortableData | SortableData | Mismo nombre, ampliado para aceptar un WritableSignal. |
GLOBALS, SortablejsService | Sin equivalente | No se exportan. La raíz del paquete solo expone la directiva, el módulo, las utilidades de arrays, provideSortable, las clases de bindings y los tipos. |
SortablejsBindings, SortablejsBinding | SortableBindings, SortableBinding | Ahora se exportan desde la raíz del paquete (antes hacía falta una importación profunda). |
| — | [autoUpdateArray], [keyboardSorting], [keyboardMessages], moveItemInArray(), transferArrayItem(), copyArrayItem() | Nuevo: autoUpdateArray, keyboardSorting, keyboardMessages y las utilidades moveItemInArray, transferArrayItem y copyArrayItem, cuyos casos límite difieren un poco de los del CDK. |
4 · Un uso típico, antes y después
Una lista de tareas ordenable con asa de arrastre: primero con ngx-sortablejs y después con ng-hub-ui-sortable.
Antes
Después
5 · Diferencias de comportamiento que revisar
Son las diferencias que más probablemente sorprenden después del cambio de nombres.
- No hay codemod, y un buscar y reemplazar de sortablejs rompe los nombres de atributo más largos. Sustituye primero sortablejsOptions, sortablejsContainer y sortablejsCloneFunction, y después la directiva sola.
- Las opciones se combinan en tres capas: globales, luego [options] y luego los inputs individuales. [options]="{ animation: 150 }" junto con [animation]="0" da 0, sin aviso. Usa un solo estilo por elemento.
- No pases la validación de soltado de options.onMove al output (move). El output no puede cancelar un movimiento, así que se aceptarían todos los soltados prohibidos.
- Un callback en [options] y el output equivalente en el mismo elemento se ejecutan los dos, de modo que un manejador conectado a ambos corre dos veces por evento. Elige un solo canal por evento.
- Nombres como (change), (start), (end), (add), (remove) y (update) en el elemento anfitrión ahora se enlazan a los outputs de la directiva, no a eventos del DOM. Trata cada enlace existente como una reescritura y mueve los listeners nativos a un elemento envoltorio.
- La instancia se crea fuera de la zona de Angular, así que los callbacks que la directiva no envuelve (callbacks de plugins, setData, store) no disparan por sí solos la detección de cambios. Escribe una signal o marca la vista tú mismo.
- Los inputs nuevos no llevan prefijo, así que un atributo estático como draggable="false" en el anfitrión llega a la opción draggable como la cadena "false" y nada se vuelve arrastrable. Pon la directiva en un envoltorio si un atributo choca.
- La reordenación con teclado viene activada por defecto: cada elemento (o su asa) pasa a ser parada de tabulación, Intro o Espacio lo coge y las flechas lo mueven. Usa [keyboardSorting]="false" si no la quieres.
6 · Documentación
La referencia completa de la directiva, con ejemplos en vivo, está en su página de documentación: Documentación de ng-hub-ui-sortable