Skip to main content

Locator

Locator 是 Playwright 自动等待和重试能力的核心部分。简而言之，locator 代表了一种随时在页面上查找元素的方法。可以使用 page.locator(selector[, options]) 方法创建 Locator。

了解更多关于 locators 的信息。

locator.allInnerTexts()​

Added in: v1.14

返回所有匹配节点的 node.innerText 值数组。

locator.allTextContents()​

Added in: v1.14

返回所有匹配节点的 node.textContent 值数组。

locator.boundingBox([options])​

Added in: v1.14

此方法返回元素的边界框，如果元素不可见，则返回 null。边界框是相对于主框架视口计算的 - 通常与浏览器窗口相同。

滚动会影响返回的边界框，类似于 Element.getBoundingClientRect。这意味着 x 和/或 y 可能为负数。

与 Element.getBoundingClientRect 不同，子框架中的元素返回相对于主框架的边界框。

假设页面是静态的，使用边界框坐标执行输入是安全的。例如，以下代码片段应单击元素的中心。

const box = await element.boundingBox();
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);

locator.check([options])​

Added in: v1.14
  • options? <Object>
    • force? <boolean> 是否绕过可操作性检查。默认为 false。#
    • noWaitAfter? <boolean> 启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志选择不等待。您只需要在特殊情况下使用此选项,例如导航到无法访问的页面。默认为 false。#
    • position? <Object> 相对于元素内边距框左上角使用的点。如果未指定,则使用元素的某个可见点。#
    • timeout? <number> 最大时间(毫秒),默认为 30 秒,传入 0 可禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 当设置时,此方法仅执行可操作性检查并跳过操作。默认为 false。适用于等待元素准备好操作而不执行它。#
  • returns: <Promise<void>>#

此方法通过执行以下步骤来选中元素：

  1. 确保元素是复选框或单选输入框。如果不是，此方法将抛出异常。如果元素已选中，此方法立即返回。
  2. 等待元素上的 可操作性 检查，除非设置了 force 选项。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.mouse 单击元素的中心。
  5. 等待启动的导航成功或失败，除非设置了 noWaitAfter 选项。
  6. 确保元素现在已选中。如果不是，此方法将抛出异常。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法将抛出异常。

当所有步骤组合在指定的 timeout 期间未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

locator.click([options])​

Added in: v1.14
  • options? <Object>
    • button? <"left"|"right"|"middle"> 默认为 left。#
    • clickCount? <number> 默认为 1。参见 UIEvent.detail。#
    • delay? <number> mousedown 和 mouseup 之间的等待时间(毫秒)。默认为 0。#
    • force? <boolean> 是否绕过可操作性检查。默认为 false。#
    • modifiers? <Array<"Alt"|"Control"|"Meta"|"Shift">> 要按下的修饰键。确保在操作期间仅按下这些修饰键,然后恢复当前的修饰键。如果未指定,则使用当前按下的修饰键。#
    • noWaitAfter? <boolean> 启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志选择不等待。您只需要在特殊情况下使用此选项,例如导航到无法访问的页面。默认为 false。#
    • position? <Object> 相对于元素内边距框左上角使用的点。如果未指定,则使用元素的某个可见点。#
    • timeout? <number> 最大时间(毫秒),默认为 30 秒,传入 0 可禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 当设置时,此方法仅执行可操作性检查并跳过操作。默认为 false。适用于等待元素准备好操作而不执行它。#
  • returns: <Promise<void>>#

此方法通过执行以下步骤来单击元素：

  1. 等待元素上的 可操作性 检查，除非设置了 force 选项。
  2. 如果需要，将元素滚动到视图中。
  3. 使用 page.mouse 单击元素的中心或指定的 position。
  4. 等待启动的导航成功或失败，除非设置了 noWaitAfter 选项。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法将抛出异常。

当所有步骤组合在指定的 timeout 期间未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

locator.count()​

Added in: v1.14

返回匹配给定选择器的元素数量。

locator.dblclick([options])​

