跳到主要内容

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)

Page 类会触发多种事件（见下文），这些事件可以通过 Node 原生的 EventEmitter 方法进行处理，比如 on、once 或 removeListener。

下面的示例为单个页面的 load 事件记录一条消息：

page.once("load", lambda: print("页面已加载！"))

要取消订阅事件，可以使用 removeListener 方法：

def log_request(intercepted_request):
    print("发起了一个请求:", intercepted_request.url)
page.on("request", log_request)
# 稍后某个时刻...
page.remove_listener("request", log_request)

方法​

add_init_script​

v1.9 之前添加 page.add_init_script

添加一个脚本，该脚本会在以下场景之一被执行：

  • 每当页面发生跳转时。
  • 每当子 frame 被附加或跳转时。在这种情况下，脚本会在新附加的 frame 上下文中执行。

该脚本会在文档创建后、任何页面脚本运行前被执行。这对于修改 JavaScript 环境很有用，例如为 Math.random 设定种子。

用法

在页面加载前重写 Math.random 的示例：

// preload.js
Math.random = () => 42;
# 在你的 playwright 脚本中，假设 preload.js 文件与脚本在同一目录
page.add_init_script(path="./preload.js")
备注

通过 browser_context.add_init_script() 和 page.add_init_script() 安装的多个脚本的执行顺序是不确定的。

参数

  • path Union[str, pathlib.Path] (可选)#

    JavaScript 文件的路径。如果 path 是相对路径，则会相对于当前工作目录进行解析。可选。

  • script str (可选)#

    要在浏览器上下文所有页面中执行的脚本。可选。

返回值

add_locator_handler​

v1.42 之前添加 page.add_locator_handler

在测试网页时，有时会遇到意外弹出的遮罩层（如“注册”对话框），这些遮罩层会阻挡你想自动化的操作，比如点击按钮。这些遮罩层并不总是以相同的方式或时间出现，因此在自动化测试中处理起来比较棘手。

此方法允许你设置一个特殊的函数（称为 handler 处理器），当检测到遮罩层可见时会自动触发。handler 的作用是移除遮罩层，使你的测试可以像没有遮罩层一样继续执行。

注意事项：

  • 如果遮罩层是可预测地出现，建议在测试中显式等待它出现并主动关闭，而不是使用 page.add_locator_handler()。
  • Playwright 会在每次执行或重试需要actionability 检查的操作前，或在执行自动等待断言检查前，检查遮罩层是否存在。如果遮罩层可见，Playwright 会先调用 handler，然后再继续执行操作或断言。注意只有在你执行操作或断言时才会调用 handler——如果遮罩层出现但你没有执行任何操作，handler 不会被触发。
  • handler 执行后，Playwright 会确保触发 handler 的遮罩层已经不可见。你可以通过 no_wait_after 选项关闭此行为。
  • handler 的执行时间会计入触发 handler 的操作或断言的超时时间。如果 handler 执行过慢，可能导致超时。
  • 你可以注册多个 handler，但同一时刻只会有一个 handler 在运行。确保 handler 内的操作不要依赖于其他 handler。
注意

handler 的运行会在测试过程中改变页面状态。例如，它会改变当前聚焦的元素并移动鼠标。请确保 handler 之后的操作是自包含的，不依赖于聚焦和鼠标状态未被改变。

例如，假设测试中先调用了 locator.focus()，然后调用 keyboard.press()。如果 handler 在这两个操作之间点击了按钮，聚焦的元素很可能会变，按键操作就会发生在意外的元素上。建议使用 locator.press() 以避免此问题。

另一个例子是连续的鼠标操作，比如 mouse.move() 后接 mouse.down()。同样，如果 handler 在这两个操作之间运行，鼠标位置会被改变，导致 mouse down 时位置不正确。建议使用 locator.click() 这类自包含的操作，避免依赖 handler 运行前后的状态。

用法

一个示例：当出现“订阅新闻通讯”对话框时自动关闭它：

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

# 正常编写测试。
page.goto("https://example.com")
page.get_by_role("button", name="Start here").click()

一个示例：当出现“确认你的安全信息”页面时自动跳过：

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

# 正常编写测试。
page.goto("https://example.com")
page.get_by_role("button", name="Start here").click()

一个示例：在每次 actionability 检查时自定义回调。这里用 <body> 作为 locator，因为它总是可见，所以 handler 会在每次 actionability 检查前被调用。需要指定 no_wait_after，因为 handler 并不会隐藏 <body> 元素。

# 设置 handler。
def handler():
  page.evaluate("window.removeObstructionsForTestIfNeeded()")
page.add_locator_handler(page.locator("body"), handler, no_wait_after=True)

# 正常编写测试。
page.goto("https://example.com")
page.get_by_role("button", name="Start here").click()

handler 可以接收原始 locator 作为参数。你也可以通过设置 times 参数，在调用指定次数后自动移除 handler：

def handler(locator):
  locator.click()
page.add_locator_handler(page.get_by_label("Close"), handler, times=1)

参数

  • locator Locator#

    触发 handler 的定位器。

  • handler Callable[Locator]:Promise[Any]#

    当 locator 出现时应运行的函数。该函数应移除阻挡点击等操作的元素。

  • no_wait_after bool (可选) v1.44 之前添加#

    默认情况下，调用 handler 后 Playwright 会等待遮罩层消失，然后才继续执行触发 handler 的操作或断言。此选项允许关闭该行为，使遮罩层在 handler 执行后仍可见。

  • times int (可选) v1.44 之前添加#

    指定 handler 最多被调用的次数。默认无限制。

返回值

add_script_tag​

v1.9 之前添加 page.add_script_tag

向页面中添加一个 <script> 标签，可以指定 url 或内容。当脚本的 onload 事件触发，或脚本内容被注入到 frame 后，返回添加的标签。

用法

page.add_script_tag()
page.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。

返回值

add_style_tag​

v1.9 之前添加 page.add_style_tag

向页面中添加一个 <link rel="stylesheet"> 标签（指定 url），或添加一个带内容的 <style type="text/css"> 标签。当样式表的 onload 事件触发，或 CSS 内容被注入到 frame 后，返回添加的标签。

用法

page.add_style_tag()
page.add_style_tag(**kwargs)

参数

  • content str (可选)#

    要注入到 frame 的原始 CSS 内容。

  • path Union[str, pathlib.Path] (可选)#

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

  • url str (可选)#

    <link> 标签的 URL。

返回值

bring_to_front​

v1.9 之前添加 page.bring_to_front

将页面置于最前（激活标签页）。

用法

page.bring_to_front()

返回值

close​

v1.9 之前添加 page.close

如果 run_before_unload 为 false，则不会运行任何 unload 处理器，并等待页面关闭。如果 run_before_unload 为 true，则会运行 unload 处理器，但不会等待页面关闭。

默认情况下，page.close() 不会运行 beforeunload 处理器。

备注

如果传入 run_before_unload 为 true，可能会弹出 beforeunload 对话框，需要通过 page.on("dialog") 事件手动处理。

用法

page.close()
page.close(**kwargs)

参数

  • reason str (可选) v1.40 新增#

    页面关闭时报告给被中断操作的原因。

  • run_before_unload bool (可选)#

    默认为 false。是否运行 before unload 页面处理器。

返回值

content​

