Skip to main content

Frame

在任何时候，页面都通过 page.main_frame 和 frame.child_frames 方法公开其当前的框架树。

Frame 对象的生命周期由在页面对象上分发的三个事件控制：

转储框架树的示例：

from playwright.sync_api import sync_playwright

def run(playwright):
    firefox = playwright.firefox
    browser = firefox.launch()
    page = browser.new_page()
    page.goto("https://www.theverge.com")
    dump_frame_tree(page.main_frame, "")
    browser.close()

def dump_frame_tree(frame, indent):
    print(indent + frame.name + '@' + frame.url)
    for child in frame.child_frames:
        dump_frame_tree(child, indent + "    ")

with sync_playwright() as playwright:
    run(playwright)

frame.add_script_tag(**kwargs)​

Added in: v1.8
  • content <str> 要注入框架的原始 JavaScript 内容。#
  • path <Union[str, pathlib.Path]> 要注入框架的 JavaScript 文件的路径。如果 path 是相对路径，则相对于当前工作目录解析。#
  • type <str> 脚本类型。使用 'module' 加载 Javascript ES6 模块。有关详细信息，请参阅 script。#
  • url <str> 要添加的脚本的 URL。#
  • 返回值: <ElementHandle>#

当脚本的 onload 触发或脚本内容被注入到框架中时，返回添加的标签。

将具有所需 url 或内容的 <script> 标签添加到页面中。

frame.add_style_tag(**kwargs)​

Added in: v1.8
  • content <str> 要注入框架的原始 CSS 内容。#
  • path <Union[str, pathlib.Path]> 要注入框架的 CSS 文件的路径。如果 path 是相对路径，则相对于当前工作目录解析。#
  • url <str> <link> 标签的 URL。#
  • 返回值: <ElementHandle>#

当样式表的 onload 触发或 CSS 内容被注入到框架中时，返回添加的标签。

将具有所需 url 的 <link rel="stylesheet"> 标签或具有内容的 <style type="text/css"> 标签添加到页面中。

