Locator

Locators 是 Playwright 自动等待和重试机制的核心部分。简而言之，Locator 代表了一种在任何时刻查找页面上元素的方法。可以使用 page.locator(selector, **kwargs) 方法创建 Locator。

了解更多关于 Locator 的信息。

locator.all_inner_texts()

Added in: v1.14

返回值: <List[str]>#

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

locator.all_text_contents()

Added in: v1.14

返回值: <List[str]>#

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

locator.bounding_box(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType|Dict>#
- x <float> 元素的 x 坐标（以像素为单位）。
- y <float> 元素的 y 坐标（以像素为单位）。
- width <float> 元素的宽度（以像素为单位）。
- height <float> 元素的高度（以像素为单位）。

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

滚动会影响返回的包围盒，类似于 Element.getBoundingClientRect。这意味着 x 和/或 y 可能是负数。

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

假设页面是静态的，使用包围盒坐标执行输入是安全的。例如，以下代码片段将点击元素的中心。

Sync
Async

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

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

locator.check(**kwargs)

Added in: v1.14

force <bool> 是否绕过可操作性检查。默认为 false。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
position <Dict> 相对于元素内边距框（padding box）左上角的点。如果未指定，则使用元素的某个可见点。#
- x <float>
- y <float>
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
trial <bool> 设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备好。#
返回值: <NoneType>#

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

确保元素是复选框（checkbox）或单选按钮（radio input）。如果不是，此方法将抛出错误。如果元素已被选中，此方法将立即返回。
等待元素通过可操作性检查，除非设置了 force 选项。
如果需要，将元素滚动到视野中。
使用 page.mouse 点击元素中心。
等待发起的导航成功或失败，除非设置了 no_wait_after 选项。
确保元素现在已被选中。如果未选中，此方法将抛出错误。

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

当所有步骤在指定的 timeout 内未完成时，此方法将抛出 TimeoutError。传递 0 超时可禁用此功能。

locator.click(**kwargs)

Added in: v1.14

button <"left"|"right"|"middle"> 默认为 left。#
click_count <int> 默认为 1。参见 UIEvent.detail。#
delay <float> mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。#
force <bool> 是否绕过可操作性检查。默认为 false。#
modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保操作期间仅按下这些修饰键，然后还原当前修饰键。如果未指定，则使用当前按下的修饰键。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
position <Dict> 相对于元素内边距框（padding box）左上角的点。如果未指定，则使用元素的某个可见点。#
- x <float>
- y <float>
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
trial <bool> 设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备好。#
返回值: <NoneType>#

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

等待元素通过可操作性检查，除非设置了 force 选项。
如果需要，将元素滚动到视野中。
使用 page.mouse 点击元素中心或指定的 position。
等待发起的导航成功或失败，除非设置了 no_wait_after 选项。

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

当所有步骤在指定的 timeout 内未完成时，此方法将抛出 TimeoutError。传递 0 超时可禁用此功能。

locator.count()

Added in: v1.14

返回值: <int>#

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

locator.dblclick(**kwargs)

Added in: v1.14

button <"left"|"right"|"middle"> 默认为 left。#
delay <float> mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。#
force <bool> 是否绕过可操作性检查。默认为 false。#
modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保操作期间仅按下这些修饰键，然后还原当前修饰键。如果未指定，则使用当前按下的修饰键。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
position <Dict> 相对于元素内边距框（padding box）左上角的点。如果未指定，则使用元素的某个可见点。#
- x <float>
- y <float>
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
trial <bool> 设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备好。#
返回值: <NoneType>#

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

等待元素通过可操作性检查，除非设置了 force 选项。
如果需要，将元素滚动到视野中。
使用 page.mouse 双击元素中心或指定的 position。
等待发起的导航成功或失败，除非设置了 no_wait_after 选项。注意，如果 dblclick() 的第一次点击触发了导航事件，此方法将抛出错误。

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

当所有步骤在指定的 timeout 内未完成时，此方法将抛出 TimeoutError。传递 0 超时可禁用此功能。

note

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

locator.dispatch_event(type, **kwargs)

Added in: v1.14

type <str> DOM 事件类型："click"、"dragstart" 等。#
event_init <EvaluationArgument> 可选的事件特定初始化属性。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType>#

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

Sync
Async

element.dispatch_event("click")

await element.dispatch_event("click")

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

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

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

Sync
Async

# 注意只能在 chromium 和 firefox 中创建 data_transfer
data_transfer = page.evaluate_handle("new DataTransfer()")
element.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

# 注意只能在 chromium 和 firefox 中创建 data_transfer
data_transfer = await page.evaluate_handle("new DataTransfer()")
await element.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

locator.drag_to(target, **kwargs)

Added in: v1.18

target <Locator> 要拖动到的目标元素的 Locator。#
force <bool> 是否绕过可操作性检查。默认为 false。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
source_position <Dict> 相对于元素内边距框左上角的此点点击源元素。如果未指定，则使用元素的某个可见点。#
- x <float>
- y <float>
target_position <Dict> 相对于元素内边距框左上角的此点在目标元素上释放。如果未指定，则使用元素的某个可见点。#
- x <float>
- y <float>
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
trial <bool> 设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备好。#
返回值: <NoneType>#

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

Sync
Async

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}
)

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

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