Added in: v1.14
  • options? <Object>
    • button? <"left"|"right"|"middle"> 默认为 left。#
    • delay? <number> mousedown 和 mouseup 之间的等待时间(毫秒)。默认为 0。#
    • force? <boolean> 是否绕过可操作性检查。默认为 false。#
    • modifiers? <Array<"Alt"|"Control"|"Meta"|"Shift">> 要按下的修饰键。确保在操作期间仅按下这些修饰键,然后恢复当前的修饰键。如果未指定,则使用当前按下的修饰键。#
    • noWaitAfter? <boolean> 启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志选择不等待。您只需要在特殊情况下使用此选项,例如导航到无法访问的页面。默认为 false。#
    • position? <Object> 相对于元素内边距框左上角使用的点。如果未指定,则使用元素的某个可见点。#
    • timeout? <number> 最大时间(毫秒),默认为 30 秒,传入 0 可禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 当设置时,此方法仅执行可操作性检查并跳过操作。默认为 false。适用于等待元素准备好操作而不执行它。#
  • returns: <Promise<void>>#

此方法通过执行以下步骤双击元素：

  1. 等待元素上的 可操作性 检查，除非设置了 force 选项。
  2. 如果需要，将元素滚动到视图中。
  3. 使用 page.mouse 双击元素的中心或指定的 position。
  4. 等待启动的导航成功或失败，除非设置了 noWaitAfter 选项。请注意，如果 dblclick() 的第一次单击触发了导航事件，此方法将抛出异常。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法将抛出异常。

当所有步骤组合在指定的 timeout 期间未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

note

element.dblclick() 派发两个 click 事件和一个 dblclick 事件。

locator.dispatchEvent(type[, eventInit, options])​

Added in: v1.14

下面的代码片段在元素上派发 click 事件。无论元素的可见性状态如何，都会派发 click。这相当于调用 element.click()。

await element.dispatchEvent('click');

在底层，它根据给定的 type 创建一个事件实例，使用 eventInit 属性对其进行初始化，并在元素上派发它。默认情况下，事件是 composed、cancelable 和冒泡的。

由于 eventInit 是特定于事件的，请参阅事件文档以获取初始属性列表：

如果您希望将活动对象传递给事件，还可以指定 JSHandle 作为属性值：

// Note you can only create DataTransfer in Chromium and Firefox
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await element.dispatchEvent('dragstart', { dataTransfer });

locator.dragTo(target[, options])​

Added in: v1.18
  • target <Locator> 要拖动到的元素的定位器。#
  • options? <Object>
    • force? <boolean> 是否绕过可操作性检查。默认为 false。#
    • noWaitAfter? <boolean> 启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志选择不等待。您只需要在特殊情况下使用此选项,例如导航到无法访问的页面。默认为 false。#
    • sourcePosition? <Object> 在源元素的此点单击,相对于元素内边距框的左上角。如果未指定,则使用元素的某个可见点。#
    • targetPosition? <Object> 在目标元素的此点放下,相对于元素内边距框的左上角。如果未指定,则使用元素的某个可见点。#
    • timeout? <number> 最大时间(毫秒),默认为 30 秒,传入 0 可禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 当设置时,此方法仅执行可操作性检查并跳过操作。默认为 false。适用于等待元素准备好操作而不执行它。#
  • returns: <Promise<void>>#

此方法将 locator 拖动到另一个目标 locator 或目标位置。它将首先移动到源元素，执行 mousedown，然后移动到目标元素或位置并执行 mouseup。

const source = page.locator('#source');
const target = page.locator('#target');

await source.dragTo(target);
// or specify exact positions relative to the top-left corners of the elements:
await source.dragTo(target, {
  sourcePosition: { x: 34, y: 7 },
  targetPosition: { x: 10, y: 20 },
});

locator.elementHandle([options])​

Added in: v1.14

将给定的 locator 解析为第一个匹配的 DOM 元素。如果没有匹配查询的元素可见，则等待它们直到给定的超时。如果多个元素匹配选择器，则抛出异常。

locator.elementHandles()​

Added in: v1.14

将给定的 locator 解析为所有匹配的 DOM 元素。

locator.evaluate(pageFunction[, arg, options])​

Added in: v1.14

返回 pageFunction 的返回值。

此方法将此句柄作为第一个参数传递给 pageFunction。

如果 pageFunction 返回 Promise，则 handle.evaluate 将等待 promise 解析并返回其值。

示例：

const tweets = page.locator('.tweet .retweets');
expect(await tweets.evaluate(node => node.innerText)).toBe('10 retweets');

locator.evaluateAll(pageFunction[, arg])​

Added in: v1.14

该方法查找与指定 locator 匹配的所有元素，并将匹配元素的数组作为第一个参数传递给 pageFunction。返回 pageFunction 调用的结果。

