用户操作 API

概述

来自 Selenium 的 操作 API 可供使用，并且已准备好通过现有的 .perform() 命令在 Nightwatch 中使用。

可用操作

.clear()

释放所有键、指针并清除内部状态。

参数

无

.click([element])

用于执行简单鼠标左键单击（按下/抬起）的简写方法。

参数
名称 类型 描述
元素
可选		 WebElement 如果指定，鼠标将首先移动到元素的中心，然后执行单击。

.contextClick([element])

用于执行简单鼠标右键单击（按下/抬起）的简写方法。

参数
名称 类型 描述
元素
可选		 WebElement 如果指定，鼠标将首先移动到元素的中心，然后执行单击。

.doubleClick([element])

用于执行鼠标双击左键的简写方法。

参数
名称 类型 描述
元素
可选		 WebElement 如果指定，鼠标将首先移动到元素的中心，然后执行单击。

.dragAndDrop(from, to)

配置拖放操作，包括以下步骤
  1. 移动到 from 元素（要拖动的元素）的中心。
  2. 按下鼠标左键。
  3. 如果 to 目标是 WebElement，则将鼠标移动到其中心。否则，将鼠标移动指定偏移量。
  4. 释放鼠标左键。
参数
名称 类型 描述
从 WebElement 要按下鼠标左键以开始拖动的元素
到 WebElement 或
{x: number, y: number}		 另一个要拖动的元素（将拖动到元素的中心），或一个指定要拖动偏移量的对象（以像素为单位）。

.insert(device, ...actions)

将操作附加到给定 device 的当前序列的末尾。如果启用了设备同步，则在插入操作后，将为所有其他设备插入暂停，以确保所有操作序列的长度相同。

参数
名称 类型 描述
设备 设备 要更新的设备
操作 ...操作 要插入的操作。

.keyDown(key)

插入按下单个键的操作。

参数
名称 类型 描述
键 字符串 | 数字 要按下的键。此键可以指定为键值、特定的 Unicode 代码点或包含单个 Unicode 代码点的字符串。

.keyUp(key)

插入释放单个键的操作。

参数
名称 类型 描述
键 字符串 | 数字 要释放的键。此键可以指定为键值、特定的 Unicode 代码点或包含单个 Unicode 代码点的字符串。

.keyboard()

参数

无

返回
类型 描述
键盘 键盘设备句柄。

.mouse()

参数

无

返回
类型 描述
指针 鼠标指针设备句柄。

.move([options])

插入操作，以将鼠标相对于指定的 origin 移动 x 和 y 像素。原点可以定义为鼠标的 当前位置、视窗 或特定 WebElement 的中心。

可以使用 duration 参数（默认为 100 毫秒）调整浏览器驱动程序执行移动所需的时间（以毫秒为单位）。

参数
名称 类型 描述
选项
可选 		对象 移动选项。默认为在 100 毫秒内将鼠标移动到视窗的左上角。

可用值为
{
  duration: {Number|undefined}, 
  origin: (Origin|WebElement|undefined), 
  x: {Number|undefined}, 
  y: {Number|undefined}
}

.pause(duration, ...devices)

为指定的设备插入暂停操作，确保每个设备在一次滴答中处于空闲状态。暂停的长度（以毫秒为单位）可以指定为此方法的第一个参数（默认为 0）。否则，你只需指定应该暂停的各个设备。

如果没有指定设备，则将为每个设备创建一个暂停操作（使用相同的持续时间）。

参数
名称 类型 描述
持续时间
可选 		数字 | 设备 要插入的暂停的长度，以毫秒为单位。或者，可以省略持续时间（产生默认的 0 毫秒暂停），并且可以指定第一个要暂停的设备。
设备 ...设备 要插入暂停的设备。如果没有指定设备，则将为所有设备插入暂停。

.press([button])

插入在鼠标当前位置按下鼠标按钮的操作。

参数
名称 类型 描述
按钮
可选 		按钮 要按下的按钮；默认为 LEFT。

.release([button])

插入在鼠标当前位置释放鼠标按钮的操作。

参数
名称 类型 描述
按钮
可选 		按钮 要释放的按钮；默认为 LEFT。

.sendKeys(...keys)

插入一系列操作，以键入提供的键序列。对于每个键，这将记录一对 keyDown 和 keyUp 操作。

参数
名称 类型 描述
键 ...字符串 | 数字 要键入的键。

.synchronize(...devices)

确保此操作序列中引用的每个设备的操作序列长度相同。对于序列太短的设备，这将插入暂停，以便每个设备在每次滴答中都具有明确定义的操作。

参数
名称 类型 描述
设备 ...设备 要同步的特定设备。如果没有指定，则将同步每个设备的操作序列。

使用操作滴答

操作序列被分成一系列“滴答”。在每次滴答中，浏览器驱动程序将为操作序列中包含的每个设备执行一项操作。在滴答 0 时，驱动程序将执行为每个设备定义的第一项操作，在滴答 1 时执行每个设备的第二项操作，依此类推，直到所有操作都执行完毕。如果某个设备在特定滴答中没有定义操作，则它将自动暂停。

默认情况下，操作序列将被同步，因此每个滴答中只有一个设备具有定义的操作。请考虑以下代码示例

describe('user actions api', function() {
  

  it('demo test', function() {
    browser
      .perform(function() {
        const actions = this.actions({async: true});
        

        return actions
          .keyDown(Keys.SHIFT)
          .move({origin: el})
          .press()
          .release()
          .keyUp(Keys.SHIFT);
      });
    })
})

这将产生以下滴答序列

设备 滴答 1 滴答 2 滴答 3 滴答 4 滴答 5
键盘 keyDown(SHIFT) pause() pause() pause() keyUp(SHIFT)
鼠标 pause() move({origin: el}) press() release() pause()

有关操作滴答的更多信息，请参阅 Selenium 文档。

工作示例

tests/sampleTest.js 
describe('example with user actions api', function () {
  

  before(browser => browser.navigateTo('https://nightwatch.node.org.cn'));
  

  it('demo test', async function (browser) {
    // retrieve the element; the actions api requires Selenium WebElement objects,
    //  which can be retrieved using the global element() utility
    const btnElement = await element('a.btn-github').findElement();
    

    await browser.perform(function() {
      // initiate the actions chain
      const actions = this.actions({async: true});
      

      return actions
        .dragAndDrop(btnElement, {x: 100, y: 100})
        .pause(500)
        .contextClick(btnElement)
        .pause(500)
        .doubleClick(btnElement)
        .pause(500)
    });
  });
});