跳到主要内容

Locator

定位器是 Playwright 自动等待和重试机制的核心。在简而言之，定位器代表了一种在任意时刻查找页面上元素的方法。可以通过 page.locator() 方法创建定位器。

了解更多关于定位器。

方法​

all​

新增于: v1.29 locator.all

当定位器指向一组元素时，该方法返回一个定位器数组，分别指向各自的元素。

备注

locator.all() 不会等待元素与定位器匹配，而是立即返回页面上当前存在的内容。

如果元素列表是动态变化的，locator.all() 可能会产生不可预测且不稳定的结果。

如果元素列表是稳定的，但动态加载，请在调用 locator.all() 之前等待完整列表加载完成。

用法

for li in page.get_by_role('listitem').all():
  li.click();

返回值

all_inner_texts​

新增于: v1.14 locator.all_inner_texts

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

断言文本

如果你需要断言页面上的文本，建议使用带有 use_inner_text 选项的 expect(locator).to_have_text() 以避免不稳定。详见断言指南。

用法

texts = page.get_by_role("link").all_inner_texts()

返回值

all_text_contents​

新增于: v1.14 locator.all_text_contents

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

断言文本

如果你需要断言页面上的文本，建议使用 expect(locator).to_have_text() 以避免不稳定。详见断言指南。

用法

texts = page.get_by_role("link").all_text_contents()

返回值

and_​

新增于: v1.34 locator.and_

创建一个同时匹配当前定位器和参数定位器的定位器。

用法

以下示例查找具有特定标题的按钮。

button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))

参数

  • locator Locator#

    需要同时匹配的额外定位器。

返回值

aria_snapshot​

新增于: v1.49 locator.aria_snapshot

捕获指定元素的 aria 快照。阅读更多关于 aria 快照 以及用于断言的 expect(locator).to_match_aria_snapshot()。

用法

page.get_by_role("link").aria_snapshot()

参数

  • ref bool (可选) 新增于: v1.52#

    为每个元素生成符号引用。捕获快照后，可以立即使用 aria-ref=<ref> 定位器对该元素执行操作。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

返回值

详细说明

该方法会捕获指定元素的 aria 快照。快照是一个字符串，表示该元素及其子元素的状态。快照可用于在测试中断言元素状态，或与未来的状态进行比较。

ARIA 快照使用 YAML 标记语言表示：

  • 对象的键为元素的角色和可选的可访问名称。
  • 值为文本内容或子元素数组。
  • 通用静态文本可用 text 键表示。

以下是 HTML 标记及其对应的 ARIA 快照：

<ul aria-label="Links">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
<ul>
- list "Links":
  - listitem:
    - link "Home"
  - listitem:
    - link "About"

blur​

新增于: v1.28 locator.blur

在元素上调用 blur。

用法

locator.blur()
locator.blur(**kwargs)

参数

返回值

bounding_box​

新增于: v1.14 locator.bounding_box

该方法返回与定位器匹配的元素的边界框（bounding box），如果元素不可见则返回 null。边界框是相对于主框架视口计算的——通常与浏览器窗口一致。

用法

box = page.get_by_role("button").bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

参数

返回值

  • NoneType | Dict#

    • x float

      元素的 x 坐标（像素）。

    • y float

      元素的 y 坐标（像素）。

    • width float

      元素的宽度（像素）。

    • height float

      元素的高度（像素）。

详细说明

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

来自子 frame 的元素返回的边界框是相对于主 frame 的，不同于 Element.getBoundingClientRect。

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

check​

新增于: v1.14 locator.check

确保复选框或单选框元素被选中。

用法

page.get_by_role("checkbox").check()

参数

  • force bool (可选)#

    是否跳过actionability检查。默认为 false。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)#

    如果设置为 true，此方法只执行actionability检查并跳过实际操作。默认为 false。用于等待元素准备好执行操作但不实际执行。

返回值

详细说明

执行以下步骤：

  1. 确保元素是复选框或单选框输入。如果不是，则抛出异常。如果元素已被选中，则立即返回。
  2. 对元素执行actionability检查，除非设置了force选项。
  3. 如有需要，将元素滚动到可视区域。
  4. 使用page.mouse点击元素中心。
  5. 确保元素现在已被选中。如果没有，则抛出异常。

如果在操作过程中元素从 DOM 中移除，则会抛出异常。

如果所有步骤在指定的timeout时间内未完成，则会抛出 TimeoutError。传递 0 可禁用超时。

clear​

新增于: v1.28 locator.clear

清空输入框内容。

用法

page.get_by_role("textbox").clear()

参数

返回值

详细说明

该方法会等待actionability检查，通过聚焦元素，清空内容，并在清空后触发 input 事件。

如果目标元素不是 <input>、<textarea> 或 [contenteditable] 元素，则会抛出异常。但如果元素在带有关联控件的 <label> 内部，则会清空该控件。

click​

新增于: v1.14 locator.click

点击元素。

用法

点击一个按钮：

page.get_by_role("button").click()

在 canvas 上指定位置 Shift+右键点击：

page.locator("canvas").click(
    button="right", modifiers=["Shift"], position={"x": 23, "y": 32}
)

