页面命令

页面命令处理页面导航、生命周期事件和页面操作。

概述

页面命令模块提供页面间导航、管理页面生命周期、处理 JavaScript 执行以及控制页面行为的功能。

pydoll.commands.page_commands

PageCommands

This class encapsulates the page commands of the Chrome DevTools Protocol (CDP).

CDP's Page domain allows for interacting with browser pages, including navigation, content manipulation, and page state monitoring. These commands provide powerful capabilities for web automation, testing, and debugging.

The commands defined in this class provide functionality for: - Navigating to URLs and managing page history - Capturing screenshots and generating PDFs - Handling JavaScript dialogs - Enabling and controlling page events - Managing download behavior - Manipulating page content and state

add_script_to_evaluate_on_new_document `staticmethod`

add_script_to_evaluate_on_new_document(source, world_name=None, include_command_line_api=None, run_immediately=None)

Creates a command to add a script that will be evaluated when a new document is created.

PARAMETER	DESCRIPTION
`source`	Script source to be evaluated when a new document is created. TYPE: `str`
`world_name`	If specified, creates an isolated world with the given name. TYPE: `Optional[str]` DEFAULT: `None`
`include_command_line_api`	Whether to include command line API. TYPE: `Optional[bool]` DEFAULT: `None`
`run_immediately`	Whether to run the script immediately on existing contexts. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[AddScriptToEvaluateOnNewDocumentResponse]`	Command[AddScriptToEvaluateOnNewDocumentResponse]: Command object with the identifier of the added script.

bring_to_front `staticmethod`

bring_to_front()

Brings the page to front.

capture_screenshot `staticmethod`

capture_screenshot(format=None, quality=None, clip=None, from_surface=None, capture_beyond_viewport=None, optimize_for_speed=None)

Creates a command to capture a screenshot of the current page.

PARAMETER	DESCRIPTION
`format`	Image compression format (jpeg, png, or webp). TYPE: `Optional[str]` DEFAULT: `None`
`quality`	Compression quality from 0-100 (jpeg only). TYPE: `Optional[int]` DEFAULT: `None`
`clip`	Region of the page to capture. TYPE: `Optional[Viewport]` DEFAULT: `None`
`from_surface`	Capture from the surface, not the view. TYPE: `Optional[bool]` DEFAULT: `None`
`capture_beyond_viewport`	Capture beyond the viewport. TYPE: `Optional[bool]` DEFAULT: `None`
`optimize_for_speed`	Optimize for speed, not for size. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[CaptureScreenshotResponse]`	Command[CaptureScreenshotResponse]: Command object with base64-encoded image data.

close `staticmethod`

close()

Creates a command to close the current page.

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to close the page.

create_isolated_world `staticmethod`

create_isolated_world(frame_id, world_name=None, grant_universal_access=None)

Creates a command to create an isolated world for the given frame.

