EventUtils 文档

EventUtils 的方法在所有浏览器 mochitests 的 EventUtils 对象中可用。

在 mochitest-plain 和 mochitest-chrome 中，您可以使用常规 HTML 脚本标签加载 "chrome://mochikit/content/tests/SimpleTest/EventUtils.js" 来访问这组实用程序。在这种情况下，此处记录的所有方法**不**在单独的对象上，而是作为全局函数可用。

鼠标输入

sendMouseEvent(aEvent, aTarget, aWindow)

向节点 aTarget 发送鼠标事件（aTarget 可以是 ID 或实际节点）。传递给 aEvent 的“事件”只是一个 JavaScript 对象，其中设置了真实鼠标事件对象应具有的属性。这包括鼠标事件的类型。几乎所有这些属性都是可选的。例如，要向 ID 为“node”的节点发送点击事件，您可以执行以下操作

sendMouseEvent({type:'click'}, 'node');

EventUtils.synthesizeMouse(aTarget, aOffsetX, aOffsetY, aEvent, aWindow)

在目标上合成鼠标事件。实际的客户端点是通过获取 aTarget 的客户端框并将其偏移 aOffsetX 和 aOffsetY 来确定的。这允许通过调用此方法来模拟鼠标点击。

aEvent 是一个对象，可能包含以下属性

shiftKey、ctrlKey、altKey、metaKey、accessKey、clickCount、button、type。有关有效的 type`s 请参阅 nsIDOMWindowUtils’ `sendMouseEvent。

如果指定了类型，则会触发该类型的鼠标事件。否则，将执行 mousedown 然后是 mouseup。

aWindow 是可选的，默认为当前窗口对象。

返回事件是否已调用 preventDefault()。

static synthesizeMouseAtCenter()

synthesizeMouse 的版本，它使用目标的中心作为鼠标

位置。参数和返回值相同。

synthesizeNativeMouseEvent(aParams)

有三种互斥的方式来指示鼠标事件的位置：设置 atCenter，或传递 offsetX 和 offsetY，或传递 screenX 和 screenY。不要尝试混合这些。

参数：

• aParams (object)

• aParams.type (string) – “click”、“mousedown”、“mouseup” 或 “mousemove”

• aParams.target (Element) – offsetX 和 offsetY 的原点，必须是元素

• aParams.atCenter (Boolean) – 代替 offsetX/Y，在 target 的中心合成事件。

• aParams.offsetX (Number) – target 中的 X 偏移量（如果 scale 为“screenPixelsPerCSSPixel”，则以 CSS 像素为单位）

• aParams.offsetY (Number) – target 中的 Y 偏移量（如果 scale 为“screenPixelsPerCSSPixel”，则以 CSS 像素为单位）

• aParams.screenX (Number) – 屏幕中的 X 偏移量（如果 scale 为“screenPixelsPerCSSPixel”，则以 CSS 像素为单位），如果设置了此值，则不得设置 offsetX/Y 或 atCenter。

• aParams.screenY (Number) – 屏幕中的 Y 偏移量（如果 scale 为“screenPixelsPerCSSPixel”，则以 CSS 像素为单位），如果设置了此值，则不得设置 offsetX/Y 或 atCenter。

• aParams.scale (String) – 如果 scale 为“screenPixelsPerCSSPixel”，则将使用 devicePixelRatio。如果 scale 为“inScreenPixels”，则 clientX/Y 和 scaleX/Y 不会随 screenPixelsPerCSSPixel 进行调整。

• aParams.button (Number) – 默认为 0，如果为“click”、“mousedown”、“mouseup”，则设置与 DOM MouseEvent.button 相同的值

• aParams.modifiers (Object) – 活动修饰符，请参阅 _parseNativeModifiers

• aParams.win (Window) – 要使用的窗口及其实用程序。默认为运行 EventUtils.js 的窗口。

• aParams.elementOnWidget (Element) – 默认为 target。如果点下的元素位于 target 的窗口小部件之外的另一个窗口小部件中，例如，当它位于 XUL <panel> 中时，请指定此值。

synthesizeMouseExpectEvent(aTarget, aOffsetX, aOffsetY, aEvent, aExpectedTarget, aExpectedEvent, aTestName, aWindow)

类似于 synthesizeMouse，只是执行了一个测试以查看是否因此在正确的目标上触发了事件。

aExpectedTarget - 事件的预期 originalTarget。aExpectedEvent - 事件的预期类型，例如“select”。aTestName - 输出结果时的测试名称

要测试事件未触发，请使用以感叹号开头的预期类型，例如“!select”。这可能用于测试例如在禁用元素上单击不会触发某些事件。

aWindow 是可选的，默认为当前窗口对象。