frame.check(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

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

  1. 查找匹配 selector 的元素。如果没有，等待直到匹配的元素附加到 DOM。
  2. 确保匹配的元素是复选框或单选输入框。如果不是，此方法报错。如果元素已处于选中状态，则此方法立即返回。
  3. 等待匹配元素上的 actionability 检查，除非设置了 force 选项。如果元素在检查期间分离，则重试整个操作。
  4. 如果需要，将元素滚动到视图中。
  5. 使用 page.mouse 点击元素的中心。
  6. 等待发起的导航成功或失败，除非设置了 no_wait_after 选项。
  7. 确保元素现在已被选中。如果不是，此方法报错。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

frame.child_frames​

Added in: v1.8

frame.click(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • button <"left"|"right"|"middle"> 默认为 left。#
  • click_count <int> 默认为 1。查看 UIEvent.detail。#
  • delay <float> mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前修饰键。如果未指定，则使用当前按下的修饰键。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

此方法通过执行以下步骤来点击匹配 selector 的元素：

  1. 查找匹配 selector 的元素。如果没有，等待直到匹配的元素附加到 DOM。
  2. 等待匹配元素上的 actionability 检查，除非设置了 force 选项。如果元素在检查期间分离，则重试整个操作。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.mouse 点击元素的中心或指定的 position。
  5. 等待发起的导航成功或失败，除非设置了 no_wait_after 选项。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

frame.content()​

Added in: v1.8

获取框架的完整 HTML 内容，包括 doctype。

frame.dblclick(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • button <"left"|"right"|"middle"> 默认为 left。#
  • delay <float> mousedown 和 mouseup 之间等待的时间（毫秒）。默认为 0。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前修饰键。如果未指定，则使用当前按下的修饰键。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

此方法通过执行以下步骤来双击匹配 selector 的元素：

  1. 查找匹配 selector 的元素。如果没有，等待直到匹配的元素附加到 DOM。
  2. 等待匹配元素上的 actionability 检查，除非设置了 force 选项。如果元素在检查期间分离，则重试整个操作。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.mouse 双击元素的中心或指定的 position。
  5. 等待发起的导航成功或失败，除非设置了 no_wait_after 选项。请注意，如果 dblclick() 的第一次单击触发了导航事件，此方法将报错。

如果所有步骤结合起来在指定的 timeout 内未完成，此方法抛出 TimeoutError。传递零超时以禁用此功能。

note

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

frame.dispatch_event(selector, type, **kwargs)​

Added in: v1.8

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

frame.dispatch_event("button#submit", "click")

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

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

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

# note you can only create data_transfer in chromium and firefox
data_transfer = frame.evaluate_handle("new DataTransfer()")
frame.dispatch_event("#source", "dragstart", { "dataTransfer": data_transfer })

frame.drag_and_drop(source, target, **kwargs)​

Added in: v1.13
  • source <str> 要搜索的源元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • target <str> 要搜索的目标元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • source_position <Dict> 点击相对于源元素左上角的像素位置（可选）。如果未提供，则点击元素的某个可见点。 Added in: v1.14#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • target_position <Dict> 放置相对于目标元素左上角的像素位置（可选）。如果未提供，则放置在元素的某个可见点上。 Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。#
  • 返回值: <NoneType>#

执行拖放操作。指定了要拖动的元素和要放入的目标元素。更多细节请参阅 Drag and Drop。

frame.eval_on_selector(selector, expression, **kwargs)​

Added in: v1.9
  • selector <str> 要查询的选择器。有关更多详细信息，请参见使用选择器。#
  • expression <str> 要在浏览器上下文中对找到的元素进行求值的 JavaScript 表达式。如果表达式求值为函数，则会自动调用该函数。#
  • arg <EvaluationArgument> 可选参数，作为第二个参数传递给 expression。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • 返回值: <Serializable> 表达式的返回值。#

返回 expression 的返回值。

caution

此方法不会等待元素通过 actionability 检查，因此可能会导致测试不稳定。建议使用 locator.evaluate(expression, **kwargs)、其他 Locator 辅助方法或 web-first 断言。

此方法在帧中查找与指定选择器匹配的元素，并将其作为第一个参数传递给 expression。有关更多详细信息，请参见使用选择器。如果没有元素匹配选择器，该方法将抛出错误。

如果 expression 返回一个 Promise，则 frame.eval_on_selector(selector, expression, **kwargs) 将等待 promise 解析并返回其值。

例子:

search_value = frame.eval_on_selector("#search", "el => el.value")
preload_href = frame.eval_on_selector("link[rel=preload]", "el => el.href")
html = frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello")

frame.eval_on_selector_all(selector, expression, **kwargs)​

Added in: v1.9
  • selector <str> 要查询的选择器。有关更多详细信息，请参见使用选择器。#
  • expression <str> 要在浏览器上下文中对找到的元素进行求值的 JavaScript 表达式。如果表达式求值为函数，则会自动调用该函数。#
  • arg <EvaluationArgument> 可选参数，作为第二个参数传递给 expression。#
  • 返回值: <Serializable> 表达式的返回值。#

返回 expression 的返回值。

note

在大多数情况下，使用 locator.evaluate_all(expression, **kwargs)、其他 Locator 辅助方法和 web-first 断言效果更好。

此方法在帧中查找与指定选择器匹配的所有元素，并将匹配元素的数组作为第一个参数传递给 expression。有关更多详细信息，请参见使用选择器。

如果 expression 返回一个 Promise，则 frame.eval_on_selector_all(selector, expression, **kwargs) 将等待 promise 解析并返回其值。

例子:

divs_counts = frame.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10)

frame.evaluate(expression, **kwargs)​

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

返回 expression 的返回值。

如果该函数传递给 frame.evaluate(expression, **kwargs) 返回一个 Promise，则 frame.evaluate(expression, **kwargs) 将等待 promise 解析并返回其值。

如果函数将非 Serializable 值返回，则 frame.evaluate(expression, **kwargs) 返回 undefined。Playwright 还支持传输一些在序列化过程中通常会丢失的附加值，如：-0, NaN, Infinity, -Infinity。

result = frame.evaluate("([x, y]) => Promise.resolve(x * y)", [7, 8])
print(result) # prints "56"

可以将字符串替代函数传递进来。

print(frame.evaluate("1 + 2")) # prints "3"
x = 10
print(frame.evaluate(f"1 + {x}")) # prints "11"

ElementHandle 实例可以作为参数传递给 frame.evaluate(expression, **kwargs):

body_handle = frame.evaluate("document.body")
html = frame.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
body_handle.dispose()

frame.evaluate_handle(expression, **kwargs)​

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

返回 expression 的返回值作为 JSHandle。

frame.evaluate(expression, **kwargs) 和 frame.evaluate_handle(expression, **kwargs) 之间的唯一区别是 frame.evaluate_handle(expression, **kwargs) 返回 JSHandle。

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

a_window_handle = frame.evaluate_handle("Promise.resolve(window)")
a_window_handle # handle for the window object.

可以将字符串替代函数传递进来。

a_handle = page.evaluate_handle("document") # handle for the "document"

JSHandle 实例可以作为参数传递给 frame.evaluate_handle(expression, **kwargs):

a_handle = page.evaluate_handle("document.body")
result_handle = page.evaluate_handle("body => body.innerHTML", a_handle)
print(result_handle.json_value())
result_handle.dispose()

frame.expect_navigation(**kwargs)​

Added in: v1.8

等待帧导航并返回主要资源响应。如果发生多次重定向，则导航将使用最后一次重定向的响应进行解析。如果导航到不同的锚点或由于使用了 History API 而进行导航，则导航将解析为 null。

此方法等待帧导航到新的 URL。当代码运行并间接导致帧导航时，此方法非常有用。请考虑以下示例：

with frame.expect_navigation():
    frame.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
# Resolves after navigation has finished
note

使用 History API 更改 URL 被视为导航。

frame.fill(selector, value, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • value <str> 要为 <input>、<textarea> 或 [contenteditable] 元素填充的值。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <NoneType>#

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

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

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

frame.focus(selector, **kwargs)​

Added in: v1.8

该方法通过 selector获取元素并聚焦它。如果没有匹配 selector 的元素，该方法将等待直到匹配的元素出现在 DOM 中。

frame.frame_element()​

Added in: v1.8

返回与此 frame 对应的 frame 或 iframe 元素句柄。

这是 element_handle.content_frame() 的逆操作。请注意，返回的句柄实际上属于父 frame。

如果在 frameElement() 返回之前 frame 已被分离，则此方法将抛出错误。

frame_element = frame.frame_element()
content_frame = frame_element.content_frame()
assert frame == content_frame

frame.frame_locator(selector)​

Added in: v1.17

当使用 iframe 时，您可以创建一个 frame locator，它将进入 iframe 并允许选择该 iframe 中的元素。以下片段定位 id 为 my-frame 的 iframe 中文本为 "Submit" 的元素，如 <iframe id="my-frame">：

locator = frame.frame_locator("#my-iframe").get_by_text("Submit")
locator.click()

frame.get_attribute(selector, name, **kwargs)​

Added in: v1.8

返回元素属性值。

frame.get_by_alt_text(text, **kwargs)​

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

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

<img alt='Castle'>

frame.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">

frame.get_by_placeholder(text, **kwargs)​

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

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

<input placeholder="Country">

frame.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-* 属性设置为默认值来复制隐式角色和属性。

frame.get_by_test_id(test_id)​

Added in: v1.27
  • test_id <str> 用于定位元素的 Id。#
  • 返回值: <Locator>#

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

frame.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>

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

# Matches <span>
page.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

另请参阅 locator.filter(**kwargs)，它允许按其他条件（如 accessible role）进行匹配，然后按文本内容进行过滤。

note

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

note

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

frame.get_by_title(text, **kwargs)​

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

允许通过 title 属性定位元素。例如，此方法将通过 title "Submit" 找到按钮：

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

frame.goto(url, **kwargs)​

Added in: v1.8

返回主要资源响应。如果发生多次重定向，则导航将使用最后一次重定向的响应进行解析。

该方法将在以下情况下抛出错误：

  • 发生 SSL 错误（例如，在自签名证书的情况下）。
  • 目标 URL 无效。
  • 导航期间超时 timeout。
  • 远程服务器不响应或无法访问。
  • 主要资源加载失败。

当远程服务器返回任何有效的 HTTP 状态代码（包括 404 "Not Found" 和 500 "Internal Server Error"）时，该方法不会抛出错误。可以通过调用 response.status 来检索此类响应的状态代码。

note

该方法要么抛出错误，要么返回主要资源响应。唯一的例外是导航到 about:blank 或导航到具有不同哈希的相同 URL，这将成功并返回 null。

note

Headless 模式不支持导航到 PDF 文档。请参阅上游问题。

frame.hover(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保在操作期间仅按下这些修饰符，然后将当前修饰符恢复原状。如果未指定，则使用当前按下的修饰符。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。 Added in: v1.11#
  • 返回值: <NoneType>#

该方法通过执行以下步骤悬停匹配 selector 的元素：

  1. 查找匹配 selector 的元素。如果没有，等待直到匹配的元素附加到 DOM。
  2. 等待匹配元素上的 actionability 检查，除非设置了 force 选项。如果元素在检查期间分离，则重试整个操作。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.mouse 悬停在元素的中心或指定的 position 上。
  5. 等待启动的导航成功或失败，除非设置了 noWaitAfter 选项。

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

frame.inner_html(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <str>#

返回 element.innerHTML。

frame.inner_text(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <str>#

返回 element.innerText。

frame.input_value(selector, **kwargs)​

Added in: v1.13
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。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> 元素内，则返回控件的值。

frame.is_checked(selector, **kwargs)​

Added in: v1.8

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

frame.is_detached()​

Added in: v1.8

如果 frame 已分离，则返回 true，否则返回 false。

frame.is_disabled(selector, **kwargs)​

Added in: v1.8

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

frame.is_editable(selector, **kwargs)​

Added in: v1.8

返回元素是否可编辑。

frame.is_enabled(selector, **kwargs)​

Added in: v1.8

返回元素是否启用。

frame.is_hidden(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 弃用 忽略此选项。frame.is_hidden(selector, **kwargs) 不会等待元素变为隐藏，而是立即返回。#
  • 返回值: <bool>#

返回元素是否隐藏，与 visible 相反。不匹配任何元素的 selector 被视为隐藏。

frame.is_visible(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 弃用 忽略此选项。frame.is_visible(selector, **kwargs) 不会等待元素变为可见，而是立即返回。#
  • 返回值: <bool>#

返回元素是否 visible。不匹配任何元素的 selector 被视为不可见。

frame.locator(selector, **kwargs)​

Added in: v1.14

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

  • has <Locator> 匹配包含匹配内部定位器的元素的元素。内部定位器是针对外部定位器进行查询的。例如，具有 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。#

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

  • has_text <str|Pattern> 匹配在内部某个位置（可能在子元素或后代元素中）包含指定文本的元素。当传递 [string] 时，匹配不区分大小写并搜索子字符串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。#

  • 返回值: <Locator>#

该方法返回一个元素定位器，可用于在此 page / frame 上执行操作。定位器在执行操作之前立即解析为元素，因此同一定位器上的一系列操作实际上可以对不同的 DOM 元素执行。如果这些操作之间的 DOM 结构发生了变化，就会发生这种情况。

了解有关定位器的更多信息。

了解有关定位器的更多信息。

frame.name​

Added in: v1.8

返回标记中指定的 frame 的 name 属性。

如果 name 为空，则返回 id 属性代替。

note

此值在创建 frame 时计算一次，如果在之后更改了属性，则不会更新。

frame.page​

Added in: v1.8

返回包含此 frame 的页面。

frame.parent_frame​

Added in: v1.8

父 frame（如果有）。分离的 frame 和主 frame 返回 null。

frame.press(selector, key, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • key <str> 要按下的键的名称或要生成的字符，例如 ArrowLeft 或 a。#
  • delay <float> keydown 和 keyup 之间等待的时间（毫秒）。默认为 0。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <NoneType>#

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"。当指定修饰符时，会在按下后续键的同时按下并按住修饰符。

frame.query_selector(selector, **kwargs)​

Added in: v1.9
  • selector <str> 要查询的选择器。有关详细信息，请参阅使用选择器。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • 返回值: <NoneType|ElementHandle>#

返回指向 frame 元素的 ElementHandle。

caution

不建议使用 ElementHandle，请使用 Locator 对象和 web-first 斷言代替。

该方法在 frame 中查找匹配指定选择器的元素。有关详细信息，请参阅使用选择器。如果没有元素匹配选择器，则返回 null。

frame.query_selector_all(selector)​

Added in: v1.9

返回指向 frame 元素的 ElementHandles。

caution

不建议使用 ElementHandle，请使用 Locator 对象代替。

该方法查找 frame 中所有匹配指定选择器的元素。有关详细信息，请参阅使用选择器。如果没有元素匹配选择器，则返回空数组。

frame.select_option(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要查询的选择器。有关详细信息，请参阅使用选择器。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • 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]>#

该方法等待匹配 selector 的元素，等待 actionability 检查，等待直到所有指定的选项都存在于 <select> 元素中并选择这些选项。

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

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

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

# single selection matching the value
frame.select_option("select#colors", "blue")
# single selection matching both the label
frame.select_option("select#colors", label="blue")
# multiple selection
frame.select_option("select#colors", value=["red", "green", "blue"])

frame.set_checked(selector, checked, **kwargs)​

Added in: v1.15
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • checked <bool> 选中还是取消选中复选框。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。#
  • 返回值: <NoneType>#

该方法通过执行以下步骤选中或取消选中匹配 selector 的元素：

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

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

frame.set_content(html, **kwargs)​

Added in: v1.8

frame.set_input_files(selector, files, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • files <Union[str, pathlib.Path]|List[Union[str, pathlib.Path]]|Dict|List[Dict]>#
    • name <str> 文件名
    • mimeType <str> 文件类型
    • buffer <bytes> 文件内容
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <NoneType>#

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

此方法期望 selector 指向 input 元素。但是，如果元素位于具有关联 control 的 <label> 元素内部，则定位该控件。

frame.tap(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • modifiers <List["Alt"|"Control"|"Meta"|"Shift"]> 要按下的修饰键。确保在操作期间仅按下这些修饰符，然后恢复当前的修饰符。如果未指定，则使用当前按下的修饰符。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

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

  1. 查找匹配 selector 的元素。如果没有，等待直到匹配的元素附加到 DOM。
  2. 等待匹配元素上的 actionability 检查，除非设置了 force 选项。如果元素在检查期间分离，则重试整个操作。
  3. 如果需要，将元素滚动到视图中。
  4. 使用 page.touchscreen 点击元素的中心或指定的 position。
  5. 等待启动的导航成功或失败，除非设置了 no_wait_after 选项。

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

note

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

frame.text_content(selector, **kwargs)​

Added in: v1.8

返回 element.textContent。

frame.title()​

Added in: v1.8

返回页面标题。

frame.type(selector, text, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • text <str> 要输入到焦点元素的文本。#
  • delay <float> 按键之间的等待时间（毫秒）。默认为 0。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <NoneType>#

为文本中的每个字符发送 keydown、keypress/input 和 keyup 事件。frame.type 可用于发送细粒度的键盘事件。要填充表单字段中的值，请使用 frame.fill(selector, value, **kwargs)。

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

frame.type("#mytextarea", "hello") # types instantly
frame.type("#mytextarea", "world", delay=100) # types slower, like a user

frame.uncheck(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要搜索的元素的选择器。如果有多个元素满足选择器，则使用第一个。有关详细信息，请参阅使用选择器。#
  • force <bool> 是否跳过 actionability 检查。默认为 false。#
  • no_wait_after <bool> 启动导航的操作会等待导航完成并等待页面开始加载。你可以通过设置此标志来选择不等待。你仅在特殊情况下（如导航到不可访问的页面）才需要此选项。默认为 false。#
  • position <Dict> 相对于元素填充框左上角的点。如果未指定，则使用元素的某个可见点。Added in: v1.11#
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • trial <bool> 设置后，此方法仅执行 actionability 检查并跳过操作。默认为 false。常用于在不执行操作的情况下等待元素准备就绪。Added in: v1.11#
  • 返回值: <NoneType>#

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

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

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

frame.url​

Added in: v1.8

返回 frame 的 URL。

frame.wait_for_function(expression, **kwargs)​

Added in: v1.8
  • expression <str> 要在浏览器上下文中评估的 JavaScript 表达式。如果表达式计算为函数，则该函数将自动调用。#
  • arg <EvaluationArgument> 传递给 expression 的可选参数。#
  • polling <float|"raf"> 如果 polling 是 'raf'，则 expression 会在 requestAnimationFrame 回调中不断执行。如果 polling 是数字，则将其视为执行函数的间隔（以毫秒为单位）。默认为 raf。#
  • timeout <float> 最长等待时间（毫秒）。默认为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <JSHandle>#

当 expression 返回真值时返回，返回该值。

frame.wait_for_function(expression, **kwargs) 可用于观察视口大小变化：

from playwright.sync_api import sync_playwright

def run(playwright):
    webkit = playwright.webkit
    browser = webkit.launch()
    page = browser.new_page()
    page.evaluate("window.x = 0; setTimeout(() => { window.x = 100 }, 1000);")
    page.main_frame.wait_for_function("() => window.x > 0")
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

将参数传递给 frame.waitForFunction 函数的谓词：

selector = ".foo"
frame.wait_for_function("selector => !!document.querySelector(selector)", selector)

frame.wait_for_load_state(**kwargs)​

Added in: v1.8

等待达到所需的加载状态。

当 frame 达到所需的加载状态（默认为 load）时返回。调用此方法时必须已提交导航。如果当前文档已达到所需状态，则立即解析。

frame.click("button") # click triggers navigation.
frame.wait_for_load_state() # the promise resolves after "load" event.

frame.wait_for_selector(selector, **kwargs)​

Added in: v1.8
  • selector <str> 要查询的选择器。有关详细信息，请参阅使用选择器。#
  • state <"attached"|"detached"|"visible"|"hidden"> 默认为 'visible'。可以是以下之一：#
    • 'attached' - 等待元素出现在 DOM 中。
    • 'detached' - 等待元素不出现在 DOM 中。
    • 'visible' - 等待元素具有非空边界框且没有 visibility:hidden。请注意，没有任何内容或具有 display:none 的元素具有空边界框，并且不被视为可见。
    • 'hidden' - 等待元素从 DOM 中分离，或者具有空边界框或 visibility:hidden。这与 'visible' 选项相反。
  • strict <bool> 如果为 true，则调用要求选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用抛出异常。Added in: v1.14#
  • timeout <float> 最长等待时间（毫秒），默认为 30 秒，传递 0 以禁用超时。可以使用 browser_context.set_default_timeout(timeout) 或 page.set_default_timeout(timeout) 方法修改默认值。#
  • 返回值: <NoneType|ElementHandle>#

当 selector 指定的元素满足 state 选项时返回。如果等待 hidden 或 detached，则返回 null。

note

Playwright 会在执行操作之前自动等待元素准备就绪。使用 Locator 对象和 web-first assertions 使代码无需 wait-for-selector。

等待 selector 满足 state 选项（从 dom 中出现/消失，或变得可见/隐藏）。如果在调用该方法时 selector 已满足条件，则该方法将立即返回。如果选择器在 timeout 毫秒内不满足条件，该函数将抛出异常。

该方法在导航期间仍然有效：

from playwright.sync_api import sync_playwright

def run(playwright):
    chromium = playwright.chromium
    browser = chromium.launch()
    page = browser.new_page()
    for current_url in ["https://google.com", "https://bbc.com"]:
        page.goto(current_url, wait_until="domcontentloaded")
        element = page.main_frame.wait_for_selector("img")
        print("Loaded image: " + str(element.get_attribute("src")))
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

frame.wait_for_timeout(timeout)​

Added in: v1.8

等待指定的 timeout 毫秒。

请注意，frame.waitForTimeout() 仅应用于调试。在生产中使用计时器的测试将会变得不稳定。请改用信号，例如网络事件、选择器变得可见等。

frame.wait_for_url(url, **kwargs)​

Added in: v1.11

等待 frame 导航到给定的 URL。

frame.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
frame.wait_for_url("**/target.html")