Puppeteer ActionOptions 深度解析：用 AbortSignal 精确控制 Locator 动作的超时与取消

在 Puppeteer 中，Locator 提供了"自动等待 + 自动重试"的页面交互能力，但真实场景往往需要外部介入——用户点击了"取消"按钮、请求需要提前终止、或竞态任务中要抢占执行权。ActionOptions 接口就是为这一需求而设计的动作选项基础类型，它通过唯一的 signal 属性（AbortSignal）为 click、fill、hover、scroll、wait 等所有 Locator 动作提供了统一的取消机制。读完本文，你将理解 ActionOptions 的接口定义与衍生选项类型、signal 在源码中如何被转换为可观测的取消信号并参与超时竞态，以及如何在测试和脚本中编写可中断、可取消的稳健自动化代码。

ActionOptions 接口定义

官方 API 文档页 puppeteer.actionoptions.md 对该接口的完整签名描述为：

export interface ActionOptions

其唯一属性如下（即文档 Properties 表的完整内容）：

Property	Modifiers	Type	Description	Default
signal	optional	AbortSignal	A signal to abort the locator action.（用于中止 Locator 动作的信号）	无默认值

在源码中，该接口定义于 packages/puppeteer-core/src/api/locators/locators.ts：

export interface ActionOptions {
  /**
   * A signal to abort the locator action.
   */
  signal?: AbortSignal;
}

几个值得注意的设计事实：

• 只有一个可选属性。整个接口没有默认值字段，signal 完全可选——不传时动作仅受 Locator 自身超时约束；传入 AbortSignal 后，外部可以随时调用 AbortController.abort() 终止动作。
• 它不是"动作配置"而是"动作生命周期控制"。像"是否等待元素启用""是否滚入视口"等行为开关并不在这里，而是由 Locator 实例方法（setWaitForEnabled、setEnsureElementIsInTheViewport、setWaitForStableBoundingBox、setTimeout 等）配置，见 locators.ts#L200-L273。ActionOptions 的定位非常克制：只管"这次动作能否被外部中止"。

ActionOptions 的衍生选项类型

ActionOptions 作为基础类型，被多个 Locator 动作选项接口继承或组合。同文件中紧随其后的定义（locators.ts#L65-L87）：

/**
 * @public
 */
export type LocatorClickOptions = ClickOptions & ActionOptions;

/**
 * @public
 */
export interface LocatorFillOptions extends ActionOptions {
  /**
   * The number of characters to type before switching to a faster fill-out
   * method.
   *
   * @defaultValue `100`
   */
  typingThreshold?: number;
}

/**
 * @public
 */
export interface LocatorScrollOptions extends ActionOptions {
  scrollTop?: number;
  scrollLeft?: number;
}

也就是说：

• locator.click(options) 接受 ClickOptions & ActionOptions，除 signal 外还能透传鼠标点击的所有参数；
• locator.fill(value, options) 在 signal 之外额外支持 typingThreshold（默认 100，短于该长度的文本走逐字输入、更长则直接赋值，见 locators.ts#L437 与 locators.ts#L555-L607）；
• locator.scroll(options) 支持 scrollTop / scrollLeft 加 signal（locators.ts#L659-L701）。

哪些 Locator 动作接受 ActionOptions

ActionOptions 作为可选参数贯穿了 Locator 抽象类的核心公共方法，均定义于 locators.ts：

方法	签名要点	说明
click(options?)	LocatorClickOptions	点击元素；内部先检查视口、边界框稳定、元素启用等前置条件，再执行点击
fill(value, options?)	LocatorFillOptions	根据运行时元素类型选择填写策略（checkbox/radio/select/contenteditable/文本输入），支持 typingThreshold
hover(options?)	ActionOptions	鼠标悬停；只检查视口与稳定边界框，不检查 disabled 状态
scroll(options?)	LocatorScrollOptions	对元素执行 scrollTop / scrollLeft 赋值
waitHandle(options?)	ActionOptions	等待 Locator 解析出元素句柄
wait(options?)	ActionOptions	等待并取回元素的 JSON 可序列化值

此外，抽象方法 _wait(options?: Readonly<ActionOptions>)（locators.ts#L711）要求每个具体 Locator 子类（NodeLocator、FunctionLocator、FilteredLocator、MappedLocator、RaceLocator）都把 signal 透传给底层的 waitForSelector / waitForFunction / 谓词求值，保证取消能力在整条等待链上端到端生效。例如 NodeLocator._wait 将 signal 传入 waitForSelector（locators.ts#L1133-L1154），FunctionLocator._wait 则传入 waitForFunction（locators.ts#L873-L883）。

信号如何生效：从 AbortSignal 到可观测的取消流

signal 参数并不是简单地"传一下"，源码中有两个关键环节让它真正参与执行流。

1. fromAbortSignal：把事件型信号转成"抛错源"

工具函数 fromAbortSignal 定义于 packages/puppeteer-core/src/common/util.ts#L440-L456：

export function fromAbortSignal(
  signal?: AbortSignal,
  cause?: Error,
): Observable<never> {
  return signal
    ? fromEvent(signal, 'abort').pipe(
        map(() => {
          if (signal.reason instanceof Error) {
            signal.reason.cause = cause;
            throw signal.reason;
          }

          throw new Error(signal.reason, {cause});
        }),
      )
    : NEVER;
}