synthesizeWheel(aTarget, aOffsetX, aOffsetY, aEvent, aWindow)

在目标上合成滚轮事件。实际的客户端点是通过获取 aTarget 的客户端框并将其偏移 aOffsetX 和 aOffsetY 来确定的。

aEvent 是一个对象，可能包含以下属性

shiftKey、ctrlKey、altKey、metaKey、accessKey、deltaX、deltaY、deltaZ、deltaMode、lineOrPageDeltaX、lineOrPageDeltaY、isMomentum、isNoLineOrPageDelta、isCustomizedByPrefs、expectedOverflowDeltaX、expectedOverflowDeltaY

必须定义 deltaMode，即使未定义其他内容也可以。

expectedOverflowDeltaX 和 expectedOverflowDeltaY 采用整数值。该值仅被检查为 0 或正数或负数。

aWindow 是可选的，默认为当前窗口对象。

EventUtils.synthesizeWheelAtPoint(aLeft, aTop, aEvent, aWindow)

在 aWindow 中的特定点合成滚轮事件，不刷新布局。

aEvent 是一个对象，可能包含以下属性

shiftKey、ctrlKey、altKey、metaKey、accessKey、deltaX、deltaY、deltaZ、deltaMode、lineOrPageDeltaX、lineOrPageDeltaY、isMomentum、isNoLineOrPageDelta、isCustomizedByPrefs、expectedOverflowDeltaX、expectedOverflowDeltaY

必须定义 deltaMode，即使未定义其他内容也可以。

expectedOverflowDeltaX 和 expectedOverflowDeltaY 采用整数值。该值仅被检查为 0 或正数或负数。

aWindow 是可选的，默认为当前窗口对象。

sendWheelAndPaint(aTarget, aOffsetX, aOffsetY, aEvent, aCallback, aWindow)

这是 synthesizeWheel 的包装器，它等待滚轮事件分派以及后续布局/绘制刷新。

这需要包含 paint_listener.js。如果测试使用此函数，则必须在完成之前调用 DOMWindowUtils.restoreNormalRefresh()。

如果未提供回调，则假定调用者有自己的方法来确定滚动完成，并且刷新驱动程序不会自动恢复。

sendWheelAndPaintNoFlush(aTarget, aOffsetX, aOffsetY, aEvent, aCallback, aWindow)

类似于 sendWheelAndPaint，但在发送滚轮事件之前不刷新布局以获取 aTarget 在 aWindow 中的位置。aOffsetX 和 aOffsetY 应相对于 aWindow 的偏移量。

键盘输入

sendKey(aKey, aWindow)

将非字符键 aKey 发送到焦点节点。键的名称应是在此键的 KeyEvent 常量名称中 DOM_VK_ 后面的部分。此时不处理修饰符。

EventUtils.sendChar(aChar, aWindow)

将字符 aChar 发送到焦点元素。此方法处理字符的大小写（发送正确的字符代码，并为大写字符发送 Shift 键）。此时不处理其他修饰符。

目前，此方法仅适用于 ASCII 字符，并在美国键盘布局上模拟 Shift 键状态。

sendString(aStr, aWindow)

将字符串 aStr 发送到焦点元素。

目前，此方法仅适用于 ASCII 字符，并在美国键盘布局上模拟 Shift 键状态。

EventUtils.synthesizeKey(aKey, aEvent, aWindow, aCallback)

accelKey、altKey、altGraphKey、ctrlKey、capsLockKey、fnKey、fnLockKey、numLockKey、metaKey、scrollLockKey、shiftKey、symbolKey、symbolLockKey 基本上，你不应该使用这些属性。 当你合成修饰键事件时，nsITextInputProcessor 会管理修饰键的状态。 但是，如果其中一些属性为真，则此函数仅在分发按键事件期间激活修饰符。 请注意，如果其中一些值为假，则会忽略它们（即，不会使用此函数停用）。

参数：

• aKey (字符串) – 应为以下之一：- 键值（推荐）。 如果你指定了一个不可打印的键名，请在前面加上 KEY_ 前缀。 否则，指定一个可打印的键，应指定键值。- 以 VK_ 开头的 keyCode 名称（例如，VK_RETURN）。 这仅适用于与旧版 API 的兼容性。 不要在新测试中使用它。

• aEvent (对象) – 关于要合成的按键事件的更多详细信息的可选事件对象。

• aEvent.code (字符串) – 如果你没有明确指定，它将从美国键盘布局的 aKey 推测出来。 请注意，此值在不同浏览器之间可能不同。 例如，“Insert” 永远不会仅在 macOS 上设置，因为实际的按键操作不会导致此代码值。 在这种情况下，该值变为空字符串。 如果你需要模拟非美国键盘布局或不模拟硬件键输入的虚拟键盘，则应将此值显式设置为空字符串。