参数

  • button "left" | "right" | "middle" (可选)#

    默认为 left。

  • click_count int (可选)#

    默认为 1。参见 UIEvent.detail。

  • delay float (可选)#

    mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。

  • force bool (可选)#

    是否跳过 可操作性 检查。默认为 false。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

    要按下的修饰键。确保在操作期间只按下这些修饰键，操作结束后恢复当前修饰键。如果未指定，则使用当前已按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。

  • no_wait_after bool (可选)#

    已废弃

    该选项未来将默认值改为 true。

    会触发导航的操作会等待这些导航发生并等待页面开始加载。你可以通过设置此标志来选择不等待。仅在极少数情况下需要此选项，例如跳转到无法访问的页面。默认为 false。

  • position Dict (可选)#

    相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)#

    如果设置为 true，此方法只执行 可操作性 检查并跳过实际操作。默认为 false。用于等待元素准备好执行操作但不实际执行。注意，无论是否设置 trial，键盘 modifiers 都会被按下，以便测试只有在按下这些键时才可见的元素。

返回值

详细说明

该方法通过以下步骤点击元素：

  1. 对元素执行 可操作性 检查，除非设置了 force 选项。
  2. 如有需要，将元素滚动到可视区域。
  3. 使用 page.mouse 在元素中心或指定的 position 处点击。
  4. 等待发起的导航成功或失败，除非设置了 no_wait_after 选项。

如果在操作过程中元素从 DOM 中移除，则会抛出异常。

如果所有步骤在指定的 timeout 时间内未完成，则会抛出 TimeoutError。传递 0 可禁用超时。

count​

新增于: v1.14 locator.count

返回与定位器匹配的元素数量。

断言数量

如果你需要断言页面上的元素数量，建议使用 expect(locator).to_have_count() 以避免不稳定。详见断言指南。

用法

count = page.get_by_role("listitem").count()

返回值

dblclick​

新增于: v1.14 locator.dblclick

双击元素。

用法

locator.dblclick()
locator.dblclick(**kwargs)

参数

  • button "left" | "right" | "middle" (可选)#

    默认为 left。

  • delay float (可选)#

    mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。

  • force bool (可选)#

    是否跳过actionability检查。默认为 false。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

    要按下的修饰键。确保在操作期间只按下这些修饰键，操作结束后恢复当前修饰键。如果未指定，则使用当前已按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)#

    如果设置为 true，此方法只执行actionability检查并跳过实际操作。默认为 false。用于等待元素准备好执行操作但不实际执行。注意，无论是否设置 trial，键盘 modifiers 都会被按下，以便测试只有在按下这些键时才可见的元素。

返回值

详细说明

该方法通过以下步骤双击元素：

  1. 对元素执行actionability检查，除非设置了force选项。
  2. 如有需要，将元素滚动到可视区域。
  3. 使用page.mouse在元素中心或指定的position处进行双击。

如果在操作过程中元素从 DOM 中移除，则会抛出异常。

如果所有步骤在指定的timeout时间内未完成，则会抛出 TimeoutError。传递 0 可禁用超时。

备注

element.dblclick() 会触发两次 click 事件和一次 dblclick 事件。

dispatch_event​

新增于: v1.14 locator.dispatch_event

以编程方式在匹配的元素上派发事件。

用法

locator.dispatch_event("click")

参数

返回值

详细说明

上述代码片段会在元素上派发 click 事件。无论元素是否可见，都会派发 click 事件。这等同于调用 element.click()。

底层实现会根据指定的 type 创建事件实例，并用 event_init 属性进行初始化，然后在元素上派发该事件。事件默认是 composed、cancelable 并且会冒泡。

由于 event_init 是事件特有的，请参考以下事件文档以获取初始化属性列表：

你也可以将 JSHandle 作为属性值传递，以便将实时对象传递给事件：

data_transfer = page.evaluate_handle("new DataTransfer()")
locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

drag_to​

新增于: v1.18 locator.drag_to

将源元素拖动到目标元素并释放。

用法

source = page.locator("#source")
target = page.locator("#target")

source.drag_to(target)
# 或者指定相对于元素左上角的精确位置：
source.drag_to(
  target,
  source_position={"x": 34, "y": 7},
  target_position={"x": 10, "y": 20}
)

参数

  • target Locator#

    要拖动到的目标元素定位器。

  • force bool (可选)#

    是否跳过actionability检查。默认为 false。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • source_position Dict (可选)#

    在源元素内相对于内边距框左上角的点进行点击。如果未指定，则使用元素的某个可见点。

  • target_position Dict (可选)#

    在目标元素内相对于内边距框左上角的点进行释放。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)#

    如果设置为 true，此方法只执行actionability检查并跳过实际操作。默认为 false。用于等待元素准备好执行操作但不实际执行。

返回值

详细说明

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

evaluate​

新增于: v1.14 locator.evaluate

在页面中执行 JavaScript 代码，并将匹配的元素作为参数传递。

用法

参数

  • expression str#

    要在浏览器上下文中执行的 JavaScript 表达式。如果表达式的结果是函数，则会自动调用该函数。

  • arg EvaluationArgument (可选)#

    传递给 expression 的可选参数。

  • timeout float (可选)#

    在执行前等待定位器的最大时间（毫秒）。注意，定位器解析后，表达式本身的执行不受超时限制。默认为 30000（30 秒）。传递 0 可禁用超时。

返回值

详细说明

返回 expression 的返回值，调用时第一个参数为匹配的元素，第二个参数为 arg。

如果 expression 返回一个 Promise，此方法会等待 promise 解析并返回其值。

