Puppeteer Keyboard.sendCharacter() 深入解析：无按键语义的字符注入与多协议实现

Keyboard.sendCharacter(char) 是 Puppeteer 中用于向页面逐字符注入文本的底层 API：它直接触发 keypress 与 input 事件，却不产生 keydown/keyup，因此不受修饰键（如 Shift）影响，是输入中文等 IME 文本与自定义合成文本的首选方案。本文基于本仓库（puppeteer1/puppeteer）中该 API 的抽象定义、Chrome（CDP）与 Firefox（WebDriver BiDi）两套实现及端到端测试，带你完整理解它的行为边界、协议底层与实战用法，读完即可在真实爬虫与自动化测试场景中正确选择 sendCharacter 而非 type 或 press。

一、方法签名与调用形态

Keyboard 是 Puppeteer 提供的虚拟键盘管理类，sendCharacter 在其中被声明为抽象方法（api/Input.ts 中声明的 Keyboard 抽象类）：

class Keyboard {
  abstract sendCharacter(char: string): Promise<void>;
}

方法说明（见 docs/api/puppeteer.keyboard.sendcharacter.md）为：Dispatches a keypress and input event. This does not send a keydown or keyup event. 即它只触发“按键产生字符输入”的那一半事件语义。

参数与返回值

项	内容
参数 char	string。要注入到页面中的单个字符（Character to send into the page）。
返回值	Promise<void>，字符插入完成后 resolve。

由于是 abstract 抽象方法，实际协议行为由具体连接实现提供（见下文第三节）。同时，该类的构造函数在源码中被标记为 internal（见 Keyboard 类文档），第三方代码不应直接构造或继承，所有操作均通过 page.keyboard.sendCharacter(...) 访问。

最小调用示例

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com'); // 打开目标页面
await page.focus('textarea');           // 先把焦点落到可输入元素上

await page.keyboard.sendCharacter('嗨'); // 向页面插入一个中文字符
await browser.close();

调用前务必先让目标元素获得焦点（page.focus() 或 elementHandle.focus()），因为 sendCharacter 是把文本“注入到当前聚焦位置”，与真实键盘的击键路径一致。

二、关键行为边界：没有 keydown/keyup，也不受修饰键影响

该 API 与 Keyboard.down/up/press/type 最大的差异在于事件模型：

1. 只派发 keypress 与 input：字符进入可编辑区域并触发输入事件，但页面上的 keydown、keyup 监听器不会被调用；
2. 修饰键不生效（Modifier keys DO NOT affect）：即使此前调用过 keyboard.down('Shift') 并一直按住，sendCharacter('a') 也只会插入小写 a，不会变成大写 A。同理，Ctrl、Alt、Meta 的组合行为也不会被模拟。

这与 Keyboard.down/press（修饰键生效，例如按住 Shift 后再按 KeyA 会得到大写文本，见 puppeteer.keyboard.down.md 与 puppeteer.keyboard.press.md）形成鲜明对比，也和 Keyboard.type 保持一致（type 同样不受修饰键影响，见 puppeteer.keyboard.type.md）。

这一设计带来的实际收益：绕过物理键位映射，直接插入“不存在于标准键盘布局”的字符。测试 page.keyboard.sendCharacter('嗨') 或小语种字符时，无需关心该字符对应的虚拟键码（keyCode/code），也就规避了 CDP Input.dispatchKeyEvent 对非 ASCII 字符映射的复杂性。

三、源码实现：CDP 与 WebDriver BiDi 的两条通道

当前仓库同时维护 Chrome（CDP）与 Firefox（BiDi）两条自动化通道，sendCharacter 在两者中的实现路径完全不同，值得分别理解。

CDP（Chrome）实现：直接调用 Input.insertText

在 packages/puppeteer-core/src/cdp/Input.ts 中实现非常简单：

override async sendCharacter(char: string): Promise<void> {
  await this.#client.send('Input.insertText', {text: char});
}

Input.insertText 是 DevTools 协议提供的“插入文本”命令，它绕过按键事件，直接把 text 插入到当前焦点所在的编辑区域，因此天然不会产生 keydown/keyup，这也正是该 API 文档描述与之一致的原因。

更值得注意的是 sendCharacter 在 CDP type() 中的内部分工（cdp/Input.ts#L177-L194）：

override async type(text: string, options: Readonly<KeyboardTypeOptions> = {}) {
  const delay = options.delay || undefined;
  for (const char of text) {
    if (this.charIsKey(char)) {
      await this.press(char, {delay});      // 能映射成物理键 → 走 press（完整 keydown/press/up）
    } else {
      if (delay) {
        await new Promise(f => setTimeout(f, delay));
      }
      await this.sendCharacter(char);       // 无法映射的字符 → 走 insertText
    }
  }
}

也就是说，当你在 Chrome 上调用 keyboard.type('hello，世界') 时，ASCII 字母会通过 press 派发完整按键事件，而标点与 CJK 字符会静默地落到 sendCharacter → Input.insertText 通道上。由此可见 sendCharacter 在整个输入链路中承担着“物理按键映射的兜底层”角色。