如果 pageFunction 返回 Promise，则 locator.evaluateAll(pageFunction[, arg]) 将等待 promise 解析并返回其值。

示例：

const elements = page.locator('div');
const divCounts = await elements.evaluateAll((divs, min) => divs.length >= min, 10);

locator.evaluateHandle(pageFunction[, arg, options])​

Added in: v1.14

将 pageFunction 的返回值作为 JSHandle 返回。

此方法将此句柄作为第一个参数传递给 pageFunction。

locator.evaluate(pageFunction[, arg, options]) 和 locator.evaluateHandle(pageFunction[, arg, options]) 之间的唯一区别是 locator.evaluateHandle(pageFunction[, arg, options]) 返回 JSHandle。

如果传递给 locator.evaluateHandle(pageFunction[, arg, options]) 的函数返回 Promise，则 locator.evaluateHandle(pageFunction[, arg, options]) 将等待 promise 解析并返回其值。

有关更多详细信息，请参阅 page.evaluateHandle(pageFunction[, arg])。

locator.fill(value[, options])​

Added in: v1.14

此方法等待 可操作性 检查，聚焦元素，填充它并在填充后触发 input 事件。请注意，您可以传递空字符串以清除输入字段。

如果目标元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法将抛出错误。但是，如果元素位于具有关联 control 的 <label> 元素内，则将填充该控件。

要发送细粒度的键盘事件，请使用 locator.type(text[, options])。

locator.filter([options])​

Added in: v1.22

  • options? <Object>

    • has? <Locator> 匹配包含与内部定位器匹配的元素的元素。内部定位器是相对于外部定位器查询的。例如,具有 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。#

      请注意,外部和内部定位器必须属于同一个框架。内部定位器不得包含 FrameLocator。

    • hasText? <string|RegExp> 匹配在内部某处包含指定文本的元素,可能在子元素或后代元素中。当传递 string 时,匹配不区分大小写并搜索子字符串。例如,"Playwright" 匹配 <article><div>Playwright</div></article>。#

  • returns: <Locator>#

此方法根据选项缩小现有 locator 的范围，例如按文本过滤。它可以链接以进行多次过滤。

const rowLocator = page.locator('tr');
// ...
await rowLocator
    .filter({ hasText: 'text in column 1' })
    .filter({ has: page.getByRole('button', { name: 'column 2 button' }) })
    .screenshot();

locator.first()​

Added in: v1.14

返回指向第一个匹配元素的 locator。

locator.focus([options])​

Added in: v1.14

在元素上调用 focus。

locator.frameLocator(selector)​

Added in: v1.17

在使用 iframe 时，您可以创建一个 frame locator，它将进入 iframe 并允许在该 iframe 中选择元素：

const locator = page.frameLocator('iframe').getByText('Submit');
await locator.click();

locator.getAttribute(name[, options])​

Added in: v1.14

返回元素属性值。