如果 expression 抛出异常或被拒绝，此方法会抛出异常。

evaluate_all​

新增于: v1.14 locator.evaluate_all

在页面中执行 JavaScript 代码，并将所有匹配的元素作为参数传递。

用法

locator = page.locator("div")
more_than_ten = locator.evaluate_all("(divs, min) => divs.length > min", 10)

参数

  • expression str#

    要在浏览器上下文中执行的 JavaScript 表达式。如果表达式的结果是函数，则会自动调用该函数。

  • arg EvaluationArgument (可选)#

    传递给 expression 的可选参数。

返回值

详细说明

返回 expression 的返回值，调用时第一个参数为所有匹配元素组成的数组，第二个参数为 arg。

如果 expression 返回一个 Promise，此方法会等待 promise 解析并返回其值。

如果 expression 抛出异常或被拒绝，此方法会抛出异常。

evaluate_handle​

新增于: v1.14 locator.evaluate_handle

在页面中执行 JavaScript 代码，将匹配的元素作为参数传递，并返回结果的 JSHandle。

用法

locator.evaluate_handle(expression)
locator.evaluate_handle(expression, **kwargs)

参数

  • expression str#

    要在浏览器上下文中执行的 JavaScript 表达式。如果表达式的结果是函数，则会自动调用该函数。

  • arg EvaluationArgument (可选)#

    传递给 expression 的可选参数。

  • timeout float (可选)#

    在执行前等待定位器的最大时间（毫秒）。注意，定位器解析后，表达式本身的执行不受超时限制。默认为 30000（30 秒）。传递 0 可禁用超时。

返回值

详细说明

返回 expression 的返回值（类型为 JSHandle），调用时第一个参数为匹配的元素，第二个参数为 arg。

locator.evaluate() 和 locator.evaluate_handle() 的唯一区别是 locator.evaluate_handle() 返回 JSHandle。

如果 expression 返回一个 Promise，此方法会等待 promise 解析并返回其值。

如果 expression 抛出异常或被拒绝，此方法会抛出异常。

详见 page.evaluate_handle()。

fill​

新增于: v1.14 locator.fill

为输入框设置内容。

用法

page.get_by_role("textbox").fill("示例内容")

参数

返回值

详细说明

该方法会等待 可操作性 检查，聚焦元素，填充内容，并在填充后触发 input 事件。注意，可以传递空字符串以清空输入框内容。

如果目标元素不是 <input>、<textarea> 或 [contenteditable] 元素，则会抛出异常。但如果元素在带有关联控件的 <label> 内部，则会填充该控件。

如需发送更细粒度的键盘事件，请使用 locator.press_sequentially()。

filter​

新增于: v1.22 locator.filter

该方法根据选项对已有定位器进行进一步筛选，例如按文本过滤。可以链式调用多次进行多重过滤。

用法

row_locator = page.locator("tr")
# ...
row_locator.filter(has_text="第1列中的文本").filter(
    has=page.get_by_role("button", name="第2列按钮")
).screenshot()

参数

  • has Locator (可选)#

    仅保留包含匹配该相对定位器元素的结果。例如，article 包含 text=Playwright 匹配 <article><div>Playwright</div></article>。

    内部定位器必须是相对于外部定位器，并且是从外部定位器匹配的元素开始查询，而不是从文档根节点。例如，可以在 <article><content><div>Playwright</div></content></article> 中查找包含 div 的 content。但查找包含 article div 的 content 会失败，因为内部定位器必须是相对的，不能使用 content 之外的元素。

    注意，外部和内部定位器必须属于同一个 frame。内部定位器不能包含 FrameLocator。

  • has_not Locator (可选) 新增于: v1.33#

    匹配不包含内部定位器匹配元素的元素。内部定位器会在外部定位器上查询。例如，article 不包含 div 匹配 <article><span>Playwright</span></article>。

    注意，外部和内部定位器必须属于同一个 frame。内部定位器不能包含 FrameLocator。

  • has_not_text str | Pattern (可选) 新增于: v1.33#

    匹配内部（包括子元素或后代元素）不包含指定文本的元素。如果传入 [字符串]，匹配时不区分大小写，并查找子串。

  • has_text str | Pattern (可选)#

    匹配内部（包括子元素或后代元素）包含指定文本的元素。如果传入 [字符串]，匹配时不区分大小写，并查找子串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

  • visible bool (可选) 新增于: v1.51#

    仅匹配可见或不可见的元素。

返回值

focus​

新增于: v1.14 locator.focus

在匹配的元素上调用 focus。

用法

locator.focus()
locator.focus(**kwargs)

参数

返回值

frame_locator​

新增于: v1.17 locator.frame_locator

在处理 iframe 时，可以创建一个 frame 定位器，进入 iframe 并在该 iframe 内定位元素：

用法

locator = page.frame_locator("iframe").get_by_text("提交")
locator.click()

参数

  • selector str#

    用于解析 DOM 元素的选择器。

返回值

get_attribute​

新增于: v1.14 locator.get_attribute

返回匹配元素的属性值。

断言属性

如果你需要断言元素的属性，建议使用 expect(locator).to_have_attribute() 以避免不稳定。详见断言指南。

用法

locator.get_attribute(name)
locator.get_attribute(name, **kwargs)

参数

返回值

get_by_alt_text​

新增于: v1.27 locator.get_by_alt_text

