Puppeteer ElementHandle.dragEnter() 深度解析：已废弃的底层拖放 API 与新拖放体系

本文围绕 Puppeteer 文档中的 ElementHandle.dragEnter() 展开：先完整解析该 API 的签名、参数与底层 CDP 实现链路，再结合仓库源码与测试用例说明它所处的"旧版拖放拦截"体系是如何工作的、为何被标记为废弃，以及在当前版本中应如何改用 drop/dragAndDrop 等新 API 完成同样的拖放验证任务。

一、API 概览：一个已被废弃的底层方法

ElementHandle.dragEnter() 是 Puppeteer 拖放（Drag and Drop）工具链中的一个底层环节，用于在指定元素上手动派发 dragenter 事件。官方文档在 docs/api/puppeteer.elementhandle.dragenter.md 中明确给出警告：

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

即：该 API 已经废弃，不推荐使用——在新版拖放 API 中，dragenter 会在拖拽过程中被自动执行，开发者无需（也不应该）再手动触发它。

方法签名

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

参数说明

参数	类型	说明
this	ElementHandle<Element>	方法调用所在的元素句柄（即 dragenter 事件的目标元素）
data	Protocol.Input.DragData（可选）	拖拽数据，包含拖拽项（items）与操作掩码（dragOperationsMask）

返回值： Promise<void>。

默认拖拽数据

文档中 data 参数标注为可选。从源码可以确认，当调用方不传 data 时，Puppeteer 会使用默认值 {items: [], dragOperationsMask: 1}（见 ElementHandle.ts），即"空的拖拽项列表 + 允许复制操作"。这一默认值意味着：如果不走拦截流程获取真实的 DragData，手动调用 dragEnter() 派发的事件中并不携带任何实际拖拽内容。

二、实现链路解析：从 ElementHandle 到 CDP 协议

2.1 ElementHandle 层的调用逻辑

dragEnter 的完整实现在 packages/puppeteer-core/src/api/ElementHandle.ts：

/**
 * @deprecated Do not use. `dragenter` will automatically be performed during dragging.
 */
@throwIfDisposed()
@bindIsolatedHandle
async dragEnter(
  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.dragEnter(target, data);
}

从源码结构看，该方法执行了四步：

1. 前置检查：@throwIfDisposed() 装饰器保证元素句柄已被销毁（disposed）时抛出异常；@bindIsolatedHandle 保证调用绑定在正确的隔离上下文中；
2. 滚动定位：scrollIntoViewIfNeeded() 确保目标元素可见；
3. 坐标计算：clickablePoint() 计算元素的可点击中心点坐标，作为 dragenter 事件的落点；
4. 委托给 Mouse：最终调用 page.mouse.dragEnter(target, data)，将"元素级"操作降级为"坐标级"操作。

2.2 Mouse 抽象层

Mouse.dragEnter 的抽象定义位于 packages/puppeteer-core/src/api/Input.ts，其文档注释说明：

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

与同族的 Mouse.dragEnter 文档一致：target 是派发 dragenter 事件的坐标点（Point 类型），data 是包含拖拽项与操作掩码的拖拽数据。

2.3 CDP 层：Input.dispatchDragEvent

CDP（Chrome DevTools Protocol）后端的实现在 packages/puppeteer-core/src/cdp/Input.ts：

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

可以看出，dragEnter 的底层本质是向浏览器发送一条 Input.dispatchDragEvent 命令，事件类型为 dragEnter，并携带坐标、当前键盘修饰键（this.#keyboard._modifiers）和拖拽数据。同文件中的 dragOver（L509-L520）与 drop（L522-L533）结构完全相同，仅 type 字段不同——三者共同构成了旧版手动拖放序列的底层原语。

2.4 浏览器支持边界：BiDi 后端不支持

值得注意的是，在 WebDriver BiDi 后端中，所有手动拖放原语（包括 dragEnter）均不可用。packages/puppeteer-core/src/bidi/Input.ts 中 drag、dragEnter、dragOver、drop、dragAndDrop 的实现全部是：

override dragEnter(): never {
  throw new UnsupportedOperation();
}

从源码结构看，这一整组手动拖放事件派发依赖的是 CDP 特有的 Input.dispatchDragEvent 能力，BiDi 规范中没有等价物。因此 dragEnter 实际上是一个仅 CDP 通道可用的底层 API，这也限制了它的可移植性。

三、旧版拖放拦截体系：dragEnter 的历史用法

dragEnter 存在的语境是 Puppeteer 的旧版"拖放拦截"（drag interception）流程：先开启拦截，通过 drag() 拿到浏览器真实产生的拖拽载荷（DragData），再手动向目标元素依次派发 dragEnter → dragOver → drop。该流程由 Page.setDragInterception 控制（该 API 如今同样被标记为 obsolete），仓库中的旧版测试 test/src/drag-and-drop.test.ts 完整演示了其中"dragEnter"一环：

await page.goto(server.PREFIX + '/input/drag-and-drop.html');
await page.setDragInterception(true);

using draggable = (await page.$('#drag'))!;
const data = await draggable.drag({x: 1, y: 1});  // 拦截拖拽载荷
assert(data instanceof Object);

