Puppeteer TouchHandle.end() 方法解析：掌控 `touchend` 事件与多触点手势生命周期

2026-09-07 14:31:13作者：胡唯隽

导读

TouchHandle.end() 是 Puppeteer（JavaScript API for Chrome and Firefox）在模拟多触点输入场景下用于结束某一个特定触摸点的 API：调用它即可为该触摸点派发一次 touchend 事件。本文以 docs/api/puppeteer.touchhandle.end.md 为主体，结合 TouchHandle 接口、Touchscreen 类以及 puppeteer-core 中 CDP 输入通道的真实实现（packages/puppeteer-core/src/cdp/Input.ts），系统讲解触摸生命周期中"结束（end）"这一环的签名、语义、底层原理与实战用法。读完本文，你将能够独立实现捏合缩放、多点拖拽等带明确"抬起阶段"的多点触控自动化测试。

一、先认识 TouchHandle：一次"按住"在 Puppeteer 中的化身

在 Puppeteer 的触摸 API 设计中，TouchHandle 是一个代表单个已开始、仍处于按住状态的触摸点的句柄（handle）。它由 Touchscreen.touchStart(x, y) 创建并返回，把一次触摸从"开始"到"结束"的全部操纵权交给调用者。

在 packages/puppeteer-core/src/api/Input.ts 中，其完整接口定义为：

export interface TouchHandle {
  /**
   * Dispatches a `touchMove` event for this touch.
   */
  move(x: number, y: number): Promise<void>;

  /**
   * Dispatches a `touchend` event for this touch.
   */
  end(): Promise<void>;
}

从源码结构可以清楚看出，一个 TouchHandle 只暴露两个方法：

方法	作用	对应文档
`move(x, y)`	将该触摸点移动/更新到新的 (x, y) 坐标并派发 `touchMove` 事件	puppeteer.touchhandle.move.md
`end()`	结束该触摸点，派发 `touchend` 事件	puppeteer.touchhandle.end.md

这其实就是真实浏览器触摸语义中"一支手指从按下、移动、到抬起"的完整生命周期。之所以要返回一个独立的句柄而非像旧的 touchStart/touchEnd 那样"只管第一个触点"，是为了支持同时按住多个触摸点（多指手势）时的独立控制：每个 touchStart 调用都会产生一个独立句柄，你可以分别对每一个触点调用 move 与 end，而不必关心事件内部究竟派发给了哪根"手指"。

二、TouchHandle.end()：签名与返回语义

在 docs/api/puppeteer.touchhandle.end.md 中，该方法的 API 定义如下：

interface TouchHandle {
  end(): Promise<void>;
}

方法职责： 为当前这个触摸点派发一次 touchend 事件。

参数： 无。与方法签名中带 x、y 两个坐标参数的 move 不同，end() 不需要坐标——结束一个触点时，其位置沿用该触点最后一次已知的坐标（在 CDP 实现中即 TouchPoint 对象内部缓存的当前位置，详见下文第四节的 #touchPoint 字段）。

返回值： Promise<void>。end() 是异步的，调用方需要 await 它以确认 touchend 事件已经投递到目标页面的 CDP 会话。该方法不会返回任何数据，仅在完成事件派发后 resolve。

2.1 从接口语义到浏览器语义：touchend 意味着什么

touchend 是 Touch Events 中标识"触点从触摸表面抬起"的终结事件。在真实移动端交互中它承担着关键职责：

触发元素上的 click 合成（在移动端浏览器中，一次完整的 touchstart → touchend 往往会被合成/派发 click）；
触发 touchend 目标的 :active 样式退出；
在多点手势（pinch、旋转等）中，某个触点抬升会改变其余触点的几何关系，进而触发新的手势阶段。

因此在 Puppeteer 中，只有当某个触摸点的生命周期走完 end() 后，这个触点才算真正"离开屏幕"，页面才能观察到与真实手指抬起一致的 UI 变化。

2.2 相对容易混淆的一组 API：TouchHandle.end() vs Touchscreen.touchEnd()

在阅读 API 文档时容易把这两者搞混，这里特别辨析一下：

TouchHandle.end()（本文主体）：针对指定触摸点结束触摸，作用于调用方手里已有的那一个句柄；
Touchscreen.touchEnd()：针对当前第一个活跃触摸点（first touch that is active）派发 touchend。它内部实现就是"取出第一个活跃触点并调用它的 end()"，相当于没有拿到句柄时的便捷入口。

从 packages/puppeteer-core/src/api/Input.ts 可以看到 touchEnd() 的抽象层实现：

async touchEnd(): Promise<void> {
  const touch = this.touches.shift();
  if (!touch) {
    throw new TouchError('Must start a new Touch first');
  }
  await touch.end();
}

也就是说，Touchscreen 内部维护着一个活跃触点的队列 touches: TouchHandle[]，touchEnd() 通过 shift() 取出并移除队首的触点，再委托给其 end()。而直接持有 TouchHandle 的使用者则可以跳出"先进先出"的限制，以任意顺序结束任意一个触点。

