框架

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

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

page.on("frameattached") - 当框架附加到页面时触发。框架只能附加到页面一次。
page.on("framenavigated") - 当框架提交导航到不同的 URL 时触发。
page.on("framedetached") - 当框架从页面分离时触发。框架只能从页面分离一次。

一个转储框架树的示例

同步
异步

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: 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)

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run(playwright: Playwright):
    firefox = playwright.firefox
    browser = await firefox.launch()
    page = await browser.new_page()
    await page.goto("https://www.theverge.com")
    dump_frame_tree(page.main_frame, "")
    await 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 + "    ")

async def main():
    async with async_playwright() as playwright:
        await run(playwright)
asyncio.run(main())

方法

add_script_tag

在 v1.9 之前添加

frame.add_script_tag

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

将一个 <script> 标签添加到页面中，包含所需的 URL 或内容。

用法

frame.add_script_tag()
frame.add_script_tag(**kwargs)

参数

content str (可选)#

要注入框架的原始 JavaScript 内容。
path Union[str, pathlib.Path] (可选)#

要注入框架的 JavaScript 文件的路径。如果 path 是相对路径，则相对于当前工作目录解析。
type str (可选)#

脚本类型。使用 'module' 以加载 JavaScript ES6 模块。有关更多详细信息，请参见 script。
url str (可选)#

要添加的脚本的 URL。

返回值

ElementHandle #

add_style_tag

在 v1.9 之前添加

frame.add_style_tag

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

将一个 <link rel="stylesheet"> 标签添加到页面中，包含所需的 URL 或一个 <style type="text/css"> 标签，包含内容。

用法

frame.add_style_tag()
frame.add_style_tag(**kwargs)

参数

content str (可选)#

要注入框架的原始 CSS 内容。
path Union[str, pathlib.Path] (可选)#

要注入框架的 CSS 文件的路径。如果 path 是相对路径，则相对于当前工作目录解析。
url str (可选)#

<link> 标签的 URL。

返回值

ElementHandle #

content

在 v1.9 之前添加

frame.content

获取框架的完整 HTML 内容，包括文档类型。

用法

frame.content()

返回值

str #

drag_and_drop

添加于：v1.13

frame.drag_and_drop

用法

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

参数

source str #

一个选择器，用于搜索要拖动的元素。如果有多个元素满足选择器，则使用第一个元素。
target str #

一个选择器，用于搜索要放置元素的元素。如果有多个元素满足选择器，则使用第一个元素。
force bool (可选)#

是否绕过可操作性检查。默认值为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
source_position Dict (可选)添加于：v1.14#
- x float
- y float
在此点（相对于元素填充框的左上角）单击源元素。如果未指定，则使用元素的某个可见点。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
target_position Dict (可选)添加于：v1.14#
- x float
- y float
在此点（相对于元素填充框的左上角）将元素放在目标元素上。如果未指定，则使用元素的某个可见点。
timeout float (可选)#

以毫秒为单位的最大时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

设置后，此方法仅执行可操作性检查并跳过操作。默认值为 false。用于在执行操作之前等待元素准备好。

返回值

NoneType #

evaluate

在 v1.9 之前添加

frame.evaluate

返回 expression 的返回值。

如果传递给 frame.evaluate() 的函数返回一个 Promise，那么 frame.evaluate() 会等待 promise 解决并返回其值。

如果传递给 frame.evaluate() 的函数返回一个非可序列化的值，那么 frame.evaluate() 将返回 undefined。Playwright 还支持传输一些不能被 JSON 序列化的额外值：-0、NaN、Infinity、-Infinity。

用法

同步
异步

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

result = await 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"

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

ElementHandle 实例可以作为参数传递给 frame.evaluate()

同步
异步

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

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

参数

expression str #

在浏览器上下文中要执行的 JavaScript 表达式。如果表达式计算结果为函数，则该函数将自动调用。
arg EvaluationArgument (可选)#

可选参数，传递给 expression。

返回值

可序列化 #

evaluate_handle

在 v1.9 之前添加

frame.evaluate_handle

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

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

如果传递给 frame.evaluate_handle() 的函数返回一个 Promise，那么 frame.evaluate_handle() 将等待 Promise 解决并返回其值。

用法

同步
异步

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

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

也可以传入字符串而不是函数。

同步
异步

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

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

JSHandle 实例可以作为参数传递给 frame.evaluate_handle()

同步
异步

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

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

参数

expression str #

在浏览器上下文中要执行的 JavaScript 表达式。如果表达式计算结果为函数，则该函数将自动调用。
arg EvaluationArgument (可选)#

可选参数，传递给 expression。

返回值

JSHandle #

frame_element

在 v1.9 之前添加

frame.frame_element

返回与该 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_element = await frame.frame_element()
content_frame = await frame_element.content_frame()
assert frame == content_frame

返回值

ElementHandle #

frame_locator

新增于：v1.17