允许通过元素的 alt 文本定位元素。

用法

例如，以下方法会通过 alt 文本 "Playwright logo" 查找图片：

<img alt='Playwright logo'>
page.get_by_alt_text("Playwright logo").click()

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意，精确匹配仍会去除首尾空白字符。

返回值

get_by_label​

新增于: v1.27 locator.get_by_label

允许通过关联 <label> 或 aria-labelledby 元素的文本，或通过 aria-label 属性定位输入元素。

用法

例如，以下方法会在如下 DOM 中通过标签 "Username" 和 "Password" 查找输入框：

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
page.get_by_label("Username").fill("john")
page.get_by_label("Password").fill("secret")

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意，精确匹配仍会去除首尾空白字符。

返回值

get_by_placeholder​

新增于: v1.27 locator.get_by_placeholder

允许通过 placeholder 占位符文本定位输入元素。

用法

例如，考虑如下 DOM 结构：

<input type="email" placeholder="name@example.com" />

你可以通过 placeholder 文本定位后填充输入框：

page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意，精确匹配仍会去除首尾空白字符。

返回值

get_by_role​

新增于: v1.27 locator.get_by_role

允许通过元素的 ARIA 角色、ARIA 属性 和 可访问名称 定位元素。

用法

考虑如下 DOM 结构：

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

你可以通过元素的隐式角色定位每个元素：

expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

page.get_by_role("checkbox", name="Subscribe").check()

page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click()

参数

  • 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 角色。

  • checked bool (可选)#

    通常由 aria-checked 或原生 <input type=checkbox> 控件设置的属性。

    了解更多关于 aria-checked。

  • disabled bool (可选)#

    通常由 aria-disabled 或 disabled 设置的属性。

    备注

    与大多数其他属性不同，disabled 会在 DOM 层级中继承。了解更多关于 aria-disabled。

  • exact bool (可选) 新增于: v1.28#

    是否精确匹配 name：区分大小写且全字符串匹配。默认为 false。当 name 为正则表达式时忽略该选项。注意，精确匹配仍会去除首尾空白字符。

  • expanded bool (可选)#

    通常由 aria-expanded 设置的属性。

    了解更多关于 aria-expanded。

  • include_hidden bool (可选)#

    控制是否匹配隐藏元素的选项。默认情况下，仅匹配非隐藏元素，详见 ARIA 定义。

    了解更多关于 aria-hidden。

  • level int (可选)#

    通常用于 heading、listitem、row、treeitem 角色的数字属性，<h1>-<h6> 元素有默认值。

    了解更多关于 aria-level。

  • name str | Pattern (可选)#

    用于匹配 可访问名称 的选项。默认情况下，匹配不区分大小写并查找子串，可通过 exact 控制此行为。

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

  • pressed bool (可选)#

    通常由 aria-pressed 设置的属性。

    了解更多关于 aria-pressed。

  • selected bool (可选)#

    通常由 aria-selected 设置的属性。

    了解更多关于 aria-selected。

返回值

详细说明

角色选择器不会替代可访问性审查和合规性测试，但可以对 ARIA 指南提供早期反馈。

许多 HTML 元素有隐式定义的角色，角色选择器可以识别这些角色。你可以在这里查看所有支持的角色。ARIA 指南不建议通过设置 role 和/或 aria-* 属性为默认值来重复隐式角色和属性。

get_by_test_id​

新增于: v1.27 locator.get_by_test_id

通过测试 id 定位元素。

用法

考虑如下 DOM 结构：

<button data-testid="directions">Itinéraire</button>

你可以通过 test id 定位该元素：

page.get_by_test_id("directions").click()

参数

返回值

详细说明

默认情况下，data-testid 属性会被用作测试 id。如果需要配置不同的测试 id 属性，可以使用 selectors.set_test_id_attribute()。

get_by_text​

新增于: v1.27 locator.get_by_text

允许通过包含指定文本的方式定位元素。

另见 locator.filter()，它允许先按其他条件（如可访问角色）匹配，再按文本内容进行过滤。

用法

考虑如下 DOM 结构：

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

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

# 匹配 <span>
page.get_by_text("world")

# 匹配第一个 <div>
page.get_by_text("Hello world")

# 匹配第二个 <div>
page.get_by_text("Hello", exact=True)

# 匹配两个 <div>
page.get_by_text(re.compile("Hello"))

# 匹配第二个 <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意，精确匹配仍会去除首尾空白字符。

返回值

详细说明

按文本匹配时总是会规范化空白字符，即使是精确匹配。例如，会将多个空格合并为一个，将换行符转换为空格，并忽略首尾空白。

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

get_by_title​

新增于: v1.27 locator.get_by_title

允许通过元素的 title 属性定位元素。

用法

考虑如下 DOM 结构：

<span title='Issues count'>25 issues</span>

你可以通过 title 文本定位后检查 issues 数量：

expect(page.get_by_title("Issues count")).to_have_text("25 issues")

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意，精确匹配仍会去除首尾空白字符。

返回值

highlight​

新增于: v1.20 locator.highlight

高亮显示屏幕上的对应元素。适用于调试，请勿将使用了 locator.highlight() 的代码提交到代码库。

用法

locator.highlight()

返回值

hover​

新增于: v1.14 locator.hover

将鼠标悬停在匹配的元素上。

用法

page.get_by_role("link").hover()