v1.9 之前添加 page.content

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

用法

page.content()

返回值

drag_and_drop​

v1.13 之前添加 page.drag_and_drop

该方法用于将源元素拖拽到目标元素。它会先移动到源元素，执行 mousedown，然后移动到目标元素并执行 mouseup。

用法

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

参数

  • source str#

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

  • target str#

    用于查找要释放的目标元素的选择器。如果有多个元素匹配该选择器，则使用第一个。

  • force bool (可选)#

    是否跳过actionability 检查。默认为 false。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • source_position Dict (可选) v1.14 新增#

    在源元素上点击的点，相对于元素内边距盒子的左上角。如果未指定，则使用元素的某个可见点。

  • strict bool (可选) v1.14 新增#

    为 true 时，要求选择器只能匹配一个元素。如果选择器匹配多个元素，则会抛出异常。

  • target_position Dict (可选) v1.14 新增#

    在目标元素上释放的点，相对于元素内边距盒子的左上角。如果未指定，则使用元素的某个可见点。

  • timeout float (可选)#

    最大超时时间（毫秒）。默认为 30000（30 秒）。传入 0 表示不设置超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。

  • trial bool (可选)#

    设置为 true 时，该方法只执行actionability 检查，不会真正执行拖拽操作。默认为 false。可用于等待元素准备好执行操作但不实际执行。

返回值

emulate_media​

v1.9 之前添加 page.emulate_media

该方法通过 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
page.emulate_media(color_scheme="dark")
page.evaluate("matchMedia('(prefers-color-scheme: dark)').matches")
# → True
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 之前添加 page.evaluate

返回 expression 执行的值。

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

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

用法

向 expression 传递参数：

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

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

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

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

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

参数

  • expression str#

    要在浏览器上下文中执行的 JavaScript 表达式。如果表达式为函数，则会自动调用该函数。

  • arg EvaluationArgument (可选)#

    传递给 expression 的可选参数。

返回值

evaluate_handle​

v1.9 之前添加 page.evaluate_handle

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

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

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

参数

  • expression str#

    要在浏览器上下文中执行的 JavaScript 表达式。如果表达式为函数，则会自动调用该函数。

  • arg EvaluationArgument (可选)#

    传递给 expression 的可选参数。

返回值

expect_console_message​

v1.9 新增 page.expect_console_message

执行操作并等待页面中记录 ConsoleMessage。如果提供了 predicate，则会将 ConsoleMessage 对象传递给 predicate 函数，并等待 predicate(message) 返回真值。如果在 page.on("console") 事件触发前页面被关闭，则会抛出异常。

用法

page.expect_console_message()
page.expect_console_message(**kwargs)

参数

返回值

expect_download​

v1.9 新增 page.expect_download

执行操作并等待新的 Download 出现。如果提供了 predicate，则会将 Download 对象传递给 predicate 函数，并等待 predicate(download) 返回真值。如果在下载事件触发前页面被关闭，则会抛出异常。

用法

page.expect_download()
page.expect_download(**kwargs)

参数

返回值

expect_event​

v1.9 之前添加 page.expect_event

等待事件触发，并将其值传递给 predicate 函数。当 predicate 返回真值时返回。如果在事件触发前页面被关闭，则会抛出异常。返回事件数据值。

用法

with page.expect_event("framenavigated") as event_info:
    page.get_by_role("button")
frame = event_info.value

参数

  • event str#

    事件名称，通常与 *.on(event) 传入的名称一致。

  • predicate Callable (可选)#

    接收事件数据，当返回真值时等待结束。

  • timeout float (可选)#

    最大等待时间（毫秒）。默认为 30000（30 秒）。传入 0 表示不设置超时。默认值可通过 browser_context.set_default_timeout() 修改。

返回值

expect_file_chooser​

v1.9 新增 page.expect_file_chooser

执行操作并等待新的 FileChooser 被创建。如果提供了 predicate，则会将 FileChooser 对象传递给 predicate 函数，并等待 predicate(fileChooser) 返回真值。如果在文件选择框打开前页面被关闭，则会抛出异常。

用法

page.expect_file_chooser()
page.expect_file_chooser(**kwargs)

参数

返回值

expect_popup​

v1.9 新增 page.expect_popup

执行操作并等待弹出 Page。如果提供了 predicate，则会将 [Popup] 对象传递给 predicate 函数，并等待 predicate(page) 返回真值。如果在弹窗事件触发前页面被关闭，则会抛出异常。

用法

page.expect_popup()
page.expect_popup(**kwargs)

参数

返回值

expect_request​

v1.9 之前添加 page.expect_request

等待匹配的请求并返回该请求。更多关于事件的细节见等待事件。

用法

with page.expect_request("http://example.com/resource") as first:
    page.get_by_text("trigger request").click()
first_request = first.value

# 或使用 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

参数

返回值

expect_request_finished​

v1.12 新增 page.expect_request_finished

执行操作并等待某个 Request 加载完成。如果提供了 predicate，则会将 Request 对象传递给 predicate 函数，并等待 predicate(request) 返回真值。如果在 page.on("requestfinished") 事件触发前页面被关闭，则会抛出异常。

用法

page.expect_request_finished()
page.expect_request_finished(**kwargs)

参数

返回值

expect_response​

v1.9 之前添加 page.expect_response

返回匹配的响应。更多关于事件的细节见等待事件。

用法

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

# 或使用 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

参数

返回值

expect_websocket​

v1.9 新增 page.expect_websocket

执行操作并等待新的 WebSocket。如果提供了 predicate，则会将 WebSocket 对象传递给 predicate 函数，并等待 predicate(webSocket) 返回真值。如果在 WebSocket 事件触发前页面被关闭，则会抛出异常。

用法

page.expect_websocket()
page.expect_websocket(**kwargs)

参数

返回值

expect_worker​

v1.9 新增 page.expect_worker

执行操作并等待新的 Worker。如果提供了 predicate，则会将 Worker 对象传递给 predicate 函数，并等待 predicate(worker) 返回真值。如果在 worker 事件触发前页面被关闭，则会抛出异常。

用法

page.expect_worker()
page.expect_worker(**kwargs)

参数

返回值

expose_binding​

v1.9 之前添加 page.expose_binding

该方法会在页面所有 frame 的 window 对象上添加一个名为 name 的函数。当调用该函数时，会执行 callback，并返回一个 Promise，该 promise 会解析为 callback 的返回值。如果 callback 返回一个 Promise，则会等待其完成。

callback 函数的第一个参数包含调用者的信息：{ browserContext: BrowserContext, page: Page, frame: Frame }。

参见 browser_context.expose_binding() 获取作用于整个上下文的方法。

备注

通过 page.expose_binding() 安装的函数在页面跳转后依然有效。

用法

一个示例：将页面 URL 暴露给页面所有 frame：

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()">点击我</button>
    <div></div>
    """)
    page.click("button")

with sync_playwright() as playwright:
    run(playwright)

参数

  • name str#

    在 window 对象上暴露的函数名。

  • callback Callable#

    Playwright 端被调用的回调函数。

  • handle bool (可选)#

    已废弃

    此选项未来将被移除。

    是否以句柄方式传递参数，而不是按值传递。以句柄方式传递时只支持一个参数，按值传递时支持多个参数。

返回值

expose_function​

v1.9 之前添加 page.expose_function

该方法会在页面所有 frame 的 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() {
            // 调用 window.sha256 并将结果显示到 div
            document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
          }
        </script>
        <button onclick="onClick()">点击我</button>
        <div></div>
    """)
    page.click("button")