frame.frame_locator

在处理 iframe 时，您可以创建一个 frame 定位器，它将进入 iframe 并允许在该 iframe 中选择元素。

用法

以下代码段在 id 为 my-frame 的 iframe 中定位文本为“Submit”的元素，例如 <iframe id="my-frame">

同步
异步

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

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

参数

selector str #

在解析 DOM 元素时要使用的选择器。

返回值

FrameLocator #

get_by_alt_text

新增于：v1.27

frame.get_by_alt_text

允许通过替代文本定位元素。

用法

例如，此方法将通过替代文本“Playwright logo”查找图像

<img alt='Playwright logo'>

同步
异步

page.get_by_alt_text("Playwright logo").click()

await page.get_by_alt_text("Playwright logo").click()

参数

text str | Pattern #

要定位的元素的文本。
exact bool (可选)#

是否查找完全匹配：区分大小写且为整个字符串。默认值为 false。在通过正则表达式定位时忽略。请注意，精确匹配仍然会修剪空格。

返回值

Locator #

get_by_label

新增于：v1.27

frame.get_by_label

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

用法

例如，此方法将通过标签“Username”和“Password”查找以下 DOM 中的输入

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

await page.get_by_label("Username").fill("john")
await page.get_by_label("Password").fill("secret")

参数

text str | Pattern #

要定位的元素的文本。
exact bool (可选)#

是否查找完全匹配：区分大小写且为整个字符串。默认值为 false。在通过正则表达式定位时忽略。请注意，精确匹配仍然会修剪空格。

返回值

Locator #

get_by_placeholder

新增于：v1.27

frame.get_by_placeholder

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

用法

例如，考虑以下 DOM 结构。

<input type="email" placeholder="[email protected]" />

您可以通过占位符文本定位输入后填写它

同步
异步

page.get_by_placeholder("[email protected]").fill("[email protected]")

await page.get_by_placeholder("[email protected]").fill("[email protected]")

参数

text str | Pattern #

要定位的元素的文本。
exact bool (可选)#

是否查找完全匹配：区分大小写且为整个字符串。默认值为 false。在通过正则表达式定位时忽略。请注意，精确匹配仍然会修剪空格。

返回值

Locator #

get_by_role

新增于：v1.27

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

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

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

await 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 的信息。

返回值

Locator #

细节

角色选择器 **不代替** 可访问性审计和一致性测试，而是提供关于 ARIA 指南的早期反馈。

许多 html 元素具有隐式定义的角色，该角色被角色选择器识别。您可以找到所有此处支持的角色。ARIA 指南 **不推荐** 通过设置 role 和/或 aria-* 属性来重复隐式角色和属性为默认值。

get_by_test_id

新增于：v1.27

frame.get_by_test_id

通过测试 ID 定位元素。

用法

考虑以下 DOM 结构。

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

您可以通过其测试 ID 定位元素

同步
异步

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

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

参数

test_id str | Pattern #

用于定位元素的 ID。

返回值

Locator #

细节

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

get_by_text

新增于：v1.27

frame.get_by_text

允许定位包含给定文本的元素。

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

用法

考虑以下 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))

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

参数

text str | Pattern #

要定位的元素的文本。
exact bool (可选)#

是否查找完全匹配：区分大小写且为整个字符串。默认值为 false。在通过正则表达式定位时忽略。请注意，精确匹配仍然会修剪空格。

返回值

Locator #

细节

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

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

get_by_title

新增于：v1.27

frame.get_by_title

允许通过其标题属性定位元素。

用法

考虑以下 DOM 结构。

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

您可以在通过标题文本定位它后检查问题计数

同步
异步

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

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

参数

text str | Pattern #

要定位的元素的文本。
exact bool (可选)#

是否查找完全匹配：区分大小写且为整个字符串。默认值为 false。在通过正则表达式定位时忽略。请注意，精确匹配仍然会修剪空格。

返回值

Locator #

goto

在 v1.9 之前添加

frame.goto

返回主资源响应。如果有多个重定向，导航将以最后一次重定向的响应解析。

该方法将抛出错误，如果

存在 SSL 错误（例如，如果是自签名证书）。
目标 URL 无效。
超时在导航过程中超过。
远程服务器没有响应或无法访问。
主资源加载失败。

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

注意

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

注意

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

用法

frame.goto(url)
frame.goto(url, **kwargs)

参数

url str #

要导航到框架的 URL。url 应包括方案，例如 https://。
referer str (可选)#

Referer 标头值。如果提供，它将优先于 page.set_extra_http_headers() 设置的 referer 标头值。
timeout float (可选)#

以毫秒为单位的最大操作时间，默认为 30 秒，传递 0 来禁用超时。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法更改默认值。
wait_until "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