参数

  • force bool (可选)#

    是否跳过 可操作性 检查。默认为 false。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

    要按下的修饰键。确保在操作期间只按下这些修饰键，操作结束后恢复当前修饰键。如果未指定，则使用当前已按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。

  • no_wait_after bool (可选) 新增于: v1.28#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)#

    如果设置为 true，此方法只执行 可操作性 检查并跳过实际操作。默认为 false。用于等待元素准备好执行操作但不实际执行。注意，无论是否设置 trial，键盘 modifiers 都会被按下，以便测试只有在按下这些键时才可见的元素。

返回值

详细说明

该方法通过以下步骤将鼠标悬停在元素上：

  1. 对元素执行 可操作性 检查，除非设置了 force 选项。
  2. 如有需要，将元素滚动到可视区域。
  3. 使用 page.mouse 在元素中心或指定的 position 处悬停。

如果在操作过程中元素从 DOM 中移除，则会抛出异常。

如果所有步骤在指定的 timeout 时间内未完成，则会抛出 TimeoutError。传递 0 可禁用超时。

inner_html​

新增于: v1.14 locator.inner_html

返回 element.innerHTML。

用法

locator.inner_html()
locator.inner_html(**kwargs)

参数

返回值

inner_text​

新增于: v1.14 locator.inner_text

返回 element.innerText。

断言文本

如果你需要断言页面上的文本，建议使用 expect(locator).to_have_text() 并配合 use_inner_text 选项，以避免不稳定。详见断言指南。

用法

locator.inner_text()
locator.inner_text(**kwargs)

参数

返回值

input_value​

新增于: v1.14 locator.input_value

返回匹配的 <input>、<textarea> 或 <select> 元素的值。

断言值

如果你需要断言输入框的值，建议使用 expect(locator).to_have_value() 以避免不稳定。详见断言指南。

用法

value = page.get_by_role("textbox").input_value()

参数

返回值

详细说明

如果元素不是 input、textarea 或 select，会抛出异常。但如果元素在带有关联控件的 <label> 内部，则返回该控件的值。

is_checked​

新增于: v1.14 locator.is_checked

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

断言选中状态

如果你需要断言复选框已被选中，建议使用 expect(locator).to_be_checked() 以避免不稳定。详见断言指南。

用法

checked = page.get_by_role("checkbox").is_checked()

参数

返回值

is_disabled​

新增于: v1.14 locator.is_disabled

返回元素是否为禁用状态，与 enabled 相反。

断言禁用状态

如果你需要断言元素为禁用状态，建议使用 expect(locator).to_be_disabled() 以避免不稳定。详见断言指南。

用法

disabled = page.get_by_role("button").is_disabled()

参数

返回值

is_editable​

新增于: v1.14 locator.is_editable

返回元素是否为 可编辑 状态。如果目标元素不是 <input>、<textarea>、<select>、[contenteditable]，且没有允许 [aria-readonly] 的角色，则该方法会抛出异常。

断言可编辑状态

如果你需要断言元素为可编辑状态，建议使用 expect(locator).to_be_editable() 以避免不稳定。详见断言指南。

用法

editable = page.get_by_role("textbox").is_editable()

参数

返回值

is_enabled​

新增于: v1.14 locator.is_enabled

返回元素是否为 可用 状态。

断言可用状态

如果你需要断言元素为可用状态，建议使用 expect(locator).to_be_enabled() 以避免不稳定。详见断言指南。

用法

enabled = page.get_by_role("button").is_enabled()

参数

返回值

is_hidden​

新增于: v1.14 locator.is_hidden

返回元素是否为隐藏状态，与 可见 相反。

断言可见性

如果你需要断言元素为隐藏状态，建议使用 expect(locator).to_be_hidden() 以避免不稳定。详见断言指南。

用法

hidden = page.get_by_role("button").is_hidden()

参数

  • timeout float (可选)#

    已废弃

    此选项无效。locator.is_hidden() 不会等待元素变为隐藏，而是立即返回。

返回值

is_visible​

新增于: v1.14 locator.is_visible

返回元素是否为 可见 状态。

断言可见性

如果你需要断言元素为可见状态，建议使用 expect(locator).to_be_visible() 以避免不稳定。详见断言指南。

用法

visible = page.get_by_role("button").is_visible()

参数

返回值

locator​

新增于: v1.14 locator.locator

该方法在当前定位器的子树中查找符合指定选择器的元素。也支持筛选选项，类似于 locator.filter() 方法。

了解更多关于定位器。

用法

locator.locator(selector_or_locator)
locator.locator(selector_or_locator, **kwargs)

参数

  • selector_or_locator str | Locator#

    用于解析 DOM 元素的选择器或定位器。

  • has Locator (可选)#

    仅保留包含匹配该相对定位器元素的结果。例如，article 包含 text=Playwright 匹配 <article><div>Playwright</div></article>。

    内部定位器必须是相对于外部定位器，并且是从外部定位器匹配的元素开始查询，而不是从文档根节点。例如，可以在 <article><content><div>Playwright</div></content></article> 中查找包含 div 的 content。但查找包含 article div 的 content 会失败，因为内部定位器必须是相对的，不能使用 content 之外的元素。

    注意，外部和内部定位器必须属于同一个 frame。内部定位器不能包含 FrameLocator。

  • has_not Locator (可选) 新增于: v1.33#

    匹配不包含内部定位器匹配元素的元素。内部定位器会在外部定位器上查询。例如，article 不包含 div 匹配 <article><span>Playwright</span></article>。

    注意，外部和内部定位器必须属于同一个 frame。内部定位器不能包含 FrameLocator。

  • has_not_text str | Pattern (可选) 新增于: v1.33#

    匹配内部（包括子元素或后代元素）不包含指定文本的元素。如果传入 [字符串]，匹配时不区分大小写，并查找子串。

  • has_text str | Pattern (可选)#

    匹配内部（包括子元素或后代元素）包含指定文本的元素。如果传入 [字符串]，匹配时不区分大小写，并查找子串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