PARAMETER	DESCRIPTION
`frame_id`	ID of the frame in which to create the isolated world. TYPE: `str`
`world_name`	Name to be reported in the Execution Context. TYPE: `Optional[str]` DEFAULT: `None`
`grant_universal_access`	Whether to grant universal access. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[CreateIsolatedWorldResponse]`	Command[CreateIsolatedWorldResponse]: Command object with the execution context ID.

disable `staticmethod`

disable()

Creates a command to disable page domain notifications.

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to disable the Page domain.

enable `staticmethod`

enable(enable_file_chooser_opened_event=None)

Creates a command to enable page domain notifications.

PARAMETER	DESCRIPTION
`enable_file_chooser_opened_event`	Whether to emit Page.fileChooserOpened event. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to enable the Page domain.

get_app_manifest `staticmethod`

get_app_manifest(manifest_id=None)

Creates a command to get the manifest for the current document.

RETURNS	DESCRIPTION
`Command[GetAppManifestResponse]`	Command[GetAppManifestResponse]: Command object with manifest information.

get_frame_tree `staticmethod`

get_frame_tree()

Creates a command to get the frame tree for the current page.

RETURNS	DESCRIPTION
`Command[GetFrameTreeResponse]`	Command[GetFrameTreeResponse]: Command object with frame tree information.

get_layout_metrics `staticmethod`

get_layout_metrics()

Creates a command to get layout metrics for the page.

RETURNS	DESCRIPTION
`Command[GetLayoutMetricsResponse]`	Command[GetLayoutMetricsResponse]: Command object with layout metrics.

get_navigation_history `staticmethod`

get_navigation_history()

Creates a command to get the navigation history for the current page.

RETURNS	DESCRIPTION
`Command[GetNavigationHistoryResponse]`	Command[GetNavigationHistoryResponse]: Command object with navigation history.

handle_javascript_dialog `staticmethod`

handle_javascript_dialog(accept, prompt_text=None)

Creates a command to handle a JavaScript dialog.

PARAMETER	DESCRIPTION
`accept`	Whether to accept or dismiss the dialog. TYPE: `bool`
`prompt_text`	Text to enter in prompt dialogs. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to handle a JavaScript dialog.

navigate `staticmethod`

navigate(url, referrer=None, transition_type=None, frame_id=None, referrer_policy=None)

Creates a command to navigate to a specific URL.

PARAMETER	DESCRIPTION
`url`	URL to navigate to. TYPE: `str`
`referrer`	Referrer URL. TYPE: `Optional[str]` DEFAULT: `None`
`transition_type`	Intended transition type. TYPE: `Optional[str]` DEFAULT: `None`
`frame_id`	Frame ID to navigate. TYPE: `Optional[str]` DEFAULT: `None`
`referrer_policy`	Referrer policy. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[NavigateResponse]`	Command[NavigateResponse]: Command object to navigate to a URL.

navigate_to_history_entry `staticmethod`

navigate_to_history_entry(entry_id)

Creates a command to navigate to a specific history entry.

PARAMETER	DESCRIPTION
`entry_id`	ID of the history entry to navigate to. TYPE: `int`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to navigate to a history entry.

print_to_pdf `staticmethod`

print_to_pdf(landscape=None, display_header_footer=None, print_background=None, scale=None, paper_width=None, paper_height=None, margin_top=None, margin_bottom=None, margin_left=None, margin_right=None, page_ranges=None, header_template=None, footer_template=None, prefer_css_page_size=None, transfer_mode=None, generate_tagged_pdf=None, generate_document_outline=None)

Creates a command to print the current page to PDF.

