Sortable初始化失败因DOM未就绪，需确保容器挂载；拖拽后数据不同步需监听onEnd或toArray更新数据源；移动端失灵要配置touchStartThreshold、scroll等；与CSS框架冲突需调整容器定位及ghost样式。
Sortable 初始化失败：DOM 元素未就绪就调用 new Sortable()
常见错误是把 new Sortable() 写在 <script></script> 标签里，且放在 顶部——此时列表 DOM 还没加载完，document.querySelector() 返回 null，直接报错 Cannot read property 'addEventListener' of null。
必须确保目标容器已挂载。推荐做法：
- 把脚本放到
前（最简单） - 或包裹在
DOMContentLoaded事件里 - 或用
document.getElementById('list')替代querySelector，避免 CSS 选择器匹配失败却无提示
示例：
<ul id="sortable-list">
<li class="item">苹果</li>
<li class="item">香蕉</li>
</ul>
<script src="https://cdn.jsdelivr.net/npm/sortablejs@1.15.0/Sortable.min.js"></script>
<script>
document.addEventListener('DOMContentLoaded', () => {
new Sortable(document.getElementById('sortable-list'), {
animation: 150,
handle: '.handle', // 可选：仅拖拽手柄区域
ghostClass: 'ghost'
});
});
</script>
拖拽后数据不同步：只改了 DOM，没更新 JS 数据源
Sortable 默认只操作 DOM 节点顺序，Array 类型的数据不会自动重排。如果你用 items = ['苹果', '香蕉'] 渲染列表，拖拽后 items 仍是原顺序，后续提交或渲染会出错。
立即学习“前端免费学习笔记（深入）”；
必须监听排序完成事件并手动同步：
- 用
onEnd钩子获取新顺序索引：evt.oldIndex→evt.newIndex - 更稳妥的是用
toArray()获取当前 DOM 的 ID 列表（需每个<li>有data-id） - 若用框架（如 Vue/React），别直接操作 DOM，应通过响应式数据驱动
示例（纯 HTML + JS）：
<ul id="sortable-list">
<li data-id="1">苹果</li>
<li data-id="2">香蕉</li>
</ul>
<script>
const sortable = new Sortable(document.getElementById('sortable-list'), {
onEnd: function (evt) {
const ids = sortable.toArray(); // 返回 ['1', '2']
console.log('新顺序 ID：', ids);
// 此处发请求或更新 state
}
});
</script>
移动端拖拽失灵或卡顿：缺少 touch 相关配置
默认情况下 Sortable 在 iOS / Android 上可能无法触发拖拽，或手指松开后元素回弹。这不是 bug，而是需要显式启用触摸支持。
关键配置项：
-
forceFallback: false（默认值，但某些安卓 WebView 需设为true强制降级） -
touchStartThreshold: 3（建议设为 1–5，降低手指滑动误判为拖拽的阈值） -
scroll: true（允许拖拽时自动滚动容器） - 确保容器有明确高度，且
overflow-y: auto，否则滚动不生效
移动端完整初始化示例：
new Sortable(el, {
animation: 150,
touchStartThreshold: 3,
scroll: true,
scrollSensitivity: 50,
scrollSpeed: 10,
fallbackTolerance: 5
});
与 CSS 框架（如 Bootstrap）冲突：样式覆盖导致拖拽视觉异常
Bootstrap 的 .list-group-item 或 Tailwind 的 flex 布局常让 <li> 失去块级行为，导致拖拽占位符（ghost）错位、高度塌陷。
核心问题是 Sortable 插入的 .sortable-ghost 和 .sortable-chosen 元素依赖父容器的 display 和 position。
- 给列表容器加
position: relative - 避免对
<li>设置display: inline-flex等非标准块行为 - 用
ghostClass自定义 ghost 样式，强制display: block !important - 如果用 flex 布局，把
Sortable绑定到<div class="d-flex"> 而不是 <code><ul></ul>，并确保子项是<div> <p>容易被忽略的是：当列表为空时，Sortable 无法计算插入点位置——务必保证至少一个子元素存在，或用伪元素占位。</p> </div>
