从 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 占用。 |
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 · 需要核对的行为差异
这些是重命名之后最容易让人意外的差异。
- 没有 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 文档