locator.element_handle(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <ElementHandle>#

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

locator.element_handles()

Added in: v1.14

返回值: <List[ElementHandle]>#

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

locator.evaluate(expression, **kwargs)

Added in: v1.14

expression <str> 要在浏览器上下文中求值的 JavaScript 表达式。如果表达式求值为函数，则会自动调用该函数。#
arg <EvaluationArgument> 传递给 expression 的可选参数。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <Serializable>#

返回 expression 的返回值。

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

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

Examples:

Sync
Async

tweets = page.locator(".tweet .retweets")
assert tweets.evaluate("node => node.innerText") == "10 retweets"

tweets = page.locator(".tweet .retweets")
assert await tweets.evaluate("node => node.innerText") == "10 retweets"

locator.evaluate_all(expression, **kwargs)

Added in: v1.14

expression <str> 要在浏览器上下文中求值的 JavaScript 表达式。如果表达式求值为函数，则会自动调用该函数。#
arg <EvaluationArgument> 传递给 expression 的可选参数。#
返回值: <Serializable>#

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

如果 expression 返回 Promise，则 locator.evaluate_all(expression, **kwargs) 会等待 promise 解析并返回其值。

Examples:

Sync
Async

elements = page.locator("div")
div_counts = elements("(divs, min) => divs.length >= min", 10)

elements = page.locator("div")
div_counts = await elements("(divs, min) => divs.length >= min", 10)

locator.evaluate_handle(expression, **kwargs)

Added in: v1.14

expression <str> 要在浏览器上下文中求值的 JavaScript 表达式。如果表达式求值为函数，则会自动调用该函数。#
arg <EvaluationArgument> 传递给 expression 的可选参数。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <JSHandle>#

以 JSHandle 形式返回 expression 的返回值。

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

locator.evaluate(expression, **kwargs) 和 locator.evaluate_handle(expression, **kwargs) 的唯一区别在于 locator.evaluate_handle(expression, **kwargs) 返回 JSHandle。

如果传递给 locator.evaluate_handle(expression, **kwargs) 的函数返回 Promise，则 locator.evaluate_handle(expression, **kwargs) 会等待 promise 解析并返回其值。

有关更多详细信息，请参阅 page.evaluate_handle(expression, **kwargs)。

locator.fill(value, **kwargs)

Added in: v1.14

value <str> 要为 <input>、<textarea> 或 [contenteditable] 元素设置的值。#
force <bool> 是否绕过可操作性检查。默认为 false。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType>#

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

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

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

locator.filter(**kwargs)

Added in: v1.22

has <Locator> 匹配包含匹配内部 locator 的元素的元素。内部 locator 相对于外部 locator 进行查询。例如，具有 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。#
请注意，外部和内部 locator 必须属于同一框架。内部 locator 不得包含 FrameLocators。
has_text <str|Pattern> 匹配内部某处（可能是子元素或后代元素）包含指定文本的元素。传递 [string] 时，匹配不区分大小写并搜索子字符串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。#
返回值: <Locator>#

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

Sync
Async

row_locator = page.locator("tr")
# ...
row_locator
    .filter(has_text="text in column 1")
    .filter(has=page.get_by_role("button", name="column 2 button"))
    .screenshot()

row_locator = page.locator("tr")
# ...
await row_locator
    .filter(has_text="text in column 1")
    .filter(has=page.get_by_role("button", name="column 2 button"))
    .screenshot()

locator.first

Added in: v1.14

返回值: <Locator>#

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

locator.focus(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType>#

在元素上调用 focus。

locator.frame_locator(selector)

Added in: v1.17

selector <str> 解析 DOM 元素时使用的选择器。有关更多详细信息，请参阅使用选择器。#
返回值: <FrameLocator>#

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

Sync
Async

locator = page.frame_locator("iframe").get_by_text("Submit")
locator.click()

locator = page.frame_locator("iframe").get_by_text("Submit")
await locator.click()

locator.get_attribute(name, **kwargs)

Added in: v1.14

name <str> 要获取值的属性名称。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType|str>#

返回元素属性值。

locator.get_by_alt_text(text, **kwargs)

Added in: v1.27

text <str|Pattern> 要定位的元素的文本。#
exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。当按正则表达式定位时忽略此项。请注意，精确匹配仍然会修剪空白。#
返回值: <Locator>#

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

<img alt='Castle'>

locator.get_by_label(text, **kwargs)

Added in: v1.27

text <str|Pattern> 要定位的元素的文本。#
exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。当按正则表达式定位时忽略此项。请注意，精确匹配仍然会修剪空白。#
返回值: <Locator>#

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

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

locator.get_by_placeholder(text, **kwargs)

Added in: v1.27

text <str|Pattern> 要定位的元素的文本。#
exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。当按正则表达式定位时忽略此项。请注意，精确匹配仍然会修剪空白。#
返回值: <Locator>#

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

<input placeholder="Country">

locator.get_by_role(role, **kwargs)

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 角色。#
checked <bool> 通常由 aria-checked 或原生 <input type=checkbox> 控件设置的属性。checked 的可用值为 true、false 和 "mixed"。#
了解更多关于 aria-checked 的信息。
disabled <bool> 通常由 aria-disabled 或 disabled 设置的布尔属性。#
note
与大多数其他属性不同，disabled 通过 DOM 层次结构继承。了解更多关于 aria-disabled 的信息。
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> 匹配 accessible name 的字符串属性。#
了解更多关于 accessible name 的信息。
pressed <bool> 通常由 aria-pressed 设置的属性。pressed 的可用值为 true、false 和 "mixed"。#
了解更多关于 aria-pressed 的信息。
selected <bool> 通常由 aria-selected 设置的布尔属性。#
了解更多关于 aria-selected 的信息。
返回值: <Locator>#

允许通过 ARIA 角色、ARIA 属性和 accessible name 定位元素。请注意，角色选择器 不能替代 可访问性审核及合规性测试，而是提供有关 ARIA 准则的早期反馈。

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

locator.get_by_test_id(test_id)

Added in: v1.27

test_id <str> 用于定位元素的 Id。#
返回值: <Locator>#

通过测试 id 定位元素。默认情况下，使用 data-testid 属性作为测试 id。如果需要，使用 selectors.set_test_id_attribute(attribute_name) 配置不同的测试 id 属性。

locator.get_by_text(text, **kwargs)

Added in: v1.27

text <str|Pattern> 要定位的元素的文本。#
exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。当按正则表达式定位时忽略此项。请注意，精确匹配仍然会修剪空白。#
返回值: <Locator>#

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

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

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

Sync
Async

# 匹配 <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))

# 匹配 <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))

另请参阅 locator.filter(**kwargs)，它允许按其他条件（如可访问角色）匹配，然后按文本内容过滤。

note

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

note

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

locator.get_by_title(text, **kwargs)

Added in: v1.27

text <str|Pattern> 要定位的元素的文本。#
exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。当按正则表达式定位时忽略此项。请注意，精确匹配仍然会修剪空白。#
返回值: <Locator>#

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

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

locator.highlight()

Added in: v1.20

返回值: <NoneType>#

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

locator.hover(**kwargs)

Added in: v1.14

force <bool> 是否绕过可操作性检查。默认为 false。#
modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保操作期间仅按下这些修饰键，然后还原当前修饰键。如果未指定，则使用当前按下的修饰键。#
position <Dict> 相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。#
- x <float>
- y <float>
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
trial <bool> 设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备好。#
返回值: <NoneType>#

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

等待元素通过可操作性检查，除非设置了 force 选项。
如果需要，将元素滚动到视野中。
使用 page.mouse 悬停在元素中心或指定的 position 上方。
等待发起的导航成功或失败，除非设置了 no_wait_after 选项。

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

当所有步骤在指定的 timeout 内未完成时，此方法将抛出 TimeoutError。传递 0 超时可禁用此功能。

locator.inner_html(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <str>#

返回 element.innerHTML。

locator.inner_text(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <str>#

返回 element.innerText。

locator.input_value(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <str>#

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

对于非输入元素引发错误。但是，如果元素位于具有关联 control 的 <label> 元素内，则返回控件的值。

locator.is_checked(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <bool>#

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

locator.is_disabled(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <bool>#

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

locator.is_editable(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <bool>#

返回元素是否可编辑。

locator.is_enabled(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <bool>#

返回元素是否启用。

locator.is_hidden(**kwargs)

Added in: v1.14

timeout <float> 已弃用 此选项被忽略。locator.is_hidden(**kwargs) 不会等待元素变更为隐藏并立即返回。#
返回值: <bool>#

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

locator.is_visible(**kwargs)

Added in: v1.14

timeout <float> 已弃用 此选项被忽略。locator.is_visible(**kwargs) 不会等待元素变更为可见并立即返回。#
返回值: <bool>#

返回元素是否可见。

locator.last

Added in: v1.14

返回值: <Locator>#

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

locator.locator(selector, **kwargs)

Added in: v1.14

selector <str> 解析 DOM 元素时使用的选择器。有关更多详细信息，请参阅使用选择器。#
has <Locator> 匹配包含匹配内部 locator 的元素的元素。内部 locator 相对于外部 locator 进行查询。例如，具有 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。#
请注意，外部和内部 locator 必须属于同一框架。内部 locator 不得包含 FrameLocators。
has_text <str|Pattern> 匹配内部某处（可能是子元素或后代元素）包含指定文本的元素。传递 [string] 时，匹配不区分大小写并搜索子字符串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。#
返回值: <Locator>#

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

了解更多关于 Locator 的信息。

locator.nth(index)

Added in: v1.14

index <int>#
返回值: <Locator>#

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

locator.page

Added in: v1.19

返回值: <Page>#

此 locator 所属的页面。

locator.press(key, **kwargs)

Added in: v1.14

key <str> 要按下的键的名称或要生成的字符，例如 ArrowLeft 或 a。#
delay <float> keydown 和 keyup 之间等待的时间（毫秒）。默认为 0。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType>#

聚焦元素，然后使用 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, etc.

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

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

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

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

locator.screenshot(**kwargs)

Added in: v1.14

animations <"disabled"|"allow"> 当设置为 "disabled" 时，停止 CSS 动画、CSS 过渡和 Web 动画。动画的处理取决于其持续时间：#
- 有限动画快进到完成，因此它们会触发 transitionend 事件。
- 无限动画取消到初始状态，然后在截图后重新播放。
默认为 "allow"，保持动画不变。
caret <"hide"|"initial"> 当设置为 "hide" 时，截图将隐藏文本光标。当设置为 "initial" 时，文本光标行为不会改变。默认为 "hide"。#
mask <List[Locator]> 指定在截取屏幕截图时应遮罩的 locator。被遮罩的元素将被粉红色框 #FF00FF 覆盖，该框完全覆盖其边界框。#
omit_background <bool> 隐藏默认的白色背景并允许捕获带有透明度的屏幕截图。不适用于 jpeg 图像。默认为 false。#
path <Union[str, pathlib.Path]> 保存图像的文件路径。截图类型将从文件扩展名推断。如果 path 是相对路径，则相对于当前工作目录解析。如果没有提供路径，图像将不会保存到磁盘。#
quality <int> 图像质量，介于 0-100 之间。不适用于 png 图像。#
scale <"css"|"device"> 当设置为 "css" 时，截图将在页面上的每个 css 像素对应一个像素。对于高 dpi 设备，这将保持截图较小。使用 "device" 选项将为每个设备像素生成一个像素，因此高 dpi 设备的截图将大两倍或更大。#
默认为 "device"。
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
type <"png"|"jpeg"> 指定截图类型，默认为 png。#
返回值: <bytes>#

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

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

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

locator.scroll_into_view_if_needed(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType>#

此方法等待 actionability 检查，然后尝试将元素滚动到视野中，除非它根据 IntersectionObserver 的 ratio 定义完全可见。

locator.select_option(**kwargs)

Added in: v1.14

force <bool> 是否绕过 actionability 检查。默认为 false。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
element <ElementHandle|List[ElementHandle]> 要选择的选项元素。可选。#
index <int|List[int]> 按索引选择的选项。可选。#
value <str|List[str]> 按值选择的选项。如果 <select> 具有 multiple 属性，则选择所有给定的选项，否则仅选择匹配传递选项之一的第一个选项。可选。#
label <str|List[str]> 按标签选择的选项。如果 <select> 具有 multiple 属性，则选择所有给定的选项，否则仅选择匹配传递选项之一的第一个选项。可选。#
返回值: <List[str]>#

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

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

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

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

Sync
Async

# 匹配值的单选
element.select_option("blue")
# 匹配标签的单选
element.select_option(label="blue")
# 多选
element.select_option(value=["red", "green", "blue"])

# 匹配值的单选
await element.select_option("blue")
# 匹配标签的单选
await element.select_option(label="blue")
# 多选
await element.select_option(value=["red", "green", "blue"])

locator.select_text(**kwargs)

Added in: v1.14

force <bool> 是否绕过 actionability 检查。默认为 false。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType>#

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

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

locator.set_checked(checked, **kwargs)

Added in: v1.15

checked <bool> 是否选中或取消选中复选框。#
force <bool> 是否绕过 actionability 检查。默认为 false。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
position <Dict> 相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。#
- x <float>
- y <float>
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
trial <bool> 设置时，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待直到元素准备好进行操作而不执行它。#
返回值: <NoneType>#

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

确保匹配的元素是复选框或单选输入。如果不是，此方法抛出错误。
如果元素已经处于正确的选中状态，此方法立即返回。
等待匹配元素上的 actionability 检查，除非设置了 force 选项。如果元素在检查期间分离，则重试整个操作。
如果需要，将元素滚动到视野中。
使用 page.mouse 单击元素中心。
等待发起的导航成功或失败，除非设置了 no_wait_after 选项。
确保元素现在已选中或取消选中。如果不是，此方法抛出错误。

当所有步骤在指定的 timeout 内未完成时，此方法将抛出 TimeoutError。传递 0 超时可禁用此功能。

locator.set_input_files(files, **kwargs)

Added in: v1.14

files <Union[str, pathlib.Path]|List[Union[str, pathlib.Path]]|Dict|List[Dict]>#
- name <str>
- mimeType <str>
- buffer <bytes>
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType>#

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

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

locator.tap(**kwargs)

Added in: v1.14

force <bool> 是否绕过 actionability 检查。默认为 false。#
modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保仅在操作期间按下这些修饰符，然后将当前修饰符恢复原状。如果未指定，则使用当前按下的修饰符。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
position <Dict> 相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。#
- x <float>
- y <float>
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
trial <bool> 设置时，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待直到元素准备好进行操作而不执行它。#
返回值: <NoneType>#

此方法通过执行以下步骤轻触元素：

等待元素通过 actionability 检查，除非设置了 force 选项。
如果需要，将元素滚动到视野中。
使用 page.touchscreen 轻触元素中心或指定的 position。
等待发起的导航成功或失败，除非设置了 no_wait_after 选项。

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

当所有步骤在指定的 timeout 内未完成时，此方法将抛出 TimeoutError。传递 0 超时可禁用此功能。

note

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

locator.text_content(**kwargs)

Added in: v1.14

timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType|str>#

返回 node.textContent。

locator.type(text, **kwargs)

Added in: v1.14

text <str> 要键入到聚焦元素的文本。#
delay <float> 按键之间等待的时间（毫秒）。默认为 0。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType>#

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

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

Sync
Async

element.type("hello") # 立即输入
element.type("world", delay=100) # 输入较慢，像用户一样

await element.type("hello") # 立即输入
await element.type("world", delay=100) # 输入较慢，像用户一样

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

Sync
Async

element = page.get_by_label("Password")
element.type("my password")
element.press("Enter")

element = page.get_by_label("Password")
await element.type("my password")
await element.press("Enter")

locator.uncheck(**kwargs)

Added in: v1.14

force <bool> 是否绕过 actionability 检查。默认为 false。#
no_wait_after <bool> 启动导航的操作会等待这些导航发生并开始加载页面。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 false。#
position <Dict> 相对于元素内边距框左上角的点。如果未指定，则使用元素的某个可见点。#
- x <float>
- y <float>
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
trial <bool> 设置时，此方法仅执行 actionability 检查并跳过操作。默认为 false。用于等待直到元素准备好进行操作而不执行它。#
返回值: <NoneType>#

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

确保元素是复选框或单选输入。如果不是，此方法抛出错误。如果元素已经取消选中，此方法立即返回。
等待 actionability 检查，除非设置了 force 选项。
如果需要，将元素滚动到视野中。
使用 page.mouse 单击元素中心。
等待发起的导航成功或失败，除非设置了 no_wait_after 选项。
确保元素现在已取消选中。如果不是，此方法抛出错误。

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

当所有步骤在指定的 timeout 内未完成时，此方法将抛出 TimeoutError。传递 0 超时可禁用此功能。

locator.wait_for(**kwargs)

Added in: v1.16

state <"attached"|"detached"|"visible"|"hidden"> 默认为 'visible'。可以是以下之一：#
- 'attached' - 等待元素出现在 DOM 中。
- 'detached' - 等待元素不出现在 DOM 中。
- 'visible' - 等待元素具有非空边界框且没有 visibility:hidden。请注意，没有任何内容或具有 display:none 的元素具有空边界框，并且不被视为可见。
- 'hidden' - 等待元素从 DOM 中分离，或具有空边界框或 visibility:hidden。这与 'visible' 选项相反。
timeout <float> 以毫秒为单位的最大时间，默认为 30 秒，传递 0 可禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法更改默认值。#
返回值: <NoneType>#

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

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

Sync
Async

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

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

locator.all_inner_texts()​

locator.all_text_contents()​

locator.bounding_box(**kwargs)​

locator.check(**kwargs)​

locator.click(**kwargs)​

locator.count()​

locator.dblclick(**kwargs)​

locator.dispatch_event(type, **kwargs)​

locator.drag_to(target, **kwargs)​

locator.element_handle(**kwargs)​

locator.element_handles()​

locator.evaluate(expression, **kwargs)​

locator.evaluate_all(expression, **kwargs)​

locator.evaluate_handle(expression, **kwargs)​

locator.fill(value, **kwargs)​

locator.filter(**kwargs)​

locator.first​

locator.focus(**kwargs)​

locator.frame_locator(selector)​

locator.get_attribute(name, **kwargs)​

locator.get_by_alt_text(text, **kwargs)​

locator.get_by_label(text, **kwargs)​

locator.get_by_placeholder(text, **kwargs)​

locator.get_by_role(role, **kwargs)​

locator.get_by_test_id(test_id)​

locator.get_by_text(text, **kwargs)​

locator.get_by_title(text, **kwargs)​

locator.highlight()​

locator.hover(**kwargs)​

locator.inner_html(**kwargs)​

locator.inner_text(**kwargs)​

locator.input_value(**kwargs)​

locator.is_checked(**kwargs)​

locator.is_disabled(**kwargs)​

locator.is_editable(**kwargs)​

locator.is_enabled(**kwargs)​

locator.is_hidden(**kwargs)​

locator.is_visible(**kwargs)​

locator.last​

locator.locator(selector, **kwargs)​

locator.nth(index)​

locator.page​

locator.press(key, **kwargs)​

locator.screenshot(**kwargs)​

locator.scroll_into_view_if_needed(**kwargs)​

locator.select_option(**kwargs)​

locator.select_text(**kwargs)​

locator.set_checked(checked, **kwargs)​

locator.set_input_files(files, **kwargs)​

locator.tap(**kwargs)​

locator.text_content(**kwargs)​

locator.type(text, **kwargs)​

locator.uncheck(**kwargs)​

locator.wait_for(**kwargs)​

locator.all_inner_texts()

locator.all_text_contents()

locator.bounding_box(**kwargs)

locator.check(**kwargs)

locator.click(**kwargs)

locator.count()

locator.dblclick(**kwargs)

locator.dispatch_event(type, **kwargs)

locator.drag_to(target, **kwargs)

locator.element_handle(**kwargs)

locator.element_handles()

locator.evaluate(expression, **kwargs)

locator.evaluate_all(expression, **kwargs)

locator.evaluate_handle(expression, **kwargs)

locator.fill(value, **kwargs)

locator.filter(**kwargs)

locator.first

locator.focus(**kwargs)

locator.frame_locator(selector)

locator.get_attribute(name, **kwargs)

locator.get_by_alt_text(text, **kwargs)

locator.get_by_label(text, **kwargs)

locator.get_by_placeholder(text, **kwargs)

locator.get_by_role(role, **kwargs)

locator.get_by_test_id(test_id)

locator.get_by_text(text, **kwargs)

locator.get_by_title(text, **kwargs)

locator.highlight()

locator.hover(**kwargs)

locator.inner_html(**kwargs)

locator.inner_text(**kwargs)

locator.input_value(**kwargs)

locator.is_checked(**kwargs)

locator.is_disabled(**kwargs)

locator.is_editable(**kwargs)

locator.is_enabled(**kwargs)

locator.is_hidden(**kwargs)

locator.is_visible(**kwargs)

locator.last

locator.locator(selector, **kwargs)

locator.nth(index)

locator.page

locator.press(key, **kwargs)

locator.screenshot(**kwargs)

locator.scroll_into_view_if_needed(**kwargs)

locator.select_option(**kwargs)

locator.select_text(**kwargs)

locator.set_checked(checked, **kwargs)

locator.set_input_files(files, **kwargs)

locator.tap(**kwargs)

locator.text_content(**kwargs)

locator.type(text, **kwargs)

locator.uncheck(**kwargs)

locator.wait_for(**kwargs)