WebDriver BiDi（Firefox）实现：execCommand 注入，且严格限制单字符

在 packages/puppeteer-core/src/bidi/Input.ts 中：

override async sendCharacter(char: string): Promise<void> {
  // Measures the number of code points rather than UTF-16 code units.
  if ([...char].length > 1) {
    throw new Error('Cannot send more than 1 character.');
  }
  const frame = await this.#page.focusedFrame();
  await frame.isolatedRealm().evaluate(async char => {
    document.execCommand('insertText', false, char);
  }, char);
}

两个关键细节：

• 最多 1 个字符：BiDi 实现通过展开运算符 [...char].length 统计的是 Unicode 码点数量而非 UTF-16 单元数，因此传入单个 emoji（可能占 2 个 UTF-16 单元）是允许的；而 'ab' 这类多字符字符串会直接抛出 Error('Cannot send more than 1 character.')。CDP 实现没有这个限制，但从语义一致性出发，调用方仍应遵守“一次一个字符”的约定。
• 插入方式不同：它定位当前聚焦的 frame，并在其 isolated realm 内执行 document.execCommand('insertText', false, char)，实现“在当前插入点插入文本并触发 input 事件”的等效行为，同时依然不产生 keydown/keyup。

四、端到端测试验证：只触发 input、绝无 keydown

本仓库的测试给出了上述行为最直接的证据。test/src/keyboard.test.ts#L133-L179 中 should send a character with sendCharacter 用例：

1. 打开 input/textarea.html，聚焦 textarea；
2. 在页面注册捕获阶段的 input 与 keydown 事件监听器并计数；
3. 执行 await page.keyboard.sendCharacter('嗨')，随后断言 textarea 值为 '嗨'、inputs === 1、keyDowns === 0；
4. 再执行 await page.keyboard.sendCharacter('a')，断言值为 '嗨a'、inputs === 2、keyDowns 仍为 0。

该用例确认：字符被成功插入、每字符恰好触发一次 input 事件、全程零次 keydown。同文件 L180 起 的 should send a character with sendCharacter in iframe 用例进一步验证了嵌套 <iframe> 场景下同样成立，证明文本会被注入到当前聚焦的 frame（而非主 frame），与 BiDi 实现中“定位 focusedFrame”的逻辑一致。

五、与 type / press / down / up 的取舍对比

API	产生的事件	受修饰键影响	适用场景
sendCharacter(char)	keypress + input	否	注入中文、emoji、小语种等无物理键位的字符，或需要“不触发 keydown 监听器”的自动化场景
type(text, {delay})	逐字符 keydown/keypress/input/keyup（无法映射字符走 sendCharacter）	否	输入一段普通文本；可设置 delay 模拟真人打字节奏
press(key, options)	keydown + keyup（必要时含 keypress/input）	是（Shift 生效）	单个按键或快捷键，如 ArrowLeft、Enter
down / up	仅 keydown / 仅 keyup	是（按住修饰键）	长按、组合键（如按住 Shift 做选区删除）

选型建议：想让页面代码完整看到“按下→输入→抬起”的全过程，用 type 或 press；只想让值“落进”输入框并触发表单绑定（input/change）而不关心按键序列，或者要输入键盘映射表之外的字符，就用 sendCharacter。若要模拟真实用户按住 Shift 输入大写字母，sendCharacter 无法胜任（详见其 Remarks），应改用 down('Shift') + press('KeyA') + up('Shift') 组合。

六、实践注意事项

• 一次只传一个字符：BiDi 通道会强制校验（多码点直接抛错）；若需批量插入，可自行 for...of 循环调用，或直接改用 keyboard.type()（其内部已做好 ASCII 与特殊字符的分流）。
• 确保焦点存在：文本会注入到当前聚焦元素/当前聚焦 frame。调用前建议使用 page.focus(selector)、frame.focus(selector) 或元素句柄的 focus()。
• 输入框校验场景：由于不经过物理键位模拟，它非常适合“验证输入事件逻辑（value 变化、maxlength 截断、防抖搜索触发）”之类的测试；而针对监听 keydown（如快捷键、阻止默认行为）的逻辑，sendCharacter 无法触达，请使用 press。
• 跨浏览器一致性：Chrome 走 Input.insertText，Firefox 走 document.execCommand('insertText')，最终在可编辑元素上的效果等价；但两者内部机制不同，跨浏览器测试时不要把“内部实现”当作“页面可见行为”的保证。
• 它是抽象 API 族的一份子：Keyboard 还提供 down/up/press/type 等高级操作，各方法行为差异与跨端实现可对照 docs/api/puppeteer.keyboard.md 与 Keyboard 类抽象定义 继续阅读。

综上，sendCharacter 是 Puppeteer 键盘 API 中最“接近 IME 输入法”的一层：它不关心键码、不受修饰键左右，只负责把给定的字符可靠地注入页面编辑区域。理解了它在 CDP 与 BiDi 两套协议下的实现差异和与 type 的分流关系，你就能在文本输入自动化的方案选型中做出最贴合场景的判断。