PARAMETER	DESCRIPTION
`landscape`	Paper orientation. TYPE: `Optional[bool]` DEFAULT: `None`
`display_header_footer`	Display header and footer. TYPE: `Optional[bool]` DEFAULT: `None`
`print_background`	Print background graphics. TYPE: `Optional[bool]` DEFAULT: `None`
`scale`	Scale of the webpage rendering. TYPE: `Optional[float]` DEFAULT: `None`
`paper_width`	Paper width in inches. TYPE: `Optional[float]` DEFAULT: `None`
`paper_height`	Paper height in inches. TYPE: `Optional[float]` DEFAULT: `None`
`margin_top`	Top margin in inches. TYPE: `Optional[float]` DEFAULT: `None`
`margin_bottom`	Bottom margin in inches. TYPE: `Optional[float]` DEFAULT: `None`
`margin_left`	Left margin in inches. TYPE: `Optional[float]` DEFAULT: `None`
`margin_right`	Right margin in inches. TYPE: `Optional[float]` DEFAULT: `None`
`page_ranges`	Paper ranges to print, e.g., '1-5, 8, 11-13'. TYPE: `Optional[str]` DEFAULT: `None`
`header_template`	HTML template for the print header. TYPE: `Optional[str]` DEFAULT: `None`
`footer_template`	HTML template for the print footer. TYPE: `Optional[str]` DEFAULT: `None`
`prefer_css_page_size`	Whether to prefer page size as defined by CSS. TYPE: `Optional[bool]` DEFAULT: `None`
`transfer_mode`	Transfer mode. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[PrintToPDFResponse]`	Command[PrintToPDFResponse]: Command object to print the page to PDF.

reload `staticmethod`

reload(ignore_cache=None, script_to_evaluate_on_load=None, loader_id=None)

Creates a command to reload the current page.

PARAMETER	DESCRIPTION
`ignore_cache`	If true, browser cache is ignored. TYPE: `Optional[bool]` DEFAULT: `None`
`script_to_evaluate_on_load`	Script to be injected into the page on load. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to reload the page.

reset_navigation_history `staticmethod`

reset_navigation_history()

Creates a command to reset the navigation history.

remove_script_to_evaluate_on_new_document `staticmethod`

remove_script_to_evaluate_on_new_document(identifier)

Creates a command to remove a script that was added to be evaluated on new documents.

PARAMETER	DESCRIPTION
`identifier`	Identifier of the script to remove. TYPE: `str`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to remove a script.

set_bypass_csp `staticmethod`

set_bypass_csp(enabled)

Creates a command to toggle bypassing page CSP.

PARAMETER	DESCRIPTION
`enabled`	Whether to bypass page CSP. TYPE: `bool`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to toggle bypassing page CSP.

set_document_content `staticmethod`

set_document_content(frame_id, html)

Creates a command to set the document content of a frame.

PARAMETER	DESCRIPTION
`frame_id`	Frame ID to set the document content for. TYPE: `str`
`html`	HTML content to set. TYPE: `str`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to set the document content.

set_intercept_file_chooser_dialog `staticmethod`

set_intercept_file_chooser_dialog(enabled)

Creates a command to set whether to intercept file chooser dialogs.

PARAMETER	DESCRIPTION
`enabled`	Whether to intercept file chooser dialogs. TYPE: `bool`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to set file chooser dialog interception.

set_lifecycle_events_enabled `staticmethod`

set_lifecycle_events_enabled(enabled)

Creates a command to enable/disable lifecycle events.

PARAMETER	DESCRIPTION
`enabled`	Whether to enable lifecycle events. TYPE: `bool`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to enable/disable lifecycle events.

stop_loading `staticmethod`

stop_loading()

Creates a command to stop loading the page.

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to stop loading the page.

add_compilation_cache `staticmethod`

add_compilation_cache(url, data)

Creates a command to add a compilation cache entry.

Experimental: This method is experimental and may be subject to change.

PARAMETER	DESCRIPTION
`url`	URL for which to add the compilation cache entry. TYPE: `str`
`data`	Base64-encoded data. TYPE: `str`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to add a compilation cache entry.

capture_snapshot `staticmethod`

capture_snapshot(format='mhtml')

Creates a command to capture a snapshot of the page.

Experimental: This method is experimental and may be subject to change.

PARAMETER	DESCRIPTION
`format`	Format of the snapshot (only 'mhtml' is supported). TYPE: `Literal['mhtml']` DEFAULT: `'mhtml'`

RETURNS	DESCRIPTION
`Command[CaptureSnapshotResponse]`	Command[CaptureSnapshotResponse]: Command object to capture a snapshot.

clear_compilation_cache `staticmethod`

clear_compilation_cache()

Creates a command to clear the compilation cache.

crash `staticmethod`

crash()

Creates a command to crash the page.

generate_test_report `staticmethod`

generate_test_report(message, group=None)

Creates a command to generate a test report.

Experimental: This method is experimental and may be subject to change.

PARAMETER	DESCRIPTION
`message`	Message to be displayed in the report. TYPE: `str`
`group`	Group label for the report. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to generate a test report.

get_ad_script_ancestry_ids `staticmethod`

get_ad_script_ancestry_ids(frame_id)

Creates a command to get the ad script ancestry IDs for a given frame.

Experimental: This method is experimental and may be subject to change.

PARAMETER	DESCRIPTION
`frame_id`	ID of the frame to get ad script ancestry IDs for. TYPE: `str`

RETURNS	DESCRIPTION
`Command[GetAdScriptAncestryIdsResponse]`	Command[GetAdScriptAncestryIdsResponse]: Command object to get ad script ancestry IDs.

get_app_id `staticmethod`

get_app_id(app_id=None, recommended_id=None)

Creates a command to get the app ID.

Experimental: This method is experimental and may be subject to change.

PARAMETER	DESCRIPTION
`app_id`	App ID for verification. TYPE: `Optional[str]` DEFAULT: `None`
`recommended_id`	Recommended app ID. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[GetAppIdResponse]`	Command[GetAppIdResponse]: Command object to get the app ID.

