Frame

在任何时刻，页面都可以通过 page.main_frame 和 frame.child_frames 方法获取其当前的 frame 树结构。

Frame 对象的生命周期由三个事件控制，这些事件会在 page 对象上触发：

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

以下是输出 frame 树的示例：

同步
异步

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 事件触发或脚本内容被注入到 frame 时，返回添加的标签。

在页面中插入一个带有指定 url 或内容的 <script> 标签。

用法

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

参数

content str (可选)#

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

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

脚本类型。使用 'module' 可以加载 JavaScript ES6 模块。详见 script。
url str (可选)#

要添加的脚本的 URL。

返回值

ElementHandle #

add_style_tag

v1.9 之前添加

frame.add_style_tag

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

在页面中插入一个带有指定 url 的 <link rel="stylesheet"> 标签，或带有内容的 <style type="text/css"> 标签。

用法

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

参数

content str (可选)#

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

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

<link> 标签的 URL。

返回值

ElementHandle #

content

v1.9 之前添加

frame.content

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

用法

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

是否跳过actionability检查。默认为 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 (可选)#

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

返回值

NoneType #

evaluate

v1.9 之前添加

frame.evaluate

返回expression的返回值。

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

如果传递给 frame.evaluate() 的函数返回一个非 Serializable 的值，则 frame.evaluate() 返回 undefined。Playwright 还支持传递一些 JSON 无法序列化的特殊值：-0、NaN、Infinity、-Infinity。

用法

同步
异步

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

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

也可以直接传递字符串而不是函数。

同步
异步

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

print(await frame.evaluate("1 + 2")) # 打印 "3"
x = 10
print(await frame.evaluate(f"1 + {x}")) # 打印 "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 的可选参数。

返回值

Dict #

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 # window 对象的句柄。

a_window_handle = await frame.evaluate_handle("Promise.resolve(window)")
a_window_handle # window 对象的句柄。

也可以直接传递字符串而不是函数。

同步
异步

a_handle = page.evaluate_handle("document") # "document" 对象的句柄

a_handle = await page.evaluate_handle("document") # "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。

如果 frame 在 frameElement() 返回前已被分离，则该方法会抛出异常。

用法

同步
异步

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 定位器（frame locator），进入指定的 iframe 并在其中选择元素。

用法

以下代码片段演示了如何在 id 为 my-iframe 的 iframe（如 <iframe id="my-iframe">）中定位文本为“Submit”的元素：

同步
异步

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

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

用法

例如，以下方法会通过 alt 文本“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 属性定位输入元素。

用法

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

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

同步
异步

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

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

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

用法

例如，考虑如下 DOM 结构：

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

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

同步
异步

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

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

参数

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>

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

同步
异步

page.get_by_test_id("directions").click()  # 点击测试 id 为 directions 的按钮

await page.get_by_test_id("directions").click()  # 点击测试 id 为 directions 的按钮

参数

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>

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

同步
异步

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

参数

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

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

用法

考虑如下 DOM 结构：

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

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

同步
异步

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 无效。
导航过程中超过了 timeout 超时时间。
远程服务器无响应或无法访问。
主资源加载失败。

当远程服务器返回任何有效的 HTTP 状态码（包括 404 "未找到" 和 500 "服务器内部错误"）时，该方法不会抛出异常。此类响应的状态码可通过调用 response.status 获取。

备注

该方法要么抛出异常，要么返回主资源响应。唯一的例外是导航到 about:blank 或仅哈希变化的同一 URL，这种情况下会成功并返回 null。

备注

无头模式下不支持导航到 PDF 文档。详见上游问题。

用法

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

参数

url str #

要导航到的 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' - 不推荐，当至少 500ms 内没有网络连接时认为操作完成。不要用此方式做测试，建议通过断言判断页面是否准备好。
- '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

该方法返回一个元素定位器（locator），可用于在当前页面或 frame 上执行操作。定位器会在每次执行操作前实时解析到元素，因此对同一个定位器连续执行操作时，如果 DOM 结构发生变化，实际上可能操作的是不同的元素。

了解更多关于定位器。

用法

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

参数

selector str #

用于解析 DOM 元素的选择器。
has Locator (可选)#

进一步筛选包含指定相对定位器元素的结果。例如，article 包含 text=Playwright 会匹配 <article><div>Playwright</div></article>。

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

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

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

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