• aEvent.repeat (数字) – 如果你模拟自动重复，则应设置重复次数。 此方法将自动合成 keydown（和 keypress）。

• aEvent.location (*) – 如果你想指定它，你可以明确指定它。 但是，如果你没有指定此值，它将根据代码值计算得出。

• aEvent.type (字符串) – 基本上，你不应该指定它。 然后，此函数将合成 keydown（、keypress）和 keyup。 如果指定了 keydown，则它只会触发 keydown（如果应该触发，则触发 keypress）。 如果指定了 keyup，则它只会触发 keyup。

• aEvent.keyCode (数字) – 必须是 0 - 255 (0xFF)。 如果显式指定了此值，则 .keyCode 值将使用此值初始化。

• aWindow (窗口) – 是可选的，默认为当前窗口对象。

• aCallback (函数) – 是可选的，可用于接收来自 TIP 的通知。

synthesizeNativeKey(aKeyboardLayout, aNativeKeyCode, aModifiers, aChars, aUnmodifiedChars, aCallback)

synthesizeNativeKey() 在活动窗口上分发本机按键事件。 这仅在 Windows 和 Mac 上实现。 请注意，此函数异步分发按键事件并立即返回。 如果提供了回调函数，则在按键分发完成后将调用回调。

参数：

• aKeyboardLayout – 上面定义的 KEYBOARD_LAYOUT_* 之一。

• aNativeKeyCode – NativeKeyCodes.js 中定义的本机键码值。

• aModifiers – 修饰键。 如果没有按下修饰键，则此值必须为 . 否则，_parseNativeModifiers() 中引用的一个或多个项目必须为真。

• aChars – 指定按键事件应生成的字符。

• aUnmodifiedChars – 指定未修改（除了 Shift）的 aChar 值的字符。

• aCallback – 如果提供，则一旦 Gecko 处理了本机键，就会调用此回调。 如果此函数返回 false，则永远不会调用。

返回值:

如果此函数成功分发本机按键事件，则返回 true。 否则，返回 false。

synthesizeKeyExpectEvent(key, aEvent, aExpectedTarget, aExpectedEvent, aTestName, aWindow)

类似于 synthesizeKey，除了执行一个测试以查看是否由于结果而在正确的目标处触发了事件。

aExpectedTarget - 事件的预期 originalTarget。aExpectedEvent - 事件的预期类型，例如“select”。aTestName - 输出结果时的测试名称

要测试事件是否未触发，请使用以感叹号开头的预期类型，例如“！select”。

aWindow 是可选的，默认为当前窗口对象。

拖放

synthesizeDragOver(aSrcElement, aDestElement, aDragData, aDropEffect="move", aWindow=window, aDestWindow=aWindow, aDragEvent={})

模拟 dragstart、dragenter 和 dragover 的事件序列。

参数：

• aSrcElement (元素) – 用于开始拖动的元素。

• aDestElement (元素) – 触发 dragover、dragenter 事件的元素

• aDragData (数组) – 要为数据传输提供的数据。 此数据格式为：[ [ {“type”: 值, “data”: 值 }, …, ], … ] 传递 null 以避免修改 dataTransfer。

• aDropEffect (字符串) – 在 dragstart 事件期间设置的放置效果，或者如果省略则为“move”。

• aWindow (窗口) – 拖动发生的窗口。 默认为加载 EventUtils.js 的窗口。

• aDestWindow (窗口) – 当 aDestElement 在与 aSrcElement 不同的窗口中时使用。 默认为与 aWindow 匹配。

• aDragEvent (对象) – 默认为空对象。 覆盖传递给 sendDragEvent 的对象。

返回值:

数组 – 一个包含两个元素的数组，其中第一个元素是 dragover 事件的 sendDragEvent 返回的值，第二个元素是当前拖动会话的 dataTransfer。

synthesizeDrop(aSrcElement, aDestElement, aDragData, aDropEffect="move", aWindow=window, aDestWindow=aWindow, aDragEvent={})

通过模拟 dragstart 并触发事件 dragenter、dragover 和 drop 来模拟拖放。

参数：

• aSrcElement (元素) – 用于开始拖动的元素。

• aDestElement (元素) – 触发 dragover、dragenter 事件的元素

• aDragData (数组) – 要为数据传输提供的数据。 此数据格式为：[ [ {“type”: 值, “data”: 值 }, …, ], … ] 传递 null 以避免修改 dataTransfer。

• aDropEffect (字符串) – 在 dragstart 事件期间设置的放置效果，或者如果省略则为“move”。

• aWindow (窗口) – 拖动发生的窗口。 默认为加载 EventUtils.js 的窗口。