三、一个触摸点的完整生命周期与 end() 的位置

3.1 生命周期全景

综合 puppeteer.touchscreen.touchstart.md 与本文的 end()，一个标准触摸点的生命周期如下：

开始：调用 page.touchscreen.touchStart(x, y)，返回一个 TouchHandle；
（可选）移动：多次调用 touchHandle.move(x, y)，派发 touchMove，模拟滑动或拖拽；
结束：调用 touchHandle.end()，派发 touchend，该触点从活跃列表中移除。

3.2 底层：tap() 与"立即结束"的便捷组合

理解生命周期后，可以回头更透彻地理解 Touchscreen.tap() 的实现——它就是"开始 + 立即结束"的语法糖。在 packages/puppeteer-core/src/api/Input.ts 中：

async tap(x: number, y: number): Promise<void> {
  const touch = await this.touchStart(x, y);
  await touch.end();
}

因此 tap() 的语义（一次 touchstart + 一次 touchend）本质上就是 touchStart 与 end() 的组合，这也再次印证了 end() 是所有"轻点类"交互中不可或缺的收尾动作。相关公开文档见 puppeteer.touchscreen.tap.md。

3.3 使用注意：先开始、后结束

end() 是针对"已开始"触摸点的方法。在没有进行 touchStart 的情况下直接调用面向全屏便捷入口 touchEnd()，会在 Input.ts 中抛出 TouchError('Must start a new Touch first')。同理，对同一个 TouchHandle 重复调用 end() 也属于非预期用法（CDP 侧 CdpTouchHandle 只对 start 做了幂等保护，而对 end 不做重复保护），正确实践是每个触点严格对应一次 start 与一次 end，一次手势完成后就让该句柄引用失效。

四、源码深处：CDP 通道中的 end() 到底做了什么

Puppeteer 支持 Chrome 与 Firefox，触摸输入在不同浏览器协议上有不同实现。从源码结构看，TouchHandle 的协议实现至少存在于两个后端：CDP（Chrome DevTools Protocol）与 WebDriver BiDi，分别位于：

packages/puppeteer-core/src/cdp/Input.ts
packages/puppeteer-core/src/bidi/Input.ts

下面以 CDP 实现（Chrome/Chromium 场景）为例，还原 end() 的底层动作。

4.1 CdpTouchHandle 的状态设计

在 packages/puppeteer-core/src/cdp/Input.ts 中，CdpTouchHandle 实现了 TouchHandle 接口，并持有以下私有字段：

export class CdpTouchHandle implements TouchHandle {
  #started = false;          // 标记该触点是否已完成 touchStart
  #touchScreen: CdpTouchscreen;
  #touchPoint: Protocol.Input.TouchPoint; // 触点当前坐标/压力等信息
  #client: CDPSession;
  #keyboard: CdpKeyboard;     // 用于携带当前键盘修饰键状态
}

其中 #touchPoint 记录的就是该触点最近一次的位置快照。move() 方法会改写 #touchPoint.x/y 后再派发 touchMove；而 end() 派发 touchend 时无需再次修改坐标，直接复用 #touchPoint 即可。

4.2 end() 的实现细节

CdpTouchHandle.end() 的核心实现（packages/puppeteer-core/src/cdp/Input.ts）如下：

async end(): Promise<void> {
  await this.#client.send('Input.dispatchTouchEvent', {
    type: 'touchEnd',
    touchPoints: [this.#touchPoint],
    modifiers: this.#keyboard._modifiers,
  });
  this.#touchScreen.removeHandle(this);
}

一次 end() 调用实际包含两个动作：

向浏览器发送 CDP 命令：调用 CDPSession.send('Input.dispatchTouchEvent', ...)，命令类型为 touchEnd，touchPoints 传入该触点的 TouchPoint，modifiers 携带当时键盘修饰键（Shift/Ctrl/Alt/Meta 等）的状态。这一条命令即对应真实浏览器中一次 touchend 事件的分发。
从活跃队列中移除自己：命令成功后调用所属 CdpTouchscreen 的 removeHandle(this)，将当前句柄从 Touchscreen.touches 数组中剔除（对应 packages/puppeteer-core/src/api/Input.ts 中的 indexOf/splice 逻辑）。这正是第四节 touchEnd() 用 shift() 能取到"下一个"活跃触点的基础——end() 之后该触点不再占用活跃队列，新的触摸点可以无缝衔接。

换句话说，end() 不仅把"手指抬起"这件事通知给页面，还在 Puppeteer 内部完成了该触点的资源回收。二者缺一不可，前者保证页面行为正确，后者保证后续多点触控模拟的队列状态一致。

4.3 touchStart 侧的对应构造

作为对照，CdpTouchscreen.touchStart()（packages/puppeteer-core/src/cdp/Input.ts）会为每个触点分配自增 id，构造 TouchPoint（坐标取整，并给定默认 radiusX/radiusY/force），touchStart 派发成功后把句柄 push 进 touches 数组并返回给调用者。可以说：start() 负责入队，end() 负责出队，这一进一出构成了 Puppeteer 多触点模拟的完整闭环。

