定位器

¥Locators

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

¥Locators is a new, experimental API that combines the functionalities of waiting and actions. With additional precondition checks, it enables automatic retries for failed actions, resulting in more reliable and less flaky automation scripts.

注意

Locators API 是实验性的，我们不会遵循 semver 对 Locators API 进行重大更改。

¥Locators API is experimental and we will not follow semver for breaking changes in the Locators API.

用例

¥Use cases

等待元素

¥Waiting for an element

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

自动检查以下先决条件：

¥The following preconditions are automatically checked:

• 等待元素变为 visible 或隐藏。

  ¥Waits for the element to become visible or hidden.

等待函数

¥Waiting for a function

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();

单击一个元素

¥Clicking an element

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

自动检查以下先决条件：

¥The following preconditions are automatically checked:

• 确保元素位于视口中。

  ¥Ensures the element is in the viewport.

• 等待元素变为 visible 或隐藏。

  ¥Waits for the element to become visible or hidden.

• 等待元素启用。

  ¥Waits for the element to become enabled.

• 等待元素在两个连续的动画帧上具有稳定的边界框。

  ¥Waits for the element to have a stable bounding box over two consecutive animation frames.

单击符合条件的元素

¥Clicking an element matching a criteria

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

自动检查以下先决条件：

¥The following preconditions are automatically checked:

• 确保元素位于视口中。

  ¥Ensures the element is in the viewport.

• 等待元素变为 visible 或隐藏。

  ¥Waits for the element to become visible or hidden.

• 等待元素启用。

  ¥Waits for the element to become enabled.

• 等待元素在两个连续的动画帧上具有稳定的边界框。

  ¥Waits for the element to have a stable bounding box over two consecutive animation frames.

填写输入

¥Filling out an input

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

自动检测输入类型并选择合适的方式用提供的值填写。

¥Automatically detects the input type and choose an approritate way to fill it out with the provided value.

自动检查以下先决条件：

¥The following preconditions are automatically checked:

• 确保元素位于视口中。

  ¥Ensures the element is in the viewport.

• 等待元素变为 visible 或隐藏。

  ¥Waits for the element to become visible or hidden.

• 等待元素启用。

  ¥Waits for the element to become enabled.

• 等待元素在两个连续的动画帧上具有稳定的边界框。

  ¥Waits for the element to have a stable bounding box over two consecutive animation frames.

检索元素属性

¥Retrieving an element property

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

将鼠标悬停在元素上

¥Hover over an element

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

自动检查以下先决条件：

¥The following preconditions are automatically checked:

• 确保元素位于视口中。

  ¥Ensures the element is in the viewport.

• 等待元素变为 visible 或隐藏。

  ¥Waits for the element to become visible or hidden.

• 等待元素在两个连续的动画帧上具有稳定的边界框。

  ¥Waits for the element to have a stable bounding box over two consecutive animation frames.

滚动一个元素

¥Scroll an element

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

自动检查以下先决条件：

¥The following preconditions are automatically checked:

• 确保元素位于视口中。

  ¥Ensures the element is in the viewport.

• 等待元素变为 visible 或隐藏。

  ¥Waits for the element to become visible or hidden.

• 等待元素在两个连续的动画帧上具有稳定的边界框。

  ¥Waits for the element to have a stable bounding box over two consecutive animation frames.

配置定位器

¥Configuring locators

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

¥Locators can be configured to tune configure the preconditions and other other options:

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

获取定位器事件

¥Getting locator events

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

¥Currently, locators support a single event that notifies you when the locator is about to perform the action:

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

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

¥This event can be used for logging/debugging or other purposes. The event might fire multiple times if the locator retries the action.