with sync_playwright() as playwright:
    run(playwright)

参数

  • name str#

    在 window 对象上暴露的函数名

  • callback Callable#

    Playwright 端被调用的回调函数

返回值

frame​

v1.9 之前添加 page.frame

返回匹配指定条件的 frame。必须指定 name 或 url。

用法

frame = page.frame(name="frame-name")
frame = page.frame(url=r".*domain.*")

参数

  • name str (可选)#

    iframe 的 name 属性指定的 frame 名称。可选。

  • url str | Pattern | Callable[URL]:bool (可选)#

    一个 glob 模式、正则表达式或接收 frame 的 url（作为 URL 对象）的谓词函数。可选。

返回值

frame_locator​

v1.17 新增 page.frame_locator

在处理 iframe 时，可以创建一个 frame 定位器，进入 iframe 并在该 iframe 内选择元素。

用法

以下代码片段会在 id 为 my-frame 的 iframe（如 <iframe id="my-frame">）中定位文本为 "Submit" 的元素：

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

参数

  • selector str#

    用于解析 DOM 元素的选择器。

返回值

get_by_alt_text​

v1.27 新增 page.get_by_alt_text

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

用法

例如，以下方法会通过 alt 文本 "Playwright logo" 找到图片：

<img alt='Playwright logo'>
page.get_by_alt_text("Playwright logo").click()

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意精确匹配仍会去除空白字符。

返回值

get_by_label​

v1.27 新增 page.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")

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意精确匹配仍会去除空白字符。

返回值

get_by_placeholder​

v1.27 新增 page.get_by_placeholder

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

用法

例如，考虑如下 DOM 结构：

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

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

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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意精确匹配仍会去除空白字符。

返回值

get_by_role​

v1.27 新增 page.get_by_role

允许通过 ARIA 角色、ARIA 属性 和 可访问名称 定位元素。

用法

考虑如下 DOM 结构：

<h3>注册</h3>
<label>
  <input type="checkbox" /> 订阅
</label>
<br/>
<button>提交</button>

你可以通过元素的隐式角色定位每个元素：

expect(page.get_by_role("heading", name="注册")).to_be_visible()

page.get_by_role("checkbox", name="订阅").check()

page.get_by_role("button", name=re.compile("提交", 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。

返回值

详情

角色选择器不会替代可访问性审查和合规性测试，但可以为 ARIA 指南提供早期反馈。

许多 html 元素有隐式定义的角色，角色选择器可以识别。你可以在这里查看所有支持的角色。ARIA 指南不推荐通过设置 role 和/或 aria-* 属性为默认值来重复隐式角色和属性。

get_by_test_id​

v1.27 新增 page.get_by_test_id

通过测试 id 定位元素。

用法

考虑如下 DOM 结构：

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

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

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

参数

返回值

详情

默认情况下，data-testid 属性被用作测试 id。如有需要，可通过 selectors.set_test_id_attribute() 配置其他测试 id 属性。

get_by_text​

v1.27 新增 page.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))

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意精确匹配仍会去除空白字符。

返回值

详情

通过文本匹配时总是会规范化空白字符，即使是精确匹配。例如，会将多个空格合并为一个，将换行符转换为空格，并忽略首尾空白。

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

get_by_title​

v1.27 新增 page.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")

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool (可选)#

    是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时忽略该选项。注意精确匹配仍会去除空白字符。

返回值

go_back​

v1.9 之前添加 page.go_back

返回主资源的响应。如果有多次重定向，导航会以最后一次重定向的响应作为结果。如果无法后退，则返回 null。

在历史记录中返回上一页。

用法

page.go_back()
page.go_back(**kwargs)

参数

  • 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 内没有网络连接时认为操作完成。不要用此方法做测试，请使用 Web 断言判断页面是否准备好。
    • 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

go_forward​

v1.9 之前添加 page.go_forward

返回主资源的响应。如果有多次重定向，导航会以最后一次重定向的响应作为结果。如果无法前进，则返回 null。

在历史记录中前进到下一页。

用法

page.go_forward()
page.go_forward(**kwargs)

参数

  • 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 内没有网络连接时认为操作完成。不要用此方法做测试，请使用 Web 断言判断页面是否准备好。
    • 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

goto​

v1.9 之前添加 page.goto

返回主资源的响应。如果有多次重定向，导航会以第一个非重定向的响应作为结果。

在以下情况下该方法会抛出异常：

  • 存在 SSL 错误（如自签名证书）。
  • 目标 URL 无效。
  • 导航过程中超出了 timeout。
  • 远程服务器无响应或无法访问。
  • 主资源加载失败。

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

备注

该方法要么抛出异常，要么返回主资源响应。唯一的例外是导航到 about:blank 或导航到同一 URL 但 hash 不同的情况，此时会成功并返回 null。

备注

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

用法

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

参数

  • url str#

    要导航到的页面 URL。URL 应包含协议，例如 https://。如果通过上下文选项提供了 base_url，且传入的 URL 是路径，则会通过 new URL() 构造合并。

  • 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 内没有网络连接时认为操作完成。不要用此方法做测试，请使用 Web 断言判断页面是否准备好。
    • 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

locator​

v1.14 新增 page.locator

该方法返回一个元素定位器，可用于在当前页面或 frame 上执行操作。定位器会在每次执行操作前即时解析到元素，因此对同一个定位器连续执行多次操作时，实际上可能作用于不同的 DOM 元素。如果操作之间 DOM 结构发生了变化，就会出现这种情况。

了解更多关于定位器。

用法

page.locator(selector)
page.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 会失败，因为内部定位器必须是相对的，不能引用 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>。

返回值

opener​

v1.9 之前添加 page.opener

返回弹窗页面的 opener（打开它的页面），其他页面返回 null。如果 opener 已经关闭，也会返回 null。

用法

page.opener()

返回值

pause​

v1.9 新增 page.pause

暂停脚本执行。Playwright 会停止执行脚本，等待用户在页面浮层中点击“继续”按钮，或在 DevTools 控制台中调用 playwright.resume()。

暂停期间，用户可以检查选择器或手动执行操作。恢复后会从暂停的位置继续运行原始脚本。

备注

该方法要求 Playwright 以有头模式启动，即 headless 选项为假值。

用法

page.pause()

返回值

pdf​

v1.9 之前添加 page.pdf

返回 PDF 的二进制内容。

page.pdf() 会以 print 媒体类型生成页面的 PDF。如需以 screen 媒体类型生成 PDF，请在调用 page.pdf() 前先调用 page.emulate_media()：

备注

默认情况下，page.pdf() 生成的 PDF 会调整颜色以适应打印。要强制渲染原始颜色，可使用 -webkit-print-color-adjust 属性。

用法

# 以 "screen" 媒体类型生成 pdf
page.emulate_media(media="screen")
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 选项包括：

  • Letter：8.5英寸 x 11英寸
  • Legal：8.5英寸 x 14英寸
  • Tabloid：11英寸 x 17英寸
  • Ledger：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. 模板中的 script 标签不会被执行。
  2. 页面样式在模板中不可见。

