【DrissionPage】入门指南及查找元素
目录
一、概述
二、特性
2.1 强大的内核
2.2 亮点功能
三、安装与升级
四、导包与简单示例
4.1 导包
4.2 简单示例
五、查找元素
5.1 概述
5.1.1 在页面中查找
5.1.2 在元素中查找
5.1.3 链式查找
5.1.4 相对查找
5.1.5 shadow root
5.1.6 简单示例
5.2 基本用法
5.2.1 查找元素的方法
ele()
eles()
5.2.2 匹配模式
精确匹配 =
模糊匹配 ：
匹配开头 ^
匹配结尾 $
5.2.3 查找语法
id 匹配符 #
class 匹配符 .
单属性匹配符 @
多属性与匹配符 @@
多属性或匹配符@|
属性否定匹配符@!
文本匹配符 text
文本匹配符 text()
@@text()的技巧
类型匹配符 tag
css selector 匹配符 css
xpath 匹配符 xpath
selenium 的 loc 元组
5.2.4 相对定位
获取父级元素
parent()
获取直接子节点
child()
children()
获取后面的同级节点
next()
nexts()
获取前面的同级节点
prev()
prevs()
在后面文档中查找节点
after()
afters()
在前面文档中查找节点
before()
befores()
5.3 更多用法
5.3.1 静态方式查找元素
s_ele()
s_eles()
5.3.2 获取当前焦点元素
5.3.3 iframe元素
查找 iframe 元素
在页面下跨级查找
在 iframe 元素下查找
5.3.4 ShadowRoot
5.3.5 等待
5.4 简化写法
5.4.1 定位符语法简化
5.4.2 shadow root 简化
5.4.3 相对定位参数简化
5.5 找不到元素时
5.5.1 默认情况
5.5.2 立即抛出异常
5.5.3 设置默认返回值
5.6 语法速查表
5.6.1 定位语法
基本用法
组合用法
简化写法
5.6.2 相对定位
5.6.3 其它
一、概述
DrissionPage 是一个基于 python 的网页自动化工具。
它既能控制浏览器，也能收发数据包，还能把两者合而为一。
可兼顾浏览器自动化的便利性和 requests 的高效率。
它功能强大，内置无数人性化设计和便捷功能。
它的语法简洁而优雅，代码量少，对新手友好。
二、特性
2.1 强大的内核
本库采用全自研的内核，内置了 N 多实用功能，对常用功能作了整合和优化，对比 selenium，有以下优点：
- 无 webdriver 特征
- 无需为不同版本的浏览器下载不同的驱动
- 运行速度更快
- 可以跨 iframe 查找元素，无需切入切出
- 把 iframe 看作普通元素，获取后可直接在其中查找元素，逻辑更清晰
- 可以同时操作浏览器中的多个标签页，即使标签页为非激活状态，无需切换
- 可以直接读取浏览器缓存来保存图片，无需用 GUI 点击另存
- 可以对整个网页截图，包括视口外的部分（90以上版本浏览器支持）
- 可处理非
open状态的 shadow-root
2.2 亮点功能
- 极简的语法规则。集成大量常用功能，代码更优雅
- 定位元素更加容易，功能更强大稳定
- 无处不在的等待和自动重试功能。使不稳定的网络变得易于控制，程序更稳定，编写更省心
- 提供强大的下载工具。操作浏览器时也能享受快捷可靠的下载功能
- 允许反复使用已经打开的浏览器。无需每次运行从头启动浏览器，调试超方便
- 使用 ini 文件保存常用配置，自动调用，提供便捷的设置，远离繁杂的配置项
- 内置 lxml 作为解析引擎，解析速度成几个数量级提升
- 使用 POM 模式封装，可直接用于测试，便于扩展
- 高度集成的便利功能，从每个细节中体现
三、安装与升级
# 安装
pip install DrissionPage
# 升级
pip install DrissionPage --upgrade
# 升级指定版本
pip install DrissionPage==4.0.0b17
四、导包与简单示例
4.1 导包
# 如果只要控制浏览器，导入ChromiumPage。
from DrissionPage import ChromiumPage
# 如果只要收发数据包，导入SessionPage。
from DrissionPage import SessionPage
# WebPage是功能最全面的页面类，既可控制浏览器，也可收发数据包。
from DrissionPage import WebPage
4.2 简单示例
from DrissionPage import ChromiumPage
# 导入
from DrissionPage import ChromiumPage
# 创建对象
page = ChromiumPage()
# 访问网页
page.get('https://www.baidu.com')
# 输入文本
page('#kw').input('DrissionPage')
# 点击按钮
page('#su').click()
# 等待页面跳转
page.wait.load_start()
# 获取所有结果
links = page.eles('tag:h3')
# 遍历并打印结果
for link in links:
print(link.text)五、查找元素
5.1 概述
本库提供一套简洁易用的语法，用于快速定位元素，并且内置等待功能、支持链式查找，减少了代码的复杂性。
同时也兼容 css selector、xpath、selenium 原生的 loc 元组。
定位元素大致分为三种方法：
- 在页面或元素内查找子元素
- 根据 DOM 结构相对定位
- 根据页面布局位置相对定位
使用方式
所有页面对象和元素对象，都可以在自己内部查找元素，元素对象还能以自己为基准，相对定位其它元素。
页面对象包括：SessionPage、ChromiumPage、ChromiumTab、ChromiumFrame、WebPage、WebPageTab
元素对象包括：SessionElement、ChromiumElement、ShadowRoot
5.1.1 在页面中查找
使用页面对象的ele()和eles()方法，获取页面内指定元素对象。
from DrissionPage import SessionPage
page = SessionPage()
page.get('https://www.baidu.com')
ele = page.ele('#su')5.1.2 在元素中查找
使用元素对象的ele()、eles()、child()、children()方法，获取元素内指定后代元素对象。
ele1 = page.ele('#s_fm')
ele2 = ele1.ele('#su')
son = ele1.child('tag:div') # 获取第一个直接div子元素
sons = ele1.children('tag:div') # 获取所有直接div子元素5.1.3 链式查找
因为对象本身又可以查找对象，所有支持链式操作，上面两个例子可合并为：
ele = page.ele('#s_fm').ele('#su')5.1.4 相对查找
元素对象在以自己为基准，执行相对查找。
ele = page.ele('#su')
parent = ele.parent(2) # 获取ele元素的第二层父元素
brother = ele.next('tag:a') # 获取ele元素后面的第一个a元素
after = ele.after('tag:div') # 获取ele后面文档中第一个div元素5.1.5 shadow root
使用浏览器元素对象的shadow_root属性获取该元素下的ShadowRoot对象。
shadow = page.ele('#ele1').shadow_root在 shadow root 元素中搜索方法与普通元素一致。
shadow = page.ele('#ele1').shadow_root
ele = shadow.ele('#ele2')5.1.6 简单示例
第一行
第二行
第三行
第二个div
id="su" class="btn self-btn bg s_btn">我们可以用页面对象去获取其中的元素：
# 获取 id 为 one 的元素
div1 = page.ele('#one')
# 获取 name 属性为 row1 的元素
p1 = page.ele('@name=row1')
# 获取包含“第二个div”文本的元素
div2 = page.ele('第二个div')
# 获取所有div元素
div_list = page.eles('tag:div')也可以获取到一个元素，然后在它里面或周围查找元素：
# 获取到一个元素div1
div1 = page.ele('#one')
# 在div1内查找所有p元素
p_list = div1.eles('tag:p')
# 获取div1后面一个元素
div2 = div1.next()5.2 基本用法
5.2.1 查找元素的方法
ele()
页面对象和元素对象都拥有此方法，用于查找其内部的一个条件匹配的元素。
页面对象和元素对象的ele()方法参数名称稍有不同，但用法一样。
SessionPage和ChromiumPage获取元素的方法是一致的，但前者返回的元素对象为SessionElement，后者是ChromiumElement。
| 参数名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
locator（元素对象） |
strTuple[str, str] |
必填 | 元素的定位信息。可以是查询字符串，或 loc 元组 |
locator（页面对象） |
strSessionElementTuple[str, str] |
必填 | 元素的定位信息。可以是查询字符串、loc 元组或一个SessionElement对象 |
index |
int |
1 |
获取第几个匹配的元素，从1开始，可输入负数表示从后面开始数 |
timeout |
float |
None |
等待元素出现的超时时间，为None使用页面对象设置，SessionPage中无效 |
| 返回类型 | 说明 |
|---|---|
SessionElement |
SessionPage或SessionElement查找到的第一个符合条件的元素对象 |
ChromiumElement |
浏览器页面对象或元素对象查找到的第一个符合条件的元素对象 |
ChromiumFrame |
当结果是框架元素时，会返回ChromiumFrame，但 IDE 中不会包含该提示 |
NoneElement |
未找到符合条件的元素时返回 |
说明
- loc 元组是指 selenium 定位符，例：(By.ID, 'XXXXX')。下同。
ele('xxxx', index=2)和eles('xxxx')[1]结果一样，不过前者会快很多。
示例：
from DrissionPage import SessionPage
page = SessionPage()
# 在页面内查找元素
ele1 = page.ele('#one')
# 在元素内查找后代元素
ele2 = ele1.ele('第二行') eles()
此方法与ele()相似，但返回的是匹配到的所有元素组成的列表。
页面对象和元素对象都可调用这个方法。
eles()返回的是普通列表，链式操作需加下标，如page.eles('...')[0].ele('...')。
| 参数名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
locator |
strTuple[str, str] |
必填 | 元素的定位信息，可以是查询字符串，或 loc 元组 |
timeout |
float |
None |
等待元素出现的超时时间，为None使用页面对象设置，SessionPage中无效 |
| 返回类型 | 说明 |
|---|---|
List[SessionElement] |
SessionPage或SessionElement找到的所有元素组成的列表 |
List[ChromiumElement, ChromiumFrame] |
浏览器页面对象或元素对象找到的所有元素组成的列表 |
示例：
# 获取页面内的所有p元素
p_eles = page.eles('tag:p')
# 获取ele1元素内的所有p元素
p_eles = ele1.eles('tag:p')
# 打印第一个p元素的文本
print(p_eles[0])5.2.2 匹配模式
精确匹配 =
表示精确匹配，匹配完全符合的文本或属性。
# 获取name属性为'row1'的元素
ele = page.ele('@name=row1')模糊匹配 ：
表示模糊匹配，匹配含有指定字符串的文本或属性。
# 获取name属性包含'row1'的元素
ele = page.ele('@name:row1') 匹配开头 ^
表示匹配开头，匹配开头为指定字符串的文本或属性。
# 获取name属性以'row1'开头的元素
ele = page.ele('@name^ro')匹配结尾 $
表示匹配结尾，匹配结尾为指定字符串的文本或属性。
# 获取name属性以'w1'结尾的元素
ele = page.ele('@name$w1')5.2.3 查找语法
id 匹配符 #
表示id属性，只在语句最前面且单独使用时生效，可配合匹配模式使用。
# 在页面中查找id属性为one的元素
ele1 = page.ele('#one')
# 在ele1元素内查找id属性包含ne文本的元素
ele2 = ele1.ele('#:ne')
class 匹配符 .
表示class属性，只在语句最前面且单独使用时生效，可配合匹配模式使用。
# 查找class属性为p_cls的元素
ele2 = ele1.ele('.p_cls')
# 查找class属性'_cls'文本开头的元素
ele2 = ele1.ele('.^_cls')
因为只加 . 时默认是精确匹配元素属性 class，所以如果某元素有多个类名，必须写 class 属性的完整值（类名的顺序也不能变）。如果需要只匹配多个类名中的一个，可以使用模糊匹配符 :。
# 精确查找class属性为`p_cls1 p_cls2 `的元素
ele2 = ele1.ele('.p_cls1 p_cls2 ')
# 模糊查找class属性含有类名 'p_cls2' 的元素
ele2 = ele1.ele('.:p_cls2')
若仍需要更复杂的匹配方式，请使用多属性匹配符。
单属性匹配符 @
表示某个属性，只匹配一个属性。
@关键字只有一个简单功能，就是匹配@后面的内容，不再对后面的字符串进行解析。因此即使后面的字符串也存在@或@@ ，也作为要匹配的内容对待。所以只要是多属性匹配，包括第一个属性在内的所有属性都必须用@@开头。
注意
如果属性中包含特殊字符（如包含@），用这个方式不能正确匹配到，需使用 css selector 方式查找。且特殊字符要用\转义。
# 查找name属性为row1的元素
ele2 = ele1.ele('@name=row1')
# 查找name属性包含row文本的元素
ele2 = ele1.ele('@name:row')
# 查找name属性以row开头的元素
ele2 = ele1.ele('@name^row')
# 查找有name属性的元素
ele2 = ele1.ele('@name')
# 查找没有任何属性的元素
ele2 = ele1.ele('@')
# 查找email属性为[email protected]的元素，有多个@也不会重复处理
ele2 = ele1.ele('@[email protected]')
# 属性中有特殊字符的情形，匹配abc@def属性等于v的元素
ele2 = ele1.ele('css:div[abc\@def="v"]')
多属性与匹配符 @@
匹配同时符合多个条件的元素时使用，每个条件前面添加@@作为开头。
注意
- 匹配文本或属性中出现
@@、@|、@!时，不能使用多属性匹配，需改用 xpath 的方式。- 如果属性中包含特殊字符（如包含
@），用这个方式不能正确匹配到，需使用 css selector 方式查找。且特殊字符要用\转义。
# 查找name属性为row1且class属性包含cls文本的元素
ele2 = ele1.ele('@@name=row1@@class:cls')
@@可以与下文介绍的tag配合使用：
ele = page.ele('tag:div@@class=p_cls@@name=row1')
多属性或匹配符@|
匹配符合多个条件中任一项的元素时使用，每个条件前面添加@|作为开头。
用法与@@一致，注意事项与@@一致。
注意
@@和@|不能同时出现在语句中。
# 查找id属性为one或id属性为two的元素
ele2 = ele1.ele('@|id=one@|id=two')
@|可以与下文介绍的tag配合使用：
ele = page.ele('tag:div@|class=p_cls@|name=row1')
属性否定匹配符@!
用于否定某个条件，可与@@或@|混用，也可单独使用。
混用时，与还是或关系视@@还是@|而定。
示例：
# 匹配arg1等于abc且arg2不等于def的元素
page.ele('@@arg1=abc@!arg2=def')
# 匹配arg1等于abc或arg2不等于def的div元素
page.ele('t:div@|arg1=abc@!arg2=def')
# 匹配arg1不等于abc
page.ele('@!arg1=abc')
# 匹配没有arg1属性的元素
page.ele('@!arg1')
文本匹配符 text
要匹配的文本，查询字符串如开头没有任何关键字，也表示根据传入的文本作模糊查找。
如果元素内有多个直接的文本节点，精确查找时可匹配所有文本节点拼成的字符串，模糊查找时可匹配每个文本节点。
没有任何匹配符时，默认匹配文本。
# 查找文本为“第二行”的元素
ele2 = ele1.ele('text=第二行')
# 查找文本包含“第二”的元素
ele2 = ele1.ele('text:第二')
# 与上一行一致
ele2 = ele1.ele('第二')
TIPS
若要查找的文本包含
text:，可下面这样写，即第一个text:为关键字，第二个是要查找的内容：
ele2 = page.ele('text:text:')
文本匹配符 text()
作为查找属性时使用的文本关键字，必须与@或@@配合使用。
# 查找文本为“第二行”的元素
ele2 = ele1.ele('@text()=第二行')
# 查找文本包含“第二行”的元素
ele2 = ele1.ele('@text():二行')
# 查找文本以“第二”开头且class属性为p_cls的元素
ele2 = ele1.ele('@@text()^第二@@class=p_cls')
# 查找文本为“二行”且没有任何属性的元素（因第一个 @@ 后为空）
ele2 = ele1.ele('@@@@text():二行')
# 查找直接子文本包含“二行”字符串的元素
ele = page.ele('@text():二行')
@@text()的技巧
值得一提的是，text()配合@@或@|能实现一种很便利的按查找方式。
网页种经常会出现元素和文本混排的情况，比如：
前沿技术
程序开发
ele = page.ele('text:前沿技术')
# 或
ele = page.ele('@text():前沿技术')
这两种写法都能获取到包含直接文本的元素。
但如果要用文本获取元素，就获取不到，因为文本不是的直接内容。
我们可以这样写：
ele = page.ele('tag:li@@text():前沿技术')
@@text()与@text()不同之处在于，前者可以搜索整个元素内所有文本，而不仅仅是直接文本，因此能实现一些非常灵活的查找。
注意
需要注意的是，使用
@@或@|时，text()不要作为唯一的查询条件，否则会定位到整个文档最高层的元素。❌ 错误做法：
ele = page.ele('@@text():前沿技术') ele = page.ele('@|text():前沿技术@|text():程序开发')⭕ 正确做法：
ele = page.ele('tag:li@|text():前沿技术@|text():程序开发')
类型匹配符 tag
表示元素的标签，只在语句最前面且单独使用时生效，可与@、@@或@|配合使用。tag:与tag=效果一致，没有tag^和tag$语法。
# 定位div元素
ele2 = ele1.ele('tag:div')
# 定位class属性为p_cls的p元素
ele2 = ele1.ele('tag:p@class=p_cls')
# 定位文本为"第二行"的p元素
ele2 = ele1.ele('tag:p@text()=第二行')
# 定位class属性为p_cls且文本为“第二行”的p元素
ele2 = ele1.ele('tag:p@@class=p_cls@@text()=第二行')
# 定位class属性为p_cls或文本为“第二行”的p元素
ele2 = ele1.ele('tag:p@|class=p_cls@|text()=第二行')
# 查找直接文本节点包含“二行”字符串的p元素
ele2 = ele1.ele('tag:p@text():二行')
# 查找内部文本节点包含“二行”字符串的p元素
ele2 = ele1.ele('tag:p@@text():二行')
注意
tag:div@text():text和tag:div@@text():text是有区别的，前者只在div的直接文本节点搜索，后者搜索div的整个内部。
css selector 匹配符 css
表示用 css selector 方式查找元素。css:与css=效果一致，没有css^和css$语法。
# 查找 div 元素
ele2 = ele1.ele('css:.div')
# 查找 div 子元素元素，这个写法是本库特有，原生不支持
ele2 = ele1.ele('css:>div')
xpath 匹配符 xpath
表示用 xpath 方式查找元素。xpath:与xpath=效果一致，没有xpath^和xpath$语法。
另外，元素对象的ele()支持完整的 xpath 语法，如能使用 xpath 直接获取元素属性（字符串类型）。
# 查找后代中第一个 div 元素
ele2 = ele1.ele('xpath:.//div')
# 和上面一行一样，查找元素的后代时，// 前面的 . 可以省略
ele2 = ele1.ele('xpath://div')
# 使用xpath获取div元素的class属性（页面元素无此功能）
ele_class_str = ele1.ele('xpath://div/@class')
TIPS
查找元素的后代时，selenium 原生代码要求 xpath 前面必须加
.，否则会变成在全个页面中查找。 作者觉得这个设计是画蛇添足，既然已经通过元素查找了，自然应该只查找这个元素内部的元素。 所以，用 xpath 在元素下查找时，最前面//或/前面的.可以省略。
selenium 的 loc 元组
查找方法能直接接收 selenium 原生定位元组进行查找，便于项目迁移。
from DrissionPage.common import By
# 查找id为one的元素
loc1 = (By.ID, 'one')
ele = page.ele(loc1)
# 按 xpath 查找
loc2 = (By.XPATH, '//p[@class="p_cls"]')
ele = page.ele(loc2)
5.2.4 相对定位
以下方法可以以某元素为基准，在 DOM 中按照条件获取其直接子节点、同级节点、祖先元素、文档前后节点。
TIPS
这里说的是“节点”，不是“元素”。因为相对定位可以获取除元素外的其它节点，包括文本、注释节点。
注意
如果元素在