匹配内部不包含指定文本的元素，文本可以在子元素或后代元素中。传递字符串时，匹配不区分大小写并查找子串。
has_text str | Pattern (可选)#

匹配内部包含指定文本的元素，文本可以在子元素或后代元素中。传递字符串时，匹配不区分大小写并查找子串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

返回值

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' - 不推荐，当至少 500ms 内没有网络连接时认为操作完成。不要用此方式做测试，建议通过断言判断页面是否准备好。
- 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

NoneType #

title

v1.9 之前添加

frame.title

返回页面标题。

用法

frame.title()

返回值

str #

wait_for_function

v1.9 之前添加

frame.wait_for_function

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

用法

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

传递给 expression 的可选参数。
polling float | "raf" (可选)#

如果 polling 为 'raf'，则 expression 会在 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

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

当 frame 达到所需的加载状态时返回，默认是 load。调用该方法时，导航必须已经提交。如果当前文档已经达到所需状态，则会立即返回。

备注

大多数情况下无需调用此方法，因为 Playwright 每个操作前都会自动等待。

用法

同步
异步

frame.click("button") # 点击会触发导航
frame.wait_for_load_state() # 在 "load" 事件后 promise 解析

await frame.click("button") # 点击会触发导航
await frame.wait_for_load_state() # 在 "load" 事件后 promise 解析

参数

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

要等待的加载状态，默认为 load。如果加载当前文档时该状态已达成，则方法会立即返回。可选值如下：
- 'load' - 等待触发 load 事件。
- 'domcontentloaded' - 等待触发 DOMContentLoaded 事件。
- 'networkidle' - 不推荐，等待至少 500ms 内没有网络连接。不要用此方式做测试，建议通过断言判断页面是否准备好。
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

等待 frame 跳转到指定的 URL。

用法

同步
异步

frame.click("a.delayed-navigation") # 点击该链接会间接触发跳转
frame.wait_for_url("**/target.html")

await frame.click("a.delayed-navigation") # 点击该链接会间接触发跳转
await frame.wait_for_url("**/target.html")

参数

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

用于等待跳转的 glob 模式、正则表达式或接收 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' - 不推荐，当至少 500ms 内没有网络连接时认为操作完成。不要用此方式做测试，建议通过断言判断页面是否准备好。
- 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

NoneType #

属性

child_frames

v1.9 之前添加

frame.child_frames

用法

frame.child_frames

返回值

List[Frame]#

is_detached

v1.9 之前添加

frame.is_detached

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

用法

frame.is_detached()

返回值

bool #

name

v1.9 之前添加

frame.name

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

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

备注

该值在 frame 创建时计算一次，如果之后属性发生变化不会更新。

用法

frame.name

返回值

str #

page

v1.9 之前添加

frame.page

返回包含该 frame 的页面对象。

用法

frame.page

返回值

Page #

parent_frame

v1.9 之前添加

frame.parent_frame

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

用法

frame.parent_frame

返回值

NoneType | Frame #

url

v1.9 之前添加

frame.url

返回 frame 的 url。

用法

frame.url

返回值

str #

已废弃

check

v1.9 之前添加

frame.check

不推荐

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

该方法通过以下步骤勾选匹配 selector 的元素：

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

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

用法

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

参数

selector str #

用于查找元素的选择器。如果有多个元素匹配该选择器，则使用第一个。
force bool (可选)#

是否跳过actionability检查。默认为 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#

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

返回值

NoneType #

click

v1.9 之前添加

frame.click

不推荐

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

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

查找匹配 selector 的元素。如果没有，则等待有匹配的元素被添加到 DOM。
对匹配的元素执行actionability检查，除非设置了 force 选项。如果检查期间元素被分离，则整个操作会重试。
如有需要，将元素滚动到可视区域。
使用 page.mouse 在元素中心或指定的 position 位置点击。
等待由点击触发的导航操作完成或失败，除非设置了 no_wait_after 选项。

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

用法

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

是否跳过actionability检查。默认为 false。
modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#

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

已废弃
该选项未来将默认为 true。

会触发导航的操作会等待导航发生并页面开始加载。你可以通过设置此参数为 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#

设置后，此方法只执行actionability检查，不执行实际操作。默认为 false。可用于等待元素准备好操作但不实际执行。注意即使设置了 trial，键盘 modifiers 依然会被按下，以便测试只有按下这些键时才可见的元素。