• aDestWindow (窗口) – 当 aDestElement 在与 aSrcElement 不同的窗口中时使用。 默认为与 aWindow 匹配。

• aDragEvent (对象) – 默认为空对象。 覆盖传递给 sendDragEvent 的对象。

返回值:

字符串 – 所需的放置效果。

synthesizeDropAfterDragOver(aResult, aDataTransfer, aDestElement, aDestWindow=window, aDragEvent={})

模拟 drop 事件和 mouseup 事件。 应在 synthesizeDragOver 之后调用此函数。

参数：

• aResult (*) – 从 synthesizeDragOver 返回的数组的第一个元素。

• aDataTransfer (DataTransfer) – 从 synthesizeDragOver 返回的数组的第二个元素。

• aDestElement (元素) – 要在其上触发 drop 事件的元素。

• aDestWindow (窗口) – 拖动发生的窗口。 默认为加载 EventUtils.js 的窗口。

• aDragEvent (对象) – 默认为空对象。 覆盖传递给 sendDragEvent 的对象。

返回值:

字符串 – 如果 aResult 为 true，则为“none”，否则为 aDataTransfer.dropEffect。

synthesizePlainDragAndDrop(aParams)

通过模拟 mousedown 和 mousemove 的 dragstart，以及触发事件 dragenter、dragover、drop 和 dragend 来模拟拖放。 这不会修改 dataTransfer，并尝试尽可能多地模拟简单的拖放，与 synthesizeDrop 相比。 请注意，如果合成的 dragstart 被取消，则会抛出异常，因为在这种情况下，Gecko 不会启动拖动会话。

参数：

• aParams (对象)

• aParams.dragEvent (事件) – DnD 事件将使用此事件中指定的修饰符生成。

• aParams.srcElement (元素) – 要开始拖动的元素。 如果设置了 srcSelection，则会为焦点节点处的元素计算此值。

• aParams.srcSelection (选择|nil) – 要开始拖动的选择，如果设置了 srcElement，则设置为 null。

• aParams.destElement (元素|nil) – 要在其上放置的元素。 传递 null 以模拟在无效目标上放置。

• aParams.srcX (数字) – srcElement 内部的初始 x 坐标，或者如果设置了 srcSelection，则忽略。

• aParams.srcY (数字) – srcElement 内部的初始 y 坐标，或者如果设置了 srcSelection，则忽略。

• aParams.stepX (数字) – srcElement 内部的 mousemove 的 x 轴步长

• aParams.stepY (数字) – srcElement 内部的 mousemove 的 y 轴步长

• aParams.finalX (数字) – srcElement 内部的最终 x 坐标

• aParams.finalY (数字) – srcElement 内部的最终 x 坐标

• aParams.id (任何) – 指针事件 ID

• aParams.srcWindow (窗口) – 在 srcElement 上分发事件的窗口，默认为当前窗口对象。

• aParams.destWindow (窗口) – 在 destElement 上分发事件的窗口，默认为当前窗口对象。

• aParams.expectCancelDragStart (布尔值) – 如果测试取消“dragstart”，则设置为 true。

• aParams.expectSrcElementDisconnected (布尔值) – 如果 srcElement 将断开连接并且不会触发“dragend”事件，则设置为 true。

• aParams.logFunc (函数) – 如果你需要记录目标的矩形，则设置一个接受一个参数的函数。 例如，console.log。

synthesizePlainDragAndCancel(aParams, aExpectedDataTransferItems)

synthesizePlainDragAndCancel() 使用 synthesizePlainDragAndDrop() 合成拖动开始，但始终通过阻止“dragstart”的默认操作来取消它。 此外，它还会检查“dragstart”事件的 dataTransfer 是否仅包含预期的项目。

参数：

• aParams (对象) – 设置为 synthesizePlainDragAndDrop() 参数的参数。

• aExpectedDataTransferItems (eqTest) – 所有预期的 dataTransfer 项目。 此数据格式为：[ [ {“type”: 值, “data”: 值, eqTest: 函数} …, ], … ] 这也可以为 null。 如果你无法使用 x == y 对预期的 dataTransfer 项目进行比较，则可以选择提供 eqTest;

返回值:

布尔值 – 如果 aExpectedDataTransferItems 与“dragstart”事件的 DragEvent.dataTransfer 匹配，则为 true。 否则，dataTransfer 对象（可能为 null）或抛出异常，而不是 false。 因此，你不应该使用。

sendDragEvent(aEvent, aTarget, aWindow)

将拖动事件发送到节点 aTarget（aTarget 可以是 ID 或实际节点）。 传递给 aEvent 的“event”只是一个 JavaScript 对象，其中设置了真实拖动事件对象应该具有的属性。 这包括拖动事件的类型。