跳至主要内容
版本: 22.5.0

定位器

定位器是一个新的实验性 API，它结合了等待和操作的功能。通过额外的先决条件检查，它可以自动重试失败的操作，从而使自动化脚本更加可靠，减少了不稳定性。

注意

定位器 API 处于实验阶段，我们不会对定位器 API 中的重大更改遵循语义化版本控制。

用例​

等待元素​

await page.locator('button').wait();

以下先决条件会自动检查

  • 等待元素变为 可见 或隐藏。

等待函数​

await page
  .locator(() => {
    let resolve!: (node: HTMLCanvasElement) => void;
    const promise = new Promise(res => {
      return (resolve = res);
    });
    const observer = new MutationObserver(records => {
      for (const record of records) {
        if (record.target instanceof HTMLCanvasElement) {
          resolve(record.target);
        }
      }
    });
    observer.observe(document);
    return promise;
  })
  .wait();

点击元素​

await page.locator('button').click();

以下先决条件会自动检查

  • 确保元素在视窗内。
  • 等待元素变为 可见 或隐藏。
  • 等待元素启用。
  • 等待元素在两个连续的动画帧中具有稳定的边界框。

点击匹配条件的元素​

await page
  .locator('button')
  .filter(button => !button.disabled)
  .click();

以下先决条件会自动检查

  • 确保元素在视窗内。
  • 等待元素变为 可见 或隐藏。
  • 等待元素启用。
  • 等待元素在两个连续的动画帧中具有稳定的边界框。

填写输入框​

await page.locator('input').fill('value');

自动检测输入类型并选择适当的方式使用提供的 value 填写输入框。

以下先决条件会自动检查

  • 确保元素在视窗内。
  • 等待元素变为 可见 或隐藏。
  • 等待元素启用。
  • 等待元素在两个连续的动画帧中具有稳定的边界框。

检索元素属性​

const enabled = await page
  .locator('button')
  .map(button => !button.disabled)
  .wait();

将鼠标悬停在元素上​

await page.locator('div').hover();

以下先决条件会自动检查

  • 确保元素在视窗内。
  • 等待元素变为 可见 或隐藏。
  • 等待元素在两个连续的动画帧中具有稳定的边界框。

滚动元素​

await page.locator('div').scroll({
  scrollLeft: 10,
  scrollTop: 20,
});

以下先决条件会自动检查

  • 确保元素在视窗内。
  • 等待元素变为 可见 或隐藏。
  • 等待元素在两个连续的动画帧中具有稳定的边界框。

配置定位器​

定位器可以配置为调整配置先决条件和其他选项

await page
  .locator('button')
  .setEnsureElementIsInTheViewport(false)
  .setTimeout(0)
  .setVisibility(null)
  .setWaitForEnabled(false)
  .setWaitForStableBoundingBox(false)
  .click();

获取定位器事件​

目前，定位器支持单个事件，该事件会在定位器即将执行操作时通知您。

let willClick = false;
await page
  .locator('button')
  .on(LocatorEvent.Action, () => {
    willClick = true;
  })
  .click();

此事件可用于日志记录/调试或其他目的。如果定位器重试操作，则该事件可能会多次触发。