原生 Page

原生 API 目录 · 手册目录

方法与属性索引

• add_init_script
• add_locator_handler
• add_script_tag
• add_style_tag
• aria_snapshot
• bring_to_front
• cancel_pick_locator
• check
• clear_console_messages
• clear_page_errors
• click
• clock
• close
• console_messages
• content
• context
• dblclick
• dispatch_event
• drag_and_drop
• emulate_media
• eval_on_selector
• eval_on_selector_all
• evaluate
• evaluate_handle
• expect_console_message
• expect_download
• expect_event
• expect_file_chooser
• expect_navigation
• expect_popup
• expect_request
• expect_request_finished
• expect_response
• expect_websocket
• expect_worker
• expose_binding
• expose_function
• fill
• focus
• frame
• frame_locator
• frames
• get_attribute
• get_by_alt_text
• get_by_label
• get_by_placeholder
• get_by_ref
• get_by_role
• get_by_test_id
• get_by_text
• get_by_title
• go_back
• go_forward
• goto
• hide_highlight
• hover
• inner_html
• inner_text
• input_value
• is_checked
• is_closed
• is_disabled
• is_editable
• is_enabled
• is_hidden
• is_visible
• keyboard
• local_storage
• locator
• main_frame
• mouse
• on
• once
• opener
• page_errors
• pause
• pdf
• pick_locator
• press
• query_selector
• query_selector_all
• reload
• remove_listener
• remove_locator_handler
• request
• request_gc
• requests
• route
• route_from_har
• route_web_socket
• screencast
• screenshot
• select_option
• session_storage
• set_checked
• set_content
• set_default_navigation_timeout
• set_default_timeout
• set_extra_http_headers
• set_input_files
• set_viewport_size
• tap
• text_content
• title
• touchscreen
• type
• uncheck
• unroute
• unroute_all
• url
• video
• viewport_size
• wait_for_event
• wait_for_function
• wait_for_load_state
• wait_for_selector
• wait_for_timeout
• wait_for_url
• webmcp
• workers

add_init_script

同步

def add_init_script(self, script: Optional[str] = None, *, path: Union[pathlib.Path, str, NoneType] = None) -> 'SyncContextManager'

Page.add_init_script

Adds a script which would be evaluated in one of the following scenarios:

• Whenever the page is navigated.
• Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame.

The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed Math.random.

Usage

An example of overriding Math.random before the page loads:

# in your playwright script, assuming the preload.js file is in same directory
page.add_init_script(path="./preload.js")

NOTE The order of evaluation of multiple scripts installed via browser_context.add_init_script() and page.add_init_script() is not defined.

Parameters

Returns

SyncContextManager

异步

async def add_init_script(self, script: Optional[str] = None, *, path: Union[pathlib.Path, str, NoneType] = None) -> 'AsyncContextManager'

Page.add_init_script

Adds a script which would be evaluated in one of the following scenarios:

• Whenever the page is navigated.
• Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame.

The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed Math.random.

Usage

An example of overriding Math.random before the page loads:

# in your playwright script, assuming the preload.js file is in same directory
await page.add_init_script(path="./preload.js")

NOTE The order of evaluation of multiple scripts installed via browser_context.add_init_script() and page.add_init_script() is not defined.

Parameters

Returns

AsyncContextManager

add_locator_handler

同步

def add_locator_handler(self, locator: 'Locator', handler: Union[Callable[[ForwardRef('Locator')], Any], Callable[[], Any]], *, no_wait_after: Optional[bool] = None, times: Optional[int] = None) -> None

Page.add_locator_handler

When testing a web page, sometimes unexpected overlays like a "Sign up" dialog appear and block actions you want to automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, making them tricky to handle in automated tests.

This method lets you set up a special function, called a handler, that activates when it detects that overlay is visible. The handler's job is to remove the overlay, allowing your test to continue as if the overlay wasn't there.

Things to keep in mind:

• When an overlay is shown predictably, we recommend explicitly waiting for it in your test and dismissing it as a part of your normal test flow, instead of using page.add_locator_handler().
• Playwright checks for the overlay every time before executing or retrying an action that requires an actionability check, or before performing an auto-waiting assertion check. When overlay is visible, Playwright calls the handler first, and then proceeds with the action/assertion. Note that the handler is only called when you perform an action/assertion - if the overlay becomes visible but you don't perform any actions, the handler will not be triggered.
• After executing the handler, Playwright will ensure that overlay that triggered the handler is not visible anymore. You can opt-out of this behavior with no_wait_after.
• The execution time of the handler counts towards the timeout of the action/assertion that executed the handler. If your handler takes too long, it might cause timeouts.
• You can register multiple handlers. However, only a single handler will be running at a time. Make sure the actions within a handler don't depend on another handler.

