Page
Page 提供了与 Browser 中的单个标签页或 Chromium 中的 扩展背景页 交互的方法。一个 Browser 实例可以有多个 Page 实例。
此示例创建一个页面,导航到 URL,然后保存屏幕截图
- 同步
- 异步
from playwright.sync_api import sync_playwright, Playwright
def run(playwright: Playwright):
webkit = playwright.webkit
browser = webkit.launch()
context = browser.new_context()
page = context.new_page()
page.goto("https://example.com")
page.screenshot(path="screenshot.png")
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()
context = await browser.new_context()
page = await context.new_page()
await page.goto("https://example.com")
await page.screenshot(path="screenshot.png")
await browser.close()
async def main():
async with async_playwright() as playwright:
await run(playwright)
asyncio.run(main())
Page 类会发出各种事件(如下所述),可以使用 Node 的任何原生 EventEmitter
方法(例如 on
、once
或 removeListener
)进行处理。
此示例记录单个页面 load
事件的消息
page.once("load", lambda: print("page loaded!"))
要取消订阅事件,请使用 removeListener
方法
def log_request(intercepted_request):
print("a request was made:", intercepted_request.url)
page.on("request", log_request)
# sometime later...
page.remove_listener("request", log_request)
方法
add_init_script
v1.9 之前添加添加一个脚本,该脚本将在以下情况之一中进行评估:
- 每当页面导航时。
- 每当子框架附加或导航时。在这种情况下,脚本在新附加框架的上下文中进行评估。
脚本在文档创建后但在任何脚本运行之前进行评估。这对于修改 JavaScript 环境非常有用,例如,为 Math.random
设置种子。
用法
在页面加载之前覆盖 Math.random
的示例
// preload.js
Math.random = () => 42;
- 同步
- 异步
# in your playwright script, assuming the preload.js file is in same directory
page.add_init_script(path="./preload.js")
# in your playwright script, assuming the preload.js file is in same directory
await page.add_init_script(path="./preload.js")
通过 browser_context.add_init_script() 和 page.add_init_script() 安装的多个脚本的评估顺序未定义。
参数
-
path
Union[str, pathlib.Path] (可选)#JavaScript 文件的路径。如果
path
是相对路径,则它相对于当前工作目录解析。可选。 -
要在浏览器上下文中所有页面中评估的脚本。可选。
返回
add_locator_handler
新增于: v1.42在测试网页时,有时会出现意外的覆盖层,例如“注册”对话框,并阻止您想要自动化的操作,例如点击按钮。这些覆盖层不总是以相同的方式或在相同的时间出现,这使得它们在自动化测试中难以处理。
此方法允许您设置一个特殊函数,称为处理程序,当它检测到覆盖层可见时激活。处理程序的任务是删除覆盖层,让您的测试继续,就像覆盖层不存在一样。
要记住的事情
- 当覆盖层可预测地显示时,我们建议在您的测试中明确等待它,并将其作为您正常测试流程的一部分进行消除,而不是使用 page.add_locator_handler()。
- Playwright 在每次执行或重试需要可操作性检查的操作之前,或在执行自动等待断言检查之前,都会检查覆盖层。当覆盖层可见时,Playwright 首先调用处理程序,然后继续执行操作/断言。请注意,处理程序仅在您执行操作/断言时调用 - 如果覆盖层变得可见但您不执行任何操作,则处理程序不会被触发。
- 执行处理程序后,Playwright 将确保触发处理程序的覆盖层不再可见。您可以使用 no_wait_after 选项退出此行为。
- 处理程序的执行时间计入执行处理程序的操作/断言的超时。如果您的处理程序花费时间过长,可能会导致超时。
- 您可以注册多个处理程序。但是,一次只能运行一个处理程序。请确保处理程序内的操作不依赖于另一个处理程序。
运行处理程序将改变您的页面状态。例如,它将改变当前焦点元素并移动鼠标。请确保在处理程序之后运行的操作是自包含的,并且不依赖于焦点和鼠标状态不变。
例如,考虑一个调用 locator.focus(),然后调用 keyboard.press() 的测试。如果您的处理程序在这两个操作之间点击了一个按钮,焦点元素很可能会出错,并且按键将发生在意外的元素上。请改用 locator.press() 以避免此问题。
另一个示例是一系列鼠标操作,其中 mouse.move() 后面跟着 mouse.down()。同样,当处理程序在这两个操作之间运行时,鼠标位置在鼠标按下时将是错误的。建议使用自包含的操作,例如 locator.click(),这些操作不依赖于处理程序不会改变状态。
用法
一个在“注册新闻通讯”对话框出现时关闭它的示例
- 同步
- 异步
# Setup the handler.
def handler():
page.get_by_role("button", name="No thanks").click()
page.add_locator_handler(page.get_by_text("Sign up to the newsletter"), handler)
# Write the test as usual.
page.goto("https://example.com")
page.get_by_role("button", name="Start here").click()
# Setup the handler.
async def handler():
await page.get_by_role("button", name="No thanks").click()
await page.add_locator_handler(page.get_by_text("Sign up to the newsletter"), handler)
# Write the test as usual.
await page.goto("https://example.com")
await page.get_by_role("button", name="Start here").click()
一个在显示“确认您的安全详细信息”页面时跳过它的示例
- 同步
- 异步
# Setup the handler.
def handler():
page.get_by_role("button", name="Remind me later").click()
page.add_locator_handler(page.get_by_text("Confirm your security details"), handler)
# Write the test as usual.
page.goto("https://example.com")
page.get_by_role("button", name="Start here").click()
# Setup the handler.
async def handler():
await page.get_by_role("button", name="Remind me later").click()
await page.add_locator_handler(page.get_by_text("Confirm your security details"), handler)
# Write the test as usual.
await page.goto("https://example.com")
await page.get_by_role("button", name="Start here").click()
一个在每次可操作性检查时带有自定义回调的示例。它使用一个始终可见的 <body>
定位符,因此处理程序在每次可操作性检查之前都会被调用。指定 no_wait_after 很重要,因为处理程序不会隐藏 <body>
元素。
- 同步
- 异步
# Setup the handler.
def handler():
page.evaluate("window.removeObstructionsForTestIfNeeded()")
page.add_locator_handler(page.locator("body"), handler, no_wait_after=True)
# Write the test as usual.
page.goto("https://example.com")
page.get_by_role("button", name="Start here").click()
# Setup the handler.
async def handler():
await page.evaluate("window.removeObstructionsForTestIfNeeded()")
await page.add_locator_handler(page.locator("body"), handler, no_wait_after=True)
# Write the test as usual.
await page.goto("https://example.com")
await page.get_by_role("button", name="Start here").click()
处理程序将原始定位器作为参数。您还可以通过设置 times 在调用次数达到一定次数后自动移除处理程序。
- 同步
- 异步
def handler(locator):
locator.click()
page.add_locator_handler(page.get_by_label("Close"), handler, times=1)
async def handler(locator):
await locator.click()
await page.add_locator_handler(page.get_by_label("Close"), handler, times=1)
参数
-
触发处理程序的定位器。
-
当 定位器 出现时应运行的函数。此函数应消除阻止点击等操作的元素。
-
no_wait_after
bool (可选)新增于:v1.44#默认情况下,在调用处理程序后,Playwright 将等待覆盖层隐藏,然后 Playwright 将继续执行触发处理程序的操作/断言。此选项允许选择退出此行为,以便在处理程序运行后覆盖层可以保持可见。
-
指定此处理程序应被调用的最大次数。默认无限制。
返回
add_script_tag
v1.9 之前添加将带有所需 URL 或内容的 <script>
标签添加到页面中。当脚本的 onload 事件触发或脚本内容注入到框架中时,返回添加的标签。
用法
page.add_script_tag()
page.add_script_tag(**kwargs)
参数
-
要注入到框架中的原始 JavaScript 内容。
-
path
Union[str, pathlib.Path] (可选)#要注入到框架中的 JavaScript 文件路径。如果
path
是相对路径,则它相对于当前工作目录解析。 -
脚本类型。使用 'module' 以加载 JavaScript ES6 模块。有关详细信息,请参阅 script。
-
要添加的脚本的 URL。
返回
add_style_tag
v1.9 之前添加使用所需 URL 向页面添加 <link rel="stylesheet">
标签或使用内容添加 <style type="text/css">
标签。当样式表 onload 事件触发或 CSS 内容注入到框架中时,返回添加的标签。
用法
page.add_style_tag()
page.add_style_tag(**kwargs)
参数
-
要注入到框架中的原始 CSS 内容。
-
path
Union[str, pathlib.Path] (可选)#要注入到框架中的 CSS 文件路径。如果
path
是相对路径,则它相对于当前工作目录解析。 -
<link>
标签的 URL。
返回
bring_to_front
v1.9 之前添加将页面带到前面(激活标签页)。
用法
page.bring_to_front()
返回
close
v1.9 之前添加如果 run_before_unload 为 false
,则不运行任何卸载处理程序并等待页面关闭。如果 run_before_unload 为 true
,则该方法将运行卸载处理程序,但不会等待页面关闭。
默认情况下,page.close()
不 运行 beforeunload
处理程序。
如果 run_before_unload 作为 true 传递,可能会出现 beforeunload
对话框,应通过 page.on("dialog") 事件手动处理。
用法
page.close()
page.close(**kwargs)
参数
-
要报告给因页面关闭而中断的操作的原因。
-
默认为
false
。是否运行 before unload 页面处理程序。
返回
content
v1.9 之前添加获取页面的完整 HTML 内容,包括 doctype。
用法
page.content()
返回
drag_and_drop
添加于:v1.13此方法将源元素拖动到目标元素。它将首先移动到源元素,执行 mousedown
,然后移动到目标元素并执行 mouseup
。
用法
- 同步
- 异步
page.drag_and_drop("#source", "#target")
# or specify exact positions relative to the top-left corners of the elements:
page.drag_and_drop(
"#source",
"#target",
source_position={"x": 34, "y": 7},
target_position={"x": 10, "y": 20}
)
await page.drag_and_drop("#source", "#target")
# or specify exact positions relative to the top-left corners of the elements:
await page.drag_and_drop(
"#source",
"#target",
source_position={"x": 34, "y": 7},
target_position={"x": 10, "y": 20}
)
参数
-
用于搜索要拖动的元素的选择器。如果有多个元素满足选择器,将使用第一个。
-
用于搜索要拖放到的元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
source_position
Dict (可选)新增于:v1.14#在此点(相对于元素内边距框的左上角)点击源元素。如果未指定,则使用元素的某个可见点。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
target_position
Dict (可选)新增于:v1.14#在此点(相对于元素内边距框的左上角)拖放到目标元素。如果未指定,则使用元素的某个可见点。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。
返回
emulate_media
v1.9 之前添加此方法通过 media
参数更改 CSS 媒体类型
,并通过 colorScheme
参数更改 'prefers-colors-scheme'
媒体功能。
用法
- 同步
- 异步
page.evaluate("matchMedia('screen').matches")
# → True
page.evaluate("matchMedia('print').matches")
# → False
page.emulate_media(media="print")
page.evaluate("matchMedia('screen').matches")
# → False
page.evaluate("matchMedia('print').matches")
# → True
page.emulate_media()
page.evaluate("matchMedia('screen').matches")
# → True
page.evaluate("matchMedia('print').matches")
# → False
await page.evaluate("matchMedia('screen').matches")
# → True
await page.evaluate("matchMedia('print').matches")
# → False
await page.emulate_media(media="print")
await page.evaluate("matchMedia('screen').matches")
# → False
await page.evaluate("matchMedia('print').matches")
# → True
await page.emulate_media()
await page.evaluate("matchMedia('screen').matches")
# → True
await page.evaluate("matchMedia('print').matches")
# → False
- 同步
- 异步
page.emulate_media(color_scheme="dark")
page.evaluate("matchMedia('(prefers-color-scheme: dark)').matches")
# → True
page.evaluate("matchMedia('(prefers-color-scheme: light)').matches")
# → False
await page.emulate_media(color_scheme="dark")
await page.evaluate("matchMedia('(prefers-color-scheme: dark)').matches")
# → True
await page.evaluate("matchMedia('(prefers-color-scheme: light)').matches")
# → False
参数
-
color_scheme
"light" | "dark" | "no-preference" | "null" (可选)添加于:v1.9#模拟 prefers-colors-scheme 媒体特性,支持的值为
'light'
和'dark'
。传入'Null'
会禁用配色方案模拟。'no-preference'
已弃用。 -
contrast
"no-preference" | "more" | "null" (可选)添加于: v1.51# -
forced_colors
"active" | "none" | "null" (可选)新增于: v1.15# -
media
"screen" | "print" | "null" (可选)添加于:v1.9#更改页面的 CSS 媒体类型。唯一允许的值是
'Screen'
、'Print'
和'Null'
。传入'Null'
会禁用 CSS 媒体模拟。 -
reduced_motion
"reduce" | "no-preference" | "null" (可选)添加于:v1.12#模拟
'prefers-reduced-motion'
媒体功能,支持的值为'reduce'
、'no-preference'
。传递null
会禁用减速运动模拟。
返回
evaluate
v1.9 之前添加返回 expression 调用的值。
如果传递给 page.evaluate() 的函数返回一个 Promise,那么 page.evaluate() 将等待 Promise 解析并返回其值。
如果传递给 page.evaluate() 的函数返回一个不可 序列化 的值,那么 page.evaluate() 解析为 undefined
。Playwright 还支持传输一些 JSON
不可序列化的额外值:-0
、NaN
、Infinity
、-Infinity
。
用法
将参数传递给 expression
- 同步
- 异步
result = page.evaluate("([x, y]) => Promise.resolve(x * y)", [7, 8])
print(result) # prints "56"
result = await page.evaluate("([x, y]) => Promise.resolve(x * y)", [7, 8])
print(result) # prints "56"
也可以传递字符串而不是函数
- 同步
- 异步
print(page.evaluate("1 + 2")) # prints "3"
x = 10
print(page.evaluate(f"1 + {x}")) # prints "11"
print(await page.evaluate("1 + 2")) # prints "3"
x = 10
print(await page.evaluate(f"1 + {x}")) # prints "11"
ElementHandle 实例可以作为参数传递给 page.evaluate()
- 同步
- 异步
body_handle = page.evaluate("document.body")
html = page.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
body_handle.dispose()
body_handle = await page.evaluate("document.body")
html = await page.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
await body_handle.dispose()
参数
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#传递给 expression 的可选参数。
返回
evaluate_handle
v1.9 之前添加将 expression 调用的值作为 JSHandle 返回。
page.evaluate() 和 page.evaluate_handle() 唯一的区别是 page.evaluate_handle() 返回 JSHandle。
如果传递给 page.evaluate_handle() 的函数返回一个 Promise,那么 page.evaluate_handle() 将等待 Promise 解析并返回其值。
用法
- 同步
- 异步
a_window_handle = page.evaluate_handle("Promise.resolve(window)")
a_window_handle # handle for the window object.
a_window_handle = await page.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 实例可以作为参数传递给 page.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()
参数
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#传递给 expression 的可选参数。
返回
expect_console_message
添加于:v1.9执行操作并等待页面记录 ConsoleMessage。如果提供了谓词,它将 ConsoleMessage 值传递给 predicate
函数,并等待 predicate(message)
返回一个真值。如果页面在 page.on("console") 事件触发之前关闭,将抛出错误。
用法
page.expect_console_message()
page.expect_console_message(**kwargs)
参数
-
predicate
可调用[ConsoleMessage]:布尔值 (可选)#接收 ConsoleMessage 对象,并在等待应解析时解析为真值。
-
最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 更改默认值。
返回
expect_download
添加于:v1.9执行操作并等待新的 Download。如果提供了谓词,它将 Download 值传递给 predicate
函数,并等待 predicate(download)
返回一个真值。如果页面在下载事件触发之前关闭,将抛出错误。
用法
page.expect_download()
page.expect_download(**kwargs)
参数
-
predicate
可调用[Download]:布尔值 (可选)#接收 Download 对象,并在等待应解析时解析为真值。
-
最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 更改默认值。
返回
expect_event
v1.9 之前添加等待事件触发并将其值传递给谓词函数。当谓词返回真值时返回。如果页面在事件触发之前关闭,将抛出错误。返回事件数据值。
用法
- 同步
- 异步
with page.expect_event("framenavigated") as event_info:
page.get_by_role("button")
frame = event_info.value
async with page.expect_event("framenavigated") as event_info:
await page.get_by_role("button")
frame = await event_info.value
参数
-
事件名称,通常传递给
*.on(event)
的相同名称。 -
接收事件数据,并在等待应该解决时解析为真值。
-
最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 更改默认值。
返回
expect_file_chooser
添加于:v1.9执行操作并等待新的 FileChooser 创建。如果提供了谓词,它将 FileChooser 值传递给 predicate
函数,并等待 predicate(fileChooser)
返回一个真值。如果页面在文件选择器打开之前关闭,将抛出错误。
用法
page.expect_file_chooser()
page.expect_file_chooser(**kwargs)
参数
-
predicate
可调用[FileChooser]:布尔值 (可选)#接收 FileChooser 对象,并在等待应解析时解析为真值。
-
最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 更改默认值。
返回
expect_popup
添加于:v1.9执行操作并等待弹出 Page。如果提供了谓词,它将 [Popup] 值传递给 predicate
函数,并等待 predicate(page)
返回一个真值。如果页面在弹出事件触发之前关闭,将抛出错误。
用法
page.expect_popup()
page.expect_popup(**kwargs)
参数
-
接收 Page 对象,并在等待应解析时解析为真值。
-
最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 更改默认值。
返回
expect_request
v1.9 之前添加等待匹配的请求并返回它。有关事件的更多详细信息,请参阅等待事件。
用法
- 同步
- 异步
with page.expect_request("http://example.com/resource") as first:
page.get_by_text("trigger request").click()
first_request = first.value
# or with a lambda
with page.expect_request(lambda request: request.url == "http://example.com" and request.method == "get") as second:
page.get_by_text("trigger request").click()
second_request = second.value
async with page.expect_request("http://example.com/resource") as first:
await page.get_by_text("trigger request").click()
first_request = await first.value
# or with a lambda
async with page.expect_request(lambda request: request.url == "http://example.com" and request.method == "get") as second:
await page.get_by_text("trigger request").click()
second_request = await second.value
参数
-
url_or_predicate
str | Pattern | 可调用[Request]:布尔值#请求 URL 字符串、正则表达式或接收 Request 对象的谓词。如果通过上下文选项提供了 base_url 并且传入的 URL 是路径,它将通过
new URL()
构造函数合并。 -
最大等待时间(毫秒),默认为 30 秒,传递
0
以禁用超时。可以使用 page.set_default_timeout() 方法更改默认值。
返回
expect_request_finished
添加于:v1.12执行操作并等待 Request 完成加载。如果提供了谓词,它将 Request 值传递给 predicate
函数,并等待 predicate(request)
返回一个真值。如果页面在 page.on("requestfinished") 事件触发之前关闭,将抛出错误。
用法
page.expect_request_finished()
page.expect_request_finished(**kwargs)
参数
-
predicate
可调用[Request]:布尔值 (可选)#接收 Request 对象,并在等待应解析时解析为真值。
-
最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 更改默认值。
返回
expect_response
v1.9 之前添加返回匹配的响应。有关事件的更多详细信息,请参阅等待事件。
用法
- 同步
- 异步
with page.expect_response("https://example.com/resource") as response_info:
page.get_by_text("trigger response").click()
response = response_info.value
return response.ok
# or with a lambda
with page.expect_response(lambda response: response.url == "https://example.com" and response.status == 200 and response.request.method == "get") as response_info:
page.get_by_text("trigger response").click()
response = response_info.value
return response.ok
async with page.expect_response("https://example.com/resource") as response_info:
await page.get_by_text("trigger response").click()
response = await response_info.value
return response.ok
# or with a lambda
async with page.expect_response(lambda response: response.url == "https://example.com" and response.status == 200 and response.request.method == "get") as response_info:
await page.get_by_text("trigger response").click()
response = await response_info.value
return response.ok
参数
-
url_or_predicate
str | Pattern | 可调用[Response]:布尔值#请求 URL 字符串、正则表达式或接收 Response 对象的谓词。如果通过上下文选项提供了 base_url 并且传入的 URL 是路径,它将通过
new URL()
构造函数合并。 -
最大等待时间(毫秒),默认为 30 秒,传递
0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
expect_websocket
添加于:v1.9执行操作并等待新的 WebSocket。如果提供了谓词,它将 WebSocket 值传递给 predicate
函数,并等待 predicate(webSocket)
返回一个真值。如果页面在 WebSocket 事件触发之前关闭,将抛出错误。
用法
page.expect_websocket()
page.expect_websocket(**kwargs)
参数
-
predicate
可调用[WebSocket]:布尔值 (可选)#接收 WebSocket 对象,并在等待应解析时解析为真值。
-
最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 更改默认值。
返回
expect_worker
添加于:v1.9执行操作并等待新的 Worker。如果提供了谓词,它将 Worker 值传递给 predicate
函数,并等待 predicate(worker)
返回一个真值。如果页面在 worker 事件触发之前关闭,将抛出错误。
用法
page.expect_worker()
page.expect_worker(**kwargs)
参数
-
predicate
可调用[Worker]:布尔值 (可选)#接收 Worker 对象,并在等待应解析时解析为真值。
-
最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 更改默认值。
返回
expose_binding
v1.9 之前添加该方法在页面中每个帧的 window
对象上添加一个名为 name 的函数。当调用时,该函数执行 callback 并返回一个 Promise,该 Promise 解析为 callback 的返回值。如果 callback 返回一个 Promise,它将被等待。
callback 函数的第一个参数包含有关调用者的信息:{ browserContext: BrowserContext, page: Page, frame: Frame }
。
有关上下文范围的版本,请参阅 browser_context.expose_binding()。
通过 page.expose_binding() 安装的函数在导航后仍然有效。
用法
将页面 URL 暴露给页面中所有框架的示例
- 同步
- 异步
from playwright.sync_api import sync_playwright, Playwright
def run(playwright: Playwright):
webkit = playwright.webkit
browser = webkit.launch(headless=False)
context = browser.new_context()
page = context.new_page()
page.expose_binding("pageURL", lambda source: source["page"].url)
page.set_content("""
<script>
async function onClick() {
document.querySelector('div').textContent = await window.pageURL();
}
</script>
<button onclick="onClick()">Click me</button>
<div></div>
""")
page.click("button")
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(headless=False)
context = await browser.new_context()
page = await context.new_page()
await page.expose_binding("pageURL", lambda source: source["page"].url)
await page.set_content("""
<script>
async function onClick() {
document.querySelector('div').textContent = await window.pageURL();
}
</script>
<button onclick="onClick()">Click me</button>
<div></div>
""")
await page.click("button")
async def main():
async with async_playwright() as playwright:
await run(playwright)
asyncio.run(main())
参数
-
窗口对象上函数的名称。
-
将在 Playwright 上下文中调用的回调函数。
-
已弃用
此选项将在未来版本中移除。
是否将参数作为句柄传递,而不是按值传递。当传递句柄时,只支持一个参数。当按值传递时,支持多个参数。
返回
expose_function
v1.9 之前添加该方法在页面中每个帧的 window
对象上添加一个名为 name 的函数。当调用时,该函数执行 callback 并返回一个 Promise,该 Promise 解析为 callback 的返回值。
如果 callback 返回一个 Promise,它将被等待。
有关上下文范围的公开函数,请参阅 browser_context.expose_function()。
通过 page.expose_function() 安装的函数在导航后仍然有效。
用法
向页面添加 sha256
函数的示例
- 同步
- 异步
import hashlib
from playwright.sync_api import sync_playwright, Playwright
def sha256(text):
m = hashlib.sha256()
m.update(bytes(text, "utf8"))
return m.hexdigest()
def run(playwright: Playwright):
webkit = playwright.webkit
browser = webkit.launch(headless=False)
page = browser.new_page()
page.expose_function("sha256", sha256)
page.set_content("""
<script>
async function onClick() {
document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
}
</script>
<button onclick="onClick()">Click me</button>
<div></div>
""")
page.click("button")
with sync_playwright() as playwright:
run(playwright)
import asyncio
import hashlib
from playwright.async_api import async_playwright, Playwright
def sha256(text):
m = hashlib.sha256()
m.update(bytes(text, "utf8"))
return m.hexdigest()
async def run(playwright: Playwright):
webkit = playwright.webkit
browser = await webkit.launch(headless=False)
page = await browser.new_page()
await page.expose_function("sha256", sha256)
await page.set_content("""
<script>
async function onClick() {
document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
}
</script>
<button onclick="onClick()">Click me</button>
<div></div>
""")
await page.click("button")
async def main():
async with async_playwright() as playwright:
await run(playwright)
asyncio.run(main())
参数
返回
frame
v1.9 之前添加返回符合指定条件的帧。必须指定 name
或 url
。
用法
frame = page.frame(name="frame-name")
frame = page.frame(url=r".*domain.*")
参数
-
在
iframe
的name
属性中指定的帧名称。可选。 -
url
str | Pattern | 可调用[URL]:布尔值 (可选)#一个全局模式、正则表达式模式或接收帧
url
作为 URL 对象的谓词。可选。
返回
frame_locator
新增于: v1.17使用 iframe 时,您可以创建一个框架定位器,它将进入 iframe 并允许选择 iframe 中的元素。
用法
以下代码片段在 id 为 my-frame
的 iframe 中查找文本为“提交”的元素,例如 <iframe id="my-frame">
- 同步
- 异步
locator = page.frame_locator("#my-iframe").get_by_text("Submit")
locator.click()
locator = page.frame_locator("#my-iframe").get_by_text("Submit")
await locator.click()
参数
返回
get_by_alt_text
新增于:v1.27允许根据元素的 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()
参数
-
用于定位元素的文本。
-
是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。
返回
get_by_label
新增于:v1.27允许通过关联的 <label>
或 aria-labelledby
元素的文本或 aria-label
属性来定位输入元素。
用法
例如,此方法将在以下 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")
参数
-
用于定位元素的文本。
-
是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。
返回
get_by_placeholder
新增于:v1.27允许通过占位符文本定位输入元素。
用法
例如,考虑以下 DOM 结构。
<input type="email" placeholder="name@example.com" />
您可以按占位符文本定位输入框后填充它
- 同步
- 异步
page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")
await page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")
参数
-
用于定位元素的文本。
-
是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。
返回
get_by_role
新增于:v1.27允许通过元素的 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 角色。
-
通常由
aria-checked
或原生<input type=checkbox>
控件设置的属性。了解更多关于
aria-checked
的信息。 -
通常由
aria-disabled
或disabled
设置的属性。注意与大多数其他属性不同,
disabled
在 DOM 层次结构中是继承的。了解更多关于aria-disabled
的信息。 -
是否精确匹配 name:区分大小写且全字符串匹配。默认为 false。当 name 是正则表达式时忽略。请注意,精确匹配仍会去除空白字符。
-
通常由
aria-expanded
设置的属性。了解更多关于
aria-expanded
的信息。 -
控制是否匹配隐藏元素的选项。默认情况下,只有非隐藏元素(由 ARIA 定义)由角色选择器匹配。
了解更多关于
aria-hidden
的信息。 -
通常用于角色
heading
、listitem
、row
、treeitem
的数字属性,<h1>-<h6>
元素具有默认值。了解更多关于
aria-level
的信息。 -
匹配 可访问名称 的选项。默认情况下,匹配不区分大小写并搜索子字符串,使用 exact 控制此行为。
了解更多关于 可访问名称 的信息。
-
通常由
aria-pressed
设置的属性。了解更多关于
aria-pressed
的信息。 -
通常由
aria-selected
设置的属性。了解更多关于
aria-selected
的信息。
返回
详情
角色选择器 不替代 可访问性审计和合规性测试,而是提供有关 ARIA 指南的早期反馈。
许多 HTML 元素具有隐式 定义角色,这些角色通过角色选择器识别。您可以在此处找到所有 支持的角色。ARIA 指南不建议通过将 role
和/或 aria-*
属性设置为默认值来重复隐式角色和属性。
get_by_test_id
新增于:v1.27按测试 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()
参数
返回
详情
默认情况下,`data-testid` 属性用作测试 ID。如有必要,使用 selectors.set_test_id_attribute() 配置不同的测试 ID 属性。
get_by_text
新增于:v1.27允许定位包含给定文本的元素。
另请参阅 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))
参数
-
用于定位元素的文本。
-
是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。
返回
详情
按文本匹配始终会规范化空格,即使是精确匹配也是如此。例如,它会将多个空格转换为一个空格,将换行符转换为空格,并忽略前导和尾随空格。
类型为 button
和 submit
的输入元素通过其 value
而不是文本内容进行匹配。例如,通过文本 "登录"
定位匹配 <input type=button value="登录">
。
get_by_title
新增于:v1.27允许通过元素的 title 属性定位元素。
用法
考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
您可以通过 title 文本定位它后检查问题数量
- 同步
- 异步
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")
参数
-
用于定位元素的文本。
-
是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。
返回
go_back
v1.9 之前添加返回主资源响应。如果存在多次重定向,导航将解析为最后一次重定向的响应。如果无法返回,则返回 null
。
导航到历史记录中的上一页。
用法
page.go_back()
page.go_back(**kwargs)
参数
-
操作的最大时间(毫秒),默认为 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'
- 当收到网络响应且文档开始加载时,认为操作完成。
返回
go_forward
v1.9 之前添加返回主资源响应。如果存在多次重定向,导航将解析为最后一次重定向的响应。如果无法前进,则返回 null
。
导航到历史记录中的下一页。
用法
page.go_forward()
page.go_forward(**kwargs)
参数
-
操作的最大时间(毫秒),默认为 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'
- 当收到网络响应且文档开始加载时,认为操作完成。
返回
goto
v1.9 之前添加返回主资源响应。如果存在多次重定向,导航将解析为第一个非重定向响应。
此方法将在以下情况下抛出错误
- 存在 SSL 错误(例如自签名证书)。
- 目标 URL 无效。
- timeout 在导航期间超出。
- 远程服务器无响应或无法访问。
- 主资源加载失败。
当远程服务器返回任何有效的 HTTP 状态码时,该方法不会抛出错误,包括 404“未找到”和 500“内部服务器错误”。此类响应的状态码可以通过调用 response.status 获取。
该方法要么抛出错误,要么返回主资源响应。唯一的例外是导航到 about:blank
或导航到具有不同哈希的相同 URL,这将成功并返回 null
。
无头模式不支持导航到 PDF 文档。请参阅 上游问题。
用法
page.goto(url)
page.goto(url, **kwargs)
参数
-
要导航到的页面 URL。URL 应包含方案,例如
https://
。如果通过上下文选项提供了 base_url 并且传入的 URL 是路径,它将通过new URL()
构造函数合并。 -
Referer 标头值。如果提供,它将优先于 page.set_extra_http_headers() 设置的 referer 标头值。
-
操作的最大时间(毫秒),默认为 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'
- 当收到网络响应且文档开始加载时,认为操作完成。
返回
locator
新增于:v1.14该方法返回一个元素定位器,可用于在此页面/框架上执行操作。定位器在执行操作之前立即解析为元素,因此在同一定位器上执行的一系列操作实际上可以在不同的 DOM 元素上执行。如果这些操作之间的 DOM 结构发生变化,就会发生这种情况。
用法
page.locator(selector)
page.locator(selector, **kwargs)
参数
-
用于解析 DOM 元素的选取器。
-
将方法的结果缩小到那些包含与此相对定位器匹配的元素的元素。例如,包含
text=Playwright
的article
匹配<article><div>Playwright</div></article>
。内部定位器必须相对于外部定位器,并且从外部定位器匹配开始查询,而不是文档根。例如,您可以在
<article><content><div>Playwright</div></content></article>
中找到具有div
的content
。但是,查找具有article div
的content
将失败,因为内部定位器必须是相对的,并且不应使用content
之外的任何元素。请注意,外部和内部定位符必须属于同一帧。内部定位符不能包含 FrameLocator。
-
has_not
Locator (可选)新增于:v1.33#匹配不包含与内部定位器匹配的元素的元素。内部定位器针对外部定位器进行查询。例如,不包含
div
的article
匹配<article><span>Playwright</span></article>
。请注意,外部和内部定位符必须属于同一帧。内部定位符不能包含 FrameLocator。
-
has_not_text
str | Pattern (可选)新增于:v1.33#匹配不包含指定文本的元素,可能在子元素或后代元素中。当传入 [字符串] 时,匹配不区分大小写并搜索子字符串。
-
匹配内部某个位置包含指定文本的元素,可能在子元素或后代元素中。当传入 [字符串] 时,匹配不区分大小写并搜索子字符串。例如,
"Playwright"
匹配<article><div>Playwright</div></article>
。
返回
opener
v1.9 之前添加对于弹出页面返回打开者,对于其他页面返回 null
。如果打开者已经关闭,则返回 null
。
用法
page.opener()
返回
pause
添加于:v1.9暂停脚本执行。Playwright 将停止执行脚本,并等待用户点击页面覆盖中的“恢复”按钮,或者在 DevTools 控制台中调用 playwright.resume()
。
用户可以在暂停时检查选择器或执行手动步骤。恢复将从暂停的位置继续运行原始脚本。
此方法要求 Playwright 在无头模式下启动,并带有虚假 headless 选项。
用法
page.pause()
返回
pdf
v1.9 之前添加返回 PDF 缓冲区。
page.pdf()
使用 print
css 媒体生成页面的 pdf。要使用 screen
媒体生成 pdf,请在调用 page.pdf()
之前调用 page.emulate_media()
默认情况下,page.pdf()
生成的 pdf 会修改颜色以进行打印。使用 -webkit-print-color-adjust
属性强制渲染精确颜色。
用法
- 同步
- 异步
# generates a pdf with "screen" media type.
page.emulate_media(media="screen")
page.pdf(path="page.pdf")
# generates a pdf with "screen" media type.
await page.emulate_media(media="screen")
await page.pdf(path="page.pdf")
width、height 和 margin 选项接受带单位的值。未标记的值被视为像素。
一些示例
page.pdf({width: 100})
- 打印宽度设置为 100 像素page.pdf({width: '100px'})
- 打印宽度设置为 100 像素page.pdf({width: '10cm'})
- 打印宽度设置为 10 厘米。
所有可能的单位是
px
- 像素in
- 英寸cm
- 厘米mm
- 毫米
format 选项有
信纸
: 8.5 英寸 x 11 英寸法律
: 8.5 英寸 x 14 英寸Tabloid
: 11 英寸 x 17 英寸账本
: 17 英寸 x 11 英寸A0
: 33.1 英寸 x 46.8 英寸A1
: 23.4 英寸 x 33.1 英寸A2
: 16.54 英寸 x 23.4 英寸A3
: 11.7 英寸 x 16.54 英寸A4
: 8.27 英寸 x 11.7 英寸A5
: 5.83 英寸 x 8.27 英寸A6
: 4.13 英寸 x 5.83 英寸
header_template 和 footer_template 标记有以下限制:> 1. 模板中的脚本标签不被评估。> 2. 页面样式在模板中不可见。
参数
-
display_header_footer
布尔值 (可选)#显示页眉和页脚。默认为
false
。 -
打印页脚的 HTML 模板。应使用与 header_template 相同的格式。
-
打印页眉的 HTML 模板。应为有效 HTML 标记,其中以下类用于注入打印值
'date'
格式化的打印日期'title'
文档标题'url'
文档位置'pageNumber'
当前页码'totalPages'
文档总页数
-
纸张高度,接受带单位的值。
-
纸张方向。默认为
false
。 -
-
上边距,接受带单位的值。默认为
0
。 -
右边距,接受带单位的值。默认为
0
。 -
下边距,接受带单位的值。默认为
0
。 -
左边距,接受带单位的值。默认为
0
。
纸张边距,默认为无。
-
-
是否将文档大纲嵌入 PDF。默认为
false
。 -
要打印的页面范围,例如 '1-5, 8, 11-13'。默认为空字符串,表示打印所有页面。
-
path
Union[str, pathlib.Path] (可选)#用于保存PDF的文件路径。如果path是相对路径,则它将相对于当前工作目录解析。如果未提供路径,则PDF不会保存到磁盘。
-
prefer_css_page_size
bool (可选)#使页面中声明的任何CSS
@page
大小优先于width和height或format选项中声明的大小。默认为false
,这将缩放内容以适应纸张大小。 -
打印背景图形。默认为
false
。 -
网页渲染的比例。默认为
1
。比例值必须在 0.1 到 2 之间。 -
是否生成带标签(可访问)的 PDF。默认为
false
。 -
纸张宽度,接受带单位的值。
返回
reload
v1.9 之前添加此方法重新加载当前页面,就像用户触发了浏览器刷新一样。返回主资源响应。在多次重定向的情况下,导航将解析为最后一次重定向的响应。
用法
page.reload()
page.reload(**kwargs)
参数
-
操作的最大时间(毫秒),默认为 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'
- 当收到网络响应且文档开始加载时,认为操作完成。
返回
remove_locator_handler
新增于:v1.44移除由page.add_locator_handler()为特定定位器添加的所有定位器处理程序。
用法
page.remove_locator_handler(locator)
参数
-
传递给page.add_locator_handler()的定位器。
返回
request_gc
新增于: v1.48请求页面执行垃圾回收。请注意,不能保证所有不可达对象都会被收集。
这对于帮助检测内存泄漏很有用。例如,如果您的页面有一个可能泄漏的大对象'suspect'
,您可以使用WeakRef
来检查它是否泄漏。
- 同步
- 异步
# 1. In your page, save a WeakRef for the "suspect".
page.evaluate("globalThis.suspectWeakRef = new WeakRef(suspect)")
# 2. Request garbage collection.
page.request_gc()
# 3. Check that weak ref does not deref to the original object.
assert page.evaluate("!globalThis.suspectWeakRef.deref()")
# 1. In your page, save a WeakRef for the "suspect".
await page.evaluate("globalThis.suspectWeakRef = new WeakRef(suspect)")
# 2. Request garbage collection.
await page.request_gc()
# 3. Check that weak ref does not deref to the original object.
assert await page.evaluate("!globalThis.suspectWeakRef.deref()")
用法
page.request_gc()
返回
route
v1.9 之前添加路由提供了修改页面发出的网络请求的能力。
一旦启用路由,每个匹配 URL 模式的请求都将暂停,除非它被继续、完成或中止。
如果响应是重定向,则处理程序将只针对第一个 URL 调用。
page.route()不会拦截Service Worker拦截的请求。请参阅此问题。我们建议在使用请求拦截时通过将service_workers设置为'block'
来禁用Service Workers。
page.route()不会拦截弹出页面的第一个请求。请改用browser_context.route()。
用法
一个简单地中止所有图片请求的处理程序示例
- 同步
- 异步
page = browser.new_page()
page.route("**/*.{png,jpg,jpeg}", lambda route: route.abort())
page.goto("https://example.com")
browser.close()
page = await browser.new_page()
await page.route("**/*.{png,jpg,jpeg}", lambda route: route.abort())
await page.goto("https://example.com")
await browser.close()
或者使用正则表达式模式的相同片段
- 同步
- 异步
page = browser.new_page()
page.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
page.goto("https://example.com")
browser.close()
page = await browser.new_page()
await page.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
await page.goto("https://example.com")
await browser.close()
可以检查请求以决定路由操作。例如,模拟所有包含某些 POST 数据的请求,并保留所有其他请求不变
- 同步
- 异步
def handle_route(route: Route):
if ("my-string" in route.request.post_data):
route.fulfill(body="mocked-data")
else:
route.continue_()
page.route("/api/**", handle_route)
async def handle_route(route: Route):
if ("my-string" in route.request.post_data):
await route.fulfill(body="mocked-data")
else:
await route.continue_()
await page.route("/api/**", handle_route)
当请求同时匹配页面路由和浏览器上下文路由时(通过browser_context.route()设置),页面路由优先。
要删除带有其处理程序的路由,可以使用page.unroute()。
启用路由会禁用 HTTP 缓存。
参数
-
url
str | Pattern | Callable[URL]:bool#一个全局模式、正则表达式模式或谓词,它接收一个URL以在路由期间匹配。如果在上下文选项中设置了base_url,并且提供的URL是一个不以
*
开头的字符串,则它将使用new URL()
构造函数进行解析。 -
handler
Callable[Route, Request]:Promise[Any] | Any#用于路由请求的处理函数。
-
路由应该被使用多少次。默认情况下,每次都会使用。
返回
route_from_har
添加于:v1.23如果指定,页面中发出的网络请求将从HAR文件提供。阅读有关从HAR重放的更多信息。
Playwright不会从HAR文件提供Service Worker拦截的请求。请参阅此问题。我们建议在使用请求拦截时通过将service_workers设置为'block'
来禁用Service Workers。
用法
page.route_from_har(har)
page.route_from_har(har, **kwargs)
参数
-
har
Union[str, pathlib.Path]#带有预录网络数据的 HAR 文件路径。如果
path
是相对路径,则它相对于当前工作目录解析。 -
not_found
"abort" | "fallback" (可选)#- 如果设置为 'abort',则 HAR 文件中未找到的任何请求都将被中止。
- 如果设置为 'fallback',则缺失的请求将被发送到网络。
默认为中止。
-
如果指定,则使用实际的网络信息更新给定的HAR,而不是从文件提供。当调用browser_context.close()时,文件将写入磁盘。
-
update_content
"embed" | "attach" (可选)新增于: v1.32#可选设置以控制资源内容管理。如果指定
attach
,资源将作为单独的文件或 ZIP 档案中的条目持久化。如果指定embed
,内容将内联存储在 HAR 文件中。 -
update_mode
"full" | "minimal" (可选)新增于: v1.32#当设置为
minimal
时,仅记录从 HAR 路由所需的信息。这会省略 HAR 信息中不用于从 HAR 重放的大小、时间、页面、cookie、安全性和其他类型的信息。默认为minimal
。 -
一个 glob 模式、正则表达式或谓词,用于匹配请求 URL。只有 URL 匹配模式的请求将从 HAR 文件中提供。如果未指定,所有请求都将从 HAR 文件中提供。
返回
route_web_socket
新增于: v1.48此方法允许修改页面建立的 websocket 连接。
请注意,只有在此方法调用后创建的 WebSocket
才会进行路由。建议在导航页面之前调用此方法。
用法
以下是一个响应单个消息的简单模拟示例。有关更多详细信息和示例,请参阅WebSocketRoute。
- 同步
- 异步
def message_handler(ws: WebSocketRoute, message: Union[str, bytes]):
if message == "request":
ws.send("response")
def handler(ws: WebSocketRoute):
ws.on_message(lambda message: message_handler(ws, message))
page.route_web_socket("/ws", handler)
def message_handler(ws: WebSocketRoute, message: Union[str, bytes]):
if message == "request":
ws.send("response")
def handler(ws: WebSocketRoute):
ws.on_message(lambda message: message_handler(ws, message))
await page.route_web_socket("/ws", handler)
参数
-
url
str | Pattern | Callable[URL]:bool#只有URL与此模式匹配的WebSocket才会被路由。字符串模式可以相对于base_url上下文选项。
-
handler
Callable[WebSocketRoute]:Promise[Any] | Any#用于路由 WebSocket 的处理函数。
返回
screenshot
v1.9 之前添加返回包含捕获的屏幕截图的缓冲区。
用法
page.screenshot()
page.screenshot(**kwargs)
参数
-
animations
"disabled" | "allow" (可选)#设置为
"disabled"
时,停止 CSS 动画、CSS 过渡和 Web 动画。动画的处理方式因其持续时间而异- 有限动画会快进到完成,因此它们会触发
transitionend
事件。 - 无限动画会取消到初始状态,然后在截图后重新播放。
默认为
"allow"
,保持动画不变。 - 有限动画会快进到完成,因此它们会触发
-
caret
"hide" | "initial" (可选)#设置为
"hide"
时,截图将隐藏文本插入符号。设置为"initial"
时,文本插入符号行为不会更改。默认为"hide"
。 -
一个指定结果图像裁剪的对象。
-
当为 true 时,截取整个可滚动页面的截图,而不是当前可见的视口。默认为
false
。 -
指定截屏时应遮罩的定位器。被遮罩的元素将被一个粉色框
#FF00FF
(由mask_color自定义)覆盖,完全覆盖其边界框。遮罩也适用于不可见元素,请参阅仅匹配可见元素以禁用该功能。 -
指定遮盖元素的覆盖框颜色,采用 CSS 颜色格式。默认颜色为粉红色
#FF00FF
。 -
隐藏默认的白色背景并允许捕获透明截图。不适用于
jpeg
图像。默认为false
。 -
path
Union[str, pathlib.Path] (可选)#保存图像的文件路径。屏幕截图类型将根据文件扩展名推断。如果path是相对路径,则它将相对于当前工作目录解析。如果未提供路径,则图像不会保存到磁盘。
-
图像质量,介于 0-100 之间。不适用于
png
图像。 -
scale
"css" | "device" (可选)#当设置为
"css"
时,屏幕截图将在页面上的每个CSS像素处有一个像素。对于高DPI设备,这将使屏幕截图很小。使用"device"
选项将为每个设备像素生成一个像素,因此高DPI设备的屏幕截图将是两倍甚至更大。默认为
"device"
。 -
创建屏幕截图时要应用的样式表文本。您可以在此处隐藏动态元素,使元素不可见或更改其属性以帮助您创建可重复的屏幕截图。此样式表会穿透Shadow DOM并应用于内部框架。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
type
"png" | "jpeg" (可选)#指定截图类型,默认为
png
。
返回
set_content
v1.9 之前添加此方法内部调用 document.write(),继承其所有特定特征和行为。
用法
page.set_content(html)
page.set_content(html, **kwargs)
参数
-
要分配给页面的 HTML 标记。
-
操作的最大时间(毫秒),默认为 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'
- 当收到网络响应且文档开始加载时,认为操作完成。
返回
set_default_navigation_timeout
v1.9 之前添加此设置将更改以下方法和相关快捷方式的默认最大导航时间
- page.go_back()
- page.go_forward()
- page.goto()
- page.reload()
- page.set_content()
- page.expect_navigation()
- page.wait_for_url()
用法
page.set_default_navigation_timeout(timeout)
参数
set_default_timeout
v1.9 之前添加此设置将更改所有接受timeout选项的方法的默认最大时间。
用法
page.set_default_timeout(timeout)
参数
set_extra_http_headers
v1.9 之前添加额外的 HTTP 头将随页面发起的每个请求一起发送。
page.set_extra_http_headers()不保证传出请求中头部的顺序。
用法
page.set_extra_http_headers(headers)
参数
返回
set_viewport_size
v1.9 之前添加在单个浏览器中存在多个页面的情况下,每个页面可以有自己的视口大小。然而,browser.new_context()允许一次性为上下文中所有页面设置视口大小(以及更多)。
page.set_viewport_size()将调整页面大小。许多网站不期望手机改变大小,因此您应该在导航到页面之前设置视口大小。page.set_viewport_size()还将重置screen
大小,如果您需要更好地控制这些属性,请使用带screen
和viewport
参数的browser.new_context()。
用法
- 同步
- 异步
page = browser.new_page()
page.set_viewport_size({"width": 640, "height": 480})
page.goto("https://example.com")
page = await browser.new_page()
await page.set_viewport_size({"width": 640, "height": 480})
await page.goto("https://example.com")
参数
返回
title
v1.9 之前添加返回页面的标题。
用法
page.title()
返回
unroute
v1.9 之前添加移除使用page.route()创建的路由。当未指定handler时,移除url的所有路由。
用法
page.unroute(url)
page.unroute(url, **kwargs)
参数
-
url
str | Pattern | Callable[URL]:bool#一个全局模式、正则表达式模式或接收URL以在路由时匹配的谓词。
-
handler
Callable[Route, Request]:Promise[Any] | Any (可选)#可选的处理函数,用于路由请求。
返回
unroute_all
新增于: v1.41移除使用page.route()和page.route_from_har()创建的所有路由。
用法
page.unroute_all()
page.unroute_all(**kwargs)
参数
-
behavior
"wait" | "ignoreErrors" | "default" (可选)#指定是否等待已运行的处理程序以及如果它们抛出错误该怎么做
'default'
- 不等待当前处理程序调用 (如果有) 完成,如果未路由的处理程序抛出错误,可能会导致未处理的错误'wait'
- 等待当前处理程序调用 (如果有) 完成'ignoreErrors'
- 不等待当前处理程序调用 (如果有) 完成,取消路由后处理程序抛出的所有错误都将被静默捕获
返回
wait_for_event
v1.9 之前添加在大多数情况下,您应该使用page.expect_event()。
等待给定event
触发。如果提供了谓词,它将事件的值传递给predicate
函数,并等待predicate(event)
返回一个真值。如果页面在event
触发之前关闭,将抛出错误。
用法
page.wait_for_event(event)
page.wait_for_event(event, **kwargs)
参数
-
事件名称,通常传递给
*.on(event)
的相同名称。 -
接收事件数据,并在等待应该解决时解析为真值。
-
最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 更改默认值。
返回
wait_for_function
v1.9 之前添加当expression返回一个真值时返回。它解析为真值的JSHandle。
用法
page.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.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.wait_for_function("() => window.x > 0")
await browser.close()
async def main():
async with async_playwright() as playwright:
await run(playwright)
asyncio.run(main())
将参数传递给page.wait_for_function()函数的谓词
- 同步
- 异步
selector = ".foo"
page.wait_for_function("selector => !!document.querySelector(selector)", selector)
selector = ".foo"
await page.wait_for_function("selector => !!document.querySelector(selector)", selector)
参数
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#要传递给expression的可选参数。
-
如果polling是
'raf'
,则expression会在requestAnimationFrame
回调中不断执行。如果polling是一个数字,则它被视为函数执行的毫秒间隔。默认为raf
。 -
等待的最大时间(毫秒)。默认为
30000
(30秒)。传递0
以禁用超时。默认值可以通过使用browser_context.set_default_timeout()或page.set_default_timeout()方法更改。
返回
wait_for_load_state
v1.9 之前添加当达到所需加载状态时返回。
当页面达到所需加载状态(默认为 load
)时解析。调用此方法时导航必须已提交。如果当前文档已达到所需状态,则立即解析。
大多数情况下,不需要此方法,因为Playwright在每次操作前都会自动等待。
用法
- 同步
- 异步
page.get_by_role("button").click() # click triggers navigation.
page.wait_for_load_state() # the promise resolves after "load" event.
await page.get_by_role("button").click() # click triggers navigation.
await page.wait_for_load_state() # the promise resolves after "load" event.
- 同步
- 异步
with page.expect_popup() as page_info:
page.get_by_role("button").click() # click triggers a popup.
popup = page_info.value
# Wait for the "DOMContentLoaded" event.
popup.wait_for_load_state("domcontentloaded")
print(popup.title()) # popup is ready to use.
async with page.expect_popup() as page_info:
await page.get_by_role("button").click() # click triggers a popup.
popup = await page_info.value
# Wait for the "DOMContentLoaded" event.
await popup.wait_for_load_state("domcontentloaded")
print(await popup.title()) # popup is ready to use.
参数
-
state
"load" | "domcontentloaded" | "networkidle" (可选)#要等待的可选加载状态,默认为
load
。如果当前文档加载期间已达到该状态,则该方法会立即解析。可以是以下之一'load'
- 等待load
事件触发。'domcontentloaded'
- 等待DOMContentLoaded
事件触发。'networkidle'
- **不推荐** 等待至少500
毫秒内没有网络连接。不要将此方法用于测试,而是依赖 Web 断言来评估准备情况。
-
操作的最大时间(毫秒),默认为 30 秒,传递
0
以禁用超时。可以使用 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
wait_for_url
添加于:v1.11等待主框架导航到给定 URL。
用法
- 同步
- 异步
page.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
page.wait_for_url("**/target.html")
await page.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
await page.wait_for_url("**/target.html")
参数
-
url
str | Pattern | Callable[URL]:bool#一个全局模式、正则表达式模式或接收URL以在等待导航时匹配的谓词。请注意,如果参数是一个不带通配符的字符串,该方法将等待导航到与该字符串完全相同的URL。
-
操作的最大时间(毫秒),默认为 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'
- 当收到网络响应且文档开始加载时,认为操作完成。
返回
属性
clock
新增于: v1.45Playwright 能够模拟时钟和时间流逝。
用法
page.clock
类型
context
v1.9 之前添加获取页面所属的浏览器上下文。
用法
page.context
返回
frames
v1.9 之前添加附加到页面的所有帧的数组。
用法
page.frames
返回
is_closed
v1.9 之前添加指示页面已关闭。
用法
page.is_closed()
返回
keyboard
v1.9 之前添加用法
page.keyboard
类型
main_frame
v1.9 之前添加页面的主框架。页面保证有一个在导航期间持久存在的主框架。
用法
page.main_frame
返回
mouse
v1.9 之前添加用法
page.mouse
类型
request
添加于:v1.16与此页面关联的API测试助手。此方法返回与页面上下文上的browser_context.request相同的实例。有关更多详细信息,请参阅browser_context.request。
用法
page.request
类型
touchscreen
v1.9 之前添加用法
page.touchscreen
类型
url
v1.9 之前添加用法
page.url
返回
video
v1.9 之前添加与此页面关联的视频对象。
用法
page.video
返回
viewport_size
v1.9 之前添加用法
page.viewport_size
返回
workers
v1.9 之前添加此方法返回与页面关联的所有专用 WebWorkers。
这不包含 ServiceWorkers
用法
page.workers
返回
事件
on("close")
v1.9 之前添加当页面关闭时发出。
用法
page.on("close", handler)
事件数据
on("console")
v1.9 之前添加当页面中的 JavaScript 调用其中一个 console API 方法(例如 console.log
或 console.dir
)时触发。
传递给console.log
的参数可在ConsoleMessage事件处理程序参数上获得。
用法
- 同步
- 异步
def print_args(msg):
for arg in msg.args:
print(arg.json_value())
page.on("console", print_args)
page.evaluate("console.log('hello', 5, { foo: 'bar' })")
async def print_args(msg):
values = []
for arg in msg.args:
values.append(await arg.json_value())
print(values)
page.on("console", print_args)
await page.evaluate("console.log('hello', 5, { foo: 'bar' })")
事件数据
on("crash")
v1.9 之前添加当页面崩溃时发出。如果浏览器页面尝试分配过多内存,可能会崩溃。当页面崩溃时,正在进行和后续操作将抛出异常。
处理崩溃最常见的方法是捕获异常
- 同步
- 异步
try:
# crash might happen during a click.
page.click("button")
# or while waiting for an event.
page.wait_for_event("popup")
except Error as e:
pass
# when the page crashes, exception message contains "crash".
try:
# crash might happen during a click.
await page.click("button")
# or while waiting for an event.
await page.wait_for_event("popup")
except Error as e:
pass
# when the page crashes, exception message contains "crash".
用法
page.on("crash", handler)
事件数据
on("dialog")
v1.9 之前添加当出现JavaScript对话框时(例如alert
、prompt
、confirm
或beforeunload
)发出。监听器必须dialog.accept()或dialog.dismiss()对话框——否则页面将冻结等待对话框,并且点击等操作将永远无法完成。
用法
page.on("dialog", lambda dialog: dialog.accept())
当没有page.on("dialog")或browser_context.on("dialog")监听器时,所有对话框都会自动关闭。
事件数据
on("domcontentloaded")
添加于:v1.9当 JavaScript DOMContentLoaded
事件被分派时发出。
用法
page.on("domcontentloaded", handler)
事件数据
on("download")
v1.9 之前添加当附件下载开始时发出。用户可以通过传递的Download实例访问下载内容的基本文件操作。
用法
page.on("download", handler)
事件数据
on("filechooser")
添加于:v1.9当文件选择器应该出现时(例如在点击<input type=file>
之后)发出。Playwright可以通过使用file_chooser.set_files()设置输入文件来响应,这些文件之后可以上传。
page.on("filechooser", lambda file_chooser: file_chooser.set_files("/tmp/myfile.pdf"))
用法
page.on("filechooser", handler)
事件数据
on("frameattached")
添加于:v1.9当框架附加时发出。
用法
page.on("frameattached", handler)
事件数据
on("framedetached")
添加于:v1.9当框架分离时发出。
用法
page.on("framedetached", handler)
事件数据
on("framenavigated")
添加于:v1.9当框架导航到新的 URL 时发出。
用法
page.on("framenavigated", handler)
事件数据
on("load")
v1.9 之前添加当 JavaScript load
事件被分派时发出。
用法
page.on("load", handler)
事件数据
on("pageerror")
添加于:v1.9当页面内发生未捕获异常时发出。
- 同步
- 异步
# Log all uncaught errors to the terminal
page.on("pageerror", lambda exc: print(f"uncaught exception: {exc}"))
# Navigate to a page with an exception.
page.goto("data:text/html,<script>throw new Error('test')</script>")
# Log all uncaught errors to the terminal
page.on("pageerror", lambda exc: print(f"uncaught exception: {exc}"))
# Navigate to a page with an exception.
await page.goto("data:text/html,<script>throw new Error('test')</script>")
用法
page.on("pageerror", handler)
事件数据
on("popup")
v1.9 之前添加当页面打开新标签页或窗口时发出。除了browser_context.on("page")之外,此事件也会发出,但仅适用于与此页面相关的弹出窗口。
页面可用的最早时刻是它导航到初始URL时。例如,当使用window.open('http://example.com')
打开一个弹出窗口时,此事件将在到"http://example.com"的网络请求完成且其响应已开始在弹出窗口中加载时触发。如果您想路由/监听此网络请求,请使用browser_context.route()和browser_context.on("request"),而不是Page上的类似方法。
- 同步
- 异步
with page.expect_event("popup") as page_info:
page.get_by_text("open the popup").click()
popup = page_info.value
print(popup.evaluate("location.href"))
async with page.expect_event("popup") as page_info:
await page.get_by_text("open the popup").click()
popup = await page_info.value
print(await popup.evaluate("location.href"))
使用page.wait_for_load_state()等待页面达到特定状态(在大多数情况下您不需要它)。
用法
page.on("popup", handler)
事件数据
on("request")
v1.9 之前添加当页面发出请求时发出。请求对象是只读的。要拦截和修改请求,请参阅page.route()或browser_context.route()。
用法
page.on("request", handler)
事件数据
on("requestfailed")
添加于:v1.9当请求失败时发出,例如由于超时。
page.on("requestfailed", lambda request: print(request.url + " " + request.failure.error_text))
HTTP错误响应(如404或503)从HTTP角度来看仍然是成功响应,因此请求将以page.on("requestfinished")事件完成,而不是以page.on("requestfailed")完成。只有当客户端无法从服务器获取HTTP响应时(例如由于网络错误net::ERR_FAILED),请求才会被视为失败。
用法
page.on("requestfailed", handler)
事件数据
on("requestfinished")
添加于:v1.9当请求成功下载响应体后完成时发出。对于成功的响应,事件序列是 request
、response
和 requestfinished
。
用法
page.on("requestfinished", handler)
事件数据
on("response")
v1.9 之前添加当请求收到响应状态和头部时发出。对于成功的响应,事件序列是request
、response
和requestfinished
。
用法
page.on("response", handler)
事件数据
on("websocket")
添加于:v1.9当WebSocket请求发送时发出。
用法
page.on("websocket", handler)
事件数据
on("worker")
v1.9 之前添加当页面生成专用 WebWorker 时发出。
用法
page.on("worker", handler)
事件数据
已弃用
accessibility
v1.9 之前添加用法
page.accessibility
类型
check
v1.9 之前添加请改用基于定位符的 locator.check()。阅读有关 定位符 的更多信息。
此方法通过执行以下步骤来检查与selector匹配的元素
- 查找与selector匹配的元素。如果不存在,则等待匹配元素附加到DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出。如果元素已被选中,此方法将立即返回。
- 对匹配元素进行可操作性检查,除非设置了force选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 点击元素中心。
- 确保元素现在已选中。如果不是,此方法将抛出异常。
当所有步骤在指定的timeout内未完成时,此方法会抛出TimeoutError。传递零超时将禁用此功能。
用法
page.check(selector)
page.check(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。
返回
click
v1.9 之前添加请改用基于定位符的 locator.click()。阅读有关 定位符 的更多信息。
此方法通过执行以下步骤来点击与selector匹配的元素
- 查找与selector匹配的元素。如果不存在,则等待匹配元素附加到DOM。
- 对匹配元素进行可操作性检查,除非设置了force选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用page.mouse点击元素的中心或指定的位置。
- 等待已启动的导航成功或失败,除非设置了no_wait_after选项。
当所有步骤在指定的timeout内未完成时,此方法会抛出TimeoutError。传递零超时将禁用此功能。
用法
page.click(selector)
page.click(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
button
"left" | "right" | "middle" (可选)#默认为
left
。 -
默认为 1。参见 UIEvent.detail。
-
mousedown
和mouseup
之间等待的时间(毫秒)。默认为 0。 -
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta"在Windows和Linux上解析为"Control",在macOS上解析为"Meta"。
-
已弃用
此选项将来默认为
true
。启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为
false
。 -
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
设置后,此方法仅执行可操作性检查并跳过该操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。请注意,无论trial
如何,都将按下键盘modifiers
,以允许测试仅在按下这些键时才可见的元素。
返回
dblclick
v1.9 之前添加请改用基于定位符的 locator.dblclick()。阅读有关 定位符 的更多信息。
此方法通过执行以下步骤双击与selector匹配的元素
- 查找与selector匹配的元素。如果不存在,则等待匹配元素附加到DOM。
- 对匹配元素进行可操作性检查,除非设置了force选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用page.mouse双击元素的中心或指定的位置。
当所有步骤在指定的timeout内未完成时,此方法会抛出TimeoutError。传递零超时将禁用此功能。
page.dblclick()
分派两次 click
事件和一次 dblclick
事件。
用法
page.dblclick(selector)
page.dblclick(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
button
"left" | "right" | "middle" (可选)#默认为
left
。 -
mousedown
和mouseup
之间等待的时间(毫秒)。默认为 0。 -
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta"在Windows和Linux上解析为"Control",在macOS上解析为"Meta"。
-
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
设置后,此方法仅执行可操作性检查并跳过该操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。请注意,无论trial
如何,都将按下键盘modifiers
,以允许测试仅在按下这些键时才可见的元素。
返回
dispatch_event
v1.9 之前添加请改用基于定位符的 locator.dispatch_event()。阅读有关 定位符 的更多信息。
下面的代码片段在元素上分派click
事件。无论元素的可见状态如何,都会分派click
。这等同于调用element.click()。
用法
- 同步
- 异步
page.dispatch_event("button#submit", "click")
await page.dispatch_event("button#submit", "click")
在底层,它根据给定的type创建事件实例,使用event_init属性初始化它,并在元素上分派它。事件默认是composed
、cancelable
和冒泡的。
由于event_init是特定于事件的,请参阅事件文档以获取初始属性列表
- DeviceMotionEvent
- DeviceOrientationEvent
- DragEvent
- Event
- FocusEvent
- KeyboardEvent
- MouseEvent
- PointerEvent
- TouchEvent
- WheelEvent
您还可以指定 JSHandle
作为属性值,如果您希望将实时对象传递到事件中
- 同步
- 异步
# note you can only create data_transfer in chromium and firefox
data_transfer = page.evaluate_handle("new DataTransfer()")
page.dispatch_event("#source", "dragstart", { "dataTransfer": data_transfer })
# note you can only create data_transfer in chromium and firefox
data_transfer = await page.evaluate_handle("new DataTransfer()")
await page.dispatch_event("#source", "dragstart", { "dataTransfer": data_transfer })
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
DOM 事件类型:
"click"
、"dragstart"
等。 -
event_init
EvaluationArgument (可选)#可选的事件特定初始化属性。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
eval_on_selector
添加于:v1.9此方法不会等待元素通过可操作性检查,因此可能导致测试不稳定。请改用locator.evaluate()、其他Locator辅助方法或web-first断言。
该方法在页面内查找与指定选择器匹配的元素,并将其作为第一个参数传递给expression。如果没有元素匹配选择器,则该方法会抛出错误。返回expression的值。
如果expression返回一个Promise,则page.eval_on_selector()将等待Promise解析并返回其值。
用法
- 同步
- 异步
search_value = page.eval_on_selector("#search", "el => el.value")
preload_href = page.eval_on_selector("link[rel=preload]", "el => el.href")
html = page.eval_on_selector(".main-container", "(e, suffix) => e.outer_html + suffix", "hello")
search_value = await page.eval_on_selector("#search", "el => el.value")
preload_href = await page.eval_on_selector("link[rel=preload]", "el => el.href")
html = await page.eval_on_selector(".main-container", "(e, suffix) => e.outer_html + suffix", "hello")
参数
-
要查询的选择器。
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#要传递给expression的可选参数。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
返回
eval_on_selector_all
添加于:v1.9在大多数情况下,locator.evaluate_all()、其他 Locator 辅助方法和 web-first 断言会做得更好。
该方法在页面内查找与指定选择器匹配的所有元素,并将其作为第一个参数传递给expression。返回expression调用的结果。
如果expression返回一个Promise,则page.eval_on_selector_all()将等待Promise解析并返回其值。
用法
- 同步
- 异步
div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10)
div_counts = await page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10)
参数
-
要查询的选择器。
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#要传递给expression的可选参数。
返回
expect_navigation
v1.9 之前添加此方法本身具有竞态条件,请改用page.wait_for_url()。
等待主框架导航并返回主资源响应。在多次重定向的情况下,导航将以最后一次重定向的响应解决。在导航到不同的锚点或由于History API使用而导致的导航情况下,导航将以null
解决。
用法
当页面导航到新URL或重新加载时,此方法解析。当您运行间接导致页面导航的代码时,这很有用。例如,点击目标有一个onclick
处理程序,该处理程序通过setTimeout
触发导航。考虑以下示例
- 同步
- 异步
with page.expect_navigation():
# This action triggers the navigation after a timeout.
page.get_by_text("Navigate after timeout").click()
# Resolves after navigation has finished
async with page.expect_navigation():
# This action triggers the navigation after a timeout.
await page.get_by_text("Navigate after timeout").click()
# Resolves after navigation has finished
使用 History API 更改 URL 被视为导航。
参数
-
操作的最大时间(毫秒),默认为 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'
- 当收到网络响应且文档开始加载时,认为操作完成。
返回
fill
v1.9 之前添加请改用基于定位符的 locator.fill()。阅读有关 定位符 的更多信息。
此方法等待与selector匹配的元素,执行可操作性检查,聚焦元素,填充它,并在填充后触发input
事件。请注意,您可以传递空字符串以清除输入字段。
如果目标元素不是<input>
、<textarea>
或[contenteditable]
元素,则此方法将抛出错误。但是,如果该元素位于具有关联control的<label>
元素内,则将填充该control。
要发送细粒度键盘事件,请使用 locator.press_sequentially()。
用法
page.fill(selector, value)
page.fill(selector, value, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要填充
<input>
、<textarea>
或[contenteditable]
元素的值。 -
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
focus
v1.9 之前添加请改用基于定位符的 locator.focus()。阅读有关 定位符 的更多信息。
此方法获取具有selector的元素并聚焦它。如果没有元素匹配selector,该方法将等待直到匹配元素出现在DOM中。
用法
page.focus(selector)
page.focus(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
get_attribute
v1.9 之前添加请改用基于定位符的 locator.get_attribute()。阅读有关 定位符 的更多信息。
返回元素属性值。
用法
page.get_attribute(selector, name)
page.get_attribute(selector, name, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要获取值的属性名称。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
hover
v1.9 之前添加请改用基于定位符的 locator.hover()。阅读有关 定位符 的更多信息。
此方法通过执行以下步骤悬停在与selector匹配的元素上
- 查找与selector匹配的元素。如果不存在,则等待匹配元素附加到DOM。
- 对匹配元素进行可操作性检查,除非设置了force选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用page.mouse悬停在元素的中心或指定的位置。
当所有步骤在指定的timeout内未完成时,此方法会抛出TimeoutError。传递零超时将禁用此功能。
用法
page.hover(selector)
page.hover(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta"在Windows和Linux上解析为"Control",在macOS上解析为"Meta"。
-
no_wait_after
bool (可选)新增于: v1.28#已弃用此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
设置后,此方法仅执行可操作性检查并跳过该操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。请注意,无论trial
如何,都将按下键盘modifiers
,以允许测试仅在按下这些键时才可见的元素。
返回
inner_html
v1.9 之前添加请改用基于定位符的 locator.inner_html()。阅读有关 定位符 的更多信息。
返回 element.innerHTML
。
用法
page.inner_html(selector)
page.inner_html(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
inner_text
v1.9 之前添加请改用基于定位符的 locator.inner_text()。阅读有关 定位符 的更多信息。
返回 element.innerText
。
用法
page.inner_text(selector)
page.inner_text(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
input_value
添加于:v1.13请改用基于定位符的 locator.input_value()。阅读有关 定位符 的更多信息。
返回选定的 <input>
、<textarea>
或 <select>
元素的 input.value
。
对于非输入元素会抛出异常。然而,如果元素位于具有关联 control 的 <label>
元素内部,则返回 control 的值。
用法
page.input_value(selector)
page.input_value(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
is_checked
v1.9 之前添加请改用基于定位符的 locator.is_checked()。阅读有关 定位符 的更多信息。
返回元素是否已选中。如果元素不是复选框或单选输入,则抛出异常。
用法
page.is_checked(selector)
page.is_checked(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
is_disabled
v1.9 之前添加请改用基于定位符的 locator.is_disabled()。阅读有关 定位符 的更多信息。
返回元素是否禁用,与 启用 相反。
用法
page.is_disabled(selector)
page.is_disabled(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
is_editable
v1.9 之前添加请改用基于定位符的 locator.is_editable()。阅读有关 定位符 的更多信息。
返回元素是否 可编辑。
用法
page.is_editable(selector)
page.is_editable(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
is_enabled
v1.9 之前添加请改用基于定位符的 locator.is_enabled()。了解更多关于 定位符 的信息。
返回元素是否 启用。
用法
page.is_enabled(selector)
page.is_enabled(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
is_hidden
v1.9 之前添加请改用基于定位符的 locator.is_hidden()。阅读有关 定位符 的更多信息。
返回元素是否隐藏,与 可见 相反。不匹配任何元素的 选择器 被认为是隐藏的。
用法
page.is_hidden(selector)
page.is_hidden(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
已弃用
此选项被忽略。page.is_hidden() 不会等待元素变为隐藏并立即返回。
返回
is_visible
v1.9 之前添加请改用基于定位符的 locator.is_visible()。阅读有关 定位符 的更多信息。
用法
page.is_visible(selector)
page.is_visible(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
已弃用
此选项被忽略。page.is_visible() 不会等待元素变为可见并立即返回。
返回
press
v1.9 之前添加请改用基于定位符的 locator.press()。阅读有关 定位符 的更多信息。
聚焦元素,然后使用 keyboard.down() 和 keyboard.up()。
key 可以指定预期的 keyboardEvent.key 值或生成文本的单个字符。key 值的超集可在 此处 找到。按键示例有:
F1
- F12
, Digit0
- Digit9
, KeyA
- KeyZ
, Backquote
, Minus
, Equal
, Backslash
, Backspace
, Tab
, Delete
, Escape
, ArrowDown
, End
, Enter
, Home
, Insert
, PageDown
, PageUp
, ArrowRight
, ArrowUp
等。
还支持以下修改快捷键:Shift
、Control
、Alt
、Meta
、ShiftLeft
、ControlOrMeta
。ControlOrMeta
在 Windows 和 Linux 上解析为 Control
,在 macOS 上解析为 Meta
。
按住 Shift
键将以大写形式输入与 key 对应的文本。
如果 key 是单个字符,则区分大小写,因此值 a
和 A
将生成不同的相应文本。
也支持快捷键,例如 key: "Control+o"
、key: "Control++
或 key: "Control+Shift+T"
。当与修饰符一起指定时,修饰符在按下后续键时被按下并保持。
用法
- 同步
- 异步
page = browser.new_page()
page.goto("https://keycode.info")
page.press("body", "A")
page.screenshot(path="a.png")
page.press("body", "ArrowLeft")
page.screenshot(path="arrow_left.png")
page.press("body", "Shift+O")
page.screenshot(path="o.png")
browser.close()
page = await browser.new_page()
await page.goto("https://keycode.info")
await page.press("body", "A")
await page.screenshot(path="a.png")
await page.press("body", "ArrowLeft")
await page.screenshot(path="arrow_left.png")
await page.press("body", "Shift+O")
await page.screenshot(path="o.png")
await browser.close()
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要按下的键的名称或要生成的字符,例如
ArrowLeft
或a
。 -
keydown
和keyup
之间等待的时间(毫秒)。默认为 0。 -
已弃用
此选项将来默认为
true
。启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为
false
。 -
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
query_selector
添加于:v1.9请改用基于定位符的 page.locator()。了解更多关于 定位符 的信息。
该方法在页面中查找与指定选择器匹配的元素。如果没有元素匹配选择器,则返回值解析为 null
。要等待页面上的元素,请使用 locator.wait_for()。
用法
page.query_selector(selector)
page.query_selector(selector, **kwargs)
参数
返回
query_selector_all
添加于:v1.9请改用基于定位符的 page.locator()。了解更多关于 定位符 的信息。
此方法在页面中查找与指定选择器匹配的所有元素。如果没有元素匹配选择器,返回值解析为 []
。
用法
page.query_selector_all(selector)
参数
返回
select_option
v1.9 之前添加请改用基于定位符的 locator.select_option()。阅读有关 定位符 的更多信息。
此方法等待与 选择器 匹配的元素,等待 可操作性 检查,等待直到所有指定的选项都存在于 <select>
元素中并选择这些选项。
如果目标元素不是 <select>
元素,则此方法会抛出错误。但是,如果元素位于具有关联 control 的 <label>
元素内部,则将使用该 control 代替。
返回已成功选择的选项值数组。
一旦所有提供的选项都已选中,将触发 change
和 input
事件。
用法
- 同步
- 异步
# Single selection matching the value or label
page.select_option("select#colors", "blue")
# single selection matching both the label
page.select_option("select#colors", label="blue")
# multiple selection
page.select_option("select#colors", value=["red", "green", "blue"])
# Single selection matching the value or label
await page.select_option("select#colors", "blue")
# single selection matching the label
await page.select_option("select#colors", label="blue")
# multiple selection
await page.select_option("select#colors", value=["red", "green", "blue"])
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
element
ElementHandle | List[ElementHandle] (可选)#要选择的选项元素。可选。
-
按索引选择的选项。可选。
-
按值选择的选项。如果
<select>
具有multiple
属性,则选择所有给定的选项,否则只选择与传入选项之一匹配的第一个选项。可选。 -
按标签选择的选项。如果
<select>
具有multiple
属性,则选择所有给定的选项,否则只选择与传入选项之一匹配的第一个选项。可选。
返回
set_checked
新增于: v1.15请改用基于定位符的 locator.set_checked()。阅读有关 定位符 的更多信息。
此方法通过执行以下步骤来检查或取消检查与 选择器 匹配的元素:
- 找到与 选择器 匹配的元素。如果没有,则等待直到匹配的元素附加到 DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出错误。
- 如果元素已经处于正确的选中状态,此方法将立即返回。
- 对匹配元素进行 可操作性 检查,除非设置了 force 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 点击元素中心。
- 确保元素现在已选中或未选中。如果不是,此方法将抛出异常。
如果在指定 timeout 期间所有步骤都未完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
用法
page.set_checked(selector, checked)
page.set_checked(selector, checked, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
是否选中或取消选中复选框。
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。
返回
set_input_files
v1.9 之前添加请改用基于定位符的 locator.set_input_files()。阅读有关 定位符 的更多信息。
将文件输入的 VALUE 设置为这些文件路径或文件。如果某些 filePaths
是相对路径,则它们相对于当前工作目录解析。对于空数组,清除选定的文件。对于具有 [webkitdirectory]
属性的输入,仅支持单个目录路径。
此方法期望 选择器 指向一个 输入元素。但是,如果元素位于具有关联 control 的 <label>
元素内部,则改为定位该 control。
用法
page.set_input_files(selector, files)
page.set_input_files(selector, files, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
files
Union[str, pathlib.Path] | List[Union[str, pathlib.Path]] | Dict | List[Dict]# -
已弃用
此选项无效。
此选项无效。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
tap
v1.9 之前添加请改用基于定位符的 locator.tap()。阅读有关 定位符 的更多信息。
此方法通过执行以下步骤来轻触与 选择器 匹配的元素:
- 找到与 选择器 匹配的元素。如果没有,则等待直到匹配的元素附加到 DOM。
- 对匹配元素进行 可操作性 检查,除非设置了 force 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 page.touchscreen 轻触元素的中心,或指定的 位置。
如果在指定 timeout 期间所有步骤都未完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
page.tap() 方法会在浏览器上下文的 has_touch 选项为 false 时抛出异常。
用法
page.tap(selector)
page.tap(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
是否绕过 可操作性 检查。默认为
false
。 -
modifiers
List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta"在Windows和Linux上解析为"Control",在macOS上解析为"Meta"。
-
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
设置后,此方法仅执行可操作性检查并跳过该操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。请注意,无论trial
如何,都将按下键盘modifiers
,以允许测试仅在按下这些键时才可见的元素。
返回
text_content
v1.9 之前添加请改用基于定位符的 locator.text_content()。阅读有关 定位符 的更多信息。
返回 element.textContent
。
用法
page.text_content(selector)
page.text_content(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
type
v1.9 之前添加在大多数情况下,您应该改用 locator.fill()。仅当页面上存在特殊键盘处理时,您才需要一个一个地按下按键——在这种情况下,请使用 locator.press_sequentially()。
为文本中的每个字符发送 keydown
、keypress
/input
和 keyup
事件。page.type
可用于发送细粒度的键盘事件。要填写表单字段的值,请使用 page.fill()。
要按特殊键,例如 `Control` 或 `ArrowDown`,请使用 keyboard.press()。
用法
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要输入到聚焦元素的文本。
-
按键之间等待的时间,以毫秒为单位。默认为 0。
-
已弃用
此选项无效。
此选项无效。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
uncheck
v1.9 之前添加请改用基于定位符的 locator.uncheck()。阅读有关 定位符 的更多信息。
此方法通过执行以下步骤来取消选中与 选择器 匹配的元素:
- 找到与 选择器 匹配的元素。如果没有,则等待直到匹配的元素附加到 DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出错误。如果元素已取消选中,此方法会立即返回。
- 对匹配元素进行 可操作性 检查,除非设置了 force 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 page.mouse 点击元素中心。
- 确保元素现在未选中。如果不是,此方法将抛出异常。
如果在指定 timeout 期间所有步骤都未完成,此方法将抛出 TimeoutError。传递零超时会禁用此功能。
用法
page.uncheck(selector)
page.uncheck(selector, **kwargs)
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。 -
设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。
返回
wait_for_selector
v1.9 之前添加请改用断言可见性的 Web 断言或基于定位符的 locator.wait_for()。了解更多关于 定位符 的信息。
当选择器指定的元素满足 state 选项时返回。如果等待 hidden
或 detached
,则返回 null
。
Playwright 会自动等待元素准备好后再执行操作。使用 Locator 对象和 Web 优先断言可以使代码摆脱 wait-for-selector。
等待 选择器 满足 state 选项(从 DOM 中出现/消失,或变为可见/隐藏)。如果在调用方法时 选择器 已经满足条件,则方法将立即返回。如果选择器在 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.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.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())
参数
-
要查询的选择器。
-
state
"attached" | "detached" | "visible" | "hidden" (可选)#默认为
'visible'
。可以是以下之一:'attached'
- 等待元素出现在 DOM 中。'detached'
- 等待元素不在 DOM 中。'visible'
- 等待元素具有非空的边界框且没有visibility:hidden
。请注意,没有任何内容或具有display:none
的元素具有空的边界框,不被视为可见。'hidden'
- 等待元素从 DOM 中分离,或具有空的边界框或visibility:hidden
。这与'visible'
选项相反。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法更改默认值。
返回
wait_for_timeout
v1.9 之前添加切勿在生产环境中等待超时。等待时间的测试本质上是不可靠的。请使用 Locator 操作和自动等待的 Web 断言。
等待给定的 超时 毫秒。
请注意,page.waitForTimeout()
仅应用于调试。在生产环境中使用定时器的测试将会变得不稳定。请改用网络事件、选择器可见性等信号。
用法
- 同步
- 异步
# wait for 1 second
page.wait_for_timeout(1000)
# wait for 1 second
await page.wait_for_timeout(1000)
参数
返回