Playwright for Python：Page 类中文版文档

Page 类用于与浏览器中的单个标签页或 Chromium 中的扩展后台页面交互，一个 Browser 实例可包含多个 Page 实例。

快速示例

基础用法（同步/异步）

同步示例

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = webkit.launch()
    context = browser.new_context()
    page = context.new_page()
    page.goto("https://example.com")
    page.screenshot(path="screenshot.png")
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

异步示例

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = await webkit.launch()
    context = await browser.new_context()
    page = await context.new_page()
    await page.goto("https://example.com")
    await page.screenshot(path="screenshot.png")
    await browser.close()

async def main():
    async with async_playwright() as playwright:
        await run(playwright)

asyncio.run(main())

事件处理

监听单次事件

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

订阅与取消订阅事件

def log_request(intercepted_request):
    print("发起请求：", intercepted_request.url)

page.on("request", log_request)
# 后续取消监听
page.remove_listener("request", log_request)

核心方法

add_init_script

在页面导航或子框架附加/导航时注入脚本，脚本在文档创建后、自身脚本运行前执行，适用于修改 JavaScript 环境。

用法示例

1. 创建 preload.js 文件：

Math.random = () => 42;

2. 注入脚本：

# 同步
page.add_init_script(path="./preload.js")
# 异步
await page.add_init_script(path="./preload.js")

参数说明

• path：JavaScript 文件路径（相对路径基于当前工作目录）
• script：直接注入的脚本字符串

add_locator_handler

检测到指定浮层（如注册弹窗）时自动执行处理函数，移除遮挡元素以保证测试流程。

用法示例

# 同步：关闭新闻订阅弹窗
def handler():
    page.get_by_role("button", name="不了，谢谢").click()

page.add_locator_handler(page.get_by_text("订阅新闻通讯"), handler)
page.goto("https://example.com")
page.get_by_role("button", name="开始使用").click()

# 异步
async def handler():
    await page.get_by_role("button", name="不了，谢谢").click()

await page.add_locator_handler(page.get_by_text("订阅新闻通讯"), handler)
await page.goto("https://example.com")
await page.get_by_role("button", name="开始使用").click()

参数说明

• locator：触发处理函数的定位器
• handler：处理浮层的函数
• no_wait_after：是否不等待浮层隐藏（默认等待）
• times：处理函数最大执行次数（默认无限制）

add_script_tag

向页面添加 <script> 标签，支持通过 URL、文件路径或直接内容注入。

参数说明

• content：原始 JavaScript 内容
• path：JavaScript 文件路径
• type：脚本类型（如 'module' 用于 ES6 模块）
• url：脚本 URL

返回值

ElementHandle（添加的脚本标签元素）

add_style_tag

向页面添加样式，支持通过 URL、文件路径或直接 CSS 内容。

参数说明

• content：原始 CSS 内容
• path：CSS 文件路径
• url：样式文件 URL

返回值

ElementHandle（添加的样式标签元素）

bring_to_front

激活当前标签页，将页面置于前台。

用法

page.bring_to_front()  # 同步
await page.bring_to_front()  # 异步

close

关闭页面，可选择是否执行 beforeunload 处理器。

参数说明

• reason：页面关闭的原因描述（v1.40+）
• run_before_unload：是否执行卸载处理器（默认 False）

content

获取页面完整 HTML 内容（包含文档类型声明）。

用法

html = page.content()  # 同步
html = await page.content()  # 异步

drag_and_drop

将源元素拖动到目标元素，支持指定拖拽起始和结束位置。

用法示例

# 同步
page.drag_and_drop("#源元素", "#目标元素")
# 指定位置拖拽
page.drag_and_drop(
    "#源元素", "#目标元素",
    source_position={"x": 34, "y": 7},
    target_position={"x": 10, "y": 20}
)

# 异步
await page.drag_and_drop("#源元素", "#目标元素")

emulate_media

模拟 CSS 媒体类型或媒体特性（如深色模式）。

用法示例

# 模拟打印模式
page.emulate_media(media="print")  # 同步
await page.emulate_media(media="print")  # 异步

# 模拟深色模式
page.emulate_media(color_scheme="dark")  # 同步
await page.emulate_media(color_scheme="dark")  # 异步

evaluate

在浏览器上下文执行 JavaScript 表达式，返回执行结果。

用法示例

# 同步
result = page.evaluate("([x, y]) => x * y", [7, 8])  # 输出 56
print(page.evaluate("1 + 2"))  # 输出 3

# 异步
result = await page.evaluate("([x, y]) => x * y", [7, 8])

