Sortable.js 必须用 JavaScript 初始化原生 DOM 节点，需确保元素已挂载、添加 ghostClass/chosenClass 样式，并在框架中手动同步状态及正确处理跨容器拖拽事件。
Sortable.js 本身不依赖 HTML，它操作的是 DOM 元素，所以你不能“用 HTML 创建”它——必须通过 JavaScript 初始化。直接写 <div sortable> 或类似属性是无效的。
初始化 Sortable 实例时必须传入真实 DOM 节点
常见错误是传入 document.querySelector 的结果为 null（比如脚本执行太早），或误传字符串、jQuery 对象、React ref 等非原生节点。
- 确保目标容器已挂载：把
new Sortable(...)放在DOMContentLoaded事件里，或放在容器元素之后的<script>中 - 只接受原生
HTMLElement：不能传$('#list')、ref.current（未赋值时）、'#list'字符串 - 示例正确写法：
const el = document.getElementById('my-list');<br>if (el) new Sortable(el, { animation: 150 });
拖拽失效或排序不更新，大概率是忽略了 ghostClass 和 chosenClass 的 CSS
Sortable 默认会添加 sortable-ghost（拖拽中占位）和 sortable-chosen（被选中项）两个 class，但不自带样式。没有它们，视觉反馈丢失，某些浏览器（如 Safari）甚至会因 layout 变化异常导致拖拽中断。
- 至少加这两条规则（可自定义类名，但需同步传入配置）：
.sortable-ghost { opacity: .6; transform: scale(.95); }<br>.sortable-chosen { background: #f0f8ff; } - 若用 Flex/Grid 布局，注意
ghost元素默认是position: absolute，可能脱离文档流——此时要给父容器加position: relative - Grid 场景下，如果子项用
grid-column/grid-row显式定位，拖拽时位置计算会出错；建议仅用display: grid+ 自动轨道
在 React/Vue 等框架中直接操作 DOM 需手动同步状态
Sortable 修改的是 DOM 顺序，但不会触发 React 的 setState 或 Vue 的响应式更新。列表 UI 会变，但后续逻辑（如提交数据、key 冲突）会出问题。
立即学习“前端免费学习笔记（深入）”；
- 必须监听
sort或end事件，并显式更新状态：new Sortable(el, {<br> onEnd: function(evt) {<br> const newIndex = evt.newIndex;<br> const oldIndex = evt.oldIndex;<br> // 更新你的 state 数组：move item from oldIndex → newIndex<br> }<br>}); - React 中避免用索引做
key：拖拽后顺序变了，但 key 没变，会导致组件复用异常；应使用每项唯一、稳定的id字段 - Vue 3 的
ref列表需用toRefs或markRaw包裹容器元素，否则响应式系统可能劫持 Sortable 的 DOM 操作
最常被跳过的一步是：没检查 evt.items 和 evt.from/evt.to 的实际值，就直接按索引重排数组——跨容器拖拽时 oldIndex 和 newIndex 不具备可比性，必须结合 evt.from 和 evt.to 判断来源/目标容器再处理。
