Puppeteer ElementHandle.dragOver 解析：dragover 事件的底层派发机制与新拖放流程

本篇围绕 Puppeteer API 文档中的 ElementHandle.dragOver() 方法展开：它如何把一个 dragover 事件精确派发到指定元素、参数 Protocol.Input.DragData 的默认值从何而来，以及该方法为何被官方标记为废弃。读完你将掌握 dragOver 从 API 层到 CDP 协议层的完整调用链、官方推荐的新拖放（drag-and-drop）替代方案，并能借助仓库自带的测试与测试页面自行验证整条事件流。

API 签名与参数

按官方 API 文档 puppeteer.elementhandle.dragover.md，方法签名如下：

class ElementHandle {
  dragOver(
    this: ElementHandle<Element>,
    data?: Protocol.Input.DragData,
  ): Promise<void>;
}

参数	类型	说明
this	ElementHandle<Element>	调用该方法的元素句柄，dragover 事件将派发到该元素的中心点
data	Protocol.Input.DragData	（可选）拖放数据，包含拖拽项列表与拖拽操作掩码

返回值：Promise<void>，事件派发完成后 resolve。

文档开头有一条明确的警告：

Warning: This API is now obsolete. Do not use. dragover will automatically be performed during dragging.

也就是说，官方不再建议手工调用 dragOver，因为在完整拖放流程中 dragover 会被自动派发。这条警告的“底气”就藏在源码里，下面逐层拆解。

源码实现：ElementHandle.dragOver 的三段式流程

ElementHandle.ts 中的实现只有五行核心逻辑：

/**
 * @deprecated Do not use. `dragover` will automatically be performed during dragging.
 */
@throwIfDisposed()
@bindIsolatedHandle
async dragOver(
  this: ElementHandle<Element>,
  data: Protocol.Input.DragData = {items: [], dragOperationsMask: 1},
): Promise<void> {
  const page = this.frame.page();
  await this.scrollIntoViewIfNeeded();
  const target = await this.clickablePoint();
  await page.mouse.dragOver(target, data);
}

从中可以确认三个实现细节：

1. 默认参数值：文档标注 data 为可选，而源码给出的默认值是 {items: [], dragOperationsMask: 1}——即空拖拽项列表加一个允许常规拖放操作的掩码。省略 data 时，派发的就是一个不携带任何拖拽内容、仅用于触发页面 dragover 监听器的事件。
2. 坐标计算：先 scrollIntoViewIfNeeded() 确保元素在视口内，再由 clickablePoint() 计算元素中心点，事件坐标最终指向元素正中央。
3. 装饰器约束：@throwIfDisposed() 保证句柄已销毁时抛错，@bindIsolatedHandle 负责跨执行上下文（isolated world）的正确绑定。

方法本身并不直接与浏览器协议打交道，而是把“点到哪个坐标”交给本句柄算好后，转调 page.mouse.dragOver(target, data)，真正的协议编解码在 Mouse 层完成。

Mouse 层抽象与 CDP 协议实现

api/Input.ts 中，Mouse 抽象类定义了各平台后端必须实现的 dragOver 接口：

/**
 * Dispatches a `dragover` event.
 * @param target - point for emitting `dragover` event
 * @param data - drag data containing items and operations mask
 */
abstract dragOver(
  target: Point,
  data: Protocol.Input.DragData,
): Promise<void>;

注释明确其语义：派发一个 dragover 事件，target 是事件触发点，data 是包含拖拽项与操作掩码的负载。

在 CDP（Chrome DevTools Protocol）后端，cdp/Input.ts 给出了具体落地方式：

override async dragOver(
  target: Point,
  data: Protocol.Input.DragData,
): Promise<void> {
  await this.#client.send('Input.dispatchDragEvent', {
    type: 'dragOver',
    x: target.x,
    y: target.y,
    modifiers: this.#keyboard._modifiers,
    data,
  });
}

关键信息有两点：

