JavaScript Element.setPointerCapture 拖拽中怎样接住移出元素后的指针事件

拖拽交互最容易出现的断点是：按下元素后开始移动，指针一旦离开元素，后续 pointermove 就不再稳定地落到原来的拖拽对象上。解决这类问题的关键不是把监听器盲目挂到 document，而是在收到 pointerdown 后，用同一个 pointerId 调用 Element.setPointerCapture()。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/Element/setPointerCapture

指针捕获会把这个指针后续产生的事件重新定向到捕获元素，直到显式调用 releasePointerCapture()，或浏览器在 pointerup、pointercancel 后自动释放。下面按“现象—原因—修复—收尾”的顺序拆开。

先理解指针捕获的生命周期

普通指针事件会根据指针当前所在位置重新做命中测试。拖拽时，指针离开原元素后，事件目标自然可能切换到容器、遮挡层或另一个元素。setPointerCapture(pointerId) 改变的是这个指针的事件路由，而不是把所有指针都锁到同一个元素。

因此，调用时要使用当前事件的 event.pointerId。不要把鼠标、触控笔和多根手指想成一个共享通道；每个活动指针都有自己的编号和状态。

在 pointerdown 中捕获同一个 pointerId

一个可复用的拖拽骨架如下。示例只维护水平位置，重点是事件顺序和清理边界：

const dragItem = document.querySelector('.drag-item');
let dragging = false;
let startX = 0;
let startLeft = 0;

dragItem.addEventListener('pointerdown', (event) => {
  // 记录本次指针的起点，后续只处理同一个 pointerId。
  dragging = true;
  startX = event.clientX;
  startLeft = dragItem.offsetLeft;

  // 捕获必须绑定当前事件的 pointerId，而不是写死某个编号。
  dragItem.setPointerCapture(event.pointerId);
});

dragItem.addEventListener('pointermove', (event) => {
  // 没有进入拖拽状态时忽略普通移动，避免误改布局。
  if (!dragging) return;

  const nextLeft = startLeft + event.clientX - startX;
  dragItem.style.left = `${nextLeft}px`;
});

function finishDrag(event) {
  // pointerup 和 pointercancel 都要走同一条清理路径。
  if (!dragging) return;
  dragging = false;

  // 释放前先确认仍由当前元素捕获这个指针，避免产生无关异常。
  if (dragItem.hasPointerCapture(event.pointerId)) {
    dragItem.releasePointerCapture(event.pointerId);
  }
}

dragItem.addEventListener('pointerup', finishDrag);
dragItem.addEventListener('pointercancel', finishDrag);

这里的核心只有两句：按下时用 event.pointerId 建立捕获，结束时用同一个编号释放。pointermove 可以继续挂在拖拽元素上，因为捕获状态会让它在指针移出元素后仍接收到事件。

为什么移出元素后仍能收到事件

可以把两种行为放在一起看：没有捕获时，事件目标跟着当前位置走；建立捕获后，后续事件先交给捕获元素，再由你的拖拽逻辑决定如何更新位置。捕获只影响指针事件的目标，不会自动替你计算坐标，也不会阻止页面滚动。

这也是为什么“把监听器挂到 document”不是完全等价的替代方案：它能扩大监听范围，却没有表达“这个 pointerId 当前属于哪个拖拽元素”。在多指触控、多个拖拽卡片同时存在时，捕获模型更容易按编号隔离状态。

pointerup、pointercancel 和显式释放怎么配合

正常松开通常走 pointerup；浏览器或系统打断手势时可能走 pointercancel。两条路径都要把业务状态设回未拖拽，清理临时样式或占用的资源。若在拖拽尚未结束前主动交还事件目标，再调用 releasePointerCapture(pointerId)。

function stopDragging(event) {
  // 先结束业务状态，再释放这个 pointerId 的捕获。
  dragging = false;
  dragItem.classList.remove('is-dragging');

  // hasPointerCapture 让重复清理和取消事件更安全。
  if (dragItem.hasPointerCapture(event.pointerId)) {
    dragItem.releasePointerCapture(event.pointerId);
  }
}

dragItem.addEventListener('pointerup', stopDragging);
dragItem.addEventListener('pointercancel', stopDragging);

dragItem.addEventListener('lostpointercapture', () => {
  // 捕获丢失时同步收口，避免界面仍显示“拖拽中”。
  dragging = false;
  dragItem.classList.remove('is-dragging');
});

lostpointercapture 适合作为兜底通知：它告诉你捕获状态已经消失，但不应替代 pointerup 和 pointercancel 的业务处理。若业务还需要知道捕获何时建立，可以监听 gotpointercapture。

触摸拖拽还要处理 touch-action

在触摸设备上，浏览器还要判断这次手势是否用于滚动或平移。元素的 touch-action 会参与这个判断；如果页面把手势交给默认滚动，拖拽可能收到 pointercancel，这不是 setPointerCapture() 失效，而是手势已经被系统接管。

.drag-item {
  /* 允许脚本接管拖拽方向，避免触摸移动被默认滚动抢走。 */
  touch-action: none;
  user-select: none;
}

不要为了让某个按钮可拖拽就全局设置 touch-action: none。应把规则限制在确实承担拖拽的区域，并根据产品是否仍需保留垂直滚动来选择更窄的方向值。

DOM 移动、多指和异常边界

指针捕获依附于元素和具体的指针状态。若拖拽过程中把元素移动到另一个 DOM 位置，按照 Pointer Events 的实践建议，应在 DOM 移动后重新调用 setPointerCapture()，避免捕获关系丢失。多指场景则要为每个 pointerId 单独保存起点，不要用一个全局布尔值掩盖多个手指的生命周期。

还要注意三个常见误区：

• setPointerCapture() 不会把屏幕像素坐标转换成元素坐标，位置计算仍要结合 clientX、滚动偏移或元素变换。
• 捕获不会阻止 pointercancel，触摸滚动、系统手势或设备状态变化仍可能中断拖拽。
• 一个 pointerId 结束后不要继续复用它的旧起点；下一次 pointerdown 应重新建立完整状态。

最后按需求选择事件方案

一句话总结：setPointerCapture() 解决的是“这个 pointerId 后续事件交给谁”，touch-action 解决的是“触摸手势是否被默认行为接管”，而 pointerup、pointercancel 和 lostpointercapture 共同决定拖拽状态怎样可靠收口。

相关问题

setPointerCapture 应该在 pointerdown 还是 pointermove 中调用？

通常在 pointerdown 中调用，因为这时已经确定了要捕获的元素和 pointerId。在移动阶段才捕获会让最初一段拖拽仍受普通命中测试影响。

为什么 pointercancel 后没有收到 pointerup？

pointercancel 表示这次指针交互被浏览器或系统中断，业务不能假设后面一定还有 pointerup。因此两个事件应使用同一套清理逻辑。

监听 document 后还需要 setPointerCapture 吗？

如果只是单个简单拖拽，document 监听也能接住一部分事件；但它不表达具体 pointerId 与拖拽元素的归属。需要多指隔离、组件封装或明确捕获语义时，优先使用指针捕获。