从 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 是该分支的分支。它是一个独立(standalone)指令,提供信号式 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 带有 Event 后缀,因为这两个名称已被 input 占用。
onMoveonMove in [options], (move)通过 [options] 中的 onMove 否决移动仍然有效。(move) output 只能观察:Angular 的 output 无法返回 false。
SortablejsDirectiveSortableDirective所有 input 都是信号式 input,因此读取变成调用(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 · 需要核对的行为差异

这些是重命名之后最容易让人意外的差异。

  • 没有 codemod,对 sortablejs 直接查找替换会破坏较长的属性名。请先替换 sortablejsOptions、sortablejsContainer 和 sortablejsCloneFunction,再替换单独的指令。
  • 选项分三层合并:全局选项,然后是 [options],最后是单独的 input。[options]="{ animation: 150 }" 与 [animation]="0" 同时使用时结果为 0,且没有警告。每个元素只使用一种写法。
  • 不要把放置校验从 options.onMove 挪到 (move) output。output 无法取消移动,所有被禁止的放置都会被接受。
  • 同一元素上 [options] 中的回调和对应的 output 都会执行,绑定到两者的处理函数每个事件会运行两次。每个事件只选一个途径。
  • 宿主元素上的 (change)、(start)、(end)、(add)、(remove)、(update) 等名称现在绑定到指令的 output,而不是 DOM 事件。请把每个现有绑定都当作需要改写的地方,并把原生监听器移到外层包装元素上。
  • 实例在 Angular zone 之外创建,所以指令没有包装的回调(插件回调、setData、store)不会自行触发变更检测。请写入信号,或自己标记视图。
  • 新的 input 没有前缀,因此宿主上像 draggable="false" 这样的静态属性会以字符串 "false" 传给 draggable 选项,结果没有任何元素可拖拽。属性发生冲突时,请把指令放到包装元素上。
  • 键盘排序默认开启:每个条目(或其手柄)都会成为 Tab 停靠点,回车或空格拿起它,方向键移动它。如果不需要,请设置 [keyboardSorting]="false"。

6 · 文档

该指令的完整参考和在线示例见其文档页面: ng-hub-ui-sortable 文档