DrissionPage 使用指南

DrissionPage 是一个强大的 Python 库，用于浏览器自动化和网页爬取。它提供了便捷的浏览器控制、标签页操作、元素定位和 iframe 处理功能。以下是基于提供的笔记补充完善后的详细指南。

---

一、浏览器对象

1. 创建并启动浏览器对象

通过 Chromium 类可以创建并连接到一个浏览器实例。

from DrissionPage import Chromium

# 连接浏览器，addr_or_opts 为浏览器启动配置
browser = Chromium(addr_or_opts=None, session_options=None)

• addr_or_opts：可以是浏览器的地址（如 "127.0.0.1:9222"）或 ChromiumOptions 对象，用于配置浏览器启动参数。
• session_options：会话相关的配置，控制浏览器行为，如是否保存会话数据。

2. 退出浏览器对象

关闭浏览器并释放资源。

browser.quit()

3. 配置浏览器对象

通过 ChromiumOptions 类设置浏览器启动参数。

（1）创建配置对象

from DrissionPage import ChromiumOptions

# 创建配置对象，默认从 ini 文件读取配置
co = ChromiumOptions()

• 常用配置方法：
  • no_imgs(True)：禁用图片加载，节省带宽。
  • mute(True)：静音，禁用浏览器音频。
  • incognito()：启用匿名模式，关闭浏览器后不保存浏览记录、Cookie 等。
  • headless(True)：启用无头模式，浏览器无 GUI 界面，后台运行，节省资源。

（2）参数设置

通过 set_argument() 添加启动参数，参数以 -- 开头，控制浏览器行为。

# 禁用沙盒模式（降低安全性，需谨慎）
co.set_argument('--no-sandbox')

# 启动时最大化窗口
co.set_argument('--start-maximized')

# 设置初始窗口大小
co.set_argument('--window-size', '800,600')

# 使用来宾模式
co.set_argument('--guest')

# 增强反检测设置（防止被识别为自动化脚本）
co.set_argument('--disable-blink-features=AutomationControlled')
co.set_argument('--disable-dev-shm-usage')
co.set_argument('--window-size=1920,1080')

（3）移除参数

删除已设置的启动参数。

# 删除指定参数
co.remove_argument('--start-maximized')
co.remove_argument('--window-size')

# 清空所有已设置参数
co.clear_arguments()

（4）设置 User-Agent

设置 User-Agent，防止在无头模式下被识别为爬虫。

co.set_user_agent('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36')

---

二、标签页对象

标签页对象用于操作浏览器中的单个标签页（如跳转网页、设置 Cookie、截图等）。

1. 获取标签页对象

（1）get_tab()

获取单个标签页对象或其 ID。

from DrissionPage import Chromium

browser = Chromium()
tab = browser.get_tab()  # 获取默认标签页
tab = browser.get_tab(tab_id='tab_id')  # 通过 ID 获取指定标签页

（2）get_tabs()

获取多个符合条件的标签页对象或 ID 列表。

tabs = browser.get_tabs()  # 获取所有标签页
tabs = browser.get_tabs(title='example')  # 获取标题包含 'example' 的标签页

（3）latest_tab

获取最新打开的标签页对象或 ID。

tab = browser.latest_tab

2. 跳转网页

（1）get()

通过 GET 请求加载网页。

tab = Chromium().latest_tab
tab.get(
    url='http://DrissionPage.cn',
    retry=1,      # 重试次数，默认 3
    interval=1,   # 重试间隔（秒），默认 2
    timeout=1.5   # 加载超时时间（秒）
)

（2）post()

通过 POST 请求加载网页，适用于需要提交数据的场景。

tab.post(
    url='http://example.com',
    data={'key': 'value'},
    retry=1,
    interval=1,
    timeout=1.5
)

3. 设置 Cookie

为标签页设置 Cookie。

tab.set.cookies([{'name': 'key', 'value': 'value', 'domain': '.example.com'}])

4. 查看 Cookie

获取当前标签页的 Cookie。

cookies = tab.cookies(all_domains=True)  # 获取所有域的 Cookie
for cookie in cookies:
    print(cookie)

5. 屏幕截图

保存当前标签页的截图。