NOTE Running the handler will alter your page state mid-test. For example it will change the currently focused element and move the mouse. Make sure that actions that run after the handler are self-contained and do not rely on the focus and mouse state being unchanged.

For example, consider a test that calls locator.focus() followed by keyboard.press(). If your handler clicks a button between these two actions, the focused element most likely will be wrong, and key press will happen on the unexpected element. Use locator.press() instead to avoid this problem.

Another example is a series of mouse actions, where mouse.move() is followed by mouse.down(). Again, when the handler runs between these two actions, the mouse position will be wrong during the mouse down. Prefer self-contained actions like locator.click() that do not rely on the state being unchanged by a handler.

Usage

An example that closes a "Sign up to the newsletter" dialog when it appears:

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

An example that skips the "Confirm your security details" page when it is shown:

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

An example with a custom callback on every actionability check. It uses a <body> locator that is always visible, so the handler is called before every actionability check. It is important to specify no_wait_after, because the handler does not hide the <body> element.

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

Handler takes the original locator as an argument. You can also automatically remove the handler after a number of invocations by setting times:

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

Parameters

异步

async def add_locator_handler(self, locator: 'Locator', handler: Union[Callable[[ForwardRef('Locator')], Any], Callable[[], Any]], *, no_wait_after: Optional[bool] = None, times: Optional[int] = None) -> None

Page.add_locator_handler

When testing a web page, sometimes unexpected overlays like a "Sign up" dialog appear and block actions you want to automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, making them tricky to handle in automated tests.

This method lets you set up a special function, called a handler, that activates when it detects that overlay is visible. The handler's job is to remove the overlay, allowing your test to continue as if the overlay wasn't there.

Things to keep in mind:

• When an overlay is shown predictably, we recommend explicitly waiting for it in your test and dismissing it as a part of your normal test flow, instead of using page.add_locator_handler().
• Playwright checks for the overlay every time before executing or retrying an action that requires an actionability check, or before performing an auto-waiting assertion check. When overlay is visible, Playwright calls the handler first, and then proceeds with the action/assertion. Note that the handler is only called when you perform an action/assertion - if the overlay becomes visible but you don't perform any actions, the handler will not be triggered.
• After executing the handler, Playwright will ensure that overlay that triggered the handler is not visible anymore. You can opt-out of this behavior with no_wait_after.
• The execution time of the handler counts towards the timeout of the action/assertion that executed the handler. If your handler takes too long, it might cause timeouts.
• You can register multiple handlers. However, only a single handler will be running at a time. Make sure the actions within a handler don't depend on another handler.

NOTE Running the handler will alter your page state mid-test. For example it will change the currently focused element and move the mouse. Make sure that actions that run after the handler are self-contained and do not rely on the focus and mouse state being unchanged.

For example, consider a test that calls locator.focus() followed by keyboard.press(). If your handler clicks a button between these two actions, the focused element most likely will be wrong, and key press will happen on the unexpected element. Use locator.press() instead to avoid this problem.

Another example is a series of mouse actions, where mouse.move() is followed by mouse.down(). Again, when the handler runs between these two actions, the mouse position will be wrong during the mouse down. Prefer self-contained actions like locator.click() that do not rely on the state being unchanged by a handler.

Usage

An example that closes a "Sign up to the newsletter" dialog when it appears:

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

An example that skips the "Confirm your security details" page when it is shown:

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

An example with a custom callback on every actionability check. It uses a <body> locator that is always visible, so the handler is called before every actionability check. It is important to specify no_wait_after, because the handler does not hide the <body> element.

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

Handler takes the original locator as an argument. You can also automatically remove the handler after a number of invocations by setting times:

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

Parameters

add_script_tag

同步

def add_script_tag(self, *, content: Optional[str] = None, path: Union[pathlib.Path, str, NoneType] = None, type: Optional[str] = None, url: Optional[str] = None) -> 'ElementHandle'

Page.add_script_tag