五、实战：用 TouchHandle + end() 模拟多指捏合缩放

TouchHandle 面向的核心诉求就是多指手势。以一个典型的"双指捏合缩放"（pinch-to-zoom）为例，展示如何在真实的多指场景下分别控制两个触点并各自调用 end()。

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  // 触摸事件需要启用 --touch-events 相关开关
  args: ['--touch-events=enabled'],
});
const page = await browser.newPage();
await page.goto('https://example.com'); // 换成任意支持 touch 手势的页面

// 双指同时按下（例如一张可缩放的图片两端）
const fingerA = await page.touchscreen.touchStart(120, 200);
const fingerB = await page.touchscreen.touchStart(280, 200);

// 双指向外张开 —— 模拟放大
await fingerA.move(80, 200);
await fingerB.move(320, 200);
await fingerA.move(60, 200);
await fingerB.move(340, 200);

// 手指依次抬起：先抬 A，再抬 B
await fingerA.end();
await fingerB.end();

await browser.close();

这段代码的关键点在于：两个触点各自拥有独立的 TouchHandle，你可以不对称地控制它们。若只想用单指画一条线并抬起，则可简化为：

const touch = await page.touchscreen.touchStart(50, 50);
await touch.move(50, 200); // 垂直滑动
await touch.move(300, 200); // 水平滑动
await touch.end();          // 手指抬起，派发 touchend

在上述单指场景中，若不关心句柄粒度，也可以直接调用 touchStart + touchMove + touchEnd 这套 Touchscreen 便捷 API——它们的终点都收敛到同一套 TouchHandle 实现上。

工程提示： move() 的坐标在 CDP 实现中会被 Math.round 取整（见 CdpTouchHandle.move() 对 #touchPoint 的赋值），因此传入小数坐标时最终派发的事件坐标是对齐到整数像素的；同时受浏览器对 touchmove 事件节流优化影响，并非每一次 move() 都会产生一个真实的 touchmove 事件（详见 puppeteer.touchscreen.touchmove.md 的 remarks）。但 touchend 不受此类节流影响，end() 的语义是确定的：只要完成 await，该触点的抬起事件必然已派发。

六、仓库内测试对 end() 语义的印证

仓库自带测试 test/src/touchscreen.test.ts 为我们提供了 end() 最真实的用法样本，可作为学习与回归验证的参考：

多点触摸、独立抬起的测试（对应测试文件中约 L499-L504 附近的用例）：

const touch1 = await page.touchscreen.touchStart(20, 20);
const touch2 = await page.touchscreen.touchStart(20, 50);
// …… 中间移动逻辑 ……
await touch2.end();
await touch1.end();

这段用例直接印证了本文的核心论点：同时按住两个触点后，可以按照与按下顺序无关的自定义顺序分别调用各自的 end() 来结束触摸，而不必依赖"先进先出"的 Touchscreen 便捷方法。

"最后抬起者"与队列衔接的测试（约 L735-L739）：

const touch1 = await page.touchscreen.touchStart(50, 50);
await page.touchscreen.touchStart(20, 20);
await touch1.end();                    // 先结束较早的 touch1
const touch3 = await page.touchscreen.touchStart(20, 100); // 结束后又能开启新触点

这组用例验证了 end() 之后触点会从活跃队列移除、后续 touchStart 不受影响的资源回收行为。

此外在 touchEnd 便捷方法测试中（约 L907-L911），仓库还专门验证了"对不存在活跃触点的 touchEnd() 会抛错"：

const touch = await page.touchscreen.touchStart(100, 100);
await touch.end();          // 队列已被清空
await page.touchscreen.touchEnd(); // 此时抛 TouchError

与前面 Input.ts 中 touchEnd() 的 shift() + 判空逻辑相互印证。有兴趣深入的同学可以直接在 puppeteer-core 的源码目录（packages/puppeteer-core/src/api/Input.ts 与 packages/puppeteer-core/src/cdp/Input.ts）中跟踪完整实现。

七、关键要点速查

一句话记忆：TouchHandle.end() = 针对该触点派发 touchend 事件，并将其从 Touchscreen 活跃触点队列中移除。
签名：end(): Promise<void>，无参数、无返回值，异步执行、需要 await。
使用前提：该句柄必须来自一次成功的 touchStart()；空队列下使用便捷方法 touchEnd() 会抛出 TouchError。
与 touchEnd() 的区别：end() 结束指定触点；touchEnd() 结束"第一个活跃触点"（内部等价于 touches.shift().end()）。
与 tap() 的关系：tap(x, y) 在源码上等价于 touchStart(x, y) 后立即调用 end()（见 Input.ts）。
底层本质（CDP 路径）：一次 Input.dispatchTouchEvent（type: 'touchEnd'）+ 一次活跃触点出队；实现位于 packages/puppeteer-core/src/cdp/Input.ts。
典型场景：多指手势收尾、双击/轻点类操作的"抬起阶段"、连续手势之间清空触点队列。