tab.get_screenshot(
    path='tmp',          # 存放图片的文件夹路径
    name='screenshot.png',  # 图片文件名
    full_page=True       # 是否截取整个页面
)

6. 鼠标滚轮滚动屏幕

使用 Actions 类控制页面滚动。

from DrissionPage._units.actions import Actions

ac = Actions(tab)
ac.scroll(1000)  # 向下滚动 1000 像素
ac.scroll(-500)  # 向上滚动 500 像素

---

三、元素对象

元素对象用于定位和操作网页中的 HTML 元素。

1. 定位语法（获取元素）

（1）@ 语法

@ 语法用于通过标签名、属性或文本定位元素。

• 基本形式：
  • @tag()=标签名：匹配指定标签。
  • @属性名=属性值：匹配指定属性值。
  • @text()=文本：匹配指定文本内容。

# 获取 id 为 'one' 的元素
tab.ele('@id=one')

# 获取第一个 div 元素
tab.ele('@tag()=div')

# 获取文本为“第一行”的元素
tab.ele('@text()=第一行')

• 逻辑匹配：
  • @@：与，匹配同时满足多个条件的元素。
  • @|：或，匹配满足任一条件的元素。
  • @!：非，匹配不满足某条件的元素。

# 查找 class 为 'p_cls' 且文本为“第三行”的元素
tab.ele('@@class=p_cls@@text()=第三行')

# 查找 id 为 'row1' 或 'row2' 的元素
tab.eles('@|id=row1@|id=row2')

# 查找 id 不为 'one' 的元素
tab.ele('@!id=one')

# 查找没有 class 属性的元素
tab.ele('@!class')

# 混合使用
tab.ele('@@class=p_cls@!id=row1')  # class 为 'p_cls' 且 id 不为 'row1'
tab.ele('@|class=p_cls@!id=row1')  # class 为 'p_cls' 或 id 不为 'row1'

• 注意：
  • 特殊字符（如 @）需使用 CSS Selector 或 XPath 方式查找，并进行转义。
  • @@ 和 @| 不可同时出现在同一查找语句中。

（2）其他常用语法

• ID 匹配符 #：

tab.ele('#one')  # 查找 id 为 'one' 的元素
tab.ele('#:ne')  # 查找 id 包含 'ne' 的元素
tab.ele('#^on')  # 查找 id 以 'on' 开头的元素
tab.ele('#$ne')  # 查找 id 以 'ne' 结尾的元素

• Class 匹配符 .：

tab.ele('.p_cls')  # 查找 class 为 'p_cls' 的元素
tab.ele('.:_cls')  # 查找 class 包含 '_cls' 的元素
tab.ele('.^p_')   # 查找 class 以 'p_' 开头的元素
tab.ele('.$_cls') # 查找 class 以 '_cls' 结尾的元素

• 文本匹配符 text：

tab.ele('text=第二行')  # 查找文本为“第二行”的元素
tab.ele('text:第二')     # 查找文本包含“第二”的元素
tab.ele('第\u00A0二')    # 匹配包含   的文本（需转义为 \u00A0）

• 标签匹配符 tag：

tab.ele('tag:div')  # 查找第一个 div 元素
tab.ele('tag:p@@class=p_cls@@text()=第二行')  # 查找 p 标签且 class 为 'p_cls' 且文本为“第二行”的元素

• CSS Selector 匹配符 css：

tab.ele('css:.div')  # 查找 class 为 'div' 的元素
tab.ele('css:>div')  # 查找直接子 div 元素（DrissionPage 特有）

• XPath 匹配符 xpath：

ele2 = ele1.ele('xpath:.//div')  # 查找 ele1 后代中的第一个 div
ele2 = ele1.ele('xpath://div')   # 同上，.// 可省略 .
ele_class = ele1.ele('xpath://div/@class')  # 获取 div 元素的 class 属性

• Selenium 的 loc 元组：

from DrissionPage.common import By

loc1 = (By.ID, 'one')
tab.ele(loc1)  # 查找 id 为 'one' 的元素

loc2 = (By.XPATH, '//p[@class="p_cls"]')
tab.ele(loc2)  # 按 XPath 查找

（3）匹配模式