返回值

nth​

新增于: v1.14 locator.nth

返回定位到第 n 个匹配元素的定位器。索引从 0 开始，nth(0) 选择第一个元素。

用法

banana = page.get_by_role("listitem").nth(2)

参数

返回值

or_​

新增于: v1.33 locator.or_

创建一个定位器，匹配两个定位器中任意一个或两个都匹配的所有元素。

注意，如果两个定位器都能匹配到元素，最终的定位器会有多个匹配项，可能导致定位器严格模式报错。

用法

假设你想点击“新邮件”按钮，但有时会弹出安全设置对话框。在这种情况下，你可以等待“新邮件”按钮或对话框出现，并据此进行操作。

备注

如果“新邮件”按钮和安全对话框同时出现在屏幕上，"or" 定位器会同时匹配到它们，可能会抛出“严格模式冲突”错误。此时可以使用 locator.first 只匹配其中一个。

new_email = page.get_by_role("button", name="New")
dialog = page.get_by_text("Confirm security settings")
expect(new_email.or_(dialog).first).to_be_visible()
if (dialog.is_visible()):
  page.get_by_role("button", name="Dismiss").click()
new_email.click()

参数

  • locator Locator#

    要匹配的备用定位器。

返回值

press​

新增于: v1.14 locator.press

聚焦匹配的元素并按下组合键。

用法

page.get_by_role("textbox").press("Backspace")

参数

  • key str#

    要按下的键名或要生成的字符，例如 ArrowLeft 或 a。

  • delay float (可选)#

    keydown 和 keyup 之间等待的时间（毫秒）。默认为 0。

  • no_wait_after bool (可选)#

    已废弃

    该选项未来会默认设为 true。

    会等待由该操作触发的页面跳转和页面加载。你可以通过设置此参数为 true 来跳过等待。通常只在跳转到不可访问页面等特殊场景下需要用到。默认为 false。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

返回值

详细说明

该方法会聚焦元素，然后调用 keyboard.down() 和 keyboard.up()。

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、ControlOrMeta。ControlOrMeta 在 Windows 和 Linux 上解析为 Control，在 macOS 上解析为 Meta。

按住 Shift 键会输入 key 对应的大写字符。

如果 key 是单个字符，则区分大小写，a 和 A 会分别生成不同的文本。

也支持如 key: "Control+o"、key: "Control++" 或 key: "Control+Shift+T" 这样的快捷键。当指定修饰键时，修饰键会被按下并保持，直到后续按键按下。

press_sequentially​

新增于: v1.38 locator.press_sequentially
提示

大多数情况下，你应该使用 locator.fill()。只有在页面有特殊键盘处理时，才需要逐个按键输入。

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

如需按下特殊按键（如 Control 或 ArrowDown），请使用 locator.press()。

用法

locator.press_sequentially("hello") # 立即输入
locator.press_sequentially("world", delay=100) # 慢速输入，类似用户操作

一个在文本框中输入内容并提交表单的示例：

locator = page.get_by_label("Password")
locator.press_sequentially("my password")
locator.press("Enter")

参数

  • text str#

    要依次输入到已聚焦元素中的字符字符串。

  • delay float (可选)#

    每次按键之间等待的时间（毫秒）。默认为 0。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

返回值

screenshot​

新增于: v1.14 locator.screenshot

对匹配定位器的元素进行截图。

用法

page.get_by_role("link").screenshot()

禁用动画并将截图保存到文件：

page.get_by_role("link").screenshot(animations="disabled", path="link.png")

参数

  • animations "disabled" | "allow" (可选)#

    设置为 "disabled" 时，会停止 CSS 动画、CSS 过渡和 Web 动画。动画根据其持续时间有不同处理方式：

    • 有限动画会被快进到结束，因此会触发 transitionend 事件。
    • 无限动画会被取消到初始状态，截图后再重新播放。

    默认为 "allow"，即动画保持不变。

  • caret "hide" | "initial" (可选)#

    设置为 "hide" 时，截图会隐藏文本光标。设置为 "initial" 时，文本光标行为不变。默认为 "hide"。

  • mask List[Locator] (可选)#

    指定截图时需要遮罩的定位器。被遮罩的元素会被一个粉色的盒子 #FF00FF（可通过 mask_color 自定义）完全覆盖其边界框。遮罩也会应用于不可见元素，详见仅匹配可见元素以禁用此行为。

  • mask_color str (可选) 新增于: v1.35#

    指定遮罩元素覆盖框的颜色，使用 CSS 颜色格式。默认颜色为粉色 #FF00FF。

  • omit_background bool (可选)#

    隐藏默认的白色背景，允许截图带有透明通道。对 jpeg 图片无效。默认为 false。

  • path Union[str, pathlib.Path] (可选)#

    图片保存的文件路径。截图类型会根据文件扩展名自动推断。如果 path 是相对路径，则相对于当前工作目录解析。如果未提供路径，则图片不会保存到磁盘。

  • quality int (可选)#

    图片质量，范围 0-100。对 png 图片无效。

  • scale "css" | "device" (可选)#

    设置为 "css" 时，截图每个 css 像素对应一个物理像素。对于高分辨率设备，这样可以保持截图较小。使用 "device" 选项会让每个设备像素都截图，因此高分辨率设备的截图会更大。

    默认为 "device"。

  • style str (可选) 新增于: v1.41#

    截图时应用的样式表文本。你可以在这里隐藏动态元素、让元素不可见或更改其属性，以帮助你创建可重复的截图。该样式表会穿透 Shadow DOM 并应用到内嵌 frame。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • type "png" | "jpeg" (可选)#

    指定截图类型，默认为 png。