Adds a <script> tag into the page with the desired url or content. Returns the added tag when the script's onload fires or when the script content was injected into frame.

Parameters

Returns

ElementHandle

异步

async def add_script_tag(self, *, content: Optional[str] = None, path: Union[pathlib.Path, str, NoneType] = None, type: Optional[str] = None, url: Optional[str] = None) -> 'ElementHandle'

Page.add_script_tag

Adds a <script> tag into the page with the desired url or content. Returns the added tag when the script's onload fires or when the script content was injected into frame.

Parameters

Returns

ElementHandle

add_style_tag

同步

def add_style_tag(self, *, content: Optional[str] = None, path: Union[pathlib.Path, str, NoneType] = None, url: Optional[str] = None) -> 'ElementHandle'

Page.add_style_tag

Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.

Parameters

Returns

ElementHandle

异步

async def add_style_tag(self, *, content: Optional[str] = None, path: Union[pathlib.Path, str, NoneType] = None, url: Optional[str] = None) -> 'ElementHandle'

Page.add_style_tag

Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.

Parameters

Returns

ElementHandle

aria_snapshot

同步

def aria_snapshot(self, *, boxes: Optional[bool] = None, depth: Optional[int] = None, mode: Optional[Literal['ai', 'default']] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> str

Page.aria_snapshot

Captures the aria snapshot of the page. Read more about aria snapshots.

Parameters

Returns

str

异步

async def aria_snapshot(self, *, boxes: Optional[bool] = None, depth: Optional[int] = None, mode: Optional[Literal['ai', 'default']] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> str

Page.aria_snapshot

Captures the aria snapshot of the page. Read more about aria snapshots.

Parameters

Returns

str

bring_to_front

同步

def bring_to_front(self) -> None

Page.bring_to_front

Brings page to front (activates tab).

异步

async def bring_to_front(self) -> None

Page.bring_to_front

Brings page to front (activates tab).

cancel_pick_locator

同步

def cancel_pick_locator(self) -> None

Page.cancel_pick_locator

Cancels an ongoing page.pick_locator() call by deactivating pick locator mode. If no pick locator mode is active, this method is a no-op.

异步

async def cancel_pick_locator(self) -> None

Page.cancel_pick_locator

Cancels an ongoing page.pick_locator() call by deactivating pick locator mode. If no pick locator mode is active, this method is a no-op.

check

同步

def check(self, selector: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Page.check

This method checks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
3. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
4. Scroll the element into view if needed.
5. Use page.mouse to click in the center of the element.
6. Ensure that the element is now checked. If not, this method throws.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

异步

async def check(self, selector: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Page.check

This method checks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
3. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
4. Scroll the element into view if needed.
5. Use page.mouse to click in the center of the element.
6. Ensure that the element is now checked. If not, this method throws.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

clear_console_messages

同步

def clear_console_messages(self) -> None

Page.clear_console_messages

Clears all stored console messages from this page. Subsequent calls to page.console_messages() will only return messages logged after the clear.

异步

async def clear_console_messages(self) -> None

Page.clear_console_messages

Clears all stored console messages from this page. Subsequent calls to page.console_messages() will only return messages logged after the clear.

clear_page_errors

同步

def clear_page_errors(self) -> None

Page.clear_page_errors

Clears all stored page errors from this page. Subsequent calls to page.page_errors() will only return errors thrown after the clear.

异步

async def clear_page_errors(self) -> None

Page.clear_page_errors

Clears all stored page errors from this page. Subsequent calls to page.page_errors() will only return errors thrown after the clear.

click

同步

def click(self, selector: str, *, button: Optional[Literal['left', 'middle', 'right']] = None, click_count: Optional[int] = None, delay: Optional[float] = None, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Page.click

This method clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to click in the center of the element, or the specified position.
5. Wait for initiated navigations to either succeed or fail, unless no_wait_after option is set.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

异步

async def click(self, selector: str, *, button: Optional[Literal['left', 'middle', 'right']] = None, click_count: Optional[int] = None, delay: Optional[float] = None, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Page.click

This method clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to click in the center of the element, or the specified position.
5. Wait for initiated navigations to either succeed or fail, unless no_wait_after option is set.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

clock

属性，直接读取；异步入口也不加 await。

Page.clock: Clock

Page.clock

Playwright has ability to mock clock and passage of time.

Returns

Clock

close

同步

def close(self, *, reason: Optional[str] = None, run_before_unload: Optional[bool] = None) -> None

Page.close

If run_before_unload is false, does not run any unload handlers and waits for the page to be closed. If run_before_unload is true the method will run unload handlers, but will not wait for the page to close.

By default, page.close() does not run beforeunload handlers.

NOTE if run_before_unload is passed as true, a beforeunload dialog might be summoned and should be handled manually via page.on('dialog') event.

Parameters

异步

async def close(self, *, reason: Optional[str] = None, run_before_unload: Optional[bool] = None) -> None

Page.close

If run_before_unload is false, does not run any unload handlers and waits for the page to be closed. If run_before_unload is true the method will run unload handlers, but will not wait for the page to close.

By default, page.close() does not run beforeunload handlers.

NOTE if run_before_unload is passed as true, a beforeunload dialog might be summoned and should be handled manually via page.on('dialog') event.

Parameters

console_messages

同步

def console_messages(self, *, filter: Optional[Literal['all', 'since-navigation']] = None) -> List[ForwardRef('ConsoleMessage')]

Page.console_messages

Returns up to (currently) 200 last console messages from this page. See page.on('console') for more details.

Parameters

Returns

List[ConsoleMessage]

异步

async def console_messages(self, *, filter: Optional[Literal['all', 'since-navigation']] = None) -> List[ForwardRef('ConsoleMessage')]

Page.console_messages

Returns up to (currently) 200 last console messages from this page. See page.on('console') for more details.

Parameters

Returns

List[ConsoleMessage]

content

同步

def content(self, *, include_shadow: Optional[bool] = None) -> str

Page.content

Gets the full HTML contents of the page, including the doctype.

Parameters

Returns

str

异步

async def content(self, *, include_shadow: Optional[bool] = None) -> str

Page.content

Gets the full HTML contents of the page, including the doctype.

Parameters

Returns

str

context

属性，直接读取；异步入口也不加 await。

Page.context: BrowserContext

Page.context

Get the browser context that the page belongs to.

Returns

BrowserContext

dblclick

同步

def dblclick(self, selector: str, *, button: Optional[Literal['left', 'middle', 'right']] = None, delay: Optional[float] = None, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Page.dblclick

This method double clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to double click in the center of the element, or the specified position.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

NOTE page.dblclick() dispatches two click events and a single dblclick event.

Parameters

异步

async def dblclick(self, selector: str, *, button: Optional[Literal['left', 'middle', 'right']] = None, delay: Optional[float] = None, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Page.dblclick

This method double clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to double click in the center of the element, or the specified position.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

NOTE page.dblclick() dispatches two click events and a single dblclick event.

Parameters

dispatch_event

同步

def dispatch_event(self, selector: str, type: str, event_init: Optional[Dict] = None, *, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Page.dispatch_event

The snippet below dispatches the click event on the element. Regardless of the visibility state of the element, click is dispatched. This is equivalent to calling element.click().

Usage

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

Under the hood, it creates an instance of an event based on the given type, initializes it with event_init properties and dispatches it on the element. Events are composed, cancelable and bubble by default.

Since event_init is event-specific, please refer to the events documentation for the lists of initial properties:

• DeviceMotionEvent
• DeviceOrientationEvent
• DragEvent
• Event
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• WheelEvent

You can also specify JSHandle as the property value if you want live objects to be passed into the event:

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

Parameters

异步

async def dispatch_event(self, selector: str, type: str, event_init: Optional[Dict] = None, *, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Page.dispatch_event

The snippet below dispatches the click event on the element. Regardless of the visibility state of the element, click is dispatched. This is equivalent to calling element.click().

Usage

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

Under the hood, it creates an instance of an event based on the given type, initializes it with event_init properties and dispatches it on the element. Events are composed, cancelable and bubble by default.

Since event_init is event-specific, please refer to the events documentation for the lists of initial properties:

• DeviceMotionEvent
• DeviceOrientationEvent
• DragEvent
• Event
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• WheelEvent

You can also specify JSHandle as the property value if you want live objects to be passed into the event:

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

Parameters

drag_and_drop

同步

def drag_and_drop(self, source: str, target: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, scroll: Optional[Literal['auto', 'none']] = None, source_position: Optional[patchright._impl._api_structures.Position] = None, steps: Optional[int] = None, strict: Optional[bool] = None, target_position: Optional[patchright._impl._api_structures.Position] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Page.drag_and_drop

This method drags the source element to the target element. It will first move to the source element, perform a mousedown, then move to the target element and perform a mouseup.

Usage

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

Parameters

异步

async def drag_and_drop(self, source: str, target: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, scroll: Optional[Literal['auto', 'none']] = None, source_position: Optional[patchright._impl._api_structures.Position] = None, steps: Optional[int] = None, strict: Optional[bool] = None, target_position: Optional[patchright._impl._api_structures.Position] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Page.drag_and_drop

This method drags the source element to the target element. It will first move to the source element, perform a mousedown, then move to the target element and perform a mouseup.

Usage

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

Parameters

emulate_media

同步

def emulate_media(self, *, color_scheme: Optional[Literal['dark', 'light', 'no-preference', 'null']] = None, contrast: Optional[Literal['more', 'no-preference', 'null']] = None, forced_colors: Optional[Literal['active', 'none', 'null']] = None, media: Optional[Literal['null', 'print', 'screen']] = None, reduced_motion: Optional[Literal['no-preference', 'null', 'reduce']] = None) -> None

Page.emulate_media

This method changes the CSS media type through the media argument, and/or the 'prefers-colors-scheme' media feature, using the colorScheme argument.

Usage

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

Parameters

异步

async def emulate_media(self, *, color_scheme: Optional[Literal['dark', 'light', 'no-preference', 'null']] = None, contrast: Optional[Literal['more', 'no-preference', 'null']] = None, forced_colors: Optional[Literal['active', 'none', 'null']] = None, media: Optional[Literal['null', 'print', 'screen']] = None, reduced_motion: Optional[Literal['no-preference', 'null', 'reduce']] = None) -> None

Page.emulate_media

This method changes the CSS media type through the media argument, and/or the 'prefers-colors-scheme' media feature, using the colorScheme argument.

Usage

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

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

Parameters

eval_on_selector

同步

def eval_on_selector(self, selector: str, expression: str, arg: Optional[Any] = None, *, strict: Optional[bool] = None) -> Any

Page.eval_on_selector

The method finds an element matching the specified selector within the page and passes it as a first argument to expression. If no elements match the selector, the method throws an error. Returns the value of expression.

If expression returns a [Promise], then page.eval_on_selector() would wait for the promise to resolve and return its value.

Usage

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

Parameters

Returns

Any

异步

async def eval_on_selector(self, selector: str, expression: str, arg: Optional[Any] = None, *, strict: Optional[bool] = None) -> Any

Page.eval_on_selector

The method finds an element matching the specified selector within the page and passes it as a first argument to expression. If no elements match the selector, the method throws an error. Returns the value of expression.

If expression returns a [Promise], then page.eval_on_selector() would wait for the promise to resolve and return its value.

Usage

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

Parameters

Returns

Any

eval_on_selector_all

同步

def eval_on_selector_all(self, selector: str, expression: str, arg: Optional[Any] = None) -> Any

Page.eval_on_selector_all

The method finds all elements matching the specified selector within the page and passes an array of matched elements as a first argument to expression. Returns the result of expression invocation.

If expression returns a [Promise], then page.eval_on_selector_all() would wait for the promise to resolve and return its value.

Usage

div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10)

Parameters

Returns

Any

异步

async def eval_on_selector_all(self, selector: str, expression: str, arg: Optional[Any] = None) -> Any

Page.eval_on_selector_all

The method finds all elements matching the specified selector within the page and passes an array of matched elements as a first argument to expression. Returns the result of expression invocation.

If expression returns a [Promise], then page.eval_on_selector_all() would wait for the promise to resolve and return its value.

Usage

div_counts = await page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10)

Parameters

Returns

Any

evaluate

同步

def evaluate(self, expression: str, arg: Optional[Any] = None, *, isolated_context: Optional[bool] = True) -> Any

Page.evaluate

Returns the value of the expression invocation.

If the function passed to the page.evaluate() returns a [Promise], then page.evaluate() would wait for the promise to resolve and return its value.

If the function passed to the page.evaluate() returns a non-[Serializable] value, then page.evaluate() resolves to undefined. Playwright also supports transferring some additional values that are not serializable by JSON: -0, NaN, Infinity, -Infinity.

Usage

Passing argument to expression:

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

A string can also be passed in instead of a function:

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

ElementHandle instances can be passed as an argument to the page.evaluate():

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

Parameters

Returns

Any

异步

async def evaluate(self, expression: str, arg: Optional[Any] = None, *, isolated_context: Optional[bool] = True) -> Any

Page.evaluate

Returns the value of the expression invocation.

If the function passed to the page.evaluate() returns a [Promise], then page.evaluate() would wait for the promise to resolve and return its value.

If the function passed to the page.evaluate() returns a non-[Serializable] value, then page.evaluate() resolves to undefined. Playwright also supports transferring some additional values that are not serializable by JSON: -0, NaN, Infinity, -Infinity.

Usage

Passing argument to expression:

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

A string can also be passed in instead of a function:

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

ElementHandle instances can be passed as an argument to the page.evaluate():

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

Parameters

Returns

Any

evaluate_handle

同步

def evaluate_handle(self, expression: str, arg: Optional[Any] = None, *, isolated_context: Optional[bool] = True) -> 'JSHandle'

Page.evaluate_handle

Returns the value of the expression invocation as a JSHandle.

The only difference between page.evaluate() and page.evaluate_handle() is that page.evaluate_handle() returns JSHandle.

If the function passed to the page.evaluate_handle() returns a [Promise], then page.evaluate_handle() would wait for the promise to resolve and return its value.

Usage

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

A string can also be passed in instead of a function:

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

JSHandle instances can be passed as an argument to the 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()

Parameters

Returns

JSHandle

异步

async def evaluate_handle(self, expression: str, arg: Optional[Any] = None, *, isolated_context: Optional[bool] = True) -> 'JSHandle'

Page.evaluate_handle

Returns the value of the expression invocation as a JSHandle.

The only difference between page.evaluate() and page.evaluate_handle() is that page.evaluate_handle() returns JSHandle.

If the function passed to the page.evaluate_handle() returns a [Promise], then page.evaluate_handle() would wait for the promise to resolve and return its value.

Usage

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

A string can also be passed in instead of a function:

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

JSHandle instances can be passed as an argument to the page.evaluate_handle():

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

Parameters

Returns

JSHandle

expect_console_message

同步

def expect_console_message(self, predicate: Optional[Callable[[ForwardRef('ConsoleMessage')], bool]] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('ConsoleMessage')]

Page.expect_console_message

Performs action and waits for a ConsoleMessage to be logged by in the page. If predicate is provided, it passes ConsoleMessage value into the predicate function and waits for predicate(message) to return a truthy value. Will throw an error if the page is closed before the page.on('console') event is fired.

Parameters

Returns

EventContextManager[ConsoleMessage]

异步

def expect_console_message(self, predicate: Optional[Callable[[ForwardRef('ConsoleMessage')], bool]] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('ConsoleMessage')]

Page.expect_console_message

Performs action and waits for a ConsoleMessage to be logged by in the page. If predicate is provided, it passes ConsoleMessage value into the predicate function and waits for predicate(message) to return a truthy value. Will throw an error if the page is closed before the page.on('console') event is fired.

Parameters

Returns

EventContextManager[ConsoleMessage]

expect_download

同步

def expect_download(self, predicate: Optional[Callable[[ForwardRef('Download')], bool]] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Download')]

Page.expect_download

Performs action and waits for a new Download. If predicate is provided, it passes Download value into the predicate function and waits for predicate(download) to return a truthy value. Will throw an error if the page is closed before the download event is fired.

Parameters

Returns

EventContextManager[Download]

异步

def expect_download(self, predicate: Optional[Callable[[ForwardRef('Download')], bool]] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Download')]

Page.expect_download

Performs action and waits for a new Download. If predicate is provided, it passes Download value into the predicate function and waits for predicate(download) to return a truthy value. Will throw an error if the page is closed before the download event is fired.

Parameters

Returns

EventContextManager[Download]

expect_event

同步

def expect_event(self, event: str, predicate: Optional[Callable] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> patchright._impl._sync_base.EventContextManager

支持的重载：

def expect_event(self, event: Literal['close'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['console'], predicate: Optional[Callable[[ForwardRef('ConsoleMessage')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('ConsoleMessage')]
def expect_event(self, event: Literal['crash'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['dialog'], predicate: Optional[Callable[[ForwardRef('Dialog')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Dialog')]
def expect_event(self, event: Literal['dialogclosed'], predicate: Optional[Callable[[ForwardRef('Dialog')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Dialog')]
def expect_event(self, event: Literal['domcontentloaded'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['download'], predicate: Optional[Callable[[ForwardRef('Download')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Download')]
def expect_event(self, event: Literal['filechooser'], predicate: Optional[Callable[[ForwardRef('FileChooser')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('FileChooser')]
def expect_event(self, event: Literal['frameattached'], predicate: Optional[Callable[[ForwardRef('Frame')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Frame')]
def expect_event(self, event: Literal['framedetached'], predicate: Optional[Callable[[ForwardRef('Frame')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Frame')]
def expect_event(self, event: Literal['framenavigated'], predicate: Optional[Callable[[ForwardRef('Frame')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Frame')]
def expect_event(self, event: Literal['load'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['pageerror'], predicate: Optional[Callable[[ForwardRef('Error')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Error')]
def expect_event(self, event: Literal['popup'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['request'], predicate: Optional[Callable[[ForwardRef('Request')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Request')]
def expect_event(self, event: Literal['requestfailed'], predicate: Optional[Callable[[ForwardRef('Request')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Request')]
def expect_event(self, event: Literal['requestfinished'], predicate: Optional[Callable[[ForwardRef('Request')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Request')]
def expect_event(self, event: Literal['response'], predicate: Optional[Callable[[ForwardRef('Response')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Response')]
def expect_event(self, event: Literal['websocket'], predicate: Optional[Callable[[ForwardRef('WebSocket')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('WebSocket')]
def expect_event(self, event: Literal['worker'], predicate: Optional[Callable[[ForwardRef('Worker')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Worker')]
def expect_event(self, event: str, predicate: Optional[Callable[..., bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._sync_base.EventContextManager[typing.Any]

Page.expect_event

Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will throw an error if the page is closed before the event is fired. Returns the event data value.

Usage

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

Parameters

Returns

EventContextManager

异步

def expect_event(self, event: str, predicate: Optional[Callable] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> patchright._impl._async_base.AsyncEventContextManager

支持的重载：

def expect_event(self, event: Literal['close'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['console'], predicate: Optional[Callable[[ForwardRef('ConsoleMessage')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('ConsoleMessage')]
def expect_event(self, event: Literal['crash'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['dialog'], predicate: Optional[Callable[[ForwardRef('Dialog')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Dialog')]
def expect_event(self, event: Literal['dialogclosed'], predicate: Optional[Callable[[ForwardRef('Dialog')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Dialog')]
def expect_event(self, event: Literal['domcontentloaded'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['download'], predicate: Optional[Callable[[ForwardRef('Download')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Download')]
def expect_event(self, event: Literal['filechooser'], predicate: Optional[Callable[[ForwardRef('FileChooser')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('FileChooser')]
def expect_event(self, event: Literal['frameattached'], predicate: Optional[Callable[[ForwardRef('Frame')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Frame')]
def expect_event(self, event: Literal['framedetached'], predicate: Optional[Callable[[ForwardRef('Frame')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Frame')]
def expect_event(self, event: Literal['framenavigated'], predicate: Optional[Callable[[ForwardRef('Frame')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Frame')]
def expect_event(self, event: Literal['load'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['pageerror'], predicate: Optional[Callable[[ForwardRef('Error')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Error')]
def expect_event(self, event: Literal['popup'], predicate: Optional[Callable[[ForwardRef('Page')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Page')]
def expect_event(self, event: Literal['request'], predicate: Optional[Callable[[ForwardRef('Request')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Request')]
def expect_event(self, event: Literal['requestfailed'], predicate: Optional[Callable[[ForwardRef('Request')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Request')]
def expect_event(self, event: Literal['requestfinished'], predicate: Optional[Callable[[ForwardRef('Request')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Request')]
def expect_event(self, event: Literal['response'], predicate: Optional[Callable[[ForwardRef('Response')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Response')]
def expect_event(self, event: Literal['websocket'], predicate: Optional[Callable[[ForwardRef('WebSocket')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('WebSocket')]
def expect_event(self, event: Literal['worker'], predicate: Optional[Callable[[ForwardRef('Worker')], bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Worker')]
def expect_event(self, event: str, predicate: Optional[Callable[..., bool]] = None, *, timeout: Optional[float] = None) -> patchright._impl._async_base.AsyncEventContextManager[typing.Any]