参数

  • display_header_footer bool (可选)#

    是否显示页眉和页脚。默认为 false。

  • footer_template str (可选)#

    打印页脚的 HTML 模板。格式应与 header_template 相同。

  • format str (可选)#

    纸张格式。如果设置，则优先于 width 或 height。默认为 'Letter'。

  • header_template str (可选)#

    打印页眉的 HTML 模板。应为有效的 HTML 标记，并使用以下类名注入打印值：

    • 'date' 格式化的打印日期
    • 'title' 文档标题
    • 'url' 文档地址
    • 'pageNumber' 当前页码
    • 'totalPages' 文档总页数

  • height str | float (可选)#

    纸张高度，支持带单位的值。

  • landscape bool (可选)#

    是否横向打印。默认为 false。

  • margin Dict (可选)#

    • top str | float (可选)

      上边距，支持带单位的值。默认为 0。

    • right str | float (可选)

      右边距，支持带单位的值。默认为 0。

    • bottom str | float (可选)

      下边距，支持带单位的值。默认为 0。

    • left str | float (可选)

      左边距，支持带单位的值。默认为 0。

    纸张边距，默认为无边距。

  • outline bool (可选) v1.42 新增#

    是否将文档大纲嵌入到 PDF。默认为 false。

  • page_ranges str (可选)#

    要打印的页码范围，例如 '1-5, 8, 11-13'。默认为空字符串，表示打印所有页面。

  • path Union[str, pathlib.Path] (可选)#

    保存 PDF 的文件路径。如果 path 是相对路径，则相对于当前工作目录解析。如果未提供路径，则不会保存到磁盘。

  • prefer_css_page_size bool (可选)#

    是否优先使用页面中声明的 CSS @page 尺寸，而不是 width、height 或 format 选项。默认为 false，即内容会缩放以适应纸张大小。

  • print_background bool (可选)#

    是否打印背景图形。默认为 false。

  • scale float (可选)#

    网页渲染的缩放比例。默认为 1。缩放比例必须在 0.1 到 2 之间。

  • tagged bool (可选) v1.42 新增#

    是否生成带标签（可访问性）的 PDF。默认为 false。

  • width str | float (可选)#

    纸张宽度，支持带单位的值。

返回值

reload​

v1.9 之前添加 page.reload

该方法会重新加载当前页面，效果等同于用户在浏览器中点击刷新按钮。返回主资源的响应。如果有多次重定向，导航会以最后一次重定向的响应作为结果。

用法

page.reload()
page.reload(**kwargs)

参数

  • 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 内没有网络连接时认为操作完成。不要用此方法做测试，请使用 Web 断言判断页面是否准备好。
    • 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

remove_locator_handler​

v1.44 新增 page.remove_locator_handler

移除通过 page.add_locator_handler() 为指定定位器添加的所有处理器。

用法

page.remove_locator_handler(locator)

参数

返回值

request_gc​

v1.48 新增 page.request_gc

请求页面执行垃圾回收。注意无法保证所有不可达对象都能被回收。

该方法有助于检测内存泄漏。例如，如果页面中有一个可能泄漏的大对象 'suspect'，你可以通过 WeakRef 检查其是否被正确回收。

# 1. 在页面中为 "suspect" 保存一个 WeakRef。
page.evaluate("globalThis.suspectWeakRef = new WeakRef(suspect)")
# 2. 请求垃圾回收。
page.request_gc()
# 3. 检查 weak ref 是否已无法引用原对象。
assert page.evaluate("!globalThis.suspectWeakRef.deref()")

用法

page.request_gc()

返回值

route​

v1.9 之前添加 page.route

路由功能允许你拦截并修改页面发起的网络请求。

一旦启用路由，所有匹配 url 模式的请求都会被拦截，除非被继续、满足或中止，否则会一直等待。

备注

如果响应发生重定向，处理函数只会在第一个 url 上被调用。

备注

page.route() 不会拦截已被 Service Worker 拦截的请求。参见此问题。建议在使用请求拦截时，通过设置 service_workers 为 'block' 来禁用 Service Worker。

备注

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 = browser.new_page()
page.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
page.goto("https://example.com")
browser.close()

你可以根据请求内容决定如何处理。例如，拦截所有包含特定 post 数据的请求并进行 mock，其他请求则正常放行：

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)

页面级路由优先于浏览器上下文级路由（通过 browser_context.route() 设置），当请求同时匹配两者时，以页面级为准。

如需移除某个路由及其处理器，可使用 page.unroute()。

备注

启用路由会禁用 http 缓存。

参数

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

    用于匹配请求的 glob 模式、正则表达式或接收 URL 的谓词函数。如果在上下文选项中设置了 base_url，且传入的 URL 是不以 * 开头的字符串，则会通过 new URL() 构造合并。

  • handler Callable[Route, Request]:Promise[Any] | Any#

    路由请求时调用的处理函数。

  • times int (可选) v1.15 新增#

    路由生效的次数。默认每次都会生效。

返回值

route_from_har​

v1.23 新增 page.route_from_har

如果指定了该方法，页面中的网络请求将会从 HAR 文件中获取。详见 从 HAR 回放。

Playwright 不会对被 Service Worker 拦截的请求使用 HAR 文件。参见此问题。建议在使用请求拦截时，通过设置 service_workers 为 'block' 来禁用 Service Worker。

用法

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'，则未命中的请求会直接发往网络。

    默认为 abort。

  • update bool (可选)#

    如果指定该参数，则会用实际的网络信息更新指定的 HAR 文件，而不是直接从文件中读取。文件会在调用 browser_context.close() 时写入磁盘。

  • update_content "embed" | "attach" (可选) v1.32 新增#

    可选设置，用于控制资源内容的管理方式。如果指定为 attach，资源会以单独文件或 ZIP 存档条目的形式保存。如果指定为 embed，内容会内嵌在 HAR 文件中。

  • update_mode "full" | "minimal" (可选) v1.32 新增#

    当设置为 minimal 时，仅记录从 HAR 路由所需的信息。不会记录大小、时序、页面、cookie、安全性等在 HAR 回放时不需要的信息。默认为 minimal。

  • url str | Pattern (可选)#

    用于匹配请求 URL 的 glob 模式、正则表达式或谓词。只有 URL 匹配该模式的请求才会从 HAR 文件中获取。如果未指定，则所有请求都从 HAR 文件获取。

返回值

route_web_socket​

v1.48 新增 page.route_web_socket

该方法允许你修改页面发起的 websocket 连接。

注意：只有在调用该方法后创建的 WebSocket 才会被路由。建议在页面导航前调用此方法。

用法

下面是一个简单的 mock 示例，会对单条消息进行响应。更多细节和示例见 WebSocketRoute。

def message_handler(ws: WebSocketRoute, message: Union[str, bytes]):
  # 如果收到消息为 "request"
  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)

参数

返回值

screenshot​

v1.9 之前添加 page.screenshot

返回截图的二进制内容。

用法

page.screenshot()
page.screenshot(**kwargs)