返回值

详细说明

该方法会对页面进行截图，并裁剪为与定位器匹配的特定元素的大小和位置。如果该元素被其他元素遮挡，则截图中实际上不会显示该元素。如果元素是可滚动容器，则截图只包含当前滚动可见的内容。

该方法会等待 可操作性 检查，然后将元素滚动到可见区域后再截图。如果元素已从 DOM 中移除，则会抛出异常。

返回捕获到的截图的字节缓冲区。

scroll_into_view_if_needed​

新增于: v1.14 locator.scroll_into_view_if_needed

该方法会等待可操作性检查，然后尝试将元素滚动到可视区域，除非该元素已经完全可见（以 IntersectionObserver 的 ratio 定义为准）。

参见滚动了解其他滚动方式。

用法

locator.scroll_into_view_if_needed()
locator.scroll_into_view_if_needed(**kwargs)

参数

返回值

select_option​

新增于: v1.14 locator.select_option

在 <select> 元素中选择一个或多个选项。

用法

<select multiple>
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>
# 单选，匹配 value 或 label
element.select_option("blue")
# 单选，匹配 label
element.select_option(label="blue")
# 多选 blue、red 和第二个选项
element.select_option(value=["red", "green", "blue"])

参数

  • force bool (可选)#

    是否跳过可操作性检查。默认为 false。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • element ElementHandle | List[ElementHandle] (可选)#

    要选择的 option 元素。可选。

  • index int | List[int] (可选)#

    通过索引选择的选项。可选。

  • value str | List[str] (可选)#

    通过 value 选择的选项。如果 <select> 有 multiple 属性，则会选择所有给定选项，否则只选择第一个匹配的选项。可选。

  • label str | List[str] (可选)#

    通过 label 选择的选项。如果 <select> 有 multiple 属性，则会选择所有给定选项，否则只选择第一个匹配的选项。可选。

返回值

详细说明

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

如果目标元素不是 <select> 元素，则会抛出异常。但如果元素在带有关联控件的 <label> 内部，则会使用该控件。

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

所有选项被选中后会触发 change 和 input 事件。

select_text​

新增于: v1.14 locator.select_text

该方法会等待可操作性检查，然后聚焦元素并选中其全部文本内容。

如果元素在带有关联控件的 <label> 内部，则会聚焦并选中控件中的文本。

用法

locator.select_text()
locator.select_text(**kwargs)

参数

返回值

set_checked​

新增于: v1.15 locator.set_checked

设置复选框或单选框的选中状态。

用法

page.get_by_role("checkbox").set_checked(True)

参数

  • checked bool#

    是否选中复选框。

  • force bool (可选)#

    是否跳过可操作性检查。默认为 false。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)#

    如果设置为 true，此方法只执行可操作性检查并跳过实际操作。默认为 false。用于等待元素准备好执行操作但不实际执行。

返回值

详细说明

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

  1. 确保匹配的元素是复选框或单选框。如果不是，则抛出异常。
  2. 如果元素已经处于目标选中状态，则立即返回。
  3. 对匹配的元素执行可操作性检查，除非设置了 force 选项。如果元素在检查期间被移除，则整个操作会重试。
  4. 如有需要，将元素滚动到可视区域。
  5. 使用 page.mouse 在元素中心点击。
  6. 确保元素现在已被选中或取消选中。如果不是，则抛出异常。

如果所有步骤在指定的 timeout 时间内未完成，则会抛出 TimeoutError。传递 0 可禁用超时。

set_input_files​

新增于: v1.14 locator.set_input_files

将文件或多个文件上传到 <input type=file> 元素。对于带有 [webkitdirectory] 属性的输入，仅支持单个目录路径。

用法

# 选择单个文件
page.get_by_label("Upload file").set_input_files('myfile.pdf')

# 选择多个文件
page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt'])

# 选择一个目录
page.get_by_label("Upload directory").set_input_files('mydir')

# 移除所有已选择的文件
page.get_by_label("Upload file").set_input_files([])