• 底层走的是 CDP 命令 Input.dispatchDragEvent，事件类型字符串为 'dragOver'，与 dragEnter、drop 共用同一个命令、仅靠 type 字段区分（见同文件 L496-L533）。
• 请求体中的 modifiers 取自当前键盘状态（this.#keyboard._modifiers），因此拖放过程中按住的控制键等修饰状态会被一并携带到页面事件里。

需要注意的平台边界：在 WebDriver BiDi 后端中，bidi/Input.ts 对 drag、dragOver、dragEnter、drop 全部直接抛出 UnsupportedOperation。也就是说，dragOver 相关的拖放 API 目前仅在 CDP 通道（Chrome）下可用，使用 BiDi 通道时无法调用。

为什么废弃：dragover 在拖放过程中被自动执行

文档警告称 “dragover will automatically be performed during dragging”，这在源码中可以直接验证。cdp/Input.ts 的 Mouse.dragAndDrop 把一整套事件序列串在了一起：

override async dragAndDrop(
  start: Point,
  target: Point,
  options: {delay?: number} = {},
): Promise<void> {
  const {delay = null} = options;
  const data = await this.drag(start, target);   // ① 触发 dragstart，拿到 DragData
  await this.dragEnter(target, data);             // ② 派发 dragenter
  await this.dragOver(target, data);             // ③ 自动派发 dragover
  if (delay) {
    await new Promise(resolve => {
      return setTimeout(resolve, delay);
    });
  }
  await this.drop(target, data);                  // ④ 派发 drop
  await this.up();
}

可以看到：调用一次 page.mouse.dragAndDrop(start, target, {delay}) 后，dragOver 作为第 ③ 步被无条件执行，delay 选项（毫秒）控制 dragover 与 drop 之间的等待时间，默认为 0。既然完整拖放已经内建 dragover，再手工调用 ElementHandle.dragOver 只会造成重复派发，这正是它被标记 obsolete 的原因。

其中第 ① 步的 Mouse.drag 实现也值得留意：它按顺序执行 move(start) → down() → move(target)，并监听 CDP 的 Input.dragIntercepted 事件，浏览器拦截真实拖拽后回传的 event.data 即为 Protocol.Input.DragData。这段数据随后被 dragEnter / dragOver / drop 复用，形成一条数据贯穿整条事件链的完整流程。

推荐的替代方案：新拖放 API 与拦截机制

既然 dragOver 弃用，实际项目中应如何使用拖放？结合 ElementHandle.ts 中同族的 drag、drop、dragAndDrop 方法，仓库实际提供了两条路径。

路径一：元素级 drag + drop（原生 HTML5 拖放事件流）

ElementHandle.drag 负责“开始拖拽并移动”，ElementHandle.drop 负责“落到目标上”。新版 drop 的推荐签名接收一个元素句柄而非原始数据：

// 新签名（推荐）：
async drop(element: ElementHandle<Element>): Promise<void>;
// 旧签名（已废弃）：
async drop(data?: Protocol.Input.DragData): Promise<void>;

其内部实现（L910-L929）为：调用 dataOrElement.drag(this) 完成拖拽移动，复位 page._isDragging 标记，再执行 page.mouse.up() 释放鼠标。典型用法：

const draggable = await page.$('#drag');
const dropzone = await page.$('#drop');
await draggable.drag(dropzone); // 拖拽至目标上方
await dropzone.drop(draggable); // 在目标上完成 drop

在未启用拦截的分支里，drag 会先 hover() 到源元素中心、mouse.down() 按下，再把鼠标移动到目标中心（元素目标则通过 target.hover()），整个过程中浏览器会自然产生 dragstart → dragenter → dragover → drop 序列——这再次印证了 dragover 无需手工触发。

路径二：mouse.dragAndDrop + 拖拽拦截

ElementHandle.dragAndDrop（标注 @deprecated，官方建议改用 ElementHandle.drop）要求前置开启拖拽拦截：

const page = this.frame.page();
assert(
  page.isDragInterceptionEnabled(),
  'Drag Interception is not enabled!',
);
await this.scrollIntoViewIfNeeded();
const startPoint = await this.clickablePoint();
const targetPoint = await target.clickablePoint();
await page.mouse.dragAndDrop(startPoint, targetPoint, options);

