Puppeteer Page.focus() 方法深度解析：用选择器精确聚焦页面元素

导读

Page.focus(selector) 是 Puppeteer 中用来把页面焦点切换到某个元素的官方 API：它会先在当前页面中按 selector 查找元素，找到后对该元素执行聚焦，找不到匹配元素则会直接抛错。它是实现"先聚焦再键入文本""按 Tab/Enter 驱动表单交互"等自动化场景的高频基础操作，也是理解 Puppeteer Page -> Frame -> ElementHandle 三级 API 委托链路的最佳入门案例。读完本文你将掌握它的签名与返回值语义、全部支持的选择器语法、底层实现调用链，以及它与 click、type、ElementHandle.focus 等相近 API 的取舍。本文内容以 docs/api/puppeteer.page.focus.md 为骨架，并对照当前仓库源码与测试逐一求证。

方法签名与语义

class Page {
  focus(selector: string): Promise<void>;
}

官方定义（docs/api/puppeteer.page.focus.md）给出的语义非常简洁明确：

• 该方法用 selector 抓取一个元素并对其聚焦；
• 如果页面上没有任何元素匹配 selector，方法会抛出错误；
• 返回的 Promise<void> 在匹配元素成功聚焦后 resolve；若不存在匹配元素，则 promise 被 reject；
• 当有多个元素同时满足同一选择器时，只有第一个元素会被聚焦（与浏览器原生 document.querySelector 的取首个匹配语义一致）。

参数说明：selector 支持的选择器体系

focus 只有一个参数 selector，类型为 string，用于在页面中查询目标元素。根据官方 API 文档，该参数支持 Puppeteer 完整的选择器体系，可分为四层：

选择器能力	说明
CSS 选择器（原生直传）	如 #username、input[type="text"]、.btn.primary 等，可直接原样传入
Puppeteer 专有选择器语法	支持按文本（text）、按无障碍 role 与名称（ARIA）、按 XPath 查询
Shadow DOM 穿透	可将上述查询跨 shadow root 组合使用，命中自定义组件内部的元素
前缀式显式指定类型	通过形如 text/、aria/、xpath/、pierce/ 等前缀，显式声明选择器的解析方式

从源码结构看，这套多类型选择器最终由 packages/puppeteer-core/src/common/QueryHandler.ts 中的 QueryHandler 体系统一承载：不同选择器类型各自实现 querySelectorAll/querySelector 原语，并提供了一套双向兜底逻辑——即"只实现了 querySelectorAll 时自动推导出单元素查询，反之亦然"，从而保证 focus 这类单元素 API 与 $$ 这类多元素 API 共享同一套查询能力。

何时触发"无匹配"错误

focus 不会等待元素出现——它不像 waitForSelector 那样带轮询/超时机制。它执行的是"即时查找、即时聚焦"：若在调用瞬间页面中还不存在匹配元素（例如元素尚未渲染、还在异步加载中），方法将直接失败。这一点决定了它适合配合显式的等待逻辑使用（如先 page.waitForSelector 再 focus，或在内容已确定的表单页面直接聚焦）。

返回值的约定

• 成功：当匹配元素成功聚焦后，返回的 Promise<void> resolve；
• 失败：当没有元素匹配 selector 时，promise 被 reject。

因此调用方可以通过 try/catch 或 await 的失败路径，把"元素不存在"当成一种可捕获的流程分支处理。

Remarks：它本质上是 Frame.focus 的快捷方式

官方文档的 Remarks 明确指出：

Shortcut for page.mainFrame().focus(selector)

也就是说 Page.focus 并不自行实现查找与聚焦逻辑，而是把请求转发给主 frame 的 Frame.focus。完整实现请见 packages/puppeteer-core/src/api/Page.ts：

/**
 * This method fetches an element with `selector` and focuses it. If
 * there's no element matching `selector`, the method throws an error.
 * ...
 * @remarks Shortcut for {@link Frame.focus | page.mainFrame().focus(selector)}.
 */
focus(selector: string): Promise<void> {
  return this.mainFrame().focus(selector);
}

这条注解意味着：所有通过 page.focus(...) 触发的聚焦都发生在主 frame。若你的目标元素位于 iframe / 子 frame 中，则应改用对应 frame 的 Frame.focus。

源码级实现链路：Page -> Frame -> ElementHandle

把 page.focus 展开，可以看到一条清晰的委托链，每一层都只做自己职责范围内的事。

第一层：Frame.focus —— 查询 + 断言

见 packages/puppeteer-core/src/api/Frame.ts：

@throwIfDetached
async focus(selector: string): Promise<void> {
  using handle = await this.$(selector);
  assert(handle, `No element found for selector: ${selector}`);
  await handle.focus();
}

Frame.focus 的职责是"查询元素并聚焦首个匹配项"，源码注释同样声明：若没有匹配元素则抛出异常。实现上分三步：

1. 通过 this.$(selector) 拿到首个匹配的 ElementHandle（等价于浏览器侧的 querySelector 语义，取首个匹配）；
2. assert(handle, ...) 对空结果做硬性校验——这就是文档所述"throws / promise rejected"的真正来源，错误信息为 No element found for selector: ${selector}，便于定位是哪个选择器失败；
3. 调用 handle.focus() 完成聚焦。

值得注意的细节是：方法同时使用了 @throwIfDetached 装饰器和 using 语法。前者保证当 frame 已从页面分离（例如页面已导航离开）时立即抛错，避免对陈旧 frame 操作；后者（using handle = ...）利用 TypeScript 显式资源管理，让临时创建的 ElementHandle 在方法结束（无论成败）时自动 dispose()，无需手动清理，避免句柄泄漏。