# 从内存上传缓冲区
page.get_by_label("Upload file").set_input_files(
    files=[
        {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"}
    ],
)

参数

返回值

详细说明

将文件输入框的值设置为这些文件路径或文件。如果 filePaths 中有相对路径，则会相对于当前工作目录解析。传入空数组时，会清除已选择的文件。

该方法要求 Locator 指向一个 input 元素。但如果元素在带有关联控件的 <label> 内部，则会操作该控件。

tap​

新增于: v1.14 locator.tap

对匹配定位器的元素执行点击（tap）手势。关于通过手动派发触摸事件模拟其他手势的示例，请参见模拟传统触摸事件页面。

用法

locator.tap()
locator.tap(**kwargs)

参数

  • force bool (可选)#

    是否跳过可操作性检查。默认为 false。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

    要按下的修饰键。确保操作期间只按下这些修饰键，操作结束后恢复当前修饰键状态。如果未指定，则使用当前已按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)#

    如果设置为 true，此方法只执行可操作性检查并跳过实际操作。默认为 false。用于等待元素准备好执行操作但不实际执行。注意，无论是否设置 trial，键盘 modifiers 都会被按下，以便测试只有在按下这些键时才可见的元素。

返回值

详细说明

该方法通过以下步骤点击元素：

  1. 对元素执行可操作性检查，除非设置了 force 选项。
  2. 如有需要，将元素滚动到可视区域。
  3. 使用 page.touchscreen 在元素中心或指定的 position 处点击。

如果操作过程中元素从 DOM 中移除，则会抛出异常。

如果所有步骤在指定的 timeout 时间内未完成，则会抛出 TimeoutError。传递 0 可禁用超时。

备注

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

text_content​

新增于: v1.14 locator.text_content

返回 node.textContent。

断言文本

如果你需要断言页面上的文本，建议使用 expect(locator).to_have_text() 以避免不稳定。详见断言指南。

用法

locator.text_content()
locator.text_content(**kwargs)

参数

返回值

uncheck​

新增于: v1.14 locator.uncheck

确保复选框或单选框元素处于未选中状态。

用法

page.get_by_role("checkbox").uncheck()

参数

  • force bool (可选)#

    是否跳过可操作性检查。默认为 false。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

  • trial bool (可选)#

    如果设置为 true，此方法只执行可操作性检查并跳过实际操作。默认为 false。用于等待元素准备好执行操作但不实际执行。

返回值

详细说明

该方法通过以下步骤取消选中元素：

  1. 确保元素是复选框或单选框。如果不是，则抛出异常。如果元素已经是未选中状态，则立即返回。
  2. 对元素执行可操作性检查，除非设置了 force 选项。
  3. 如有需要，将元素滚动到可视区域。
  4. 使用 page.mouse 在元素中心点击。
  5. 确保元素现在已处于未选中状态。如果不是，则抛出异常。

如果操作过程中元素从 DOM 中移除，则会抛出异常。

如果所有步骤在指定的 timeout 时间内未完成，则会抛出 TimeoutError。传递 0 可禁用超时。

wait_for​

新增于: v1.16 locator.wait_for

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

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

用法

order_sent = page.locator("#order-sent")
order_sent.wait_for()

参数

  • state "attached" | "detached" | "visible" | "hidden" (可选)#

    默认为 'visible'。可选值如下：

    • 'attached' - 等待元素出现在 DOM 中。
    • 'detached' - 等待元素不在 DOM 中。
    • 'visible' - 等待元素有非空的边界框且没有 visibility:hidden。注意，没有任何内容或 display:none 的元素边界框为空，不被视为可见。
    • 'hidden' - 等待元素被移除出 DOM，或边界框为空，或 visibility:hidden。这与 'visible' 选项相反。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

返回值

属性​

content_frame​

新增于: v1.43 locator.content_frame

返回一个指向与该定位器相同 iframe 的 FrameLocator 对象。

当你已经获取了一个 Locator 对象，并且之后需要与该 frame 内部内容交互时非常有用。

反向操作请使用 frame_locator.owner。

用法

locator = page.locator("iframe[name=\"embedded\"]")
# ...
frame_locator = locator.content_frame
frame_locator.get_by_role("button").click()

返回值

first​

新增于: v1.14 locator.first

返回定位到第一个匹配元素的定位器。

用法

locator.first

返回值

last​

新增于: v1.14 locator.last

返回定位到最后一个匹配元素的定位器。

用法

banana = page.get_by_role("listitem").last

返回值

page​

新增于: v1.19 locator.page

该定位器所属的页面。

用法

locator.page

返回值

已废弃​

element_handle​

新增于: v1.14 locator.element_handle
不推荐

应始终优先使用 Locator 和 Web 断言，而不是 ElementHandle，因为后者本质上容易产生竞态问题。

将给定的定位器解析为第一个匹配的 DOM 元素。如果没有匹配元素，则会等待出现一个。如果有多个元素匹配该定位器，则会抛出异常。

用法

locator.element_handle()
locator.element_handle(**kwargs)

参数

返回值

element_handles​

新增于: v1.14 locator.element_handles
不推荐

应始终优先使用 Locator 和 Web 断言，而不是 ElementHandle，因为后者本质上容易产生竞态问题。

将给定的定位器解析为所有匹配的 DOM 元素。如果没有匹配的元素，则返回空列表。

用法

locator.element_handles()

返回值

type​

新增于: v1.14 locator.type
已废弃

大多数情况下，你应该使用 locator.fill()。只有在页面有特殊键盘处理时，才需要逐个按键输入——此时请使用 locator.press_sequentially()。

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

如需按下特殊按键（如 Control 或 ArrowDown），请使用 locator.press()。

用法

参数

  • text str#

    要输入到已聚焦元素中的文本。

  • delay float (可选)#

    每次按键之间等待的时间（毫秒）。默认为 0。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改。

返回值