using dropzone = (await page.$('#drop'))!;
await dropzone.dragEnter(data);   // 在 #drop 上派发 dragenter

expect(await getDragState()).toBe(12);  // 页面状态位标记 dragenter 已触发

这里的关键机制是：开启拦截后，CDP 后端的 drag() 会执行 move → down → move 并挂起等待 Input.dragIntercepted 事件，从浏览器取回真实的 DragData（包含 items 与 dragOperationsMask）后返回。测试随后用这个"真实数据"手动补发 dragEnter，页面测试资产 test/assets/input/drag-and-drop.html 通过位标记（12、123、12334 等）精确断言每个拖放事件是否按序触发——dragEnter 之后状态为 12，再执行 dragOver 变为 123，最后 drop 变为 12334（见 drag-and-drop.test.ts 的后续用例）。

四、为何废弃：dragenter 已在新拖放流程中自动发生

dragEnter 被废弃的根本原因，是新拖放 API 把整条事件序列自动串起来了。CDP 后端的 dragAndDrop 实现（packages/puppeteer-core/src/cdp/Input.ts）清楚展示了这一自动化链路：

override async dragAndDrop(
  start: Point,
  target: Point,
  options: {delay?: number} = {},
): Promise<void> {
  const {delay = null} = options;
  const data = await this.drag(start, target);   // 1. 拖拽并拦截载荷
  await this.dragEnter(target, data);            // 2. 自动派发 dragenter
  await this.dragOver(target, data);             // 3. 自动派发 dragover
  if (delay) {
    await new Promise(resolve => {
      return setTimeout(resolve, delay);
    });
  }
  await this.drop(target, data);                 // 4. 自动派发 drop
  await this.up();                               // 5. 松开鼠标
}

可以看到，dragEnter 在此流程中依然会被调用，但由框架内部自动完成，且使用的是第 1 步拦截到的真实 DragData——这正是文档警告"dragenter will automatically be performed during dragging"的源码依据。

相应地，当前版本推荐的 ElementHandle 级用法是（对应新拖放测试用例 test/src/drag-and-drop.test.ts）：

// 方式一：drop —— 最简洁的"拖过去并放下"
using draggable = await page.$('#drag');
using dropzone = await page.$('#drop');
await dropzone.drop(draggable);          // 触发完整 dragenter/dragover/drop，页面状态 1234

// 方式二：drag + drop 分步
await draggable.drag(dropzone);          // 拖到目标
await dropzone.drop(draggable);

// 方式三：纯鼠标事件手工驱动（不依赖任何拖放拦截）
await draggable.hover();
await page.mouse.down();
await dropzone.hover();                  // 页面已收到 dragstart/dragenter/dragover（状态 123）
await page.mouse.up();                   // 松开即 drop（状态 1234）

从 ElementHandle.drop 的实现 看，当传入参数是另一个 ElementHandle（而非 DragData）时，它内部执行 dataOrElement.drag(this)、复位 page._isDragging 并调用 page.mouse.up()，即"拖过去 + 松手"的完整动作；而传入 DragData 的旧重载则已被标记为 @deprecated No longer supported.。

五、迁移与使用建议

结合文档声明与源码证据，对存量代码给出如下对照：

旧版写法（已废弃）	新版替代
page.setDragInterception(true)	不再需要，新 API 内部自动处理拦截
const data = await src.drag(pt); await target.dragEnter(data)	await target.drop(src)（dragenter 自动发生）
target.dragEnter(data) / target.dragOver(data) / target.drop(data) 手动序列	src.dragAndDrop(target)，或 src.drag(target) + target.drop(src)
需要逐步观察事件序列	用 hover + mouse.down() + up() 手工驱动，页面原生事件按序触发

几点使用注意：

1. 不要在新项目中主动调用 dragEnter：它只在手动复刻旧版拦截序列时才有意义，且默认拖拽数据为空载荷，无法替代真实拖拽内容；
2. 通道限制：整套 CDP 拖放事件派发（drag/dragEnter/dragOver/drop/dragAndDrop）在 BiDi 后端均抛出 UnsupportedOperation，编写跨通道脚本时需考虑这一差异（bidi/Input.ts）；
3. 事件顺序可验证：借助 test/assets/input/drag-and-drop.html 这类"状态位"页面的思路（dragstart=1、dragenter=2、dragover=3、drop=4 按位叠加），可以独立验证每种拖放方式触发了哪些 DOM 事件。

小结

ElementHandle.dragEnter() 是 Puppeteer 旧版拖放拦截体系中负责手动派发 dragenter 事件的底层方法：它在元素句柄层完成定位与坐标换算，经 Page.mouse.dragEnter 最终落到 CDP 的 Input.dispatchDragEvent 命令，且仅在 CDP 通道可用。随着新版 drop/dragAndDrop API 将 dragenter 自动纳入拖放序列，该方法被标记为 obsolete——理解它的存在与废弃，有助于把握 Puppeteer 拖放 API 从"手动拦截 + 手动派发"到"一键自动化"的演进脉络，并为遗留拖放脚本的迁移提供明确的替换路径。