参数

  • animations "disabled" | "allow" (可选)#

    设置为 "disabled" 时，会停止 CSS 动画、CSS 过渡和 Web 动画。动画根据持续时间有不同处理方式：

    • 有限动画会快进到结束，因此会触发 transitionend 事件。
    • 无限动画会被取消回初始状态，截图后重新播放。

    默认为 "allow"，即动画不做处理。

  • caret "hide" | "initial" (可选)#

    设置为 "hide" 时，截图会隐藏文本光标。设置为 "initial" 时，文本光标行为不变。默认为 "hide"。

  • clip Dict (可选)#

    • x float

      裁剪区域左上角的 x 坐标

    • y float

      裁剪区域左上角的 y 坐标

    • width float

      裁剪区域的宽度

    • height float

      裁剪区域的高度

    指定截图结果裁剪区域的对象。

  • full_page bool (可选)#

    为 true 时，截图整个可滚动页面，而不是当前可见视口。默认为 false。

  • mask List[Locator] (可选)#

    指定截图时需要遮罩的定位器。被遮罩的元素会被一个粉色的盒子 #FF00FF（可通过 mask_color 自定义）完全覆盖其边界框。遮罩也会应用于不可见元素，参见仅匹配可见元素了解如何禁用。

  • mask_color str (可选) v1.35 新增#

    指定遮罩元素覆盖盒子的颜色，使用 CSS 颜色格式。默认颜色为粉色 #FF00FF。

  • omit_background bool (可选)#

    隐藏默认白色背景，允许截图带有透明通道。对 jpeg 图片无效。默认为 false。

  • path Union[str, pathlib.Path] (可选)#

    保存图片的文件路径。截图类型会根据文件扩展名推断。如果 path 是相对路径，则相对于当前工作目录解析。如果未提供路径，则不会保存到磁盘。

  • quality int (可选)#

    图片质量，0-100 之间。对 png 图片无效。

  • scale "css" | "device" (可选)#

    设置为 "css" 时，截图每个 css 像素对应一个像素。对于高分辨率设备，这样截图较小。使用 "device" 选项会每个设备像素对应一个像素，高分辨率设备截图会更大。

    默认为 "device"。

  • style str (可选) v1.41 新增#

    截图时应用的样式表文本。可用于隐藏动态元素、让元素不可见或更改属性，以帮助生成可重复的截图。该样式表会穿透 Shadow DOM 并应用于内嵌 frame。

  • timeout float (可选)#

    最大等待时间（毫秒）。默认为 30000（30 秒）。传入 0 表示不设置超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。

  • type "png" | "jpeg" (可选)#

    指定截图类型，默认为 png。

返回值

set_content​

v1.9 之前添加 page.set_content

该方法内部调用了 document.write()，因此继承了其所有特性和行为。

用法

page.set_content(html)
page.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 内没有网络连接时认为操作完成。不要用此方法做测试，请使用 Web 断言判断页面是否准备好。
    • 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

set_default_navigation_timeout​

v1.9 之前添加 page.set_default_navigation_timeout

该设置会更改以下方法及其相关快捷方式的默认最大导航时间：

备注

page.set_default_navigation_timeout() 的优先级高于 page.set_default_timeout()、browser_context.set_default_timeout() 和 browser_context.set_default_navigation_timeout()。

用法

page.set_default_navigation_timeout(timeout)

参数

  • timeout float#

    最大导航时间（毫秒）

set_default_timeout​

v1.9 之前添加 page.set_default_timeout

该设置会更改所有支持 timeout 选项方法的默认最大超时时间。

备注

page.set_default_navigation_timeout() 的优先级高于 page.set_default_timeout()。

用法

page.set_default_timeout(timeout)

参数

  • timeout float#

    最大超时时间（毫秒）。传入 0 表示不设置超时。

set_extra_http_headers​

v1.9 之前添加 page.set_extra_http_headers

额外的 HTTP 请求头会随着页面发起的每个请求一起发送。

备注

page.set_extra_http_headers() 不保证请求头在请求中的顺序。

用法

page.set_extra_http_headers(headers)

参数

  • headers Dict[str, str]#

    包含要随每个请求发送的额外 HTTP 请求头的对象。所有请求头的值必须为字符串。

返回值

set_viewport_size​

v1.9 之前添加 page.set_viewport_size

在单个浏览器中有多个页面的情况下，每个页面都可以有自己的视口大小。不过，browser.new_context() 允许为上下文中的所有页面统一设置视口大小（以及更多参数）。

page.set_viewport_size() 会调整页面大小。许多网站并不期望手机设备会改变尺寸，因此建议在导航到页面之前设置视口大小。page.set_viewport_size() 也会重置 screen 尺寸，如果需要更精细地控制这些属性，请使用 browser.new_context() 并传递 screen 和 viewport 参数。

用法

page = browser.new_page()
page.set_viewport_size({"width": 640, "height": 480})
page.goto("https://example.com")

参数

  • viewport_size Dict#

    • width int

      页面宽度（像素）。

    • height int

      页面高度（像素）。

返回值

title​

v1.9 之前添加 page.title

返回页面的标题。

用法

page.title()

返回值

unroute​

v1.9 之前添加 page.unroute

移除通过 page.route() 创建的路由。当未指定 handler 时，会移除该 url 的所有路由。

用法

page.unroute(url)
page.unroute(url, **kwargs)

参数

返回值

unroute_all​

v1.41 新增 page.unroute_all

移除通过 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.wait_for_event
备注

大多数情况下，你应该使用 page.expect_event()。

等待指定的 event 事件被触发。如果提供了 predicate，会将事件的值传递给 predicate 函数，并等待 predicate(event) 返回真值。如果页面在事件触发前关闭，则会抛出异常。

用法

page.wait_for_event(event)
page.wait_for_event(event, **kwargs)

参数

  • event str#

    事件名称，通常与传递给 *.on(event) 的名称一致。

  • predicate Callable (可选)#

    接收事件数据，当返回真值时等待结束。

  • timeout float (可选)#

    最大等待时间（毫秒）。默认为 30000（30 秒）。传入 0 表示不设置超时。默认值可通过 browser_context.set_default_timeout() 修改。

返回值

wait_for_function​

v1.9 之前添加 page.wait_for_function

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

如需向 page.wait_for_function() 的谓词函数传递参数：

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

参数

返回值

wait_for_load_state​

v1.9 之前添加 page.wait_for_load_state

当页面达到指定的加载状态时返回。

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

备注

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

用法

page.get_by_role("button").click() # 点击会触发导航
page.wait_for_load_state() # 在 "load" 事件后 promise 解析
with page.expect_popup() as page_info:
    page.get_by_role("button").click() # 点击会弹出新窗口
popup = page_info.value
# 等待 "DOMContentLoaded" 事件
popup.wait_for_load_state("domcontentloaded")
print(popup.title()) # 弹窗页面已可用

参数

返回值

wait_for_url​

v1.11 新增 page.wait_for_url

等待主框架导航到指定的 URL。

用法

page.click("a.delayed-navigation") # 点击链接会间接触发导航
page.wait_for_url("**/target.html")

参数

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

    用于匹配导航时 URL 的 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 内没有网络连接时认为操作完成。不要用此方法做测试，请使用 Web 断言判断页面是否准备好。
    • 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

属性​

clock​

v1.45 新增 page.clock

Playwright 支持模拟时钟和时间流逝。

用法

page.clock

类型

context​

v1.9 之前添加 page.context

获取页面所属的浏览器上下文（BrowserContext）。

用法

page.context

返回值