get_installability_errors `staticmethod`

get_installability_errors()

Creates a command to get the installability errors.

get_origin_trials `staticmethod`

get_origin_trials(frame_id)

Creates a command to get origin trials for a given origin.

Experimental: This method is experimental and may be subject to change.

PARAMETER	DESCRIPTION
`frame_id`	Frame ID to get trials for. TYPE: `Optional[str]`

RETURNS	DESCRIPTION
`Command[GetOriginTrialsResponse]`	Command[GetOriginTrialsResponse]: Command object to get origin trials.

get_permissions_policy_state `staticmethod`

get_permissions_policy_state(frame_id)

Creates a command to get the permissions policy state.

get_resource_content `staticmethod`

get_resource_content(frame_id, url)

Creates a command to get the resource content.

get_resource_tree `staticmethod`

get_resource_tree()

Creates a command to get the resource tree.

produce_compilation_cache `staticmethod`

produce_compilation_cache(scripts)

Creates a command to produce a compilation cache entry.

screencast_frame_ack `staticmethod`

screencast_frame_ack(session_id)

Creates a command to acknowledge a screencast frame.

search_in_resource `staticmethod`

search_in_resource(frame_id, url, query, case_sensitive=None, is_regex=None)

Creates a command to search for a string in a resource.

set_ad_blocking_enabled `staticmethod`

set_ad_blocking_enabled(enabled)

Creates a command to set ad blocking enabled.

set_font_families `staticmethod`

set_font_families(font_families, for_scripts)

Creates a command to set font families.

set_font_sizes `staticmethod`

set_font_sizes(font_sizes)

Creates a command to set font sizes.

set_prerendering_allowed `staticmethod`

set_prerendering_allowed(allowed)

Creates a command to set prerendering allowed.

set_rph_registration_mode `staticmethod`

set_rph_registration_mode(mode)

Creates a command to set the RPH registration mode.

set_spc_transaction_mode `staticmethod`

set_spc_transaction_mode(mode)

Creates a command to set the SPC transaction mode.

set_web_lifecycle_state `staticmethod`

set_web_lifecycle_state(state)

Creates a command to set the web lifecycle state.

start_screencast `staticmethod`

start_screencast(format, quality=None, max_width=None, max_height=None, every_nth_frame=None)

Creates a command to start a screencast.

stop_screencast `staticmethod`

stop_screencast()

Creates a command to stop a screencast.

wait_for_debugger `staticmethod`

wait_for_debugger()

Creates a command to wait for a debugger.

用法

“Tab”类广泛使用页面命令进行导航和页面管理：

from pydoll.commands.page_commands import navigate, reload, enable
from pydoll.connection.connection_handler import ConnectionHandler

# Navigate to a URL
connection = ConnectionHandler()
await enable(connection)  # Enable page events
await navigate(connection, url="https://example.com")

# Reload the page
await reload(connection)

关键功能

页面命令模块提供以下函数：

页面生命周期

enable() / disable() - 启用/禁用页面事件
get_frame_tree() - 获取页面框架结构
get_navigation_history() - 获取导航历史记录

内容管理

get_resource_content() - 获取页面资源内容
search_in_resource() - 在页面资源内搜索
set_document_content() - 设置页面 HTML 内容

截图和 PDF

capture_screenshot() - 页面截图
print_to_pdf() - 将页面保存为PDF
capture_snapshot() - 页面快照

JavaScript 执行

add_script_to_evaluate_on_new_document() - 添加启动脚本(在网页加载前注入js)
remove_script_to_evaluate_on_new_document() - 移除启动脚本

页面设置

set_lifecycle_events_enabled() - 控制生命周期事件
set_ad_blocking_enabled() - 启用/禁用广告拦截
set_bypass_csp() - 绕过内容安全策略

高级功能

框架管理

# Get all frames in the page
frame_tree = await get_frame_tree(connection)
for frame in frame_tree.child_frames:
    print(f"Frame: {frame.frame.url}")

资源拦截

# Get resource content
content = await get_resource_content(
    connection, 
    frame_id=frame_id, 
    url="https://example.com/script.js"
)

页面事件

