简介 - 《Pydoll 开发文档 - 帮助手册 - 教程》

⭐ 卓越功能
目录
🔥 安装
⚡ 快速开始
🎯 核心组件
🚀 高级功能
- 事件系统
  - async on(event_name: str, callback: callable, temporary: bool = False) -> int
  - async enable_network_events() -> None

Pydoll 是一个创新的 Python 库，正在重新定义 Chromium 浏览器自动化！与其他解决方案不同，Pydoll 完全消除了对 WebDriver 的依赖，提供了更流畅、更可靠的自动化体验。

⭐ 卓越功能

无需 WebDriver！ 告别 WebDriver 兼容性问题和繁琐的配置
原生验证码绕过！ 可自然通过 Cloudflare Turnstile 和 reCAPTCHA v3 *
高性能，得益于原生异步编程
真实交互，模拟人类行为
高级事件系统，支持复杂和响应式自动化

注意：对于 Cloudflare 验证码，您需要手动点击复选框。只需找到包含 iframe 的 div 并使用 .click() 方法。自动检测和点击功能即将推出！

🔥 安装

pip install pydoll-python

⚡ 快速开始

看看 Pydoll 有多简单——无需 WebDriver 配置！

import asyncio
from pydoll.browser.chrome import Chrome
from pydoll.constants import By
async def main():
    # 无需额外 WebDriver 配置即可启动浏览器！
    async with Chrome() as browser:
        await browser.start()
        page = await browser.get_page()
        # 轻松访问受 Cloudflare 保护的网站
        await page.go_to('https://example-with-cloudflare.com')
        button = await page.find_element(By.CSS_SELECTOR, 'button')
        await button.click()
asyncio.run(main())

如果您需要自定义浏览器配置，可以这样做：

from pydoll.browser.chrome import Chrome
from pydoll.browser.options import Options
options = Options()
# 选择使用公共或私有代理！
options.add_argument('--proxy-server=username:password@ip:port')
# 需要更改默认浏览器路径？没问题！
options.binary_location = '/path/to/your/browser'
async with Chrome(options=options) as browser:
    await browser.start()

您可以在此处找到所有可用的浏览器选项：Chromium 命令行参数

🎯 核心组件

浏览器接口

Browser 领域提供对浏览器本身的直接控制，允许全局管理整个浏览器实例。与特定页面操作不同，这些方法影响整个浏览器，支持管理多个页面、窗口属性、全局 Cookie 以及整个会话的事件监听。

示例代码：

async def browser_examples():
    async with Chrome() as browser:
        await browser.start()
        # 轻松管理多个页面
        pages = [await browser.get_page() for _ in range(3)]
        # 只需一行代码即可调整窗口大小
        await browser.set_window_maximized()

浏览器管理

`async start() -> None`

启动浏览器，为自动化做好准备！

async with Chrome() as browser:
    await browser.start()  # 启动浏览器

`async stop() -> None`

优雅地关闭浏览器。

await browser.stop()  # 关闭浏览器

`async get_page() -> Page`

获取现有页面或创建新页面。

page = await browser.get_page()
await page.go_to("https://www.example.com")

`async new_page(url: str = '') -> str`

打开新页面并返回其 ID，适用于多标签自动化。

page_id = await browser.new_page("https://www.example.com")

`async get_page_by_id(page_id: str) -> Page`

根据页面 ID 获取特定页面。

page = await browser.get_page_by_id(page_id)

`async get_targets() -> list`

获取所有打开的页面。

targets = await browser.get_targets()
for target in targets:
    print(f"页面: {target.get('title')} - URL: {target.get('url')}")

`async set_window_bounds(bounds: dict) -> None`

设置窗口大小和位置。

await browser.set_window_bounds({
    'left': 100, 
    'top': 100, 
    'width': 1024, 
    'height': 768
})

`async get_cookies() -> list[dict]`

获取浏览器存储的所有 Cookie。

cookies = await browser.get_cookies()
for cookie in cookies:
    print(f"名称: {cookie['name']}, 值: {cookie['value']}")

`async delete_all_cookies() -> None`

清除所有 Cookie。