第二层：ElementHandle.focus —— 真正的焦点授予

见 packages/puppeteer-core/src/api/ElementHandle.ts：

/**
 * Calls {@link .../HTMLElement/focus | focus} on the element.
 */
@throwIfDisposed()
@bindIsolatedHandle
async focus(): Promise<void> {
  await this.evaluate(element => {
    if (!(element instanceof HTMLElement)) {
      throw new Error('Cannot focus non-HTMLElement');
    }
    return element.focus();
  });
}

ElementHandle.focus 通过 evaluate 把一段函数注入页面执行：

• 先做类型检查：只有 HTMLElement 才能接收焦点，若目标是 SVGElement、HTMLDocument 等非 HTMLElement 节点，会抛出 Cannot focus non-HTMLElement；
• 最终调用的是浏览器原生 element.focus()（对应 MDN 的 HTMLElement.focus()），也就是让页面真正产生焦点效果——包括触发该元素的 focus 事件、让 document.activeElement 指向该元素等标准浏览器行为。

小结：一条调用链对应三条文档

page.focus(selector) 等价于 page.mainFrame().focus(selector) 等价于"在首帧内查找元素再 handle.focus()"。三者分别对应仓库中的三份 API 文档：

• docs/api/puppeteer.page.focus.md
• docs/api/puppeteer.frame.focus.md
• docs/api/puppeteer.elementhandle.focus.md

实测用法与测试佐证

在仓库测试中，page.focus 最典型的用途是"聚焦输入区后紧接着用键盘键入内容"。例如 test/src/keyboard.test.ts 与 test/src/mouse.test.ts 中反复出现如下模式：

await page.focus('textarea');
await page.keyboard.type('...'); // 聚焦后向 textarea 键入文本

page.focus 还会出现在需要"先聚焦、再模拟按键"的场景（如快捷键、Tab 切换、回车提交表单），典型引用散见于 test/src/click.test.ts、test/src/accessibility.test.ts 等文件中，例如 await page.focus('[placeholder="Empty input"]')。

一个最小可运行的完整示例（README 级别的用法）：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setContent('<input id="name"><button>Submit</button>');

await page.focus('#name');            // 聚焦输入框（CSS 选择器直传）
await page.keyboard.type('Ada');      // 键入内容
await page.keyboard.press('Tab');     // 焦点顺移到下一个可聚焦元素
await page.keyboard.press('Enter');   // 触发按钮

await browser.close();

聚焦失败的错误处理

当选择器匹配不到任何元素时，promise 会 reject。通常建议配合显式等待使用：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

// 元素可能是异步渲染的：先等待出现，再聚焦
await page.waitForSelector('#username');
await page.focus('#username');
await page.keyboard.type('hello');

// 若不等待直接聚焦，元素不存在时会抛出：
//   No element found for selector: #username
await browser.close();

与相近 API 的区分

focus 看似与 click、hover、type 同族，但行为差异明显，容易踩坑：

API	是否滚动进视口	是否派发鼠标事件	额外行为	实现位置
page.focus	否	否	仅调用原生 element.focus()	委托 mainFrame().focus（Page.ts）
page.click	是（内部 scrollIntoViewIfNeeded）	是	计算可点击点并派发 mouse 事件序列	委托 mainFrame().click
page.hover	是	是（mouse 移动到元素中心）	—	委托 mainFrame().hover
page.type	否（纯键盘）	否	逐个字符派发 keydown/input/keyup	需要先保证目标已聚焦
page.focus + page.type	否	否	组合后等价"聚焦并键入"	—

从源码对比看（Frame.ts 中 click 与 focus 相邻实现），click 会先 scrollIntoViewIfNeeded 并派发完整鼠标事件，而 focus 不做滚动、不产生鼠标事件，只把"键盘焦点的归属"切到目标元素上。因此：

• 需要键盘事件输入对象（文本域、输入框）→ 用 focus；
• 需要视觉上先滚动到目标再模拟点击→ 用 click；
• 需要逐个字符键入且目标已聚焦 → 可直接 page.type(selector, text) 一步到位，此时内部等价于 focus + 键入的组合。

补充：Frame 层与 ElementHandle 层的对等 API

如果已经持有一个 ElementHandle（例如通过 page.$ 拿到），可直接调用 handle.focus()，省去二次查询的开销。若目标在 iframe 内，应使用对应 frame.focus(...)。三者底层最终都落在同一个原生 element.focus() 调用上，区别只在于"由谁、以什么方式找到元素"。

关键结论速查

• 签名：page.focus(selector: string): Promise<void>，只接受一个字符串参数；
• 行为：取首个匹配元素聚焦；无匹配 → 抛错 / promise reject；多个匹配 → 聚焦第一个；
• 本质：page.mainFrame().focus(selector) 的快捷方式，作用于主 frame；
• 不等待：元素不存在时立即失败，需配合 waitForSelector 等显式等待；
• 底层：Frame.focus 经 this.$(selector) 查询并 assert 非空，再调用 ElementHandle.focus → 页面内原生 element.focus()，且全程通过 using 自动释放临时句柄；
• 适用范围：键盘交互（先聚焦后键入、按键提交表单、无障碍流程）的首选 API；HTML 结构或虚拟 DOM 渲染会影响可聚焦性时，聚焦逻辑仍遵循页面内原生 HTMLElement.focus() 的规则。

如需进一步阅读，可在仓库中对照 Page.focus 官方 API 文档、Frame.focus 文档、ElementHandle.focus 文档 以及核心实现 Page.ts、Frame.ts、ElementHandle.ts 追本溯源。