Переход с ngx-sortablejs на ng-hub-ui-sortable

ngx-sortablejs не выпускал релизов с декабря 2020 года. Это руководство сопоставляет его директиву, inputs и outputs с ng-hub-ui-sortable, показывает список до и после и указывает, что меняется во время выполнения. Новые имена проверены по исходному коду библиотеки, старые — по опубликованному пакету 11.1.0.

1 · Зачем переходить

Последний релиз ngx-sortablejs, 11.1.0, вышел 25 декабря 2020 года. Он объявляет peer-зависимостью Angular 11 и опубликован в формате до Ivy (View Engine), поддержку которого Angular прекратил в версии 16, поэтому современное приложение на Angular не может его собрать.

Если нужен тот же API шаблонов на современном Angular, есть поддерживаемый форк: @worktile/ngx-sortablejs, версия 22.0.0 которого вышла в сентябре 2026 года для Angular 22. Он сохраняет имена селектора, inputs и outputs, так что меняется только импорт. Переход на ng-hub-ui-sortable оправдан, когда вам нужны ещё и inputs на сигналах, настоящие outputs и остальные новинки ниже, ценой переписывания каждого шаблона, где используется директива.

ng-hub-ui-sortable — форк этого форка. Это standalone-директива с inputs на сигналах, по одному input на каждую опцию SortableJS, outputs для колбэков SortableJS, переключателем 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)Директива standalone. 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] продолжают работать. Outputs новые. У sort и filter есть суффикс Event, потому что эти имена уже заняты inputs.
onMoveonMove in [options], (move)Запрет через onMove в [options] по-прежнему работает. Output (move) только наблюдает: output Angular не может вернуть false.
SortablejsDirectiveSortableDirectiveВсе inputs — на сигналах, поэтому чтение становится вызовом (options()), а запись невозможна.
SortableDataSortableDataТо же имя, расширено для приёма WritableSignal.
GLOBALS, SortablejsService Аналога нет Не экспортируются. Корень пакета открывает только директиву, модуль, помощники для массивов, provideSortable, классы привязок и типы.
SortablejsBindings, SortablejsBindingSortableBindings, 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, а потом саму директиву.
  • Опции объединяются в три слоя: глобальные, затем [options], затем отдельные inputs. [options]="{ animation: 150 }" вместе с [animation]="0" даст 0 без предупреждения. Используйте один способ на элемент.
  • Не переносите проверку сброса с options.onMove на output (move). Output не может отменить перемещение, поэтому будут приняты все запрещённые сбросы.
  • Колбэк в [options] и соответствующий output на одном элементе выполняются оба, поэтому обработчик, подключённый к обоим, срабатывает дважды на событие. Выберите один канал на событие.
  • Имена вроде (change), (start), (end), (add), (remove) и (update) на хост-элементе теперь привязываются к outputs директивы, а не к событиям DOM. Считайте каждую существующую привязку переписыванием и вынесите нативные слушатели на обёртку.
  • Экземпляр создаётся вне зоны Angular, поэтому колбэки, которые директива не оборачивает (колбэки плагинов, setData, store), сами не запускают обнаружение изменений. Запишите значение в сигнал или пометьте представление самостоятельно.
  • У новых inputs нет префикса, поэтому статический атрибут вроде draggable="false" на хосте попадает в опцию draggable как строка "false", и ничего не становится перетаскиваемым. Если атрибут конфликтует, поставьте директиву на элемент-обёртку.
  • Сортировка с клавиатуры включена по умолчанию: каждый элемент (или его ручка) становится остановкой Tab, Enter или Пробел берёт его, стрелки перемещают. Чтобы отключить, задайте [keyboardSorting]="false".

6 · Документация

Полный справочник по директиве с живыми примерами находится на её странице документации: Документация ng-hub-ui-sortable