Electron InputEvent 对象详解sendInputEvent 合成输入事件的完整参考与源码剖析【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron本文以 Electron 的 InputEvent 对象 为核心完整梳理type与modifiers两个字段的全部取值并结合 KeyboardInputEvent、MouseInputEvent、MouseWheelInputEvent 三个子类讲清如何通过webContents.sendInputEvent()向页面注入键盘、鼠标与滚轮事件。文末进一步深入到 C 分发实现 与 gin 转换器说明事件解析、修饰键别名映射与轮询相位补偿的底层细节帮助你在自动化测试与页面控制场景中正确构造并发送合成输入事件。一、InputEvent 是什么基类结构与字段全表InputEvent是 Electron 中表示一次输入事件的基础结构体所有具体的输入事件对象键盘、鼠标、滚轮都继承自它。它本身只有两个字段字段类型说明typestring事件类型。可取undefined或下表中列出的 40 个字符串之一modifiersstring[]可选事件的修饰键数组可取 17 个字符串值见下表type字段的全部取值type的值按输入源可分为五组完整枚举如下依据 input-event.md分组取值鼠标事件mouseDown、mouseUp、mouseMove、mouseEnter、mouseLeave、contextMenu、mouseWheel键盘事件rawKeyDown、keyDown、keyUp、char手势滚动/缩放gestureScrollBegin、gestureScrollEnd、gestureScrollUpdate、gestureFlingStart、gestureFlingCancel、gesturePinchBegin、gesturePinchEnd、gesturePinchUpdate手势点按gestureTapDown、gestureShowPress、gestureTap、gestureTapCancel、gestureShortPress、gestureLongPress、gestureLongTap、gestureTwoFingerTap、gestureTapUnconfirmed、gestureDoubleTap触摸与指针touchStart、touchMove、touchEnd、touchCancel、touchScrollStarted、pointerDown、pointerUp、pointerMove、pointerRawUpdate、pointerCancel、pointerCausedUaActionmodifiers字段的全部取值modifiers是一个字符串数组表示事件触发时处于按下/开启状态的修饰键取值含义shiftShift 键control/ctrlCtrl 键两个名称等价altAlt 键meta/command/cmdMeta 键macOS 的 Command三个名称等价iskeypad按键来自小键盘isautorepeat按键处于自动重复状态leftbuttondown/middlebuttondown/rightbuttondown左/中/右鼠标按钮处于按下状态capslock/numlock大写锁定 / 数字锁定开启left/right事件与左/右键相关继承体系三个具体子类InputEvent是纯基类实际传给sendInputEvent的是它的子类。三个子类的文档与基类字段之外的扩展字段如下MouseInputEventextends InputEvent字段类型说明typestring可取mouseDown、mouseUp、mouseEnter、mouseLeave、contextMenu、mouseWheel、mouseMovex/yInteger事件在页面中的坐标buttonstring可选按下的按钮left、middle、rightglobalX/globalYInteger可选全局屏幕坐标movementX/movementYInteger可选相对移动量clickCountInteger可选点击计数KeyboardInputEventextends InputEvent字段类型说明typestring可取rawKeyDown、keyDown、keyUp、charkeyCodestring将作为键盘事件发送的字符只能使用合法的 Accelerator 键码如a、Escape、TabMouseWheelInputEventextends MouseInputEvent字段类型说明typestring只能为mouseWheeldeltaX/deltaYInteger可选滚动增量wheelTicksX/wheelTicksYInteger可选滚轮刻度增量accelerationRatioX/accelerationRatioYInteger可选加速度比hasPreciseScrollingDeltasboolean可选是否为精确滚动增量canScrollboolean可选页面是否可滚动二、实战用法webContents.sendInputEvent()InputEvent结构体的主要消费入口是 webContents.sendInputEvent(inputEvent)const { app, BrowserWindow } require(electron); app.whenReady().then(() { const win new BrowserWindow({ width: 800, height: 600 }); win.focus(); // 关键窗口必须处于聚焦状态sendInputEvent 才能生效 win.loadFile(index.html).then(() { const wc win.webContents; // 键盘按 CtrlShiftZ 组合键 wc.sendInputEvent({ type: keyDown, keyCode: Z, modifiers: [shift, ctrl] }); wc.sendInputEvent({ type: keyUp, keyCode: Z, modifiers: [shift, ctrl] }); // 键盘输入一个字符char 事件直接产生文本 wc.sendInputEvent({ type: char, keyCode: a }); // 鼠标在 (100, 100) 位置模拟一次左键单击 wc.sendInputEvent({ type: mouseDown, button: left, x: 100, y: 100 }); wc.sendInputEvent({ type: mouseUp, button: left, x: 100, y: 100 }); // 滚轮向下滚动 wc.sendInputEvent({ type: mouseWheel, x: 100, y: 100, deltaY: -120 }); }); });要点说明参数类型inputEvent接受 MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent 三种对象之一它们都包含InputEvent基类的type/modifiers字段。聚焦前提官方文档明确提示sendInputEvent()生效要求包含该内容的BrowserWindow处于聚焦状态见 web-contents.md 中的 NOTE。这是使用中最容易踩的坑无头测试或隐藏窗口场景下需先focus()。keyCode 的合法性KeyboardInputEvent.keyCode必须使用合法的 Accelerator 键码如A、Escape、Tab否则事件构造会失败。webview 标签页同样支持webview.sendInputEvent(event)直接转发到webContents.sendInputEvent。sendInputEvent在 webview 同步方法白名单中被归类为异步方法见 web-view-methods.ts。三、源码剖析事件是如何被解析与分发的3.1 type 字符串 → blink 枚举的转换类型解析发生在 blink_converter.ccConverterblink::WebInputEvent::Type::FromV8通过BLINK_EVENT_TYPES()宏将 JS 侧的type字符串逐个映射到blink::WebInputEvent::Type枚举如mouseDown→kMouseDown、keyDown→kKeyDown。两个值得注意的实现细节匹配不区分大小写宏内使用base::EqualsCaseInsensitiveASCII比较因此Keydown与keyDown等价。枚举覆盖面比 API 更大宏表包含了上文第一组表格中的全部 40 个类型含 gesture、touch、pointer 系列即所有type取值都能被解析解析器本身不会报错。随后 GetWebInputEventType 从事件对象中取出type字段用于分发决策Converterblink::WebInputEvent::FromV8 再把modifiers数组按位或合并为blink::WebInputEvent::Modifiers位掩码并由 C 侧自动填充时间戳base::TimeTicks::Now()JS 调用者无需也不能指定时间戳。3.2 modifiers 的名称规范与别名映射修饰键的字符串名与位掩码的映射定义在 blink_converter.cc分两张表规范表既可传入也可返回shift、control、alt、meta、iskeypad、isautorepeat、leftbuttondown、middlebuttondown、rightbuttondown、capslock、numlock、left、right。别名字典只接受、不返回cmd与command都映射到metactrl映射到control。这说明源码层面ctrl/command/cmd只是为书写习惯提供的别名事件对象序列化回 JS 时只会输出规范名。另外从 ToV8 实现 可以看出键盘/鼠标事件会转换为对应子类对象返回其余类型则退化为只含type与modifiers的普通对象——这也解释了为什么基类文档只定义这两个字段。3.3 SendInputEvent 的三条分发路径C 侧入口是 WebContents::SendInputEvent经 第 5043 行 注册为 JS 方法sendInputEvent。它先解析type再走三条互斥路径路径一鼠标事件IsMouseEventType转换为blink::WebMouseEvent后若WebContents是离屏渲染OSR模式走GetOffScreenRenderWidgetHostView()-SendMouseEvent()否则调用rwh-ForwardMouseEvent()转发给content::RenderWidgetHost。路径二键盘事件IsKeyboardEventType构造input::NativeWebKeyboardEvent其中有一个向后兼容行为如果传入type: keyDownC 侧会静默将其改写为rawKeyDown再转发源码注释标明是为兼容旧用法见 第 3963–3966 行。键盘事件的keyCode字符串还会经KeyboardCodeFromStr解析为ui::KeyboardCode并推导dom_code/dom_key对char与rawKeyDown类型当键码对应的是可打印字符如、空格时会用字符本身而非键名保证页面收到正确的文本blink_converter.cc 第 311–319 行。路径三滚轮事件kMouseWheel这是实现中最精巧的一处。Chromium 期望滚轮事件携带完整的相位phase信息并对此做 DCHECK 校验因此非 OSR 模式下SendInputEvent会做如下处理第 3976–3990 行把用户事件标记为phase kPhaseBegan、dispatch_type kBlocking后转发紧接着再合成一条delta_x/delta_y均为 0 的kPhaseEnded事件dispatch_type kEventNonBlocking以结束本次滚动序列。也就是说JS 侧发一条mouseWheel事件C 侧实际向渲染进程投递了两条事件。这一补偿逻辑是页面滚动行为“一次到位”、不会停在中间相位的原因。兜底三条路径的ConvertFromV8全部失败时会抛出Invalid event object异常第 3996–3997 行。从源码结构看虽然 40 种type都能通过解析但SendInputEvent只实际分发鼠标、键盘、滚轮三类gesture/touch/pointer 类型目前会走到兜底逻辑构造这类对象传入不会得到有效分发。3.4 测试用例中的典型用法仓库测试套件大量使用sendInputEvent驱动页面行为可作为构造事件的真实参照api-web-contents-spec.tsdescribe(sendInputEvent(event))覆盖组合键{ type: keyDown, keyCode: Z, modifiers: [shift, ctrl] }、char输入、以及Space/Plus这类字符键的处理api-browser-window-spec.ts用{ type: keyDown, keyCode: Escape }触发页面行为chromium-spec.ts构造Tab/ShiftTab按键事件验证焦点在窗口与 webview 之间的移动autofill-spec.ts用Tab键切换表单焦点后依次发送char事件填写自动补全字段。这些用例共同印证了实战规律键盘输入通常由keyDowncharkeyUp组合模拟点击由mouseDownmouseUp成对模拟。四、使用注意事项小结窗口必须先聚焦BrowserWindow未聚焦时sendInputEvent可能不产生效果自动化脚本中记得在发送前win.focus()。keyCode 必须合法只能使用 Accelerator 支持的键码字符串char类型用于向可编辑元素输入文本keyDown/keyUp用于触发按键处理逻辑。keyDown会被改写为rawKeyDown从源码看这是刻意的向后兼容行为依赖e.type keydown的页面逻辑需注意区分。修饰键别名ctrl、command、cmd可自由书写但规范名是control、meta事件序列化回 JS 时只会返回规范名。滚轮事件是成对投递的单条mouseWheel输入会在 C 侧展开为kPhaseBegan 合成kPhaseEnded两条事件页面收到的滚动是完整闭环的。坐标语义x/y是页面坐标globalX/globalY是屏幕全局坐标两者不可混用。通过本文你可以完整掌握InputEvent基类与三个子类的全部字段、sendInputEvent的正确调用姿势以及从 JS 对象到blink::WebInputEvent的解析与分发链路从而在 Electron 应用开发与自动化测试中可靠地构造合成输入事件。【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/7 7:56:04 · 阅读 1.2k Electron InputEvent 对象详解：sendInputEvent 合成输入事件的完整参考与源码剖析
Electron InputEvent 对象详解sendInputEvent 合成输入事件的完整参考与源码剖析【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron本文以 Electron 的 InputEvent 对象 为核心完整梳理type与modifiers两个字段的全部取值并结合 KeyboardInputEvent、MouseInputEvent、MouseWheelInputEvent 三个子类讲清如何通过webContents.sendInputEvent()向页面注入键盘、鼠标与滚轮事件。文末进一步深入到 C 分发实现 与 gin 转换器说明事件解析、修饰键别名映射与轮询相位补偿的底层细节帮助你在自动化测试与页面控制场景中正确构造并发送合成输入事件。一、InputEvent 是什么基类结构与字段全表InputEvent是 Electron 中表示一次输入事件的基础结构体所有具体的输入事件对象键盘、鼠标、滚轮都继承自它。它本身只有两个字段字段类型说明typestring事件类型。可取undefined或下表中列出的 40 个字符串之一modifiersstring[]可选事件的修饰键数组可取 17 个字符串值见下表type字段的全部取值type的值按输入源可分为五组完整枚举如下依据 input-event.md分组取值鼠标事件mouseDown、mouseUp、mouseMove、mouseEnter、mouseLeave、contextMenu、mouseWheel键盘事件rawKeyDown、keyDown、keyUp、char手势滚动/缩放gestureScrollBegin、gestureScrollEnd、gestureScrollUpdate、gestureFlingStart、gestureFlingCancel、gesturePinchBegin、gesturePinchEnd、gesturePinchUpdate手势点按gestureTapDown、gestureShowPress、gestureTap、gestureTapCancel、gestureShortPress、gestureLongPress、gestureLongTap、gestureTwoFingerTap、gestureTapUnconfirmed、gestureDoubleTap触摸与指针touchStart、touchMove、touchEnd、touchCancel、touchScrollStarted、pointerDown、pointerUp、pointerMove、pointerRawUpdate、pointerCancel、pointerCausedUaActionmodifiers字段的全部取值modifiers是一个字符串数组表示事件触发时处于按下/开启状态的修饰键取值含义shiftShift 键control/ctrlCtrl 键两个名称等价altAlt 键meta/command/cmdMeta 键macOS 的 Command三个名称等价iskeypad按键来自小键盘isautorepeat按键处于自动重复状态leftbuttondown/middlebuttondown/rightbuttondown左/中/右鼠标按钮处于按下状态capslock/numlock大写锁定 / 数字锁定开启left/right事件与左/右键相关继承体系三个具体子类InputEvent是纯基类实际传给sendInputEvent的是它的子类。三个子类的文档与基类字段之外的扩展字段如下MouseInputEventextends InputEvent字段类型说明typestring可取mouseDown、mouseUp、mouseEnter、mouseLeave、contextMenu、mouseWheel、mouseMovex/yInteger事件在页面中的坐标buttonstring可选按下的按钮left、middle、rightglobalX/globalYInteger可选全局屏幕坐标movementX/movementYInteger可选相对移动量clickCountInteger可选点击计数KeyboardInputEventextends InputEvent字段类型说明typestring可取rawKeyDown、keyDown、keyUp、charkeyCodestring将作为键盘事件发送的字符只能使用合法的 Accelerator 键码如a、Escape、TabMouseWheelInputEventextends MouseInputEvent字段类型说明typestring只能为mouseWheeldeltaX/deltaYInteger可选滚动增量wheelTicksX/wheelTicksYInteger可选滚轮刻度增量accelerationRatioX/accelerationRatioYInteger可选加速度比hasPreciseScrollingDeltasboolean可选是否为精确滚动增量canScrollboolean可选页面是否可滚动二、实战用法webContents.sendInputEvent()InputEvent结构体的主要消费入口是 webContents.sendInputEvent(inputEvent)const { app, BrowserWindow } require(electron); app.whenReady().then(() { const win new BrowserWindow({ width: 800, height: 600 }); win.focus(); // 关键窗口必须处于聚焦状态sendInputEvent 才能生效 win.loadFile(index.html).then(() { const wc win.webContents; // 键盘按 CtrlShiftZ 组合键 wc.sendInputEvent({ type: keyDown, keyCode: Z, modifiers: [shift, ctrl] }); wc.sendInputEvent({ type: keyUp, keyCode: Z, modifiers: [shift, ctrl] }); // 键盘输入一个字符char 事件直接产生文本 wc.sendInputEvent({ type: char, keyCode: a }); // 鼠标在 (100, 100) 位置模拟一次左键单击 wc.sendInputEvent({ type: mouseDown, button: left, x: 100, y: 100 }); wc.sendInputEvent({ type: mouseUp, button: left, x: 100, y: 100 }); // 滚轮向下滚动 wc.sendInputEvent({ type: mouseWheel, x: 100, y: 100, deltaY: -120 }); }); });要点说明参数类型inputEvent接受 MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent 三种对象之一它们都包含InputEvent基类的type/modifiers字段。聚焦前提官方文档明确提示sendInputEvent()生效要求包含该内容的BrowserWindow处于聚焦状态见 web-contents.md 中的 NOTE。这是使用中最容易踩的坑无头测试或隐藏窗口场景下需先focus()。keyCode 的合法性KeyboardInputEvent.keyCode必须使用合法的 Accelerator 键码如A、Escape、Tab否则事件构造会失败。webview 标签页同样支持webview.sendInputEvent(event)直接转发到webContents.sendInputEvent。sendInputEvent在 webview 同步方法白名单中被归类为异步方法见 web-view-methods.ts。三、源码剖析事件是如何被解析与分发的3.1 type 字符串 → blink 枚举的转换类型解析发生在 blink_converter.ccConverterblink::WebInputEvent::Type::FromV8通过BLINK_EVENT_TYPES()宏将 JS 侧的type字符串逐个映射到blink::WebInputEvent::Type枚举如mouseDown→kMouseDown、keyDown→kKeyDown。两个值得注意的实现细节匹配不区分大小写宏内使用base::EqualsCaseInsensitiveASCII比较因此Keydown与keyDown等价。枚举覆盖面比 API 更大宏表包含了上文第一组表格中的全部 40 个类型含 gesture、touch、pointer 系列即所有type取值都能被解析解析器本身不会报错。随后 GetWebInputEventType 从事件对象中取出type字段用于分发决策Converterblink::WebInputEvent::FromV8 再把modifiers数组按位或合并为blink::WebInputEvent::Modifiers位掩码并由 C 侧自动填充时间戳base::TimeTicks::Now()JS 调用者无需也不能指定时间戳。3.2 modifiers 的名称规范与别名映射修饰键的字符串名与位掩码的映射定义在 blink_converter.cc分两张表规范表既可传入也可返回shift、control、alt、meta、iskeypad、isautorepeat、leftbuttondown、middlebuttondown、rightbuttondown、capslock、numlock、left、right。别名字典只接受、不返回cmd与command都映射到metactrl映射到control。这说明源码层面ctrl/command/cmd只是为书写习惯提供的别名事件对象序列化回 JS 时只会输出规范名。另外从 ToV8 实现 可以看出键盘/鼠标事件会转换为对应子类对象返回其余类型则退化为只含type与modifiers的普通对象——这也解释了为什么基类文档只定义这两个字段。3.3 SendInputEvent 的三条分发路径C 侧入口是 WebContents::SendInputEvent经 第 5043 行 注册为 JS 方法sendInputEvent。它先解析type再走三条互斥路径路径一鼠标事件IsMouseEventType转换为blink::WebMouseEvent后若WebContents是离屏渲染OSR模式走GetOffScreenRenderWidgetHostView()-SendMouseEvent()否则调用rwh-ForwardMouseEvent()转发给content::RenderWidgetHost。路径二键盘事件IsKeyboardEventType构造input::NativeWebKeyboardEvent其中有一个向后兼容行为如果传入type: keyDownC 侧会静默将其改写为rawKeyDown再转发源码注释标明是为兼容旧用法见 第 3963–3966 行。键盘事件的keyCode字符串还会经KeyboardCodeFromStr解析为ui::KeyboardCode并推导dom_code/dom_key对char与rawKeyDown类型当键码对应的是可打印字符如、空格时会用字符本身而非键名保证页面收到正确的文本blink_converter.cc 第 311–319 行。路径三滚轮事件kMouseWheel这是实现中最精巧的一处。Chromium 期望滚轮事件携带完整的相位phase信息并对此做 DCHECK 校验因此非 OSR 模式下SendInputEvent会做如下处理第 3976–3990 行把用户事件标记为phase kPhaseBegan、dispatch_type kBlocking后转发紧接着再合成一条delta_x/delta_y均为 0 的kPhaseEnded事件dispatch_type kEventNonBlocking以结束本次滚动序列。也就是说JS 侧发一条mouseWheel事件C 侧实际向渲染进程投递了两条事件。这一补偿逻辑是页面滚动行为“一次到位”、不会停在中间相位的原因。兜底三条路径的ConvertFromV8全部失败时会抛出Invalid event object异常第 3996–3997 行。从源码结构看虽然 40 种type都能通过解析但SendInputEvent只实际分发鼠标、键盘、滚轮三类gesture/touch/pointer 类型目前会走到兜底逻辑构造这类对象传入不会得到有效分发。3.4 测试用例中的典型用法仓库测试套件大量使用sendInputEvent驱动页面行为可作为构造事件的真实参照api-web-contents-spec.tsdescribe(sendInputEvent(event))覆盖组合键{ type: keyDown, keyCode: Z, modifiers: [shift, ctrl] }、char输入、以及Space/Plus这类字符键的处理api-browser-window-spec.ts用{ type: keyDown, keyCode: Escape }触发页面行为chromium-spec.ts构造Tab/ShiftTab按键事件验证焦点在窗口与 webview 之间的移动autofill-spec.ts用Tab键切换表单焦点后依次发送char事件填写自动补全字段。这些用例共同印证了实战规律键盘输入通常由keyDowncharkeyUp组合模拟点击由mouseDownmouseUp成对模拟。四、使用注意事项小结窗口必须先聚焦BrowserWindow未聚焦时sendInputEvent可能不产生效果自动化脚本中记得在发送前win.focus()。keyCode 必须合法只能使用 Accelerator 支持的键码字符串char类型用于向可编辑元素输入文本keyDown/keyUp用于触发按键处理逻辑。keyDown会被改写为rawKeyDown从源码看这是刻意的向后兼容行为依赖e.type keydown的页面逻辑需注意区分。修饰键别名ctrl、command、cmd可自由书写但规范名是control、meta事件序列化回 JS 时只会返回规范名。滚轮事件是成对投递的单条mouseWheel输入会在 C 侧展开为kPhaseBegan 合成kPhaseEnded两条事件页面收到的滚动是完整闭环的。坐标语义x/y是页面坐标globalX/globalY是屏幕全局坐标两者不可混用。通过本文你可以完整掌握InputEvent基类与三个子类的全部字段、sendInputEvent的正确调用姿势以及从 JS 对象到blink::WebInputEvent的解析与分发链路从而在 Electron 应用开发与自动化测试中可靠地构造合成输入事件。【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考