返回值

NoneType #

dblclick

v1.9 之前添加

frame.dblclick

不推荐

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

该方法通过以下步骤双击匹配 selector 的元素：

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

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

备注

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

是否跳过actionability检查。默认为 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#

设置后，此方法只执行actionability检查，不执行实际操作。默认为 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 作为属性值传递，以便将实时对象传递到事件中：

同步
异步

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

# 注意，只有在 chromium 和 firefox 中才能创建 data_transfer
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-first 断言。

返回 expression 的返回值。

该方法会在 frame 内查找与指定选择器匹配的元素，并将其作为第一个参数传递给 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 时，要求选择器只能匹配到一个元素。如果选择器匹配到多个元素，则抛出异常。

返回值

Dict #

eval_on_selector_all

新增于: v1.9

frame.eval_on_selector_all

不推荐

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

返回 expression 的返回值。

该方法会在 frame 内查找所有与指定选择器匹配的元素，并将匹配到的元素数组作为第一个参数传递给 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 的可选参数。

返回值

Dict #

v1.9 之前添加

frame.expect_navigation

已废弃

该方法本身存在竞态问题，请使用 frame.wait_for_url() 代替。

等待 frame 导航并返回主资源响应对象。如果发生多次重定向，导航操作会返回最后一次重定向的响应。如果是跳转到不同的锚点或通过 History API 导航，则会返回 null。

用法

该方法会等待 frame 跳转到新 URL。适用于你执行的代码会间接导致 frame 导航的场景。例如：

同步
异步

with frame.expect_navigation():
    frame.click("a.delayed-navigation") # 点击该链接会间接触发跳转
# 跳转完成后解析

async with frame.expect_navigation():
    await frame.click("a.delayed-navigation") # 点击该链接会间接触发跳转
# 跳转完成后解析

备注

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

用于等待跳转的 glob 模式、正则表达式或接收 URL 的谓词函数。注意，如果参数是没有通配符的字符串，则方法会等待跳转到与该字符串完全相等的 URL。
wait_until "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

何时认为操作成功，默认为 load。可选事件如下：
- 'domcontentloaded' - 当触发 DOMContentLoaded 事件时认为操作完成。
- 'load' - 当触发 load 事件时认为操作完成。
- 'networkidle' - 不推荐，当至少 500ms 内没有网络连接时认为操作完成。不要用此方式做测试，建议通过断言判断页面是否准备好。
- 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

EventContextManager[Response]#

fill

v1.9 之前添加

frame.fill

不推荐

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

该方法会等待出现匹配 selector 的元素，等待actionability检查，聚焦该元素，填充内容，并在填充后触发 input 事件。注意，你可以传递空字符串来清空输入框。

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

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

用法

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

参数

selector str #

用于查找元素的选择器。如果有多个元素匹配该选择器，则使用第一个。
value str #

要填充到 <input>、<textarea> 或 [contenteditable] 元素的值。
force bool (可选) 新增于: v1.13#

是否跳过actionability检查。默认为 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 的元素并聚焦。如果没有匹配的元素，则会等待直到有匹配的元素出现在 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。
对匹配的元素执行actionability检查，除非设置了 force 选项。如果检查期间元素被分离，则整个操作会重试。
如有需要，将元素滚动到可视区域。
使用 page.mouse 在元素中心或指定的 position 位置悬停。

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

用法

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

参数

selector str #

用于查找元素的选择器。如果有多个元素匹配该选择器，则使用第一个。
force bool (可选)#

是否跳过actionability检查。默认为 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#

设置后，此方法只执行actionability检查，不执行实际操作。默认为 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> 内，则返回 control 的值。

用法

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()。了解更多关于定位器。

返回元素是否为隐藏状态，与可见相反。如果 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。

会触发导航的操作会等待导航发生并页面开始加载。你可以通过设置此参数为 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()。了解更多关于定位器。

返回指向 frame 元素的 ElementHandle。

警告

不推荐使用 ElementHandle，请使用 Locator 对象和 web-first 断言。

该方法会在 frame 内查找与指定选择器匹配的元素。如果没有元素匹配选择器，则返回 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()。了解更多关于定位器。

返回指向 frame 元素的 ElementHandle 列表。

警告