frames​

v1.9 之前添加 page.frames

返回页面上所有已附加的 frame 的数组。

用法

page.frames

返回值

is_closed​

v1.9 之前添加 page.is_closed

指示页面是否已关闭。

用法

page.is_closed()

返回值

keyboard​

v1.9 之前添加 page.keyboard

用法

page.keyboard

类型

main_frame​

v1.9 之前添加 page.main_frame

页面的主 frame。页面始终保证有一个主 frame，并且在导航过程中会一直存在。

用法

page.main_frame

返回值

mouse​

v1.9 之前添加 page.mouse

用法

page.mouse

类型

request​

v1.16 新增 page.request

与该页面关联的 API 测试辅助对象。该方法返回与页面上下文 browser_context.request 相同的实例。更多详情见 browser_context.request。

用法

page.request

类型

touchscreen​

v1.9 之前添加 page.touchscreen

用法

page.touchscreen

类型

url​

v1.9 之前添加 page.url

用法

page.url

返回值

video​

v1.9 之前添加 page.video

与该页面关联的视频对象。

用法

page.video

返回值

viewport_size​

v1.9 之前添加 page.viewport_size

用法

page.viewport_size

返回值

  • NoneType | Dict#

    • width int

      页面宽度（像素）。

    • height int

      页面高度（像素）。

workers​

v1.9 之前添加 page.workers

该方法返回页面关联的所有专用 WebWorker。

备注

不包含 ServiceWorker

用法

page.workers

返回值

事件​

on("close")​

v1.9 之前添加 page.on("close")

当页面关闭时触发。

用法

page.on("close", handler)

事件数据

on("console")​

v1.9 之前添加 page.on("console")

当页面中的 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' })")

事件数据

on("crash")​

v1.9 之前添加 page.on("crash")

当页面崩溃时触发。如果页面尝试分配过多内存，浏览器页面可能会崩溃。当页面崩溃时，正在进行和后续的操作都会抛出异常。

最常见的处理崩溃方式是捕获异常：

try:
    # 崩溃可能发生在点击期间。
    page.click("button")
    # 或者在等待事件时发生。
    page.wait_for_event("popup")
except Error as e:
    pass
    # 当页面崩溃时，异常信息会包含 "crash"。

用法

page.on("crash", handler)

事件数据

on("dialog")​

v1.9 之前添加 page.on("dialog")

当 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 新增 page.on("domcontentloaded")

当 JavaScript DOMContentLoaded 事件被触发时触发。

用法

page.on("domcontentloaded", handler)

事件数据

on("download")​

v1.9 之前添加 page.on("download")

当附件下载开始时触发。用户可以通过传递的 Download 实例对下载内容进行基本的文件操作。

用法

page.on("download", handler)

事件数据

on("filechooser")​

v1.9 新增 page.on("filechooser")

当文件选择框即将出现时触发，例如点击 <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")

当 frame 被附加到页面时触发。

用法

page.on("frameattached", handler)

事件数据

on("framedetached")​

v1.9 新增 page.on("framedetached")

当 frame 从页面分离时触发。

用法

page.on("framedetached", handler)

事件数据

on("framenavigated")​

v1.9 新增 page.on("framenavigated")

当某个 frame 导航到新 URL 时触发。

用法

page.on("framenavigated", handler)

事件数据

on("load")​

v1.9 之前添加 page.on("load")

当 JavaScript load 事件被触发时触发。

用法

page.on("load", handler)

事件数据

on("pageerror")​

v1.9 新增 page.on("pageerror")

当页面内发生未捕获异常时触发。

# 将所有未捕获的异常打印到终端
page.on("pageerror", lambda exc: print(f"未捕获异常: {exc}"))

# 跳转到一个会抛出异常的页面
page.goto("data:text/html,<script>throw new Error('test')</script>")

用法

page.on("pageerror", handler)

事件数据

on("popup")​

v1.9 之前添加 page.on("popup")

当页面打开新标签页或新窗口时触发。该事件除了会在 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"))
备注

使用 page.wait_for_load_state() 等待页面达到特定状态（大多数情况下无需手动调用）。

用法

page.on("popup", handler)

事件数据

on("request")​

v1.9 之前添加 page.on("request")

当页面发起请求时触发。request 对象是只读的。如需拦截和修改请求，请参见 page.route() 或 browser_context.route()。

用法

page.on("request", handler)

事件数据

on("requestfailed")​

v1.9 新增 page.on("requestfailed")

当请求失败时触发，例如超时。

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 新增 page.on("requestfinished")

当请求成功完成并下载响应体后触发。对于成功的响应，事件顺序为 request、response 和 requestfinished。

用法

page.on("requestfinished", handler)

事件数据

on("response")​

v1.9 之前添加 page.on("response")

当收到请求的 response 状态和响应头时触发。对于成功的响应，事件顺序为 request、response 和 requestfinished。

用法

page.on("response", handler)

事件数据

on("websocket")​

v1.9 新增 page.on("websocket")

当页面发起 WebSocket 请求时触发。

用法

page.on("websocket", handler)

事件数据

on("worker")​

v1.9 之前添加 page.on("worker")

当页面创建专用 WebWorker 时触发。

用法

page.on("worker", handler)

事件数据

已废弃​

accessibility​

v1.9 之前添加 page.accessibility
已废弃

该属性已不推荐使用。如果需要测试页面可访问性，请使用 Axe 等其他库。关于与 Axe 的集成可参考我们的 Node.js 指南。

用法

page.accessibility

类型

check​

v1.9 之前添加 page.check
不推荐

请使用基于定位器的 locator.check()。阅读更多关于定位器的内容。

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

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

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

用法

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

参数

  • selector str#

    用于查找元素的选择器。如果有多个元素满足选择器，将使用第一个。

  • force bool (可选)#

    是否跳过actionability 检查。默认为 false。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选) v1.11 新增#

    相对于元素内边距盒子左上角的点。如果未指定，则使用元素的某个可见点。

  • 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。可用于等待元素准备好操作但不实际执行。

返回值

click​

v1.9 之前添加 page.click
不推荐

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

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

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

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

用法

page.click(selector)
page.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 (可选)#

    相对于元素内边距盒子左上角的点。如果未指定，则使用元素的某个可见点。

  • 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 都会被按下，以便测试只有在这些键按下时才可见的元素。

返回值

dblclick​

v1.9 之前添加 page.dblclick
不推荐

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

该方法通过以下步骤对与 selector 匹配的元素执行双击操作：

  1. 查找与 selector 匹配的元素。如果没有，则等待直到有匹配的元素被添加到 DOM。
  2. 对匹配的元素执行actionability 检查，除非设置了 force 选项。如果元素在检查期间被移除，整个操作会重试。
  3. 如有需要，将元素滚动到可视区域。
  4. 使用 page.mouse 在元素中心或指定的 position 位置执行双击。

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

备注

page.dblclick() 会触发两次 click 事件和一次 dblclick 事件。

用法

page.dblclick(selector)
page.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 (可选)#

    相对于元素内边距盒子左上角的点。如果未指定，则使用元素的某个可见点。

  • 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 都会被按下，以便测试只有在这些键按下时才可见的元素。

返回值

dispatch_event​

v1.9 之前添加 page.dispatch_event
不推荐