locator.getByAltText(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配:区分大小写且完整字符串。默认为 false。在通过正则表达式定位时忽略。请注意,精确匹配仍然会修剪空格。#
  • returns: <Locator>#

允许通过其 alt 文本定位元素。例如，此方法将通过 alt 文本 "Castle" 查找图像：

<img alt='Castle'>

locator.getByLabel(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配:区分大小写且完整字符串。默认为 false。在通过正则表达式定位时忽略。请注意,精确匹配仍然会修剪空格。#
  • returns: <Locator>#

允许通过关联标签的文本定位输入元素。例如，此方法将在以下 DOM 中通过标签文本 Password 查找输入：

<label for="password-input">Password:</label>
<input id="password-input">

locator.getByPlaceholder(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配:区分大小写且完整字符串。默认为 false。在通过正则表达式定位时忽略。请注意,精确匹配仍然会修剪空格。#
  • returns: <Locator>#

允许通过占位符文本定位输入元素。例如，此方法将通过占位符 "Country" 查找输入：

<input placeholder="Country">

locator.getByRole(role[, options])​

Added in: v1.27

  • role <"alert"|"alertdialog"|"application"|"article"|"banner"|"blockquote"|"button"|"caption"|"cell"|"checkbox"|"code"|"columnheader"|"combobox"|"complementary"|"contentinfo"|"definition"|"deletion"|"dialog"|"directory"|"document"|"emphasis"|"feed"|"figure"|"form"|"generic"|"grid"|"gridcell"|"group"|"heading"|"img"|"insertion"|"link"|"list"|"listbox"|"listitem"|"log"|"main"|"marquee"|"math"|"meter"|"menu"|"menubar"|"menuitem"|"menuitemcheckbox"|"menuitemradio"|"navigation"|"none"|"note"|"option"|"paragraph"|"presentation"|"progressbar"|"radio"|"radiogroup"|"region"|"row"|"rowgroup"|"rowheader"|"scrollbar"|"search"|"searchbox"|"separator"|"slider"|"spinbutton"|"status"|"strong"|"subscript"|"superscript"|"switch"|"tab"|"table"|"tablist"|"tabpanel"|"term"|"textbox"|"time"|"timer"|"toolbar"|"tooltip"|"tree"|"treegrid"|"treeitem"> 必需的 aria 角色。#

  • options? <Object>

    • checked? <boolean> 通常由 aria-checked 或原生 <input type=checkbox> 控件设置的属性。checked 的可用值为 true、false 和 "mixed"。#

      了解更多关于 aria-checked 的信息。

    • disabled? <boolean> 通常由 aria-disabled 或 disabled 设置的布尔属性。#

      note

      与大多数其他属性不同,disabled 通过 DOM 层次结构继承。了解更多关于 aria-disabled 的信息。

    • expanded? <boolean> 通常由 aria-expanded 设置的布尔属性。#

      了解更多关于 aria-expanded 的信息。

    • includeHidden? <boolean> 控制是否匹配隐藏元素的布尔属性。默认情况下,仅匹配 ARIA 定义的非隐藏元素。#

      了解更多关于 aria-hidden 的信息。

    • level? <number> 通常存在于 heading、listitem、row、treeitem 角色的数字属性,<h1>-<h6> 元素具有默认值。#

      了解更多关于 aria-level 的信息。

    • name? <string|RegExp> 匹配可访问名称的字符串属性。#

      了解更多关于可访问名称的信息。

    • pressed? <boolean> 通常由 aria-pressed 设置的属性。pressed 的可用值为 true、false 和 "mixed"。#

      了解更多关于 aria-pressed 的信息。

    • selected? <boolean> 通常由 aria-selected 设置的布尔属性。#

      了解更多关于 aria-selected 的信息。

  • returns: <Locator>#

允许通过其 ARIA role、ARIA attributes 和 accessible name 定位元素。请注意，role selector 不能替代 可访问性审计和一致性测试，而是提供有关 ARIA 准则的早期反馈。

请注意，许多 html 元素具有 role selector 识别的隐式 定义角色。您可以在此处找到所有 支持的角色。ARIA 准则 不建议 通过将 role 和/或 aria-* 属性设置为默认值来重复隐式角色和属性。

locator.getByTestId(testId)​

Added in: v1.27

通过测试 id 定位元素。默认情况下，data-testid 属性用作测试 id。如有必要，使用 selectors.setTestIdAttribute(attributeName) 配置不同的测试 id 属性。

locator.getByText(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配:区分大小写且完整字符串。默认为 false。在通过正则表达式定位时忽略。请注意,精确匹配仍然会修剪空格。#
  • returns: <Locator>#

允许定位包含给定文本的元素。考虑以下 DOM 结构：

<div>Hello <span>world</span></div>
<div>Hello</div>

您可以通过文本子字符串、精确字符串或正则表达式进行定位：

// Matches <span>
page.getByText('world')

// Matches first <div>
page.getByText('Hello world')

// Matches second <div>
page.getByText('Hello', { exact: true })

// Matches both <div>s
page.getByText(/Hello/)

// Matches second <div>
page.getByText(/^hello$/i)

另请参阅 locator.filter([options])，它允许按其他标准（如可访问角色）进行匹配，然后按文本内容进行过滤。

note

按文本匹配总是规范化空白，即使是精确匹配也是如此。例如，它将多个空格转换为一个，将换行符转换为空格，并忽略前导和尾随空白。

note

类型为 button 和 submit 的输入元素通过其 value 而不是文本内容进行匹配。例如，通过文本 "Log in" 定位匹配 <input type=button value="Log in">。

locator.getByTitle(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配:区分大小写且完整字符串。默认为 false。在通过正则表达式定位时忽略。请注意,精确匹配仍然会修剪空格。#
  • returns: <Locator>#

允许通过其标题定位元素。例如，此方法将通过其标题 "Submit" 查找按钮：

<button title='Place the order'>Order Now</button>

locator.highlight()​

Added in: v1.20

在屏幕上高亮显示相应的元素。用于调试，不要提交使用 locator.highlight() 的代码。

locator.hover([options])​

Added in: v1.14
  • options? <Object>
    • force? <boolean> 是否绕过可操作性检查。默认为 false。#
    • modifiers? <Array<"Alt"|"Control"|"Meta"|"Shift">> 要按下的修饰键。确保在操作期间仅按下这些修饰键,然后恢复当前的修饰键。如果未指定,则使用当前按下的修饰键。#
    • position? <Object> 相对于元素内边距框左上角使用的点。如果未指定,则使用元素的某个可见点。#
    • timeout? <number> 最大时间(毫秒),默认为 30 秒,传入 0 可禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 当设置时,此方法仅执行可操作性检查并跳过操作。默认为 false。适用于等待元素准备好操作而不执行它。#
  • returns: <Promise<void>>#

此方法通过执行以下步骤悬停在元素上：

  1. 等待元素上的 可操作性 检查，除非设置了 force 选项。
  2. 如果需要，将元素滚动到视图中。
  3. 使用 page.mouse 悬停在元素的中心或指定的 position 上。
  4. 等待启动的导航成功或失败，除非设置了 noWaitAfter 选项。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法将抛出异常。

当所有步骤组合在指定的 timeout 期间未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

locator.innerHTML([options])​

Added in: v1.14

返回 element.innerHTML。

locator.innerText([options])​

Added in: v1.14

返回 element.innerText。

locator.inputValue([options])​

Added in: v1.14

返回所选 <input>、<textarea> 或 <select> 元素的 input.value。

对于非输入元素抛出异常。但是，如果元素位于具有关联 control 的 <label> 元素内，则返回控件的值。

locator.isChecked([options])​

Added in: v1.14

返回元素是否被选中。如果元素不是复选框或单选输入框，则抛出异常。

locator.isDisabled([options])​

Added in: v1.14

返回元素是否被禁用，与 enabled 相反。

locator.isEditable([options])​

Added in: v1.14

返回元素是否 可编辑。

locator.isEnabled([options])​

Added in: v1.14

返回元素是否 启用。

locator.isHidden([options])​

Added in:v1.14

返回元素是否隐藏，与 visible 相反。

locator.isVisible([options])​

Added in: v1.14

返回元素是否 可见。

locator.last()​

Added in: v1.14

返回指向最后一个匹配元素的 locator。

locator.locator(selector[, options])​

Added in: v1.14

  • selector <string> 解析 DOM 元素时使用的选择器。有关更多详细信息,请参阅使用选择器。#

  • options? <Object>

    • has? <Locator> 匹配包含与内部定位器匹配的元素的元素。内部定位器是相对于外部定位器查询的。例如,具有 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。#

      请注意,外部和内部定位器必须属于同一个框架。内部定位器不得包含 FrameLocator。

    • hasText? <string|RegExp> 匹配在内部某处包含指定文本的元素,可能在子元素或后代元素中。当传递 string 时,匹配不区分大小写并搜索子字符串。例如,"Playwright" 匹配 <article><div>Playwright</div></article>。#

  • returns: <Locator>#

该方法在 locator 的子树中查找与指定选择器匹配的元素。它还接受过滤选项，类似于 locator.filter([options]) 方法。

了解更多关于 locators 的信息。

locator.nth(index)​

Added in: v1.14

返回指向第 n 个匹配元素的 locator。它是从零开始的，nth(0) 选择第一个元素。

locator.page()​

Added in: v1.19

此 locator 所属的页面。

locator.press(key[, options])​

Added in: v1.14
  • key <string> Name of the key to press or a character to generate, such as ArrowLeft or a.#
  • options? <Object>
    • delay? <number> keydown 和 keyup 之间的等待时间(以毫秒为单位)。默认为 0。#
    • noWaitAfter? <boolean> 启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志来选择退出等待。您只需要在特殊情况下使用此选项，例如导航到无法访问的页面。默认为 false。#
    • timeout? <number> 最长时间(以毫秒为单位)，默认为 30 秒，传递 0 可禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
  • returns: <Promise<void>>#

聚焦元素，然后使用 keyboard.down(key) 和 keyboard.up(key)。

key 可以指定预期的 keyboardEvent.key 值或要为其生成文本的单个字符。可以在此处找到 key 值的超集。键的示例如下：

F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp 等。

还支持以下修饰键快捷方式：Shift、Control、Alt、Meta、ShiftLeft。

按住 Shift 将输入与大写 key 对应的文本。

如果 key 是单个字符，则区分大小写，因此值 a 和 A 将生成不同的相应文本。

也支持快捷键，如 key: "Control+o" 或 key: "Control+Shift+T"。当指定修饰符时，修饰符被按下并保持，同时按下后续键。

locator.screenshot([options])​

Added in: v1.14

  • options? <Object>

    • animations? <"disabled"|"allow"> 当设为 "disabled" 时，将暂停 CSS 动画、CSS 过渡和 Web Animations。不同持续时间的动画会受到不同处理：#

      • 有限时长的动画会被快速推进至完成状态，从而触发 transitionend 事件。
      • 无限循环的动画会被重置到初始状态，并在截图完成后重新播放。

      默认值为 "allow"，即保留动画原样。

    • caret? <"hide"|"initial"> 设为 "hide" 时，截图中将隐藏文本光标；设为 "initial" 时，文本光标行为保持不变。默认值为 "hide"。#

    • mask? <Array<Locator>> 指定在截图时需要遮盖的定位器。被遮盖的元素将被一个粉色（#FF00FF）方框完全覆盖其边界区域。#

    • omitBackground? <boolean> 隐藏默认的白色背景，允许截取带透明通道的图像。该选项不适用于 jpeg 格式。默认值为 false。#

    • path? <string> 保存图像的文件路径。截图格式将根据文件扩展名自动推断。若 path 为相对路径，则相对于当前工作目录解析。若未提供路径，图像将不会保存到磁盘。#

    • quality? <number> 图像质量，取值范围为 0–100。该选项不适用于 png 格式。#

    • scale? <"css"|"device"> 设为 "css" 时，截图将按页面上的每个 CSS 像素生成一个图像像素，这在高 DPI 设备上可减小截图体积；设为 "device" 时，则按设备实际像素生成，因此高 DPI 设备的截图尺寸可能翻倍甚至更大。#

      默认值为 "device"。

    • timeout? <number> 最大等待时间（单位：毫秒），默认为 30 秒。传入 0 可禁用超时。该默认值可通过 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法修改。#

    • type? <"png"|"jpeg"> 指定截图格式，默认为 png。#

  • 返回值： <Promise<Buffer>>#

此方法捕获页面的屏幕截图，并剪裁到与 locator 匹配的特定元素的大小和位置。如果元素被其他元素覆盖，则它在屏幕截图中实际上不可见。如果元素是可滚动容器，则只有当前滚动的内容在屏幕截图中可见。

此方法等待 可操作性 检查，然后在截取屏幕截图之前将元素滚动到视图中。如果元素从 DOM 中分离，该方法将抛出错误。

返回包含捕获的屏幕截图的缓冲区。

locator.scrollIntoViewIfNeeded([options])​

Added in:v1.14

此方法会先等待 可操作性 检查通过，然后尝试将目标元素滚动到视口内——仅当该元素根据 IntersectionObserver 的 intersectionRatio 判定为未完全可见时才会执行滚动。

locator.selectOption(values[, options])​

Added in: v1.14
  • values <null|string|ElementHandle|Array<string>|Object|Array<ElementHandle>|Array<Object>> 要选择的选项。如果 <select> 元素具有 multiple 属性，则所有匹配的选项都会被选中；否则，仅第一个匹配的选项会被选中。字符串值等价于 {value: 'string'}。只有当选项的所有指定属性都匹配时，才视为匹配项。#
    • value? <string> 通过 option.value 匹配。可选。
    • label? <string> 通过 option.label（即选项文本）匹配。可选。
    • index? <number> 通过选项在 <select> 中的索引位置匹配。可选。
  • options? <Object>
    • force? <boolean> 是否跳过 可操作性 检查。默认为 false。#
    • noWaitAfter? <boolean> 默认情况下，若操作会触发页面导航，Playwright 会等待导航开始。设置此选项为 true 可跳过该等待。仅在特殊场景（如跳转到不可访问的页面）下才需要使用。默认为 false。#
    • timeout? <number> 最大等待时间（单位：毫秒），默认为 30 秒。传入 0 可禁用超时。该默认值可通过 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法修改。#
  • 返回值： <Promise<Array<string>>> 返回实际被选中的选项的 value 值数组。#

此方法等待 可操作性 检查，等待直到所有指定的选项都出现在 <select> 元素中，并选择这些选项。

如果目标元素不是 <select> 元素，此方法将抛出错误。但是，如果元素位于具有关联 control 的 <label> 元素内，则将使用该控件。

返回已成功选择的选项值数组。

一旦选择了所有提供的选项，就会触发 change 和 input 事件。

// single selection matching the value
element.selectOption('blue');

// single selection matching the label
element.selectOption({ label: 'Blue' });

// multiple selection
element.selectOption(['red', 'green', 'blue']);

locator.selectText([options])​

Added in: v1.14

此方法等待 可操作性 检查，然后聚焦元素并选择其所有文本内容。

如果元素位于具有关联 control 的 <label> 元素内，则聚焦并选择控件中的文本。

locator.setChecked(checked[, options])​

Added in: v1.15
  • checked <boolean> 是否选中或取消选中复选框。#
  • options? <Object>
    • force? <boolean> 是否绕过 可操作性 检查。默认为 false。#
    • noWaitAfter? <boolean> 启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志来选择退出等待。您只需要在特殊情况下使用此选项，例如导航到无法访问的页面。默认为 false。#
    • position? <Object> 相对于元素填充框左上角使用的点。如果未指定，则使用元素的某个可见点。#
    • timeout? <number> 最长时间(以毫秒为单位)，默认为 30 秒，传递 0 可禁用超时。可以使用 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法更改默认值。#
    • trial? <boolean> 设置后，此方法仅执行 可操作性 检查并跳过操作。默认为 false。在不执行操作的情况下等待元素准备好执行操作时很有用。#
  • returns: <Promise<void>>#

此方法通过执行以下步骤选中或取消选中元素：

  1. 确保匹配的元素是复选框或单选输入框。如果不是，此方法将抛出异常。
  2. 如果元素已经具有正确的选中状态，此方法将立即返回。
  3. 等待匹配元素上的 可操作性 检查，除非设置了 force 选项。如果在检查期间元素分离，则重试整个操作。
  4. 如果需要，将元素滚动到视图中。
  5. 使用 page.mouse 单击元素的中心。
  6. 等待启动的导航成功或失败，除非设置了 noWaitAfter 选项。
  7. 确保元素现在已选中或取消选中。如果不是，此方法将抛出异常。

当所有步骤组合在指定的 timeout 期间未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

locator.setInputFiles(files[, options])​

Added in: v1.14

将文件输入的值设置为这些文件路径或文件。如果某些 filePaths 是相对路径，则它们相对于当前工作目录进行解析。对于空数组，清除所选文件。

此方法期望 Locator 指向 input element。但是，如果元素位于具有关联 control 的 <label> 元素内，则以控件为目标。

locator.tap([options])​

Added in:v1.14
  • options? <Object>
    • force? <boolean> 是否跳过 可操作性 检查。默认为 false。#
    • modifiers? <Array<"Alt"|"Control"|"Meta"|"Shift">> 要在点击时按下的修饰键。操作期间将仅按下指定的修饰键，并在操作结束后恢复原来的修饰键状态。若未指定，则使用当前已按下的修饰键。#
    • noWaitAfter? <boolean> 默认情况下，若操作会触发页面导航，Playwright 会等待导航开始。设置此选项为 true 可跳过该等待。仅在特殊场景（如跳转到不可访问的页面）下才需要使用。默认值为 false。#
    • position? <Object> 相对于元素 padding box 左上角的坐标点。若未指定，将自动选择元素内某个可见位置进行 tap 操作。#
    • timeout? <number> 最大等待时间（单位：毫秒），默认为 30 秒。传入 0 可禁用超时。该默认值可通过 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法修改。#
    • trial? <boolean> 若设为 true，该方法仅执行 可操作性 检查，但不会实际执行 tap 操作。默认为 false。适用于仅需等待元素准备好、而不立即交互的场景。#
  • 返回值： <Promise<void>>#

此方法通过执行以下步骤点击元素：

  1. 等待元素上的 可操作性 检查，除非设置了 force 选项。
  2. 如果需要，将元素滚动到视图中。
  3. 使用 page.touchscreen 点击元素的中心或指定的 position。
  4. 等待启动的导航成功或失败，除非设置了 noWaitAfter 选项。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法将抛出异常。

当所有步骤组合在指定的 timeout 期间未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

note

element.tap() 要求浏览器上下文的 hasTouch 选项设置为 true。

locator.textContent([options])​

Added in: v1.14

返回元素的 node.textContent。

locator.type(text[, options])​

Added in:v1.14
  • text <string> 要输入到已聚焦元素中的文本。#
  • options? <Object>
    • delay? <number> 每次按键之间的延迟时间（单位：毫秒）。默认为 0，即无延迟快速输入。#
    • noWaitAfter? <boolean> 默认情况下，若操作会触发页面导航，Playwright 会等待导航开始。设置此选项为 true 可跳过该等待。仅在特殊场景（如跳转到不可访问的页面）下才需要使用。默认值为 false。#
    • timeout? <number> 最大等待时间（单位：毫秒），默认为 30 秒。传入 0 可禁用超时。该默认值可通过 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法修改。#
  • 返回值： <Promise<void>>#

聚焦元素，然后为文本中的每个字符发送 keydown、keypress/input 和 keyup 事件。

要按特殊键，如 Control 或 ArrowDown，请使用 locator.press(key[, options])。

await element.type('Hello'); // Types instantly
await element.type('World', {delay: 100}); // Types slower, like a user

在文本字段中输入然后提交表单的示例：

const element = page.getByLabel('Password');
await element.type('my password');
await element.press('Enter');

locator.uncheck([options])​

Added in: v1.14
  • options? <Object>
    • force? <boolean> 是否跳过 可操作性 检查。默认为 false。#
    • noWaitAfter? <boolean> 默认情况下，若操作会触发页面导航，Playwright 会等待导航开始。设置此选项为 true 可跳过该等待。仅在特殊场景（如跳转到不可访问的页面）下才需要使用。默认值为 false。#
    • position? <Object> 相对于元素 padding box 左上角的点击坐标点。若未指定，将自动选择元素内某个可见位置进行操作。#
    • timeout? <number> 最大等待时间（单位：毫秒），默认为 30 秒。传入 0 可禁用超时。该默认值可通过 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法修改。#
    • trial? <boolean> 若设为 true，该方法仅执行 可操作性 检查，但不会实际执行取消勾选操作。默认为 false。适用于仅需等待元素准备好、而不立即交互的场景。#
  • 返回值： <Promise<void>>#

此方法通过执行以下步骤选中元素：

  1. 确保元素是复选框或单选输入框。如果不是，此方法将抛出异常。如果元素已取消选中，此方法将立即返回。
  2. 等待元素上的 可操作性 检查，除非设置了 force 选项。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.mouse 单击元素的中心。
  5. 等待启动的导航成功或失败，除非设置了 noWaitAfter 选项。
  6. 确保元素现在已取消选中。如果不是，此方法将抛出异常。

如果元素在操作期间的任何时刻从 DOM 中分离，此方法将抛出异常。

当所有步骤组合在指定的 timeout 期间未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

locator.waitFor([options])​

Added in:v1.16
  • options? <Object>
    • state? <"attached"|"detached"|"visible"|"hidden"> 等待元素达到指定的状态。默认值为 'visible'。可选值包括：#
      • 'attached' — 等待元素出现在 DOM 中。
      • 'detached' — 等待元素从 DOM 中移除。
      • 'visible' — 等待元素具有非空的边界框（bounding box）且未设置 visibility: hidden。注意：无内容或设置了 display: none 的元素边界框为空，因此不被视为可见。
      • 'hidden' — 等待元素要么从 DOM 中移除，要么边界框为空，要么设置了 visibility: hidden。此状态是 'visible' 的反面。
    • timeout? <number> 最大等待时间（单位：毫秒），默认为 30 秒。传入 0 可禁用超时。该默认值可通过 browserContext.setDefaultTimeout(timeout) 或 page.setDefaultTimeout(timeout) 方法修改。#
  • 返回值： <Promise<void>>#

当 locator 指定的元素满足 state 选项时返回。

如果目标元素已满足条件，则该方法立即返回。否则，等待最多 timeout 毫秒，直到满足条件。

const orderSent = page.locator('#order-sent');
await orderSent.waitFor();