拦截开关为 Page.setDragInterception / Page.isDragInterceptionEnabled。不过要注意：这两个方法同样已被标记 @deprecated，官方注释写道 “We no longer support intercepting drag payloads. Use the new drag APIs found on ElementHandle to drag (or just use the Page.mouse)”——即拦截拖拽负载（DragData）的能力正在被新元素级拖放 API 取代。对已有代码，mouse.dragAndDrop 仍是可用的底层入口，但新项目建议优先采用路径一的 drag + drop。

测试验证：用状态码确认整条事件链

仓库自带完整的拖放测试与测试页面，可以直接用来验证 dragOver 在事件序列中的位置。

测试页面 test/assets/input/drag-and-drop.html 监听四个事件，并把状态位追加到 #drag-state 的文本中：dragstart 记 1、dragenter 记 2、dragover 记 3、drop 记 4。

对应测试 test/src/drag-and-drop.test.ts 的断言链条：

it('should emit a dragOver event', async () => {
  // ...
  const data = await draggable.drag({x: 1, y: 1});
  assert(data instanceof Object);
  using dropzone = (await page.$('#drop'))!;
  await dropzone.dragEnter(data);
  await dropzone.dragOver(data);   // 手工派发 dragOver
  expect(await getDragState()).toBe(123); // 1=draft, 2=enter, 3=over
});

it('can be dropped', async () => {
  // ...
  await dropzone.dragEnter(data);
  await dropzone.dragOver(data);
  await dropzone.drop(data);
  expect(await getDragState()).toBe(12334); // 末尾 4 = drop 生效
});

从测试还能读出两个实现事实：

• draggable.drag({x: 1, y: 1}) 的返回值是 Protocol.Input.DragData 对象（测试断言 data.items 长度为 1），与 ElementHandle.drag 在拦截开启时 return await page.mouse.drag(source, target) 的返回路径一致；
• 另一用例（L93-L100）先 page.setDragInterception(true) 再 draggable.dragAndDrop(dropzone)，同样得到状态码 12334，说明拦截路径下的自动 dragOver（对应 Mouse.dragAndDrop 第 ③ 步）与手工派发等价。

使用注意事项

综合文档警告与源码，使用 dragOver 及相关拖放 API 时需注意：

1. 优先使用新 API：dragOver、dragEnter、dragAndDrop 以及基于 setDragInterception 的拦截式拖放均被废弃或建议替换；新的元素级 drop(element) 是官方推荐入口，dragover 事件在拖放过程中会自动派发。
2. 平台限制：Mouse.dragOver 仅在 CDP 后端可用；BiDi 后端对 dragOver 抛出 UnsupportedOperation，跨浏览器方案需改用模拟鼠标事件等替代手段。
3. data 参数语义：省略 data 时默认值为 {items: [], dragOperationsMask: 1}，仅触发监听器而不携带拖拽内容；若需要在 drop 时读取自定义负载，应让数据经由真实 dragstart（dataTransfer.setData）注入，由 drag 返回的 DragData 自动流转。
4. 坐标系：事件派发点为元素 clickablePoint() 计算的中心点，且会先自动滚动元素进入视口；若页面使用 transform 等布局，中心点计算依赖 CDP 的框模型，复杂场景建议用测试页面确认命中区域。

小结

ElementHandle.dragOver 是 Puppeteer 早期“分步手工派发拖放事件”模式的一部分：API 层计算元素中心点，CDP 层 通过 Input.dispatchDragEvent（type: 'dragOver'）把事件连同修饰键与 DragData 注入页面。随着 mouse.dragAndDrop 等组合 API 把 dragenter → dragover → drop 序列自动化，该方法已无单独调用的必要并被标记废弃。新代码应使用元素级 drag + drop 完成拖放；如需理解事件流转细节，可直接运行 test/src/drag-and-drop.test.ts 与 测试页面 中的状态码断言来验证。