何时将操作视为成功，默认为 load。事件可以是：
- 'domcontentloaded' - 在触发 DOMContentLoaded 事件时，将操作视为已完成。
- 'load' - 在触发 load 事件时，将操作视为已完成。
- 'networkidle' - 不建议 在至少 500 毫秒内没有网络连接时，将操作视为已完成。不要将此方法用于测试，而是依靠 Web 断言来评估准备状态。
- 'commit' - 在收到网络响应并开始加载文档时，将操作视为已完成。

返回值

NoneType | Response #

is_enabled

在 v1.9 之前添加

frame.is_enabled

返回元素是否已启用。

用法

frame.is_enabled(selector)
frame.is_enabled(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

bool #

locator

添加于：v1.14

frame.locator

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

了解更多关于定位器的信息.

用法

frame.locator(selector)
frame.locator(selector, **kwargs)

参数

selector str #

在解析 DOM 元素时要使用的选择器。
has Locator (可选)#

将方法的结果缩小到包含与该相对定位器匹配的元素的结果。例如，article 具有 text=Playwright 匹配 <article><div>Playwright</div></article>。

内部定位器 **必须相对于** 外部定位器，并且从外部定位器匹配开始查询，而不是从文档根开始。例如，您可以找到 content 具有 div 在 <article><content><div>Playwright</div></content></article> 中。但是，寻找 content 具有 article div 会失败，因为内部定位器必须是相对的，并且不应使用 content 外部的任何元素。

注意，外部和内部定位器必须属于同一个框架。内部定位器不能包含 FrameLocator。
has_not Locator (可选)添加于: v1.33#

匹配不包含与内部定位器匹配的元素的元素。内部定位器针对外部定位器进行查询。例如，article 不具有 div 匹配 <article><span>Playwright</span></article>。

注意，外部和内部定位器必须属于同一个框架。内部定位器不能包含 FrameLocator。
has_not_text str | Pattern (可选)添加于: v1.33#

匹配不包含在内部的任何地方（可能在子元素或后代元素中）包含指定文本的元素。当传递一个 [字符串] 时，匹配不区分大小写，并搜索子字符串。
has_text str | Pattern (可选)#

匹配包含在内部的任何地方（可能在子元素或后代元素中）包含指定文本的元素。当传递一个 [字符串] 时，匹配不区分大小写，并搜索子字符串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

返回值

Locator #

set_content

在 v1.9 之前添加

frame.set_content

此方法在内部调用 document.write()，继承其所有特定特征和行为。

用法

frame.set_content(html)
frame.set_content(html, **kwargs)

参数

html str #

要分配给页面的 HTML 标记。
timeout float (可选)#

以毫秒为单位的最大操作时间，默认为 30 秒，传递 0 来禁用超时。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法更改默认值。
wait_until "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

何时将操作视为成功，默认为 load。事件可以是：
- 'domcontentloaded' - 在触发 DOMContentLoaded 事件时，将操作视为已完成。
- 'load' - 在触发 load 事件时，将操作视为已完成。
- 'networkidle' - 不建议 在至少 500 毫秒内没有网络连接时，将操作视为已完成。不要将此方法用于测试，而是依靠 Web 断言来评估准备状态。
- 'commit' - 在收到网络响应并开始加载文档时，将操作视为已完成。

返回值

NoneType #

title

在 v1.9 之前添加

frame.title

返回页面标题。

用法

frame.title()

返回值

str #

wait_for_function

在 v1.9 之前添加

frame.wait_for_function

当表达式返回真值时返回，返回该值。

用法

the frame.wait_for_function() 可用于观察视窗大小的变化

同步
异步

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: 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)

import asyncio
from playwright.async_api import async_playwright, Playwright

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

async def main():
    async with async_playwright() as playwright:
        await run(playwright)
asyncio.run(main())

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

同步
异步

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

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

参数

expression str #

在浏览器上下文中要执行的 JavaScript 表达式。如果表达式计算结果为函数，则该函数将自动调用。
arg EvaluationArgument (可选)#

要传递给表达式的可选参数。
polling float | "raf" (可选)#

如果 polling 是 'raf'，那么表达式会在 requestAnimationFrame 回调中不断执行。如果 polling 是一个数字，那么它将被视为以毫秒为单位的间隔，函数将在该间隔内执行。默认值为 raf。
timeout float (可选)#

以毫秒为单位的最大等待时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。

返回值

JSHandle #

wait_for_load_state

在 v1.9 之前添加

frame.wait_for_load_state

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

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

注意

大多数情况下，不需要此方法，因为 Playwright 在每个操作之前自动等待。

用法

同步
异步

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

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

参数

state "load" | "domcontentloaded" | "networkidle" (可选)#

要等待的可选加载状态，默认值为 load。如果在加载当前文档时已经达到该状态，则该方法立即解析。可以是以下之一
- 'load' - 等待 load 事件被触发。
- 'domcontentloaded' - 等待 DOMContentLoaded 事件被触发。
- 'networkidle' - 不建议使用 等待至少 500 毫秒没有网络连接。不要使用此方法进行测试，而是依靠 Web 断言来评估就绪状态。
timeout float (可选)#