await browser.delete_all_cookies()

`async set_download_path(path: str) -> None`

设置下载目录。

await browser.set_download_path("/path/to/downloads")

页面接口

Page 代表单个浏览器标签页，提供精准的页面控制功能，例如交互、事件监听、截图等。

示例代码：

async def page_examples():
    await page.go_to('https://example.com')
    # 获取页面信息
    current_url = await page.current_url
    content = await page.page_source
    # 截图
    await page.get_screenshot('/screenshots/evidence.png')
    # 操作 Cookie
    cookies = await page.get_cookies()
    await page.set_cookies([{'name': 'session', 'value': 'xyz123'}])
    # 执行 JavaScript
    await page.execute_script('return document.title')

页面管理

`async go_to(url: str, timeout=300) -> None`

访问指定 URL。

await page.go_to("https://www.example.com", timeout=60)

`async refresh() -> None`

刷新页面。

await page.refresh()

`async close() -> None`

关闭当前页面。

await page.close()

`async current_url -> str`

获取当前页面 URL。

url = await page.current_url
print(f"当前 URL: {url}")

`async get_screenshot(path: str) -> None`

截图并保存。

await page.get_screenshot("/path/to/screenshot.png")

`async print_to_pdf(path: str) -> None`

将页面保存为 PDF。

await page.print_to_pdf("/path/to/document.pdf")

`async has_dialog() -> bool`

检测是否有弹窗。

if await page.has_dialog():
    print("检测到弹窗")

`async accept_dialog() -> None`

自动接受弹窗。

if await page.has_dialog():
    await page.accept_dialog()

`async set_download_path(path: str) -> None`

设置页面的下载目录。

await page.set_download_path("/my_downloads")

`async get_network_logs(matches: list[str] = []) -> list`

获取网络请求日志。

await page.enable_network_events()  # 必须先启用网络监听
await page.go_to('https://example.com')
logs = await page.get_network_logs(['/api'])

{
  "method": "Network.requestWillBeSent",
  "params": {
    "requestId": "764F3179D5C6D0A1A3F67E7C0ECD88DB",
    "loaderId": "764F3179D5C6D0A1A3F67E7C0ECD88DB",
    "documentURL": "https://google.com/",
    "request": {
      "url": "https://google.com/",
      "method": "GET",
      "headers": {
        "Upgrade-Insecure-Requests": "1",
        "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
        "sec-ch-ua": "\"Chromium\";v=\"130\", \"Google Chrome\";v=\"130\", \"Not?A_Brand\";v=\"99\"",
        "sec-ch-ua-mobile": "?0",
        "sec-ch-ua-platform": "\"Linux\""
      },
      "mixedContentType": "none",
      "initialPriority": "VeryHigh",
      "referrerPolicy": "strict-origin-when-cross-origin",
      "isSameSite": true
    },
    "timestamp": 152714.232433,
    "wallTime": 1741737850.444337,
    "initiator": {
      "type": "other"
    },
    "redirectHasExtraInfo": false,
    "type": "Document",
    "frameId": "2EC0B50381EB2D8CF48BE3CF1D933B59",
    "hasUserGesture": false
  }
}

`async get_network_response_bodies(matches: list[str] = []) -> list`

捕获 API 调用的实际响应数据 - 非常适合验证！

# 获取 API 请求的响应
responses = await page.get_network_response_bodies(['google.com'])

你将得到类似这样的数据：

[
    {
        'body': '...',
        'base64Encoded': False
    }
]

`async get_network_response_body(request_id: str) -> tuple`

针对特定请求进行详细分析。

# 获取特定请求的响应体
logs = await page.get_network_logs(['api/products'])
body, encoded = await page.get_network_response_body(logs[0]['params']['requestId'])

`async on(event_name: str, callback: callable, temporary: bool = False) -> int`

使你的自动化能够实时响应页面事件！详细信息请查看事件系统部分。

`async execute_script(script: str, element: WebElement = None)`

直接从你的 Python 代码执行 JavaScript，释放 JavaScript 的全部威力！