可以观察到两点实现细节：

• 如果 signal 未提供，返回永不发射的 NEVER 流，等于该分支不参与竞态；
• 一旦 abort 事件触发，它会抛出 signal.reason（保留你 abort(reason) 时传入的自定义原因，并补上 cause 字段指向是哪个 Locator 动作发起的竞态），否则包装成 new Error(signal.reason, {cause})。这就是测试中能够断言错误信息包含 /aborted/ 的来源。

2. retryAndRaceWithSignalAndTimer：取消与超时的竞速

每个动作（#click、#fill、#hover、#scroll 等）的 Observable 管道末端都会接上同一个算子工厂（locators.ts#L179-L192）：

retryAndRaceWithSignalAndTimer: <T>(
  signal?: AbortSignal,
  cause?: Error,
): OperatorFunction<T, T> => {
  const candidates = [];
  if (signal) {
    candidates.push(fromAbortSignal(signal, cause));
  }
  candidates.push(timeout(this._timeout, cause));
  return pipe(
    retry({delay: RETRY_DELAY}),
    raceWith<T, never[]>(...candidates),
  );
},

由此可以完整描述动作的执行模型：

1. 定位失败（元素未出现、未可见、边界框不稳定、处于 disabled 状态等）时，管道内以 RETRY_DELAY（100ms，见 locators.ts#L1220）为间隔不断重试；
2. 重试流与两个"候选方"竞速：你传入的 AbortSignal（如有）和 Locator 自身的 timeout（默认取 Page.getDefaultTimeout()，未设置时回落到 30000ms，见字段初始化 locators.ts#L158 与 setTimeout 文档 locators.ts#L200-L212）；
3. 谁先"发射"，谁就决定结局：动作成功则正常返回；超时则抛 TimeoutError；signal 先 abort 则按 reason 抛错。

换句话说，signal 提供的是主动取消，timeout 提供的是被动兜底，两者通过 raceWith 组合在同一个竞速结构里，且 signal 随时可以比超时更早触发。

实战用法

用户侧取消一个正在重试的点击

这是最典型的场景：动作卡在等待（例如等待隐藏的按钮变为可见），外部 UI 允许用户放弃：

const controller = new AbortController();
const clickPromise = page.locator('button').click({
  signal: controller.signal,
});

// 例如挂到一个"取消"按钮上
cancelBtn.addEventListener('click', () => controller.abort('User cancelled'));

try {
  await clickPromise;
} catch (err) {
  // 被 abort 时，错误信息即你传入 abort 的 reason（含 cause 指向 'Locator.click'）
  console.error('action failed:', err);
}

取消 Locator.race 竞态任务

Locator.race 让多个 Locator 并行定位、只让最先就绪者执行动作；signal 同样作用于整体竞态（locators.ts#L1202-L1208 中 RaceLocator._wait 把同一份 options 分发给每个候选 Locator）：

const controller = new AbortController();

const result = Locator.race([
  page.locator('.modal #close-btn'),
  page.locator('.banner #close-btn'),
])
  .setTimeout(5000)
  .click({signal: controller.signal});

setTimeout(() => controller.abort('superseded by new navigation'), 2000);

与超时组合使用

不传 signal 时行为不变，完全由 setTimeout 决定上限（传 0 可禁用超时）；传了 signal 后，实际生效的上限是"超时"与"abort 时刻"两者中更早者。这一组合行为有仓库测试直接验证。

测试证据：官方测试如何验证取消行为

仓库测试 test/src/locator.test.ts 中有两处对 signal 取消行为的直接断言：

• click 场景（locator.test.ts#L331-L337）：页面放置一个 display: none 的按钮（点击必然进入重试等待），使用 sinon 假时钟推进 2 秒后调用 abortController.abort()，断言 page.locator('button').click({signal}) 的 Promise 以 /aborted/ 结尾的错误被 reject；
• race 场景（locator.test.ts#L791-L802）：对 Locator.race([...]).setTimeout(5000).click({signal}) 做同样的中断，验证竞态 Locator 同样遵守 signal。

两处测试共同确认：取消是即时生效的（不等重试间隔或超时窗口），且 reject 原因与 signal 的 abort 语义一致。

小结

• ActionOptions 是 Locator 动作的取消选项接口，唯一属性 signal?: AbortSignal，定义见 locators.ts#L59-L64；
• 它被 LocatorClickOptions、LocatorFillOptions、LocatorScrollOptions 继承/组合，覆盖 click、fill、hover、scroll、wait、waitHandle 全部动作，并经由各子类 _wait 透传到底层等待 API；
• 底层由 util.ts 中的 fromAbortSignal 将 abort 事件转换为携带 reason/cause 的抛错流，再与超时流 raceWith 竞速；
• 行为契约由 test/src/locator.test.ts 中的 "can be aborted" 系列用例固化：abort 即刻中断重试，错误信息保留 abort 原因。

对于编写长生命周期自动化脚本（等待网络、等待用户输入、驱动复杂表单）的开发者来说，ActionOptions.signal 是让"Locator 的自动重试"不变成"不可控的无限等待"的关键逃生舱。