不推荐使用 ElementHandle，请使用 Locator 对象。

该方法会在 frame 内查找所有与指定选择器匹配的元素。如果没有元素匹配选择器，则返回空数组。

用法

frame.query_selector_all(selector)

参数

selector str #

用于查询的选择器。

返回值

List[ElementHandle]#

select_option

v1.9 之前添加

frame.select_option

不推荐

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

该方法会等待出现匹配 selector 的元素，等待actionability检查，等待所有指定的选项出现在 <select> 元素中，并选择这些选项。

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

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

当所有提供的选项被选中后，会触发 change 和 input 事件。

用法

同步
异步

# 单选，匹配 value 或 label
frame.select_option("select#colors", "blue")
# 单选，匹配 label
frame.select_option("select#colors", label="blue")
# 多选
frame.select_option("select#colors", value=["red", "green", "blue"])

# 单选，匹配 value 或 label
await frame.select_option("select#colors", "blue")
# 单选，匹配 label
await frame.select_option("select#colors", label="blue")
# 多选
await frame.select_option("select#colors", value=["red", "green", "blue"])

参数

selector str #

用于查询的选择器。
force bool (可选) 新增于: v1.13#

是否跳过actionability检查。默认为 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] (可选)#

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

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

通过 value 选择的选项。如果 <select> 有 multiple 属性，则会选中所有给定的选项，否则只选中第一个匹配的选项。可选。
label str | List[str] (可选)#

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

返回值

List[str]#

set_checked

新增于: v1.15

frame.set_checked

不推荐

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

该方法会对匹配 selector 的元素进行勾选或取消勾选，具体步骤如下：

查找匹配 selector 的元素。如果没有，则等待有匹配的元素被添加到 DOM。
确保匹配的元素是复选框或单选框。如果不是，则该方法会抛出异常。
如果元素已经处于目标勾选状态，则方法会立即返回。
对匹配的元素执行actionability检查，除非设置了 force 选项。如果检查期间元素被分离，则整个操作会重试。
如有需要，将元素滚动到可视区域。
使用 page.mouse 在元素中心点击。
确保元素现在已被勾选或取消勾选。如果不是，则该方法会抛出异常。

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

用法

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

参数

selector str #

用于查找元素的选择器。如果有多个元素匹配该选择器，则使用第一个。
checked bool #

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

是否跳过actionability检查。默认为 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 (可选)#

设置后，此方法只执行actionability检查，不执行实际操作。默认为 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。
对匹配的元素执行actionability检查，除非设置了 force 选项。如果检查期间元素被分离，则整个操作会重试。
如有需要，将元素滚动到可视区域。
使用 page.touchscreen 在元素中心或指定的 position 位置点击。

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

备注

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

用法

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

参数

selector str #

用于查找元素的选择器。如果有多个元素匹配该选择器，则使用第一个。
force bool (可选)#

是否跳过actionability检查。默认为 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#

设置后，此方法只执行actionability检查，不执行实际操作。默认为 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 的元素执行取消勾选操作，具体步骤如下：

查找匹配 selector 的元素。如果没有，则等待有匹配的元素被添加到 DOM。
确保匹配的元素是复选框或单选框。如果不是，则该方法会抛出异常。如果元素已经处于未勾选状态，则方法会立即返回。
对匹配的元素执行actionability检查，除非设置了 force 选项。如果检查期间元素被分离，则整个操作会重试。
如有需要，将元素滚动到可视区域。
使用 page.mouse 在元素中心点击。
确保元素现在已被取消勾选。如果不是，则该方法会抛出异常。

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

用法

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

参数

selector str #

用于查找元素的选择器。如果有多个元素匹配该选择器，则使用第一个。
force bool (可选)#

是否跳过actionability检查。默认为 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#

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

返回值

NoneType #

wait_for_selector

v1.9 之前添加

frame.wait_for_selector

不推荐

请使用断言可见性的 web 断言或基于定位器的 locator.wait_for() 代替。了解更多关于定位器。

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

备注

Playwright 会在执行操作前自动等待元素就绪。使用 Locator 对象和 web-first 断言可以让代码无需 wait-for-selector。

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

用法

该方法可跨页面跳转使用：

同步
异步

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("已加载图片: " + 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("已加载图片: " + 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 断言。

等待指定的 timeout 毫秒。

注意，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