# 在页面上执行 JavaScript
title = await page.execute_script('return document.title')
# 在特定元素上执行 JavaScript
button = await page.find_element(By.CSS_SELECTOR, 'button')
await page.execute_script('arguments[0].click()', button)

WebElement 接口

WebElement 代表浏览器中的 DOM 元素，允许你以模拟真实用户行为的方式与其交互。本节介绍与网页元素交互的最有用的方法。

`value -> str`

获取元素的当前值 - 非常适合检查表单字段。

# 检查输入框的值
input_element = await page.find_element(By.CSS_SELECTOR, 'input')
print(f"当前值: {input_element.value}")

`class_name -> str`

访问元素的 CSS 类 - 用于样式验证。

# 检查 CSS 类
button = await page.find_element(By.CSS_SELECTOR, 'button')
print(f"类名: {button.class_name}")

`id -> str`

获取元素的 ID - 适用于唯一标识。

# 获取元素的 ID
element = await page.find_element(By.CSS_SELECTOR, 'div')
print(f"ID: {element.id}")

`is_enabled -> bool`

快速检查元素是否可交互。

# 在点击前检查按钮是否可用
button = await page.find_element(By.CSS_SELECTOR, 'button')
if button.is_enabled:
    await button.click()

`async bounds -> list`

获取元素的精确边界坐标。

# 获取元素的坐标
element = await page.find_element(By.CSS_SELECTOR, 'div')
bounds = await element.bounds
print(f"坐标: {bounds}")

`async inner_html -> str`

获取元素的内部 HTML - 适用于网页抓取！

# 获取容器的内部 HTML
container = await page.find_element(By.CSS_SELECTOR, '.container')
html = await container.inner_html
print(f"内部 HTML: {html}")

`async get_element_text() -> str`

获取元素的文本内容 - 干净且可直接使用。

# 获取元素的文本
element = await page.find_element(By.CSS_SELECTOR, 'p')
text = await element.get_element_text()
print(f"文本: {text}")

`async click(x_offset: int = 0, y_offset: int = 0)`

精确点击元素 - 甚至可以带偏移量。

# 进行带偏移的点击
slider = await page.find_element(By.CSS_SELECTOR, '.slider')
# 在元素中心的右侧 10 像素处点击
await slider.click(x_offset=10, y_offset=0)

`async send_keys(text: str)`

快速向表单字段输入文本。

# 填写文本框
input_field = await page.find_element(By.CSS_SELECTOR, 'input[name="username"]')
await input_field.send_keys("user123")

`async type_keys(text: str)`

像真实用户一样逐键输入文本，模拟人工输入。

# 模拟真实输入 - 每个键之间有短暂停顿
password_field = await page.find_element(By.CSS_SELECTOR, 'input[type="password"]')
await password_field.type_keys("secure_password123")  # 真实的打字体验！

`async get_screenshot(path: str)`

捕获元素的截图 - 适用于测试或存档。

# 截取特定元素的截图
error_message = await page.find_element(By.CSS_SELECTOR, '.error-message')
await error_message.get_screenshot('/screenshots/error.png')

🚀 高级功能

事件系统

Pydoll 的事件系统让你的自动化变得更智能！实时监听并响应浏览器事件，使你的脚本更加动态。

`async on(event_name: str, callback: callable, temporary: bool = False) -> int`

为任何浏览器事件注册回调函数。例如，监听页面加载事件：

from pydoll.events.page import PageEvents
# 监听任何页面的导航事件
async def on_page_loaded(event):
    print(f"🌐 正在导航到: {event['params'].get('url')}")
await browser.enable_page_events()  # 激活页面事件
await browser.on(PageEvents.PAGE_LOADED, on_page_loaded) # 全局监听！

`async enable_network_events() -> None`

实时查看所有网络活动 - 适用于调试或 API 监控！

from pydoll.events.network import NetworkEvents
async def on_request(event):
    print(f"🔄 发送请求至: {event['params']['request']['url']}")
await browser.enable_network_events()
await browser.on(NetworkEvents.REQUEST_WILL_BE_SENT, on_request)

这只是 Pydoll 提供的一部分功能，你可以利用它来实现高效的自动化！🚀