• 精确匹配 =：

tab.ele('@id=row1')  # id 精确为 'row1'

• 模糊匹配 :：

tab.ele('@id:ow')  # id 包含 'ow'

• 匹配开头 ^：

tab.ele('@id^row')  # id 以 'row' 开头

• 匹配结尾 $：

tab.ele('@id$w1')  # id 以 'w1' 结尾

2. 页面或元素内查找（相对定位）

在元素内部查找子孙元素，使用 ele() 或 eles() 方法。

# 在 tab 中查找 id 为 'parent' 的元素
parent = tab.ele('@id=parent')

# 在 parent 元素内查找 class 为 'child' 的子元素
child = parent.ele('@class=child', timeout=5)  # 等待 5 秒

# 获取 parent 内所有 class 为 'child' 的子元素
children = parent.eles('@class=child')

• timeout：设置等待元素出现的时间（秒），类似 Selenium 的显式等待。

3. 相对定位（父子孙元素）

（1）获取直接子节点

• child()：返回单个直接子节点。

child = parent.child('@class=child')  # 获取第一个 class 为 'child' 的子节点
child = parent.child(index=2)         # 获取第二个子节点

• children()：返回所有符合条件的直接子节点列表。

children = parent.children('@class=child')  # 获取所有 class 为 'child' 的子节点

（2）获取父节点

parent = child.parent()  # 获取直接父节点
parent = child.parent('@tag=div')  # 获取符合条件的父节点

（3）获取兄弟节点

sibling = child.next()   # 获取下一个兄弟节点
siblings = child.nexts() # 获取所有后续兄弟节点
sibling = child.prev()   # 获取上一个兄弟节点
siblings = child.prevs() # 获取所有前序兄弟节点

4. 获取元素信息

（1）text

获取元素内所有文本（已格式化，移除多余换行，适合阅读）。

text = ele.text  # 获取元素文本

（2）attr()

获取元素指定属性的值（如 src、href），无该属性时返回 None。

src = ele.attr('src')  # 获取 src 属性（自动补全完整路径）
href = ele.attr('href')  # 获取 href 属性
class_name = ele.attrs['class']  # 获取原始 class 属性值

---

四、iframe 操作

1. 获取 iframe 对象

通过 get_frame() 获取页面中的 <frame> 或 <iframe> 对象。

frame = tab.get_frame('@id=frame1')  # 获取 id 为 'frame1' 的 iframe
frame = tab.get_frame('css:iframe')  # 使用 CSS Selector 获取 iframe

2. 切换到 iframe

在 iframe 内操作元素前，需切换上下文。

tab.to_frame(frame)  # 切换到指定 iframe
tab.to_main_frame()  # 切换回主页面

3. 在 iframe 内查找元素

切换到 iframe 后，可使用与主页面相同的定位方法查找元素。

tab.to_frame(frame)
ele = tab.ele('@id=inner_element')  # 在 iframe 内查找元素

---

五、其他实用功能

1. 页面刷新

tab.refresh()  # 刷新当前标签页

2. 执行 JavaScript

result = tab.run_js('return document.title;')  # 执行 JS 并获取返回值
tab.run_js('alert("Hello!");')  # 执行 JS 代码

3. 等待元素出现

ele = tab.ele('@id=delayed_element', timeout=10)  # 等待元素出现，最多 10 秒

4. 处理弹窗

tab.handle_alert(accept=True)  # 接受弹窗
tab.handle_alert(accept=False, text='input text')  # 拒绝弹窗并输入文本

---

六、注意事项

• 反检测：使用 disable-blink-features=AutomationControlled 和自定义 User-Agent 可有效降低被检测为自动化的风险。
• 超时设置：合理设置 timeout、retry 和 interval 参数，确保在网络不稳定时有足够的容错能力。
• 特殊字符：在定位包含特殊字符的元素时，优先使用 CSS Selector 或 XPath，并正确转义。
• 无头模式：适合服务器环境，但需确保反检测设置完善以避免被拦截。

---

此指南涵盖了 DrissionPage 的核心功能，适用于浏览器自动化、网页爬取和元素操作任务。根据实际需求，可结合官方文档进一步深入学习。