API 参考

这里是 sortable 的完整契约：你可以绑定、监听、投影和设置主题的一切，都集中在一处。接入你需要的部分，自定义你想要的样式——它是 standalone 的，且对 signal 友好。

输入

通过 39 个输入项精细调校 sortable。像绑定任意 Angular @Input 一样绑定它们。

名称	类型	默认值	描述
`hubSortable`	`SortableData<T> \| SortableBindings`	—	绑定到可排序容器的数据：普通数组、响应式 `FormArray` 或可写信号。会与拖放操作保持同步。该输入是可选的：仅写 `hubSortable` 属性也能启用该指令，此时输出会报告每一次移动而不改动任何数据。
`options`	`Options`	—	完整的 SortableJS 选项对象。每个 SortableJS 选项也可以作为独立的 input 直接绑定（例如 `handle`、`animation` 或 `group`）。
`autoUpdateArray`	`boolean`	`true`	为 `true`（默认）时，指令会在每次拖动后自动修改绑定的数组。设为 `false` 可手动控制并自行更新数组。
`cloneFunction`	`(item: T) => T`	—	当分组配置为 `pull: 'clone'` 模式时，用于克隆条目的工厂函数。
`container`	`string`	—	当宿主包裹实际列表时，应成为可排序的嵌套元素的 CSS 选择器。
`keyboardSorting`	`boolean`	`true`	键盘重新排序，默认开启。每个条目都是一个 Tab 停留点：`Enter` 或 `空格` 抓起它，方向键移动它，`Home` 和 `End` 把它送到两端，`Escape` 放回原位。若应用自带键盘操作路径，可设为 `false`。
`keyboardMessages`	`Partial<SortableKeyboardMessages>`	—	替换键盘重新排序通过实时区域播报的语句。未提供的部分保留默认的英文文案。
`group`	`Options['group']`	—	用于连接多个列表并控制哪些列表可以给出或接收条目的分组名称或配置对象。
`sort`	`boolean`	—	启用或禁用列表内条目的重新排序。
`delay`	`number`	—	开始拖拽前需要按住指针的毫秒数。默认为 `0`；在触摸设备上调高该值，短按即为滚动而非拖拽。
`disabled`	`boolean`	—	在不移除指令的情况下禁用可排序行为。
`draggable`	`string`	—	限制哪些子元素可被拖动的 CSS 选择器。
`handle`	`string`	—	每个条目内启动拖动的元素的 CSS 选择器，其余部分仍可交互。
`animation`	`number`	—	重新排序动画的持续时间（毫秒）。
`ghostClass`	`string`	—	拖动时显示的占位符所应用的 CSS 类。
`chosenClass`	`string`	—	从被选中到拖拽结束期间应用于该项的 CSS 类。默认为 `sortable-chosen`。
`dragClass`	`string`	—	拖拽过程中跟随指针的元素所应用的 CSS 类。默认为 `sortable-drag`。
`fallbackOnBody`	`boolean`	—	把拖拽预览挂到 `document.body` 而不是列表上，避免被带 `overflow: hidden` 的祖先元素裁切。
`fallbackTolerance`	`number`	—	回退拖拽启动前指针需要移动的像素数。默认为 `0`；调高可避免轻点被当作拖拽。
`fallbackClass`	`string`	—	绕过原生 HTML5 拖放时所用克隆预览元素的 CSS 类。
`fallbackOffset`	`{ x: number; y: number }`	—	回退拖拽预览相对指针的像素偏移。
`forceFallback`	`boolean`	—	不使用浏览器原生的 HTML5 拖放，始终拖动克隆元素，在各浏览器中外观一致。
`filter`	`string \| ((event, target, sortable) => boolean)`	—	标记不可拖动元素的 CSS 选择器（或谓词函数）。
`preventOnFilter`	`boolean`	—	对触发 `filter` 的事件调用 `preventDefault()`。默认为 `true`；当被过滤元素是仍需响应点击的控件时应关闭。
`direction`	`'vertical' \| 'horizontal' \| ((event, target, dragEl) => 'vertical' \| 'horizontal')`	—	列表排列所沿的轴向。未设置时自动判定；网格和会换行的列表请显式指定，自动判定在那里容易出错。
`swapThreshold`	`number`	—	触发交换前指针需覆盖目标项的比例（0 到 1）。默认为 `1`；值越小越早交换。
`invertSwap`	`boolean`	—	始终使用反转的交换区域：交换发生在指针离开某项时，而非进入时。
`invertedSwapThreshold`	`number`	—	交换区域反转时使用的阈值。未设置时沿用 `swapThreshold`。
`removeCloneOnHide`	`boolean`	—	克隆元素隐藏期间将其从 DOM 移除，而不只是隐藏。默认为 `true`。
`ignore`	`string`	—	项内不得触发拖拽的元素的 CSS 选择器，例如输入框或链接。
`touchStartThreshold`	`number`	—	延迟拖拽被取消前手指可移动的像素数，也就是拖拽与滚动之间的余量。
`emptyInsertThreshold`	`number`	—	距离空列表多少像素时把拖拽项插入其中。默认为 `5`；设为 `0` 则指针必须位于列表内。
`dropBubble`	`boolean`	—	允许 drop 事件继续向祖先元素冒泡。
`dragoverBubble`	`boolean`	—	允许 dragover 事件继续向祖先元素冒泡。
`dataIdAttr`	`string`	—	`Sortable.toArray()` 与 `store` 用作各项 id 的 HTML 属性。默认为 `data-id`。
`delayOnTouchOnly`	`boolean`	—	只对触摸输入应用 `delay`，鼠标拖拽仍然立即开始。
`easing`	`string`	—	重排动画的 CSS 缓动函数，例如 `cubic-bezier(1, 0, 0, 1)`。
`setData`	`(dataTransfer: DataTransfer, draggedElement: HTMLElement) => void`	—	拖拽开始时调用，用于写入原生 `DataTransfer`，这是拖拽到页面之外的接入点。
`store`	`{ get: (sortable: Sortable) => string[]; set: (sortable: Sortable) => void }`	—	用于持久化排序并在下次加载时恢复的 `get`/`set` 回调对，以 `dataIdAttr` 为键。

输出

响应 sortable 的行为——有 13 个事件可供你挂接逻辑。

名称	类型	描述
`init`	`Sortable`	在底层 SortableJS 实例创建后触发。
`start`	`SortableEvent`	在拖动操作开始时触发。
`end`	`SortableEvent`	无论结果如何，在拖动操作结束时触发。
`add`	`SortableEvent`	当条目从另一个列表被放入此列表时触发。
`update`	`SortableEvent`	当条目在同一列表内改变位置时触发。
`sortEvent`	`SortableEvent`	每当列表顺序改变时触发（在 `add` 或 `update` 之后）。
`remove`	`SortableEvent`	当条目离开此列表前往另一个列表时触发。
`filterEvent`	`SortableEvent`	当尝试拖动被过滤（不可拖动）的条目时触发。
`change`	`SortableEvent`	当列表因添加或移除操作而改变时触发。
`choose`	`SortableEvent`	当条目被选中（指针按下）时触发。
`unchoose`	`SortableEvent`	当条目未经拖动被释放时触发。
`clone`	`SortableEvent`	在克隆模式下克隆条目时触发。
`move`	`SortableMoveEventPayload`	拖动期间持续触发；其返回值可控制是否允许此次移动。

模板

尚未记录任何模板。