get_by_* 定位方法

一系列基于语义的定位方法，简化元素查找：

方法	用途	示例
get_by_alt_text	通过替代文本定位（如图片）	page.get_by_alt_text("Playwright 图标").click()
get_by_label	通过标签文本定位输入框	page.get_by_label("用户名").fill("john")
get_by_placeholder	通过占位文本定位输入框	page.get_by_placeholder("name@example.com").fill("test@xxx.com")
get_by_role	通过 ARIA 角色定位	page.get_by_role("button", name="提交").click()
get_by_test_id	通过测试 ID 定位	page.get_by_test_id("directions").click()
get_by_text	通过文本内容定位	page.get_by_text("Hello world").click()
get_by_title	通过 title 属性定位	page.get_by_title("问题数量").text_content()

goto

导航到指定 URL，返回主资源响应。

用法

page.goto("https://example.com")  # 同步
await page.goto("https://example.com")  # 异步

参数说明

• url：目标 URL（需包含协议，如 https://）
• referer：Referer 请求头
• timeout：导航超时时间（默认 30 秒）
• wait_until：导航完成条件（load/domcontentloaded/networkidle/commit）

locator

创建元素定位器，用于后续操作（定位器在执行操作前实时解析元素）。

用法示例

# 同步
locator = page.locator("button").has_text("确认")
locator.click()

# 异步
locator = page.locator("button").has_text("确认")
await locator.click()

pdf

将页面导出为 PDF 文件，支持自定义纸张大小、边距等。

用法示例

# 同步：模拟屏幕媒体类型导出
page.emulate_media(media="screen")
page.pdf(path="page.pdf")

# 异步
await page.emulate_media(media="screen")
await page.pdf(path="page.pdf")

screenshot

捕获页面截图，支持全屏、裁剪、指定格式等。

用法示例

# 同步：捕获全屏 PNG
page.screenshot(path="full_page.png", full_page=True)
# 捕获 JPEG 格式（质量 80）
page.screenshot(path="image.jpg", type="jpeg", quality=80)

# 异步
await page.screenshot(path="full_page.png", full_page=True)

set_content

设置页面 HTML 内容，内部调用 document.write()。

用法

page.set_content("<h1>Hello Playwright</h1>")  # 同步
await page.set_content("<h1>Hello Playwright</h1>")  # 异步

set_viewport_size

设置页面视口大小。

用法

# 同步
page.set_viewport_size({"width": 1920, "height": 1080})
# 异步
await page.set_viewport_size({"width": 1920, "height": 1080})

title

获取页面标题。

用法

title = page.title()  # 同步
title = await page.title()  # 异步

route

拦截并修改页面网络请求，支持按 URL 模式匹配。

用法示例

# 同步：拦截所有图片请求并中止
page.route("**/*.{png,jpg,jpeg}", lambda route: route.abort())
page.goto("https://example.com")

# 异步
await page.route("**/*.{png,jpg,jpeg}", lambda route: route.abort())
await page.goto("https://example.com")

wait_for_url

等待页面导航到指定 URL。

用法

# 同步
page.click("a[href='target.html']")
page.wait_for_url("**/target.html")

# 异步
await page.click("a[href='target.html']")
await page.wait_for_url("**/target.html")

核心属性

属性	用途	返回类型
clock	模拟时钟和时间流逝（v1.45+）	Clock
context	获取页面所属的浏览器上下文	BrowserContext
frames	获取页面所有框架	List[Frame]
is_closed	检查页面是否已关闭	bool
keyboard	键盘操作对象	Keyboard
main_frame	页面主框架	Frame
mouse	鼠标操作对象	Mouse
url	获取当前页面 URL	str
viewport_size	获取当前视口大小	Dict（width/height）
workers	获取页面关联的 WebWorker	List[Worker]

常用事件

事件	触发时机	事件数据
close	页面关闭时	Page
console	页面调用 console 方法时	ConsoleMessage
dialog	页面出现弹窗时（alert/confirm 等）	Dialog
download	页面开始下载时	Download
load	页面 load 事件触发时	Page
pageerror	页面发生未捕获异常时	Error
popup	页面打开新标签页时	Page
request	页面发起网络请求时	Request
response	页面收到网络响应时	Response

废弃/不推荐方法

以下方法已不推荐使用，建议替换为 locator 相关方法：

• check → locator.check()
• click → locator.click()
• dblclick → locator.dblclick()
• fill → locator.fill()
• hover → locator.hover()
• press → locator.press()
• select_option → locator.select_option()
• wait_for_selector → locator.wait_for() 或断言

---