以毫秒为单位的最大操作时间，默认为 30 秒，传递 0 来禁用超时。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法更改默认值。

返回值

NoneType #

wait_for_url

添加于: v1.11

frame.wait_for_url

等待框架导航到给定的 URL。

用法

同步
异步

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

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

参数

url str | Pattern | Callable[URL]:bool #

一个全局模式、正则表达式模式或接收 URL 的谓词，在等待导航时进行匹配。请注意，如果参数是字符串，没有通配符，该方法将等待导航到完全等于该字符串的 URL。
timeout float (可选)#

以毫秒为单位的最大操作时间，默认为 30 秒，传递 0 来禁用超时。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法更改默认值。
wait_until "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

何时将操作视为成功，默认为 load。事件可以是：
- 'domcontentloaded' - 在触发 DOMContentLoaded 事件时，将操作视为已完成。
- 'load' - 在触发 load 事件时，将操作视为已完成。
- 'networkidle' - 不建议 在至少 500 毫秒内没有网络连接时，将操作视为已完成。不要将此方法用于测试，而是依靠 Web 断言来评估准备状态。
- 'commit' - 在收到网络响应并开始加载文档时，将操作视为已完成。

返回值

NoneType #

属性

child_frames

在 v1.9 之前添加

frame.child_frames

用法

frame.child_frames

返回值

List[Frame]#

is_detached

在 v1.9 之前添加

frame.is_detached

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

用法

frame.is_detached()

返回值

bool #

name

在 v1.9 之前添加

frame.name

返回框架的名称属性，如标签中指定。

如果名称为空，则返回 id 属性。

注意

此值在创建框架时计算一次，如果以后更改属性，则不会更新。

用法

frame.name

返回值

str #

page

在 v1.9 之前添加

frame.page

返回包含此框架的页面。

用法

frame.page

返回值

Page #

parent_frame

在 v1.9 之前添加

frame.parent_frame

父框架（如果有）。已分离的框架和主框架返回 null。

用法

frame.parent_frame

返回值

NoneType | Frame #

url

在 v1.9 之前添加

frame.url

返回框架的 url。

用法

frame.url

返回值

str #

已弃用

check

在 v1.9 之前添加

frame.check

不建议

使用基于定位器的 locator.check() 代替。阅读有关定位器的更多信息。

此方法通过执行以下步骤来检查与选择器匹配的元素

查找与选择器匹配的元素。如果没有，则等待匹配的元素附加到 DOM。
确保匹配的元素是复选框或单选按钮。如果不是，则此方法会抛出异常。如果元素已选中，则此方法会立即返回。
等待可操作性检查匹配的元素，除非设置了 force 选项。如果元素在检查期间被分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 点击元素的中心。
确保元素现在已选中。如果不是，则此方法会抛出异常。

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

用法

frame.check(selector)
frame.check(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
force bool (可选)#

是否绕过可操作性检查。默认值为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
position Dict (可选)添加于: v1.11#
- x float
- y float
相对于元素内边距框左上角的点。如果没有指定，则使用元素的一些可见点。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

以毫秒为单位的最大时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)添加于: v1.11#

设置后，此方法仅执行可操作性检查并跳过操作。默认值为 false。用于在执行操作之前等待元素准备好。

返回值

NoneType #

click

在 v1.9 之前添加

frame.click

不建议

使用基于定位器的 locator.click() 代替。阅读有关定位器的更多信息。

此方法通过执行以下步骤来点击与选择器匹配的元素

查找与选择器匹配的元素。如果没有，则等待匹配的元素附加到 DOM。
等待可操作性检查匹配的元素，除非设置了 force 选项。如果元素在检查期间被分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 点击元素的中心，或指定的位置。
等待启动的导航成功或失败，除非设置了 no_wait_after 选项。

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

用法