请使用基于定位器的 locator.dispatch_event()。阅读更多关于定位器。

下面的示例会在元素上派发 click 事件。无论元素是否可见，都会派发 click 事件。这等价于调用 element.click()。

用法

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

底层会根据指定的 type 创建事件实例，并用 event_init 属性初始化，然后在元素上派发该事件。事件默认是 composed、cancelable 并且会冒泡。

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

你也可以将 JSHandle 作为属性值传递，如果你希望将实时对象传递到事件中：

# 注意，只有在 chromium 和 firefox 下才能创建 data_transfer
data_transfer = page.evaluate_handle("new DataTransfer()")
page.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() 方法修改。

返回值

eval_on_selector​

v1.9 新增 page.eval_on_selector
不推荐

该方法不会等待元素通过可操作性检查，因此可能导致测试不稳定。请优先使用 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")

参数

  • selector str#

    用于查询的选择器。

  • expression str#

    要在浏览器上下文中执行的 JavaScript 表达式。如果表达式为函数，则会自动调用该函数。

  • arg EvaluationArgument (可选)#

    传递给 expression 的可选参数。

  • strict bool (可选) v1.14 新增#

    为 true 时，要求选择器只能匹配一个元素。如果选择器匹配多个元素，则会抛出异常。

返回值

eval_on_selector_all​

v1.9 新增 page.eval_on_selector_all
不推荐

大多数情况下，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)

参数

  • selector str#

    用于查询的选择器。

  • expression str#

    要在浏览器上下文中执行的 JavaScript 表达式。如果表达式为函数，则会自动调用该函数。

  • arg EvaluationArgument (可选)#

    传递给 expression 的可选参数。

返回值

expect_navigation​

v1.9 之前添加 page.expect_navigation
已废弃

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

等待主框架导航，并返回主资源的响应。如果发生多次重定向，导航会返回最后一次重定向的响应。如果只是锚点跳转或通过 History API 导航，则会返回 null。

用法

当页面跳转到新 URL 或重新加载时，该方法会解析。适用于你执行的代码会间接导致页面导航的场景。例如，点击目标有一个 onclick 处理器，通过 setTimeout 触发导航。如下示例：

with page.expect_navigation():
    # 此操作会在超时后触发导航
    page.get_by_text("Navigate after timeout").click()
# 导航完成后解析
备注

使用 History API 修改 URL 也会被视为一次导航。

参数

  • timeout float (可选)#

    最大操作时间（毫秒），默认为 30 秒，传入 0 表示不设置超时。默认值可通过 browser_context.set_default_navigation_timeout()、browser_context.set_default_timeout()、page.set_default_navigation_timeout() 或 page.set_default_timeout() 方法修改。

  • url str | Pattern | Callable[URL]:bool (可选)#

    用于匹配导航时 URL 的 glob 模式、正则表达式或接收 URL 的谓词函数。注意，如果参数是没有通配符的字符串，则方法会等待导航到与该字符串完全相等的 URL。

  • wait_until "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#

    何时认为操作成功，默认为 load。事件可以是：

    • 'domcontentloaded' - 当触发 DOMContentLoaded 事件时认为操作完成。
    • 'load' - 当触发 load 事件时认为操作完成。
    • 'networkidle' - 不推荐，当至少 500ms 内没有网络连接时认为操作完成。不要用此方法做测试，请使用 Web 断言判断页面是否准备好。
    • 'commit' - 当收到网络响应且文档开始加载时认为操作完成。

返回值

fill​

v1.9 之前添加 page.fill
不推荐

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

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

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

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

用法

page.fill(selector, value)
page.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() 方法修改。

返回值

focus​

v1.9 之前添加 page.focus
不推荐

请使用基于定位器的 locator.focus()。阅读更多关于定位器。

该方法会查找与 selector 匹配的元素并聚焦。如果没有匹配的元素，则会等待直到有匹配的元素出现在 DOM 中。

用法

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

参数

  • selector str#

    用于查找元素的选择器。如果有多个元素满足选择器，将使用第一个。

  • strict bool (可选) v1.14 新增#

    为 true 时，要求选择器只能匹配一个元素。如果选择器匹配多个元素，则会抛出异常。

  • timeout float (可选)#

    最大等待时间（毫秒）。默认为 30000（30 秒）。传入 0 表示不设置超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。

返回值

get_attribute​

v1.9 之前添加 page.get_attribute
不推荐

请使用基于定位器的 locator.get_attribute()。阅读更多关于定位器。

返回元素的属性值。

用法

page.get_attribute(selector, name)
page.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() 方法修改。

返回值

hover​

v1.9 之前添加 page.hover
不推荐

请使用基于定位器的 locator.hover()。阅读更多关于定位器。

该方法通过以下步骤悬停在与 selector 匹配的元素上：

  1. 查找与 selector 匹配的元素。如果没有，则等待直到有匹配的元素被添加到 DOM。
  2. 对匹配的元素执行actionability 检查，除非设置了 force 选项。如果元素在检查期间被移除，整个操作会重试。
  3. 如有需要，将元素滚动到可视区域。
  4. 使用 page.mouse 在元素中心或指定的 position 位置悬停。

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

用法

page.hover(selector)
page.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 (可选)#

    相对于元素内边距盒子左上角的点。如果未指定，则使用元素的某个可见点。

  • 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 都会被按下，以便测试只有在这些键按下时才可见的元素。

返回值

inner_html​

v1.9 之前添加 page.inner_html
不推荐

请使用基于定位器的 locator.inner_html()。阅读更多关于定位器。

返回 element.innerHTML。

用法

page.inner_html(selector)
page.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() 方法修改。

返回值

inner_text​

v1.9 之前添加 page.inner_text
不推荐

请使用基于定位器的 locator.inner_text()。阅读更多关于定位器。

返回 element.innerText。

用法

page.inner_text(selector)
page.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() 方法修改。

返回值

input_value​

v1.13 新增 page.input_value
不推荐

请使用基于定位器的 locator.input_value()。阅读更多关于定位器。

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

如果元素不是输入元素会抛出异常。但如果该元素在带有关联 control 的 <label> 元素内，则返回控件的值。

用法

page.input_value(selector)
page.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() 方法修改。

返回值

is_checked​

v1.9 之前添加 page.is_checked
不推荐

请使用基于定位器的 locator.is_checked()。阅读更多关于定位器。

返回元素是否被选中。如果元素不是复选框或单选框会抛出异常。

用法

page.is_checked(selector)
page.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() 方法修改。

返回值

is_disabled​

v1.9 之前添加 page.is_disabled
不推荐

请使用基于定位器的 locator.is_disabled()。阅读更多关于定位器。

返回元素是否为禁用状态，与 enabled 相反。

用法

page.is_disabled(selector)
page.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() 方法修改。

返回值

is_editable​

v1.9 之前添加 page.is_editable
不推荐

请使用基于定位器的 locator.is_editable()。阅读更多关于定位器。

返回元素是否为 可编辑 状态。

用法

page.is_editable(selector)
page.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() 方法修改。

返回值

is_enabled​

v1.9 之前添加 page.is_enabled
不推荐

请使用基于定位器的 locator.is_enabled()。阅读更多关于定位器。

返回元素是否为 启用 状态。

用法

page.is_enabled(selector)
page.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() 方法修改。

返回值

is_hidden​