页面命令可与各种页面事件配合使用： - Page.loadEventFired - 页面加载完成 - Page.domContentEventFired - DOM 内容已加载 - Page.frameNavigated - 框架访问结束 - Page.frameStartedLoading - 框架加载开始

!!! 小提示“Tab 类集成” 大多数页面操作都可以通过 Tab 类方法实现，例如 tab.go_to()、tab.reload() 和 tab.screenshot()，这些方法提供了更便捷的 API。

页面命令

概述

pydoll.commands.page_commands

PageCommands

add_script_to_evaluate_on_new_document staticmethod

bring_to_front staticmethod

capture_screenshot staticmethod

close staticmethod

create_isolated_world staticmethod

disable staticmethod

enable staticmethod

get_app_manifest staticmethod

get_frame_tree staticmethod

get_layout_metrics staticmethod

get_navigation_history staticmethod

handle_javascript_dialog staticmethod

navigate staticmethod

navigate_to_history_entry staticmethod

print_to_pdf staticmethod

reload staticmethod

reset_navigation_history staticmethod

remove_script_to_evaluate_on_new_document staticmethod

set_bypass_csp staticmethod

set_document_content staticmethod

set_intercept_file_chooser_dialog staticmethod

set_lifecycle_events_enabled staticmethod

stop_loading staticmethod

add_compilation_cache staticmethod

capture_snapshot staticmethod

clear_compilation_cache staticmethod

crash staticmethod

generate_test_report staticmethod

get_ad_script_ancestry_ids staticmethod

get_app_id staticmethod

get_installability_errors staticmethod

get_origin_trials staticmethod

get_permissions_policy_state staticmethod

get_resource_content staticmethod

get_resource_tree staticmethod

produce_compilation_cache staticmethod

screencast_frame_ack staticmethod

search_in_resource staticmethod

set_ad_blocking_enabled staticmethod

set_font_families staticmethod

set_font_sizes staticmethod

set_prerendering_allowed staticmethod

set_rph_registration_mode staticmethod

set_spc_transaction_mode staticmethod

set_web_lifecycle_state staticmethod

start_screencast staticmethod

stop_screencast staticmethod

wait_for_debugger staticmethod

用法

关键功能

导航

页面生命周期

内容管理

截图和 PDF

JavaScript 执行

页面设置

高级功能

框架管理

资源拦截

页面事件

add_script_to_evaluate_on_new_document `staticmethod`

bring_to_front `staticmethod`

capture_screenshot `staticmethod`

close `staticmethod`

create_isolated_world `staticmethod`

disable `staticmethod`

enable `staticmethod`

get_app_manifest `staticmethod`

get_frame_tree `staticmethod`

get_layout_metrics `staticmethod`

get_navigation_history `staticmethod`

handle_javascript_dialog `staticmethod`

navigate `staticmethod`

navigate_to_history_entry `staticmethod`

print_to_pdf `staticmethod`

reload `staticmethod`

reset_navigation_history `staticmethod`

remove_script_to_evaluate_on_new_document `staticmethod`

set_bypass_csp `staticmethod`

set_document_content `staticmethod`

set_intercept_file_chooser_dialog `staticmethod`

set_lifecycle_events_enabled `staticmethod`

stop_loading `staticmethod`

add_compilation_cache `staticmethod`

capture_snapshot `staticmethod`

clear_compilation_cache `staticmethod`

crash `staticmethod`

generate_test_report `staticmethod`

get_ad_script_ancestry_ids `staticmethod`

get_app_id `staticmethod`

get_installability_errors `staticmethod`

get_origin_trials `staticmethod`

get_permissions_policy_state `staticmethod`

get_resource_content `staticmethod`

get_resource_tree `staticmethod`

produce_compilation_cache `staticmethod`

screencast_frame_ack `staticmethod`

search_in_resource `staticmethod`

set_ad_blocking_enabled `staticmethod`

set_font_families `staticmethod`

set_font_sizes `staticmethod`

set_prerendering_allowed `staticmethod`

set_rph_registration_mode `staticmethod`

set_spc_transaction_mode `staticmethod`

set_web_lifecycle_state `staticmethod`

start_screencast `staticmethod`

stop_screencast `staticmethod`

wait_for_debugger `staticmethod`