frame.click(selector)
frame.click(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
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 (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果没有指定，则使用元素的一些可见点。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

以毫秒为单位的最大时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)添加于: v1.11#

当设置时，此方法仅执行可操作性检查，并跳过操作。默认为 false。用于在不执行操作的情况下等待元素准备好执行操作。请注意，无论 trial 如何，键盘 modifiers 都将被按下，以允许测试仅在按下这些键时才可见的元素。

返回值

NoneType #

dblclick

在 v1.9 之前添加

frame.dblclick

不建议

使用基于定位器的 locator.dblclick() 代替。阅读有关定位器的更多信息。

此方法通过执行以下步骤来双击与选择器匹配的元素

查找与选择器匹配的元素。如果没有，则等待匹配的元素附加到 DOM。
等待可操作性检查匹配的元素，除非设置了 force 选项。如果元素在检查期间被分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 双击元素的中心，或指定的位置。如果 dblclick() 的第一次点击触发了导航事件，则此方法将抛出异常。

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

注意

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

用法

frame.dblclick(selector)
frame.dblclick(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
button "left" | "right" | "middle" (可选)#

默认为 left。
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 (可选)#

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果没有指定，则使用元素的一些可见点。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

以毫秒为单位的最大时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)添加于: v1.11#

当设置时，此方法仅执行可操作性检查，并跳过操作。默认为 false。用于在不执行操作的情况下等待元素准备好执行操作。请注意，无论 trial 如何，键盘 modifiers 都将被按下，以允许测试仅在按下这些键时才可见的元素。

返回值

NoneType #

dispatch_event

在 v1.9 之前添加

frame.dispatch_event

不建议

使用基于定位器的 locator.dispatch_event() 代替。阅读有关定位器的更多信息。

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

用法

同步
异步

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

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

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

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
type str #

DOM 事件类型："click"、"dragstart" 等。
event_init EvaluationArgument (可选)#

可选的特定于事件的初始化属性。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

NoneType #

eval_on_selector

添加于：v1.9

frame.eval_on_selector

不建议

此方法不会等待元素通过可操作性检查，因此会导致测试不稳定。请改用 locator.evaluate()、其他 Locator 辅助方法或 Web 首选断言。

返回 expression 的返回值。

该方法在框架内查找与指定选择器匹配的元素，并将其作为第一个参数传递给 expression。如果没有元素与选择器匹配，该方法将抛出错误。

如果 expression 返回一个 Promise，那么 frame.eval_on_selector() 将等待 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")

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

参数

selector str #

要查询的选择器。
expression str #

在浏览器上下文中要执行的 JavaScript 表达式。如果表达式计算结果为函数，则该函数将自动调用。
arg EvaluationArgument (可选)#

传递给 expression 的可选参数。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。

返回值

Serializable #

eval_on_selector_all

添加于：v1.9

frame.eval_on_selector_all

不建议

在大多数情况下，locator.evaluate_all()、其他 Locator 辅助方法和 Web 首选断言可以更好地完成工作。

返回 expression 的返回值。

该方法查找框架内与指定选择器匹配的所有元素，并将匹配元素的数组作为第一个参数传递给 expression。

如果 expression 返回一个 Promise，那么 frame.eval_on_selector_all() 将等待 promise 解决并返回其值。

用法

同步
异步

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

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

参数

selector str #

要查询的选择器。
expression str #

在浏览器上下文中要执行的 JavaScript 表达式。如果表达式计算结果为函数，则该函数将自动调用。
arg EvaluationArgument (可选)#

传递给 expression 的可选参数。

返回值

Serializable #

在 v1.9 之前添加

frame.expect_navigation

已弃用

此方法本质上是竞争性的，请改用 frame.wait_for_url()。

等待框架导航并返回主资源响应。如果出现多次重定向，导航将使用最后一次重定向的响应来解决。如果导航到不同的锚点或由于使用历史记录 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

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

注意

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

参数

timeout float (可选)#

以毫秒为单位的最大操作时间，默认为 30 秒，传递 0 来禁用超时。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法更改默认值。
url str | Pattern | Callable[URL]:bool (可选)#

一个全局模式、正则表达式模式或接收 URL 的谓词，在等待导航时进行匹配。请注意，如果参数是字符串，没有通配符，该方法将等待导航到完全等于该字符串的 URL。
wait_until "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

何时将操作视为成功，默认为 load。事件可以是：
- 'domcontentloaded' - 在触发 DOMContentLoaded 事件时，将操作视为已完成。
- 'load' - 在触发 load 事件时，将操作视为已完成。
- 'networkidle' - 不建议 在至少 500 毫秒内没有网络连接时，将操作视为已完成。不要将此方法用于测试，而是依靠 Web 断言来评估准备状态。
- 'commit' - 在收到网络响应并开始加载文档时，将操作视为已完成。

返回值

EventContextManager[Response]#

fill

在 v1.9 之前添加

frame.fill

不建议

请改用基于定位器的 locator.fill()。详细了解定位器。

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

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

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

用法

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

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
value str #

要为 <input>、<textarea> 或 [contenteditable] 元素填充的值。
force bool (可选)添加于：v1.13#

是否绕过可操作性检查。默认值为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

NoneType #

focus

在 v1.9 之前添加

frame.focus

不建议

请改用基于定位器的 locator.focus()。详细了解定位器。

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

用法

frame.focus(selector)
frame.focus(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

NoneType #

get_attribute

在 v1.9 之前添加

frame.get_attribute

不建议

使用基于定位器的 locator.get_attribute() 代替。了解更多关于定位器。

返回元素属性值。

用法

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

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
name str #

要获取值的属性名称。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

NoneType | str #

hover

在 v1.9 之前添加

frame.hover

不建议

使用基于定位器的 locator.hover() 代替。了解更多关于定位器。

此方法通过执行以下步骤将鼠标悬停在与 selector 匹配的元素上

找到与 selector 匹配的元素。如果没有，则等待匹配的元素附加到 DOM。
等待匹配元素上的可操作性检查，除非设置了 force 选项。如果元素在检查期间被分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 将鼠标悬停在元素的中心或指定的位置上。

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

用法

frame.hover(selector)
frame.hover(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
force bool (可选)#

是否绕过可操作性检查。默认值为 false。
modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前修饰键。如果未指定，则使用当前按下的修饰键。 "ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。
no_wait_after bool (可选)新增于：v1.28#

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果没有指定，则使用元素的一些可见点。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

以毫秒为单位的最大时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)添加于: v1.11#

当设置时，此方法仅执行可操作性检查，并跳过操作。默认为 false。用于在不执行操作的情况下等待元素准备好执行操作。请注意，无论 trial 如何，键盘 modifiers 都将被按下，以允许测试仅在按下这些键时才可见的元素。

返回值

NoneType #

inner_html

在 v1.9 之前添加

frame.inner_html

不建议

使用基于定位器的 locator.inner_html() 代替。了解更多关于定位器。

返回 element.innerHTML。

用法

frame.inner_html(selector)
frame.inner_html(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

str #

inner_text

在 v1.9 之前添加

frame.inner_text

不建议

使用基于定位器的 locator.inner_text() 代替。了解更多关于定位器。

返回 element.innerText。

用法

frame.inner_text(selector)
frame.inner_text(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

str #

input_value

添加于：v1.13

frame.input_value

不建议

使用基于定位器的 locator.input_value() 代替。了解更多关于定位器。

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

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

用法

frame.input_value(selector)
frame.input_value(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

str #

is_checked

在 v1.9 之前添加

frame.is_checked

不建议

使用基于定位器的 locator.is_checked() 代替。了解更多关于定位器。

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

用法

frame.is_checked(selector)
frame.is_checked(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

bool #

is_disabled

在 v1.9 之前添加

frame.is_disabled

不建议

使用基于定位器的 locator.is_disabled() 代替。了解更多关于定位器。

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

用法

frame.is_disabled(selector)
frame.is_disabled(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

bool #

is_editable

在 v1.9 之前添加

frame.is_editable

不建议

使用基于定位器的 locator.is_editable() 代替。了解更多关于定位器。

返回元素是否可编辑。

用法

frame.is_editable(selector)
frame.is_editable(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

bool #

is_hidden

在 v1.9 之前添加

frame.is_hidden

不建议

使用基于定位器的 locator.is_hidden() 代替。了解更多关于定位器。

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

用法

frame.is_hidden(selector)
frame.is_hidden(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

已弃用
此选项将被忽略。 frame.is_hidden() 不会等待元素变为隐藏，并立即返回。

返回值

bool #

is_visible

在 v1.9 之前添加

frame.is_visible

不建议

使用基于定位器的 locator.is_visible() 代替。了解更多关于定位器。

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

用法

frame.is_visible(selector)
frame.is_visible(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

已弃用
此选项被忽略。 frame.is_visible() 不会等待元素变为可见，而是立即返回。

返回值

bool #

press

在 v1.9 之前添加

frame.press

不建议

请改用基于定位器的 locator.press()。了解更多关于定位器。

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" 等快捷方式。当使用修饰符指定时，修饰符将在按下后续键时按下并保持按下状态。

用法

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

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
key str #

要按下的键的名称或要生成的字符，例如 ArrowLeft 或 a。
delay float (可选)#

keydown 和 keyup 之间等待的时间（以毫秒为单位）。默认值为 0。
no_wait_after bool (可选)#

已弃用
此选项将在将来默认为 true。

启动导航的操作将等待这些导航发生，并等待页面开始加载。您可以通过设置此标志来选择退出等待。您只需要在特殊情况下使用此选项，例如导航到不可访问的页面。默认为 false。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

NoneType #

query_selector

添加于：v1.9

frame.query_selector

不建议

请改用基于定位器的 frame.locator()。了解更多关于定位器。

返回指向框架元素的 ElementHandle。

注意

不建议使用 ElementHandle，请改用 Locator 对象和以网页为中心的断言。

此方法在框架内查找与指定选择器匹配的元素。如果没有任何元素与选择器匹配，则返回 null。

用法

frame.query_selector(selector)
frame.query_selector(selector, **kwargs)

参数

selector str #

要查询的选择器。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。

返回值

NoneType | ElementHandle #

query_selector_all

添加于：v1.9

frame.query_selector_all

不建议

请改用基于定位器的 frame.locator()。了解更多关于定位器。

返回指向框架元素的 ElementHandles。

注意

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

此方法在框架内查找与指定选择器匹配的所有元素。如果没有任何元素与选择器匹配，则返回空数组。

用法

frame.query_selector_all(selector)

参数

selector str #

要查询的选择器。

返回值

List[ElementHandle]#

select_option

在 v1.9 之前添加

frame.select_option

不建议

请改用基于定位器的 locator.select_option()。了解更多关于定位器。

此方法将等待与 selector 匹配的元素，等待操作性检查，等待所有指定的选项出现在 <select> 元素中，然后选择这些选项。

如果目标元素不是 <select> 元素，则此方法将引发错误。但是，如果元素位于与 control 关联的 <label> 元素中，则将改用该控制元素。

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

在选择完所有提供的选项后，触发 change 和 input 事件。

用法

同步
异步

# Single selection matching the value or label
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"])

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

参数

selector str #

要查询的选择器。
force bool (可选)添加于：v1.13#

是否绕过可操作性检查。默认值为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

以毫秒为单位的最大时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
element ElementHandle | List[ElementHandle] (可选)#

要选择的选项元素。可选。
index int | List[int] (可选)#

要按索引选择的选项。可选。
value str | List[str] (可选)#

要按值选择的选项。如果 <select> 具有 multiple 属性，则选择所有给定的选项，否则仅选择与传递的选项之一匹配的第一个选项。可选。
label str | List[str] (可选)#

要按标签选择的选项。如果 <select> 具有 multiple 属性，则选择所有给定的选项，否则仅选择与传递的选项之一匹配的第一个选项。可选。

返回值

List[str]#

set_checked

新增于：v1.15

frame.set_checked

不建议

请改用基于定位器的 locator.set_checked()。了解更多关于定位器。

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

查找与 selector 匹配的元素。如果没有，则等待与 DOM 关联的匹配元素。
确保匹配的元素是复选框或单选按钮。如果不是，则此方法将引发错误。
如果元素已经具有正确的选中状态，则此方法会立即返回。
在匹配的元素上等待操作性检查，除非设置了 force 选项。如果元素在检查期间被分离，则会重试整个操作。
如果需要，将元素滚动到视图中。
使用 page.mouse 点击元素的中心。
确保元素现在已选中或取消选中。如果不是，则此方法将引发错误。

如果在指定超时时间内，所有步骤都未完成，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

用法

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

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
checked bool #

是否选中复选框。
force bool (可选)#

是否绕过可操作性检查。默认值为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果没有指定，则使用元素的一些可见点。
strict bool (可选)#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

以毫秒为单位的最大时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)#

设置后，此方法仅执行可操作性检查并跳过操作。默认值为 false。用于在执行操作之前等待元素准备好。

返回值

NoneType #

set_input_files

在 v1.9 之前添加

frame.set_input_files

不建议

请使用基于定位器的 locator.set_input_files()。了解更多关于定位器的信息。

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

此方法期望 selector 指向 input 元素。但是，如果元素在具有关联 control 的 <label> 元素中，则将目标定位到 control。

用法

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

参数

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 (可选)#

已弃用
此选项无效。

此选项无效。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

NoneType #

tap

在 v1.9 之前添加

frame.tap

不建议

请使用基于定位器的 locator.tap()。了解更多关于定位器的信息。

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

找到与 selector 匹配的元素。如果没有，则等待匹配的元素附加到 DOM。
等待对匹配元素进行可操作性检查，除非设置了 force 选项。如果元素在检查期间被分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.touchscreen 点击元素的中心或指定的位置。

如果在指定超时时间内，所有步骤都未完成，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

注意

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

用法

frame.tap(selector)
frame.tap(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
force bool (可选)#

是否绕过可操作性检查。默认值为 false。
modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前修饰键。如果未指定，则使用当前按下的修饰键。 "ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
position Dict (可选)#
- x float
- y float
相对于元素内边距框左上角的点。如果没有指定，则使用元素的一些可见点。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

以毫秒为单位的最大时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)添加于: v1.11#

当设置时，此方法仅执行可操作性检查，并跳过操作。默认为 false。用于在不执行操作的情况下等待元素准备好执行操作。请注意，无论 trial 如何，键盘 modifiers 都将被按下，以允许测试仅在按下这些键时才可见的元素。

返回值

NoneType #

text_content

在 v1.9 之前添加

frame.text_content

不建议

请使用基于定位器的 locator.text_content()。了解更多关于定位器的信息。

返回 element.textContent。

用法

frame.text_content(selector)
frame.text_content(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

NoneType | str #

type

在 v1.9 之前添加

frame.type

已弃用

在大多数情况下，您应该使用 locator.fill()。只有当页面上有特殊的键盘处理时，您才需要逐个按下键 - 在这种情况下，请使用 locator.press_sequentially()。

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

要按下特殊键，例如 Control 或 ArrowDown，请使用 keyboard.press()。

用法

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
text str #

要输入到聚焦元素的文本。
delay float (可选)#

键入之间等待的时间，以毫秒为单位。默认为 0。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

NoneType #

uncheck

在 v1.9 之前添加

frame.uncheck

不建议

请使用基于定位器的 locator.uncheck()。了解更多关于定位器的信息。

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

查找与选择器匹配的元素。如果不存在，则等待直到匹配元素附加到 DOM。
确保匹配的元素是复选框或单选按钮。如果不是，此方法将抛出异常。如果元素已经取消选中，则此方法立即返回。
等待对匹配元素进行操作性检查，除非设置了force选项。如果元素在检查期间分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 点击元素的中心。
确保元素现在已取消选中。如果不是，此方法将抛出异常。

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

用法

frame.uncheck(selector)
frame.uncheck(selector, **kwargs)

参数

selector str #

用于搜索元素的选择器。如果有多个元素满足选择器，则将使用第一个元素。
force bool (可选)#

是否绕过可操作性检查。默认值为 false。
no_wait_after bool (可选)#

已弃用
此选项无效。

此选项无效。
position Dict (可选)添加于: v1.11#
- x float
- y float
相对于元素内边距框左上角的点。如果没有指定，则使用元素的一些可见点。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

以毫秒为单位的最大时间。默认值为 30000（30 秒）。传递 0 以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
trial bool (可选)添加于: v1.11#

设置后，此方法仅执行可操作性检查并跳过操作。默认值为 false。用于在执行操作之前等待元素准备好。

返回值

NoneType #

wait_for_selector

在 v1.9 之前添加

frame.wait_for_selector

不建议

使用断言可见性或基于定位器的locator.wait_for()的 Web 断言。详细了解定位器。

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

注意

Playwright 会自动等待元素准备好，然后再执行操作。使用Locator 对象和 Web 首选断言可以使代码无需等待选择器。

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

用法

此方法在导航之间有效

同步
异步

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: 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)

import asyncio
from playwright.async_api import async_playwright, Playwright

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

async def main():
    async with async_playwright() as playwright:
        await run(playwright)
asyncio.run(main())

参数

selector str #

要查询的选择器。
state "attached" | "detached" | "visible" | "hidden" (可选)#

默认为 'visible'。可以是以下之一：
- 'attached' - 等待元素出现在 DOM 中。
- 'detached' - 等待元素不再出现在 DOM 中。
- 'visible' - 等待元素具有非空边界框且没有 visibility:hidden。请注意，没有内容或具有 display:none 的元素具有空边界框，不被视为可见。
- 'hidden' - 等待元素从 DOM 中分离，或具有空边界框或 visibility:hidden。这与 'visible' 选项相反。
strict bool (可选)添加于：v1.14#

如果为 true，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会引发异常。
timeout float (可选)#

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

返回值

NoneType | ElementHandle #

wait_for_timeout

在 v1.9 之前添加

frame.wait_for_timeout

不建议

永远不要在生产环境中等待超时。等待时间的测试本质上是脆弱的。使用Locator 操作和自动等待的 Web 断言。

等待给定的超时（以毫秒为单位）。

请注意，frame.waitForTimeout() 仅应用于调试。在生产环境中使用计时器的测试将很脆弱。相反，请使用网络事件、选择器变为可见等信号。

用法

frame.wait_for_timeout(timeout)

参数

timeout float #

要等待的超时

返回值

NoneType #

方法​

add_script_tag​

add_style_tag​

content​

drag_and_drop​

evaluate​

evaluate_handle​

frame_element​

frame_locator​

get_by_alt_text​

get_by_label​

get_by_placeholder​

get_by_role​

get_by_test_id​

get_by_text​

get_by_title​

goto​

is_enabled​

locator​

set_content​

title​

wait_for_function​

wait_for_load_state​

wait_for_url​

属性​

child_frames​

is_detached​

name​

page​

parent_frame​

url​

已弃用​

check​

click​

dblclick​

dispatch_event​

eval_on_selector​

eval_on_selector_all​

expect_navigation​

fill​

focus​

get_attribute​

hover​

inner_html​

inner_text​

input_value​

is_checked​

is_disabled​

is_editable​

is_hidden​

is_visible​

press​

query_selector​

query_selector_all​

select_option​

set_checked​

set_input_files​

tap​

text_content​

type​

uncheck​

wait_for_selector​

wait_for_timeout​

方法

add_script_tag

add_style_tag

content

drag_and_drop

evaluate

evaluate_handle

frame_element

frame_locator

get_by_alt_text

get_by_label

get_by_placeholder

get_by_role

get_by_test_id

get_by_text

get_by_title

goto

is_enabled

locator

set_content

title

wait_for_function

wait_for_load_state

wait_for_url

属性

child_frames

is_detached

name

page

parent_frame

url

已弃用

check

click

dblclick

dispatch_event

eval_on_selector

eval_on_selector_all

expect_navigation

fill

focus

get_attribute

hover

inner_html

inner_text

input_value

is_checked

is_disabled

is_editable

is_hidden

is_visible

press

query_selector

query_selector_all

select_option

set_checked

set_input_files

tap

text_content

type

uncheck

wait_for_selector

wait_for_timeout