v1.9 之前添加 page.is_hidden
不推荐

请使用基于定位器的 locator.is_hidden()。阅读更多关于定位器。

返回元素是否为隐藏状态，与 visible 相反。如果 selector 没有匹配到任何元素，则视为隐藏。

用法

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

参数

  • selector str#

    用于查找元素的选择器。如果有多个元素满足选择器，将使用第一个。

  • strict bool (可选) v1.14 新增#

    为 true 时，要求选择器只能匹配一个元素。如果选择器匹配多个元素，则会抛出异常。

  • timeout float (可选)#

    已废弃

    此选项无效。page.is_hidden() 不会等待元素变为隐藏，会立即返回。

返回值

is_visible​

v1.9 之前添加 page.is_visible
不推荐

请使用基于定位器的 locator.is_visible()。阅读更多关于定位器。

返回元素是否为 可见 状态。如果 selector 没有匹配到任何元素，则视为不可见。

用法

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

参数

  • selector str#

    用于查找元素的选择器。如果有多个元素满足选择器，将使用第一个。

  • strict bool (可选) v1.14 新增#

    为 true 时，要求选择器只能匹配一个元素。如果选择器匹配多个元素，则会抛出异常。

  • timeout float (可选)#

    已废弃

    此选项无效。page.is_visible() 不会等待元素变为可见，会立即返回。

返回值

press​

v1.9 之前添加 page.press
不推荐

请使用基于定位器的 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()

参数

  • 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() 方法修改。

返回值

query_selector​

v1.9 新增 page.query_selector
不推荐

请使用基于定位器的 page.locator()。阅读更多关于定位器。

该方法会在页面中查找与指定选择器匹配的第一个元素。如果没有元素匹配选择器，则返回值为 null。如需等待页面上出现元素，请使用 locator.wait_for()。

用法

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

参数

  • selector str#

    用于查询的选择器。

  • strict bool (可选) v1.14 新增#

    为 true 时，要求选择器只能匹配一个元素。如果选择器匹配多个元素，则会抛出异常。

返回值

query_selector_all​

v1.9 新增 page.query_selector_all
不推荐

请使用基于定位器的 page.locator()。阅读更多关于定位器。

该方法会在页面中查找所有与指定选择器匹配的元素。如果没有元素匹配选择器，则返回值为 []。

用法

page.query_selector_all(selector)

参数

  • selector str#

    用于查询的选择器。

返回值

select_option​

v1.9 之前添加 page.select_option
不推荐

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

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

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

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

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

用法

# 单选，匹配 value 或 label
page.select_option("select#colors", "blue")
# 单选，匹配 label
page.select_option("select#colors", label="blue")
# 多选
page.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 属性，则会选择所有给定的选项，否则只选择第一个匹配的选项。可选。

返回值

set_checked​

v1.15 新增 page.set_checked
不推荐

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

该方法会通过以下步骤勾选或取消勾选与 selector 匹配的元素：

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

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

用法

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

参数

  • selector str#

    用于查找元素的选择器。如果有多个元素满足选择器，将使用第一个。

  • checked bool#

    是否勾选该复选框。

  • force bool (可选)#

    是否跳过actionability 检查。默认为 false。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选)#

    相对于元素内边距盒子左上角的点。如果未指定，则使用元素的某个可见点。

  • strict bool (可选)#

    为 true 时，要求选择器只能匹配一个元素。如果选择器匹配多个元素，则会抛出异常。

  • timeout float (可选)#

    最大等待时间（毫秒）。默认为 30000（30 秒）。传入 0 表示不设置超时。默认值可通过 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法修改。

  • trial bool (可选)#

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

返回值

set_input_files​

v1.9 之前添加 page.set_input_files
不推荐

请使用基于定位器的 locator.set_input_files()。阅读更多关于定位器。

将文件输入框的值设置为指定的文件路径或文件。如果 filePaths 中有相对路径，则会相对于当前工作目录进行解析。传入空数组会清空已选择的文件。对于带有 [webkitdirectory] 属性的输入框，仅支持单个目录路径。

该方法要求 selector 指向一个 input 元素。但如果该元素在带有关联 control 的 <label> 元素内，则会操作该控件。

用法

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

参数

返回值

tap​

v1.9 之前添加 page.tap
不推荐

请使用基于定位器的 locator.tap()。阅读更多关于定位器。

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

  1. 查找与 selector 匹配的元素。如果没有，则等待直到有匹配的元素被添加到 DOM。
  2. 对匹配的元素执行actionability 检查，除非设置了 force 选项。如果元素在检查期间被移除，整个操作会重试。
  3. 如有需要，将元素滚动到可视区域。
  4. 使用 page.touchscreen 在元素中心或指定的 position 位置点击。

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

备注

如果浏览器上下文的 has_touch 选项为 false，则调用 page.tap() 方法会抛出异常。

用法

page.tap(selector)
page.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 (可选)#

    相对于元素内边距盒子左上角的点。如果未指定，则使用元素的某个可见点。

  • 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 都会被按下，以便测试只有在这些键按下时才可见的元素。

返回值

text_content​

v1.9 之前添加 page.text_content
不推荐

请使用基于定位器的 locator.text_content()。阅读更多关于定位器。

返回 element.textContent。

用法

page.text_content(selector)
page.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() 方法修改。

返回值

type​

v1.9 之前添加 page.type
已废弃

大多数情况下建议使用 locator.fill()。只有在页面有特殊键盘处理时才需要逐个按键输入——此时请使用 locator.press_sequentially()。

会为文本中的每个字符发送一次 keydown、keypress/input 和 keyup 事件。page.type 可用于发送细粒度的键盘事件。要在表单字段中填充值，请使用 page.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() 方法修改。

返回值

uncheck​

v1.9 之前添加 page.uncheck
不推荐

请使用基于定位器的 locator.uncheck()。阅读更多关于定位器。

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

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

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

用法

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

参数

  • selector str#

    用于查找元素的选择器。如果有多个元素满足选择器，将使用第一个。

  • force bool (可选)#

    是否跳过actionability 检查。默认为 false。

  • no_wait_after bool (可选)#

    已废弃

    此选项无效。

    此选项无效。

  • position Dict (可选) v1.11 新增#

    相对于元素内边距盒子左上角的点。如果未指定，则使用元素的某个可见点。

  • 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。可用于等待元素准备好操作但不实际执行。

返回值

wait_for_selector​

v1.9 之前添加 page.wait_for_selector
不推荐

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

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

备注

Playwright 会在执行操作前自动等待元素就绪。使用 Locator 对象和 web 优先断言可以让代码无需使用 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.wait_for_selector("img")
        print("已加载图片: " + str(element.get_attribute("src")))
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

参数

  • 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() 方法修改。

返回值

wait_for_timeout​

v1.9 之前添加 page.wait_for_timeout
不推荐

生产环境下不要使用超时等待。依赖时间等待的测试本质上不稳定。请使用 Locator 操作和自动等待的 web 断言。

等待指定的 timeout 毫秒。

注意，page.waitForTimeout() 只应在调试时使用。在生产环境中使用定时器的测试会变得不稳定。请使用如网络事件、选择器变为可见等信号来替代。

用法

# 等待 1 秒
page.wait_for_timeout(1000)

参数

  • timeout float#

    要等待的超时时间

返回值