blackteay/DrissionPage
1
0
Fork 0
mirror of https://gitee.com/g1879/DrissionPage.git synced 2024-12-10 04:00:23 +08:00
Code Issues Projects Releases Wiki Activity

3.0.28修改文档

Browse Source
This commit is contained in:
g1879 2023-01-04 16:45:13 +08:00
parent 57273ca79d
commit be9fe5ab79
34 changed files with 1583 additions and 1401 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/MixPage使用方法/Drission对象.md
View File

@ -2,14 +2,14 @@
可直接读取 ini 文件配置信息创建，也可以在初始化时传入配置信息。 可直接读取 ini 文件配置信息创建，也可以在初始化时传入配置信息。
在“[使用方法->创建页面对象](创建页面对象.md)”章节已经涉及过`Drission`的用法，这里介绍属性和方法。 在“[使用方法->创建页面对象](创建页面对象.md)”章节已经涉及过`Drission`的用法，这里介绍属性和方法。
# `Drission`类 # ✔️ `Drission`类
初始化参数： **初始化参数：**
- driver_or_options：`WebDriver`对象或`DriverOptions`、`Options`类，传入`False`则创建空配置对象 - `driver_or_options`：`WebDriver`对象或`DriverOptions`、`Options`类，传入`False`则创建空配置对象
- session_or_options：`Session`对象或设置字典，传入`False`则创建空配置对象 - `session_or_options`：`Session`对象或设置字典，传入`False`则创建空配置对象
- ini_path：ini 文件路径 - `ini_path`：ini 文件路径
- proxy：代理设置，`dict`类型。格式：{'http': '127.0.0.1:1080', 'https': '127.0.0.1:1080'} - `proxy`：代理设置，`dict`类型。格式：{'http': '127.0.0.1:1080', 'https': '127.0.0.1:1080'}
前两个参数可直接接收`WebDriver`和`Session`对象，这时后面两个参数无效。 前两个参数可直接接收`WebDriver`和`Session`对象，这时后面两个参数无效。
若接收配置对象，则按照配置创建`WebDriver`和`Session`对象。 若接收配置对象，则按照配置创建`WebDriver`和`Session`对象。
@ -35,117 +35,117 @@ do = DriverOptions()
drission = Drission(driver_options=do) drission = Drission(driver_options=do)
``` ```
## session ## 📍 `session`
此属性返回该对象管理的`Session`对象。 此属性返回该对象管理的`Session`对象。
## driver ## 📍 `driver`
此属性返回该对象管理的`WebDriver`对象。 此属性返回该对象管理的`WebDriver`对象。
## driver_options ## 📍 `driver_options`
此属性返回用于创建`WebDriver`对象的`DriverOptions`对象。 此属性返回用于创建`WebDriver`对象的`DriverOptions`对象。
## session_options ## 📍 `session_options`
此属性以`dict`形式返回用于创建 Session 对象的配置参数。可传入`dict`或`SessionOptions`赋值。 此属性以`dict`形式返回用于创建 Session 对象的配置参数。可传入`dict`或`SessionOptions`赋值。
## proxy ## 📍 `proxy`
此属性返回代理信息，`dict`形式。可传入`dict`赋值。格式：{'http': '127.0.0.1:1080', 'https': '127.0.0.1:1080'} 此属性返回代理信息，`dict`形式。可传入`dict`赋值。格式：{'http': '127.0.0.1:1080', 'https': '127.0.0.1:1080'}
## debugger_progress ## 📍 `debugger_progress`
此属性返回浏览器进程（如有）。 此属性返回浏览器进程（如有）。
## kill_browser() ## 📍 `kill_browser()`
此方法用于关闭浏览器进程。 此方法用于关闭浏览器进程。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## get_browser_progress_id() ## 📍 `get_browser_progress_id()`
此方法用于获取浏览器进程 id。 此方法用于获取浏览器进程 id。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## hide_browser() ## 📍 `hide_browser()`
此方法用于隐藏浏览器进程窗口。 此方法用于隐藏浏览器进程窗口。
参数：无 **参数：** 无
返回： `None` **返回：**`None`
## show_browser() ## 📍 `show_browser()`
此方法用于显示浏览器进程窗口。 此方法用于显示浏览器进程窗口。
参数：无 **参数：** 无
返回： `None` **返回：**`None`
## set_cookies() ## 📍 `set_cookies()`
此方法用于设置`cookies`。可选择对某个对象设置。 此方法用于设置`cookies`。可选择对某个对象设置。
参数： **参数：**
- cookies：`cookies`信息，可为`CookieJar`,`list`,`tuple`,`str`,`dict` - `cookies`：`cookies`信息，可为`CookieJar`,`list`,`tuple`,`str`,`dict`
- set_session：是否设置`Session`对象的`cookies` - `set_session`：是否设置`Session`对象的`cookies`
- set_driver：是否设置浏览器的`cookies` - `set_driver`：是否设置浏览器的`cookies`
返回：None **返回：**`None`
## cookies_to_session() ## 📍 `cookies_to_session()`
此方法用于把`WebDriver`对象的`cookies`复制到`Session`对象。 此方法用于把`WebDriver`对象的`cookies`复制到`Session`对象。
参数： **参数：**
- copy_user_agent：是否复制 user agent 信息 - `copy_user_agent`：是否复制 user agent 信息
返回：None **返回：**`None`
## cookies_to_driver() ## 📍 `cookies_to_driver()`
此方法用于把`Session`对象的`cookies`复制到`WebDriver`对象。 此方法用于把`Session`对象的`cookies`复制到`WebDriver`对象。
复制`cookies`到浏览器必须指定域名。 复制`cookies`到浏览器必须指定域名。
参数： **参数：**
- url：作用域 - `url`：作用域
返回：`None` **返回：**`None`
## close_driver() ## 📍 `close_driver()`
此方法用于关闭`WebDriver`对象，可选择是否关闭浏览器进程。 此方法用于关闭`WebDriver`对象，可选择是否关闭浏览器进程。
参数： **参数：**
- kill：是否关闭浏览器进程 - `kill`：是否关闭浏览器进程
返回：None **返回：**`None`
## close_session() ## 📍 `close_session()`
此方法用于关闭`Session`对象。 此方法用于关闭`Session`对象。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## close() ## 📍 `close()`
此方法用于关闭`Session`和`WebDriver`对象。 此方法用于关闭`Session`和`WebDriver`对象。
参数：无 **参数：** 无
返回：`None` **返回：**`None`

5
docs/MixPage使用方法/DriverPage和SessionPage.md
View File

@ -1,7 +1,7 @@
如果无须切换模式，可根据需要只使用 DriverPage 或 SessionPage。 如果无须切换模式，可根据需要只使用 DriverPage 或 SessionPage。
分别对应 d 和 s 模式，用法和 MixPage 相似。 分别对应 d 和 s 模式，用法和 MixPage 相似。
# SessionPage # ✔️ SessionPage
```python ```python
from DrissionPage.session_page import SessionPage from DrissionPage.session_page import SessionPage
@ -18,7 +18,7 @@ page.get('http://www.baidu.com')
print(page.ele('#su').text) print(page.ele('#su').text)
``` ```
# DriverPage # ✔️ DriverPage
```python ```python
from DrissionPage.driver_page import DriverPage from DrissionPage.driver_page import DriverPage
@ -34,4 +34,3 @@ page.get('http://www.baidu.com')
# 输出：百度一下 # 输出：百度一下
print(page.ele('#su').text) print(page.ele('#su').text)
``` ```

5
docs/MixPage使用方法/cookies的使用.md
View File

@ -14,7 +14,4 @@ page.get_cookies(all_domains=True)
page.set_cookies(cookies) page.set_cookies(cookies)
``` ```
?> **Tips:** <br> ?> **Tips:** <br>d 模式设置`cookies`后要刷新页面才能看到效果。 <br>s 模式可在 ini 文件、`SessionOptions`、配置字典中设置`cookies`，在`MixPage`初始化时即可传入，d 模式只能用`set_cookies()`函数设置。
d 模式设置`cookies`后要刷新页面才能看到效果。 <br>
s 模式可在 ini 文件、`SessionOptions`、配置字典中设置`cookies`，在`MixPage`初始化时即可传入，d 模式只能用`set_cookies()`函数设置。

234
docs/MixPage使用方法/元素操作.md
View File

@ -1,8 +1,8 @@
d 模式下的`DriverElement`对象可以对浏览器相应元素进行控制。 d 模式下的`DriverElement`对象可以对浏览器相应元素进行控制。
# 元素操作方法 # ✔️ 元素操作方法
## click() ## 📍 `click()`
此方法用于点击元素。可以选择是否用 js 方式点击，可以在点击失败时自动重试。默认情况下，使用 selenium 原生的点击方法，如果重试超过限定时间，自动改用 js 方式点击。可通过`by_js`参数设置点击方式。 此方法用于点击元素。可以选择是否用 js 方式点击，可以在点击失败时自动重试。默认情况下，使用 selenium 原生的点击方法，如果重试超过限定时间，自动改用 js 方式点击。可通过`by_js`参数设置点击方式。
此设计除了可保证点击成功，还可以用于检测页面上的遮罩层是否消失。遮罩层经常出现在 js 方式翻页的时候，它出现的时候会阻碍 selenium 此设计除了可保证点击成功，还可以用于检测页面上的遮罩层是否消失。遮罩层经常出现在 js 方式翻页的时候，它出现的时候会阻碍 selenium
@ -11,12 +11,12 @@ d 模式下的`DriverElement`对象可以对浏览器相应元素进行控制。
!> 注意：<br>使用 js 方式点击时，是不会进行重试的。 !> 注意：<br>使用 js 方式点击时，是不会进行重试的。
参数： **参数：**
- by_js：是否用 js 方式点击，为`None`时先用 selenium 原生方法点击，重试失败超时后改为用 js 点击；为`True`时直接用 js 点击；为`False`时即使重试超时也不会改用 js。 - `by_js`：是否用 js 方式点击，为`None`时先用 selenium 原生方法点击，重试失败超时后改为用 js 点击；为`True`时直接用 js 点击；为`False`时即使重试超时也不会改用 js。
- timeout：点击失败重试超时时间，为`None`时使用父页面`timeout`设置。 - `timeout`：点击失败重试超时时间，为`None`时使用父页面`timeout`设置。
返回：`bool`，表示是否点击成功。 **返回：**`bool`，表示是否点击成功。
```python ```python
# 点击一个元素，重试超时根据所在页面元素而定，都失败就改用 js 点击 # 点击一个元素，重试超时根据所在页面元素而定，都失败就改用 js 点击
@ -30,19 +30,19 @@ ele.click(timeout = 10) # 不断重试点击，直到遮罩层消失，或到
ele.click(by_js=True) # 无视遮罩层，直接用 js 点击下方元素 ele.click(by_js=True) # 无视遮罩层，直接用 js 点击下方元素
``` ```
## click_at() ## 📍 `click_at()`
此方法用于带偏移量点击元素，偏移量相对于元素左上角坐标。不传入`x`或`y`值时点击元素中点。可选择是否用 js 方式点击，但不会进行重试。 此方法用于带偏移量点击元素，偏移量相对于元素左上角坐标。不传入`x`或`y`值时点击元素中点。可选择是否用 js 方式点击，但不会进行重试。
可用于点击一些奇怪的东西，比如用伪元素表示的控件。 可用于点击一些奇怪的东西，比如用伪元素表示的控件。
点击的目标不一定在元素上，可以传入负值，或大于元素大小的值，点击元素附近的区域。向右和向下为正值，向左和向上为负值。 点击的目标不一定在元素上，可以传入负值，或大于元素大小的值，点击元素附近的区域。向右和向下为正值，向左和向上为负值。
参数： **参数：**
- x：相对元素左上角坐标的 x 轴偏移量 - `x`：相对元素左上角坐标的 x 轴偏移量
- y：相对元素左上角坐标的 y 轴偏移量 - `y`：相对元素左上角坐标的 y 轴偏移量
- by_js：是否用 js 点击 - `by_js`：是否用 js 点击
返回：`None` **返回：**`None`
```python ```python
# 点击元素右上方 50*50 的位置 # 点击元素右上方 50*50 的位置
@ -55,35 +55,35 @@ ele.click_at(x=50)
ele.click_at() ele.click_at()
``` ```
## r_click() ## 📍 `r_click()`
此方法实现右键单击元素。 此方法实现右键单击元素。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
```python ```python
ele.r_click() ele.r_click()
``` ```
## r_click_at() ## 📍 `r_click_at()`
此方法用于带偏移量右键点击元素，用法和`click_at()`相似，但没有`by_js`参数。 此方法用于带偏移量右键点击元素，用法和`click_at()`相似，但没有`by_js`参数。
参数： **参数：**
- x：相对元素左上角坐标的x轴偏移量 - `x`：相对元素左上角坐标的x轴偏移量
- y：相对元素左上角坐标的y轴偏移量 - `y`：相对元素左上角坐标的y轴偏移量
返回：`None` **返回：** `None`
```python ```python
# 点击距离元素左上角 50*50 的位置（位于元素内部） # 点击距离元素左上角 50*50 的位置（位于元素内部）
ele.r_click_at(50, 50) ele.r_click_at(50, 50)
``` ```
## input() ## 📍 `input()`
此方法用于向元素输入文本或组合键，也可用于输入文件路径到`input`元素（文件间用`\n`间隔）。可选择输入前是否清空元素。 此方法用于向元素输入文本或组合键，也可用于输入文件路径到`input`元素（文件间用`\n`间隔）。可选择输入前是否清空元素。
insure 参数为 `True` 时可自动确保输入正确。该功能是为了应对 selenium 原生输入在某些i情况下会失效的问题。但只能用于 input 元素且 `type` 为 `text` 的情况。 接收组合键的时候可接收 insure 参数为 `True` 时可自动确保输入正确。该功能是为了应对 selenium 原生输入在某些i情况下会失效的问题。但只能用于 input 元素且 `type` 为 `text` 的情况。 接收组合键的时候可接收
@ -91,14 +91,14 @@ selenium 的 `Keys` 对象的值。组合键要放在一个 `tuple` 中传入。
!> **注意：** <br>`insure` 为 `True` 时不能用于接收组合键。 !> **注意：** <br>`insure` 为 `True` 时不能用于接收组合键。
?> **Tips:** <br>- 有些文本框可以接收回车代替点击按钮，可以直接在文本末尾加上`'\n'`。<br>- 非传入`tuple`时，会自动把非`str`转换为`str`。 ?> **Tips:** <br>- 有些文本框可以接收回车代替点击按钮，可以直接在文本末尾加上`'\n'`。<br>- 非传入`tuple`时，会自动把非`str`转换为`str`。
参数： **参数：**
- vals：文本值或按键组合 - `vals`：文本值或按键组合
- clear：输入前是否清空文本框 - `clear`：输入前是否清空文本框
- insure：是否确保输入正确，不能用于输入组合键 - `insure`：是否确保输入正确，不能用于输入组合键
- timeout：尝试输入的超时时间，不指定则使用父页面的超时时间，只在 `insure_input` 参数为 `True` 时生效 - `timeout`：尝试输入的超时时间，不指定则使用父页面的超时时间，只在 `insure_input` 参数为 `True` 时生效
返回：`bool`类型，表示是否成功输入。`insure` 为 `False` 时始终返回 `True`。 **返回：**`bool`类型，表示是否成功输入。`insure` 为 `False` 时始终返回 `True`。
```python ```python
# 输入文本 # 输入文本
@ -116,47 +116,47 @@ ele.input((Keys.CONTROL, 'a'), insure=False)
ele.input('D:\\test1.txt\nD:\\test2.txt') ele.input('D:\\test1.txt\nD:\\test2.txt')
``` ```
## clear() ## 📍 `clear()`
此方法用于清空元素文本，可使用确保清空的方式，若元素是不可编辑的，返回`None`。 此方法用于清空元素文本，可使用确保清空的方式，若元素是不可编辑的，返回`None`。
参数： **参数：**
- insure：是否确保清空。为`True`则用`input()`确保值变成`''`，为`False`则用 selenium 元素`clear()`方法 - `insure`：是否确保清空。为`True`则用`input()`确保值变成`''`，为`False`则用 selenium 元素`clear()`方法
返回：`bool`，是否清空成功，不能清空的元素返回`None` **返回：**`bool`，是否清空成功，不能清空的元素返回`None`
```python ```python
ele.clear() ele.clear()
``` ```
## run_script() ## 📍 `run_script()`
此方法用于对元素执行 js 代码，代码中用`arguments[0]`表示自己。 此方法用于对元素执行 js 代码，代码中用`arguments[0]`表示自己。
参数： **参数：**
- script：js 文本 - `script`：js 文本
- *args：传入 js 的参数 - `*args`：传入 js 的参数
返回：js 执行的结果 **返回：** js 执行的结果
```python ```python
# 用执行 js 的方式点击元素 # 用执行 js 的方式点击元素
ele.run_script('arguments[0].click()') ele.run_script('arguments[0].click()')
``` ```
## wait_ele() ## 📍 `wait_ele()`
此方法用于等待当前元素的某个下级元素到达某种状态。 此方法用于等待当前元素的某个下级元素到达某种状态。
调用此方法返回一个`ElementWaiter`对象，调用该对象方法实现各种方式的等待。 调用此方法返回一个`ElementWaiter`对象，调用该对象方法实现各种方式的等待。
参数： **参数：**
- loc_or_ele：要等待的元素，可以是元素或定位符 - `loc_or_ele`：要等待的元素，可以是元素或定位符
- timeout：等待超时时间，默认使用页面超时时间 - `timeout`：等待超时时间，默认使用页面超时时间
方法： **方法：**
| 方法 | 参数说明 | 功能 | | 方法 | 参数说明 | 功能 |
|:---------:|:----:|:------------:| |:---------:|:----:|:------------:|
@ -178,111 +178,111 @@ ele2 = ele1.ele('#div1')
ele1.wait_ele(ele2).hidden() ele1.wait_ele(ele2).hidden()
``` ```
## screenshot() ## 📍 `screenshot()`
此方法用于对元素进行截图。 此方法用于对元素进行截图。
如果是图片元素，会自动等待加载结束才截图。 如果是图片元素，会自动等待加载结束才截图。
此方法能自动获取能够使用的文件名，避免重名覆盖原有文件。并返回保存路径。 此方法能自动获取能够使用的文件名，避免重名覆盖原有文件。并返回保存路径。
保存格式为 png，也可以返回图片的二进制文本。 保存格式为 png，也可以返回图片的二进制文本。
参数： **参数：**
- path：图片保持路径 - `path`：图片保持路径
- filename：图片文件名，不传入时以元素`tag`标签命名 - `filename`：图片文件名，不传入时以元素`tag`标签命名
- as_bytes：是否已字节形式返回图片，为True时上面两个参数失效 - `as_bytes`：是否已字节形式返回图片，为True时上面两个参数失效
返回：图片完整路径或字节文本 **返回：** 图片完整路径或字节文本
```python ```python
path = ele.screenshot(r'D:\tmp', 'img1') # 保存到路径，文件名为img1.png path = ele.screenshot(r'D:\tmp', 'img1') # 保存到路径，文件名为img1.png
bytes = ele.screenshot(as_bytes=True) # 返回截图二进制文本 bytes = ele.screenshot(as_bytes=True) # 返回截图二进制文本
``` ```
## set_prop() ## 📍 `set_prop()`
此方法用于设置元素`property`属性。 此方法用于设置元素`property`属性。
参数： **参数：**
- prop： 属性名 - `prop`： 属性名
- value： 属性值 - `value`： 属性值
返回：`bool`，是否设置成功 **返回：**`bool`，是否设置成功
```python ```python
ele.set_prop('value', 'Hello world!') ele.set_prop('value', 'Hello world!')
``` ```
## set_attr() ## 📍 `set_attr()`
此方法用于设置元素`attribute`属性。 此方法用于设置元素`attribute`属性。
参数： **参数：**
- attr：属性名 - `attr`：属性名
- value：属性值 - `value`：属性值
返回：`bool`，是否设置成功 **返回：**`bool`，是否设置成功
```python ```python
ele.set_attr('href', 'http://www.gitee.com') ele.set_attr('href', 'http://www.gitee.com')
``` ```
## remove_attr() ## 📍 `remove_attr()`
此方法用于删除元素`attribute`属性。 此方法用于删除元素`attribute`属性。
参数： **参数：**
- attr：属性名 - `attr`：属性名
返回：`bool`，是否删除成功 **返回：**`bool`，是否删除成功
```python ```python
ele.remove_attr('href') ele.remove_attr('href')
``` ```
## submit() ## 📍 `submit()`
此方法用于提交表单，若元素不在表单内，返回`None`，否则返回`True`。 此方法用于提交表单，若元素不在表单内，返回`None`，否则返回`True`。
参数：无 **参数：** 无
返回：`True`或`None` **返回：**`True`或`None`
```python ```python
ele.submit() ele.submit()
``` ```
## drag() ## 📍 `drag()`
此方法用于拖拽元素到相对于当前的一个新位置，可以设置速度，可以选择是否随机抖动。 此方法用于拖拽元素到相对于当前的一个新位置，可以设置速度，可以选择是否随机抖动。
参数： **参数：**
- x：x 变化值 - `x`：x 变化值
- y：y 变化值 - `y`：y 变化值
- speed：拖动的速度，传入 0 即瞬间到达 - `speed`：拖动的速度，传入 0 即瞬间到达
- shake：是否随机抖动 - `shake`：是否随机抖动
返回：None **返回：**`None`
```python ```python
# 拖动当前元素到距离 50*50 的位置，速度为 100，不随机抖动 # 拖动当前元素到距离 50*50 的位置，速度为 100，不随机抖动
ele.drag(50, 50, 100, False) ele.drag(50, 50, 100, False)
``` ```
## drag_to() ## 📍 `drag_to()`
此方法用于拖拽元素到另一个元素上或一个坐标上。 此方法用于拖拽元素到另一个元素上或一个坐标上。
参数： **参数：**
- ele_or_loc： 另一个元素或坐标元组，接收元素时坐标是元素中点的坐标。可接收 selenium 的`WebElement`或本库的`DriverElement` - `ele_or_loc`： 另一个元素或坐标元组，接收元素时坐标是元素中点的坐标。可接收 selenium 的`WebElement`或本库的`DriverElement`
- speed： 拖动的速度，传入 0 即瞬间到达 - `speed`： 拖动的速度，传入 0 即瞬间到达
- shake： 是否随机抖动 - `shake`： 是否随机抖动
返回：None **返回：**`None`
```python ```python
# 把 ele1 拖拽到 ele2 上 # 把 ele1 拖拽到 ele2 上
@ -294,7 +294,7 @@ ele1.drag_to(ele2)
ele1.drag_to((50, 50)) ele1.drag_to((50, 50))
``` ```
## scroll ## 📍 `scroll`
此属性用于以某种方式滚动元素中的滚动条。 此属性用于以某种方式滚动元素中的滚动条。
调用此属性返回一个`Scroll`对象，调用该对象方法实现各种方式的滚动。 调用此属性返回一个`Scroll`对象，调用该对象方法实现各种方式的滚动。
@ -326,16 +326,16 @@ ele.scroll.down(200)
ele.scroll.to_location(100, 300) ele.scroll.to_location(100, 300)
``` ```
## hover() ## 📍 `hover()`
此方法用于模拟鼠标悬停在元素上，可接受偏移量，偏移量相对于元素左上角坐标。不传入`x`或`y`值时悬停在元素中点。`x`和`y`值可接受负值。 此方法用于模拟鼠标悬停在元素上，可接受偏移量，偏移量相对于元素左上角坐标。不传入`x`或`y`值时悬停在元素中点。`x`和`y`值可接受负值。
参数： **参数：**
- x：相对元素左上角坐标的 x 轴偏移量 - `x`：相对元素左上角坐标的 x 轴偏移量
- y：相对元素左上角坐标的 y 轴偏移量 - `y`：相对元素左上角坐标的 y 轴偏移量
返回：`None` **返回：**`None`
```python ```python
# 悬停在元素右上方 50*50 的位置 # 悬停在元素右上方 50*50 的位置
@ -348,7 +348,7 @@ ele.hover(x=50)
ele.hover() ele.hover()
``` ```
# `Select`类 # ✔️ `Select`类
`select`元素的操作较为复杂，因此专门做了一个类用于处理它。每个`DriverElement`都有`select`属性，如果是`select`元素，该属性是一个`Select`类，否则该属性为`False`。 `select`元素的操作较为复杂，因此专门做了一个类用于处理它。每个`DriverElement`都有`select`属性，如果是`select`元素，该属性是一个`Select`类，否则该属性为`False`。
`select`元素要操作列表时，实际上是对这个`Select`对象进行操作。 `select`元素要操作列表时，实际上是对这个`Select`对象进行操作。
@ -359,9 +359,9 @@ ele.select
?> **Tips:** <br>网页操作中经常遇到动态变化的表单，这时需要等待列表项加载。`Select`类内置等待功能，默认为页面等待时间。 ?> **Tips:** <br>网页操作中经常遇到动态变化的表单，这时需要等待列表项加载。`Select`类内置等待功能，默认为页面等待时间。
## 属性 ## 📍 属性
### is_multi ### 📎 `is_multi`
该属性表示当前`select`元素是否多选列表。 该属性表示当前`select`元素是否多选列表。
@ -369,7 +369,7 @@ ele.select
ele.select.is_multi ele.select.is_multi
``` ```
### options ### 📎 `options`
该属性以列表形式返回当前`select`元素下所有列表项元素对象，这些对象是`DriverElement`。 该属性以列表形式返回当前`select`元素下所有列表项元素对象，这些对象是`DriverElement`。
@ -377,7 +377,7 @@ ele.select.is_multi
options = ele.select.options options = ele.select.options
``` ```
### selected_option ### 📎 `selected_option`
该属性返回第一个被选中的元素对象。 该属性返回第一个被选中的元素对象。
@ -385,7 +385,7 @@ options = ele.select.options
option_ele = ele.select.selected_option option_ele = ele.select.selected_option
``` ```
### selected_options ### 📎 `selected_options`
该属性以列表形式返回第所有被选中的元素对象。如果是单选列表，返回一个列表 该属性以列表形式返回第所有被选中的元素对象。如果是单选列表，返回一个列表
@ -393,21 +393,21 @@ option_ele = ele.select.selected_option
options = ele.select.select.selected_options options = ele.select.select.selected_options
``` ```
## 方法 ## 📍 方法
### select() ### 📎 `select()`
该方法用于选定下拉列表中子元素。 该方法用于选定下拉列表中子元素。
接收`int`类型时根据序号选择，接收`str`类型时根据文本选择。 接收`int`类型时根据序号选择，接收`str`类型时根据文本选择。
接收`list`或`tuple`时同时选择多个项，多项可序号和文本混排。只能在多选列表使用。 接收`list`或`tuple`时同时选择多个项，多项可序号和文本混排。只能在多选列表使用。
Select 类的`__call__()`方法直接调用这个方法，因此可以直接`ele.select()`来替代这个方法。写法更直观。 Select 类的`__call__()`方法直接调用这个方法，因此可以直接`ele.select()`来替代这个方法。写法更直观。
参数： **参数：**
- text_or_index：根据文本或序号择选项，若允许多选，传入`list`或`tuple`可多选 - `text_or_index`：根据文本或序号择选项，若允许多选，传入`list`或`tuple`可多选
- timeout：等待列表项出现的时间 - `timeout`：等待列表项出现的时间
返回：是否选择成功 **返回：** 是否选择成功
```python ```python
# 根据文本选择下拉列表项，等待1秒 # 根据文本选择下拉列表项，等待1秒
@ -426,14 +426,14 @@ ele.select((0, 2))
ele.select(('text1', 2)) ele.select(('text1', 2))
``` ```
### select_by_value() ### 📎 `select_by_value()`
参数： **参数：**
- value：`value`属性值，若允许多选，传入`list`或`tuple`可多选 - `value`：`value`属性值，若允许多选，传入`list`或`tuple`可多选
- timeout：等待列表项出现的时间 - `timeout`：等待列表项出现的时间
返回：是否选择成功 **返回：** 是否选择成功
此方法用于根据`value`值选择项。当元素是多选列表时，可以接受`list`或`tuple`，同时选择多个项，可和序号混排。 此方法用于根据`value`值选择项。当元素是多选列表时，可以接受`list`或`tuple`，同时选择多个项，可和序号混排。
@ -445,16 +445,16 @@ ele.select.select_by_value('value1')
ele.select.select_by_value(('value1', 2)) ele.select.select_by_value(('value1', 2))
``` ```
### deselect() ### 📎 `deselect()`
此方法用于取消选定下拉列表中子元素。当元素是多选列表时，可以接受`list`或`tuple`，同时取消选择多个项。 此方法用于取消选定下拉列表中子元素。当元素是多选列表时，可以接受`list`或`tuple`，同时取消选择多个项。
参数： **参数：**
- text_or_index：根据文本、值选或序号择选项，若允许多选，传入`list`或`tuple`可多选 - `text_or_index`：根据文本、值选或序号择选项，若允许多选，传入`list`或`tuple`可多选
- timeout：等待列表项出现的时间 - `timeout`：等待列表项出现的时间
返回：是否取消选择成功 **返回：** 是否取消选择成功
```python ```python
# 根据文本取消选择下拉列表项 # 根据文本取消选择下拉列表项
@ -473,16 +473,16 @@ ele.select.deselect((0, 1))
ele.select.deselect(('text1', 2)) ele.select.deselect(('text1', 2))
``` ```
### deselect_by_value() ### 📎 `deselect_by_value()`
此方法用于根据`value`值取消选择项。当元素是多选列表时，可以接受`list`或`tuple`，同时取消选择多个项，可和序号混排。 此方法用于根据`value`值取消选择项。当元素是多选列表时，可以接受`list`或`tuple`，同时取消选择多个项，可和序号混排。
参数： **参数：**
- value：`value`属性值，若允许多选，传入`list`或`tuple`可取消多项 - `value`：`value`属性值，若允许多选，传入`list`或`tuple`可取消多项
- timeout：等待列表项出现的时间 - `timeout`：等待列表项出现的时间
返回：是否取消选择成功 **返回：** 是否取消选择成功
```python ```python
# 根据 value 值取消选择列表项 # 根据 value 值取消选择列表项
@ -492,27 +492,27 @@ ele.select.deselect_by_value('value1')
ele.select.deselect_by_value(('value1', 2)) ele.select.deselect_by_value(('value1', 2))
``` ```
## 多项列表独有功能 ## 📍 多项列表独有功能
### clear() ### 📎 `clear()`
此方法用于清空多选列表选项。 此方法用于清空多选列表选项。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
```python ```python
ele.select.clear() ele.select.clear()
``` ```
### invert() ### 📎 `invert()`
此方法用于反选多选列表选项。 此方法用于反选多选列表选项。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
```python ```python
ele.select.invert() ele.select.invert()

68
docs/MixPage使用方法/创建页面对象.md
View File

@ -3,22 +3,22 @@
可以通过指定配置信息创建须要的页面对象，如无界面的浏览器、是否加载插件、是否接管已打开的浏览器、设置`headers`、设置代理等等。 可以通过指定配置信息创建须要的页面对象，如无界面的浏览器、是否加载插件、是否接管已打开的浏览器、设置`headers`、设置代理等等。
这些配置信息，可以通过几种方式设置。配置的详细用法后文再讲。本节先了解创建页面对象的几种方式。 这些配置信息，可以通过几种方式设置。配置的详细用法后文再讲。本节先了解创建页面对象的几种方式。
# `MixPage`类 # ✔️ `MixPage`类
`MixPage`页面对象封装了常用的网页操作，并实现在两种模式之间的切换。 `MixPage`页面对象封装了常用的网页操作，并实现在两种模式之间的切换。
`MixPage`须控制一个`Drission`对象并使用其中的`WebDriver`或`Session`对象来实现。对浏览器或网络连接的操作。如没有传入，`MixPage`会自己创建一个（使用传入的配置信息或从默认 ini 文件读取）。 `MixPage`须控制一个`Drission`对象并使用其中的`WebDriver`或`Session`对象来实现。对浏览器或网络连接的操作。如没有传入，`MixPage`会自己创建一个（使用传入的配置信息或从默认 ini 文件读取）。
初始化参数： **初始化参数：**
- mode：初始化时模式，`'d'`或`'s'`，默认为`'d'` - `mode`：初始化时模式，`'d'`或`'s'`，默认为`'d'`
- drission：Drission 对象，不传入时会自动创建 - `drission`：Drission 对象，不传入时会自动创建
- timeout：超时时间，s 模式时为连接时间，d 模式时为查找元素、处理弹出框、输入文本等超时时间 - `timeout`：超时时间，s 模式时为连接时间，d 模式时为查找元素、处理弹出框、输入文本等超时时间
- driver_options：浏览器设置，没传入`drission`参数时会用这个设置新建`Drission`对象中的`WebDriver`对象，传入`False`则不创建 - `driver_options`：浏览器设置，没传入`drission`参数时会用这个设置新建`Drission`对象中的`WebDriver`对象，传入`False`则不创建
- session_options：requests 设置，没传入`drission`参数时会用这个设置新建`Drission`对象中的`Session`对象，传入`False`则不创建 - `session_options`：requests 设置，没传入`drission`参数时会用这个设置新建`Drission`对象中的`Session`对象，传入`False`则不创建
!> **注意：** <br>有传入`drission`参数时，`driver_options`和`session_options`参数无效 !> **注意：** <br>有传入`drission`参数时，`driver_options`和`session_options`参数无效
# 直接创建 # ✔️ 直接创建
这种方式代码最简洁，程序会从配置文件中读取配置，自动生成页面对象。可以保持代码简洁。 这种方式代码最简洁，程序会从配置文件中读取配置，自动生成页面对象。可以保持代码简洁。
在基本概念一节我们提到过，本库使用配置文件记录常用配置信息，也可以直接把配置写在代码里。 在基本概念一节我们提到过，本库使用配置文件记录常用配置信息，也可以直接把配置写在代码里。
@ -31,20 +31,20 @@ page = MixPage('d')
page = MixPage('s') page = MixPage('s')
``` ```
# 通过配置信息创建 # ✔️ 通过配置信息创建
本库有两种管理配置信息的对象，分别是`DriverOptions`和`SessionOptions`，对应 d 模式和 s 模式的配置。 本库有两种管理配置信息的对象，分别是`DriverOptions`和`SessionOptions`，对应 d 模式和 s 模式的配置。
须要时，可以创建相应的配置对象进行设置。 须要时，可以创建相应的配置对象进行设置。
## `DriverOptions`类 ## 📍 `DriverOptions`类
`DriverOptions`用于管理创建浏览器时的配置，浏览器创建后再修改这个配置是没有效果的。 `DriverOptions`用于管理创建浏览器时的配置，浏览器创建后再修改这个配置是没有效果的。
`DriverOptions`对象能实现链式操作。 `DriverOptions`对象能实现链式操作。
初始化参数： **初始化参数：**
- read_file：是否从 ini 文件中读取配置信息 - `read_file`：是否从 ini 文件中读取配置信息
- ini_path：ini 文件路径，为`None`则读取默认 ini 文件 - `ini_path`：ini 文件路径，为`None`则读取默认 ini 文件
```python ```python
# 导入 DriverOptions # 导入 DriverOptions
@ -56,14 +56,14 @@ do = DriverOptions().set_mute().set_no_imgs()
page = MixPage(driver_options=do) page = MixPage(driver_options=do)
``` ```
## `SessionOptions`类 ## 📍 `SessionOptions`类
`SessionOptions`用于管理创建`Session`对象时的配置，内置了常用的配置，并能实现链式操作。详细使用方法见“启动配置”一节。 `SessionOptions`用于管理创建`Session`对象时的配置，内置了常用的配置，并能实现链式操作。详细使用方法见“启动配置”一节。
初始化参数： **初始化参数：**
- read_file：是否从 ini 文件中读取配置信息 - `read_file`：是否从 ini 文件中读取配置信息
- ini_path：ini 文件路径，为`None`则读取默认 ini 文件 - `ini_path`：ini 文件路径，为`None`则读取默认 ini 文件
!>**注意：**<br>`Session`对象创建后再修改这个配置是没有效果的。 !>**注意：**<br>`Session`对象创建后再修改这个配置是没有效果的。
@ -86,7 +86,7 @@ d 模式的配置和 s 模式的配置是可以同时使用的，不会互相影
page = MixPage(mode='s', session_options=so, driver_options=do) page = MixPage(mode='s', session_options=so, driver_options=do)
``` ```
# 传入`Drission`对象创建 # ✔️ 传入`Drission`对象创建
在入门指南的基本概念一节里，我们讲过`Drission`对象相当于驱动器的角色。事实上，上述两种方式，`MixPage`都会自动创建一个`Drission`对象用于管理与网站或浏览器的连接，我们当然也可以手动创建并传入`MixPage`。 在入门指南的基本概念一节里，我们讲过`Drission`对象相当于驱动器的角色。事实上，上述两种方式，`MixPage`都会自动创建一个`Drission`对象用于管理与网站或浏览器的连接，我们当然也可以手动创建并传入`MixPage`。
`Drission`一般是不用手动创建的，要手动创建的时候，一般是用于i以下几种情况： `Drission`一般是不用手动创建的，要手动创建的时候，一般是用于i以下几种情况：
@ -95,16 +95,16 @@ page = MixPage(mode='s', session_options=so, driver_options=do)
- 在不同`MixPage`间传递驱动器 - 在不同`MixPage`间传递驱动器
- 与 selenium 或 requests 原生代码拼接，用于兼容这两者的代码 - 与 selenium 或 requests 原生代码拼接，用于兼容这两者的代码
## `Drission`类 ## 📍 `Drission`类
初始化参数： **初始化参数：**
- driver_or_options：`WebDriver`对象、`DriverOptions`对象或`Options`对象。传入`False`时自动创建一个空配置对象。 - `driver_or_options`：`WebDriver`对象、`DriverOptions`对象或`Options`对象。传入`False`时自动创建一个空配置对象。
- session_or_options：`Session`对象、`SessionOptions`对象、`Options`对象或设置字典。传入`False`时自动创建一个空配置对象。 - `session_or_options`：`Session`对象、`SessionOptions`对象、`Options`对象或设置字典。传入`False`时自动创建一个空配置对象。
- ini_path：要使用的 ini 文件的路径 - `ini_path`：要使用的 ini 文件的路径
- proxy：初始化时设置代理 - `proxy`：初始化时设置代理
## 使用其它 ini 文件创建 ## 📍 使用其它 ini 文件创建
```python ```python
from DrissionPage import MixPage, Drission from DrissionPage import MixPage, Drission
@ -113,7 +113,7 @@ d = Drission(ini_path=r'./config1.ini')
page = MixPage(drission=d) page = MixPage(drission=d)
``` ```
## 传递驱动器 ## 📍 传递驱动器
多页面对象间共用驱动器，如多个`MixPage`控制一个浏览器： 多页面对象间共用驱动器，如多个`MixPage`控制一个浏览器：
@ -125,7 +125,7 @@ d = page1.drission
page2 = MixPage(drission=d) page2 = MixPage(drission=d)
``` ```
## 从 selenium 和 requests 代码传入 ## 📍 从 selenium 和 requests 代码传入
DrissionPage 的代码能和 selenium 及 requests 代码兼容，便于不同程序间的对接。 DrissionPage 的代码能和 selenium 及 requests 代码兼容，便于不同程序间的对接。
只需把`WebDriver`对象或`Session`传入`Drission`对象即可。 只需把`WebDriver`对象或`Session`传入`Drission`对象即可。
@ -143,7 +143,7 @@ page = MixPage(drission=d)
page.get('https://www.baidu.com') page.get('https://www.baidu.com')
``` ```
## 用配置信息创建 ## 📍 用配置信息创建
因为`MixPage`创建时能直接接收配置信息，所以这个方法基本不需要用到，写出来只是表示有这个功能。 因为`MixPage`创建时能直接接收配置信息，所以这个方法基本不需要用到，写出来只是表示有这个功能。
@ -157,7 +157,7 @@ d = Drission(driver_or_options=do, session_or_options=so)
page = MixPage(drission=d) page = MixPage(drission=d)
``` ```
# 接管手动打开的浏览器 # ✔️ 接管手动打开的浏览器
如果须要手动打开浏览器，手动操作后再接管，可以这样做： 如果须要手动打开浏览器，手动操作后再接管，可以这样做：
@ -184,7 +184,7 @@ page = MixPage(driver_options=do)
?>**Tips：**<br>接管使用 bat 文件打开的浏览器也是一样做法做法。<br>接管浏览器时只有`local_port`、`debugger_address`、`driver_path`参数是有效的。 ?>**Tips：**<br>接管使用 bat 文件打开的浏览器也是一样做法做法。<br>接管浏览器时只有`local_port`、`debugger_address`、`driver_path`参数是有效的。
# 多 Chrome 浏览器共存 # ✔️ 多 Chrome 浏览器共存
如果想要同时操作多个 Chrome 浏览器，或者自己在使用 Chrome 上网，同时控制另外几个跑自动化，就须要给这些被程序控制的浏览器设置单独的端口和用户文件夹，否则会造成冲突。具体用`DriverOptions`对象进行设置，示例如下： 如果想要同时操作多个 Chrome 浏览器，或者自己在使用 Chrome 上网，同时控制另外几个跑自动化，就须要给这些被程序控制的浏览器设置单独的端口和用户文件夹，否则会造成冲突。具体用`DriverOptions`对象进行设置，示例如下：
@ -223,19 +223,19 @@ page2 = MixPage(driver_options=do2)
?> **Tips：**<br>使用 bat 文件打开浏览器再接管操作是一样的。 ?> **Tips：**<br>使用 bat 文件打开浏览器再接管操作是一样的。
# 一些技巧 # ✔️ 一些技巧
事实上，本库默认启动浏览器的方式是先通过程序在 9222（或用户指定的）端口运行一个浏览器进程，然后通过程序接管。这种做法有很多好处： 事实上，本库默认启动浏览器的方式是先通过程序在 9222（或用户指定的）端口运行一个浏览器进程，然后通过程序接管。这种做法有很多好处：
## 可重复使用的浏览器对象 ## 📍 可重复使用的浏览器对象
当程序运行完毕，浏览器不会主动关闭，下次再运行的时候可以直接在当前状态下继续运行。于是无须每次打开新的浏览器对象，无须从最开始步骤重新运行整个程序，一些前置条件（如登录）也无须每次运行，大大提高开发效率。 当程序运行完毕，浏览器不会主动关闭，下次再运行的时候可以直接在当前状态下继续运行。于是无须每次打开新的浏览器对象，无须从最开始步骤重新运行整个程序，一些前置条件（如登录）也无须每次运行，大大提高开发效率。
## 简便的调试方式 ## 📍 简便的调试方式
通过重复使用浏览器对象，用户可以把浏览器页面调整到某个状态再用程序接管，对调试某个特定问题效率极高。比如有些通过很多步骤才能到达的页面，如果每次重新运行会花费大量时间，而将页面固定再由程序接管，测试各种细节非常方便快捷。 通过重复使用浏览器对象，用户可以把浏览器页面调整到某个状态再用程序接管，对调试某个特定问题效率极高。比如有些通过很多步骤才能到达的页面，如果每次重新运行会花费大量时间，而将页面固定再由程序接管，测试各种细节非常方便快捷。
## 一行代码传递登录状态到 requests ## 📍 一行代码传递登录状态到 requests
本库的一个特点是打通了浏览器和`requests`之间的登录状态，我们可以手动登录浏览器，再用程序接管，然后切换到 s 模式，这时 s 模式的`Session`对象即已活动浏览器的登录信息，无须用`requests` 本库的一个特点是打通了浏览器和`requests`之间的登录状态，我们可以手动登录浏览器，再用程序接管，然后切换到 s 模式，这时 s 模式的`Session`对象即已活动浏览器的登录信息，无须用`requests`
处理登录过程，极大地简化了开发复杂程度。示例： 处理登录过程，极大地简化了开发复杂程度。示例：

185
docs/MixPage使用方法/启动配置/Chrome启动配置.md
View File

@ -1,185 +0,0 @@
为使浏览器设置更便利，本库扩展了`selenium.webdriver.chrome.options`的`Options`对象功能，创建了`DriverOptions`类，专门用于管理浏览器的启动配置。
!> **注意：** <br>
1、`DriverOptions`仅用于管理启动配置，浏览器启动后再修改无效。 <br>
2、若设置了`local_port`或`debugger_address`且浏览器未启动，则只有`arguments`、`driver_path`、`chrome_path`参数生效。 <br>
3、若设置了`local_port`或`debugger_address`且接管已有浏览器，只有`driver_path`参数生效。
# DriverOptions 类
`DriverOptions`类继承自`Options 类`，保留了原来所有功能，原生功能不在这里叙述，只介绍增加的功能。
对象创建时，可从配置文件中读取配置来进行初始化，不从文件读取则创建一个空配置对象。
该类绝大部分方法都支持链式操作。
初始化参数：
- read_file：是否从默认 ini 文件中读取配置信息
- ini_path：ini 文件路径，为`None`则读取默认 ini 文件
## driver_path
此属性返回 chromedriver 文件路径。
## chrome_path
此属性返回 Chrome 浏览器启动文件路径，即`binary_location`。
为空时程序会根据注册表或系统路径查找。
## set_paths()
该方法用于设置浏览器用到的几种路径信息。
参数：
- driver_path：chromedriver.exe 路径
- chrome_path：chrome.exe 路径
- local_port：本地端口号
- debugger_address：调试浏览器地址，会覆盖`local_port`设置，例：127.0.0.1:9222
- download_path：下载文件路径
- user_data_path：用户数据路径
- cache_path：缓存路径
返回：`None`
## save()
此方法用于保存当前配置对象的信息到配置文件。
参数：
- path：配置文件的路径，默认保存到当前读取的配置文件，传入`'default'`保存到默认 ini 文件
返回：配置文件绝对路径
## save_to_default()
此方法用于保存当前配置对象的信息到默认 ini 文件。
参数：无
返回：配置文件绝对路径
## remove_argument()
此方法用于移除一个`argument`项。
参数：
- value：设置项名称，带有值的设置项传入设置名称即可
返回：当前对象
## remove_experimental_option()
此方法用于移除一个实验设置，传入key值删除。
参数：
- key：实验设置的名称
返回：当前对象
## remove_all_extensions()
此方法用于移除所有插件。
参数：无
返回：当前对象
## set_argument()
此方法用于设置浏览器配置的`argument`属性。
参数：
- arg：属性名
- value：属性值，有值的属性传入值，没有的传入`bool`类型表示开关
返回：当前对象
## set_timeouts()
此方法用于设置三种超时时间，selenium 4 以上版本有效。
参数：
- implicit：查找元素超时时间
- pageLoad：页面加载超时时间
- script：脚本运行超时时间
返回：当前对象
## set_headless()
该方法用于设置是否已无头模式启动浏览器。
参数：
- on_off：`bool`类型，表示开或关
返回：None
## set_no_imgs()
该方法用于设置是否禁止加载图片。
参数：
- on_off：`bool`类型，表示开或关
返回：`None`
## set_mute()
该方法用于设置是否静音。
参数：
- on_off：`bool`类型，表示开或关
返回：None
## set_proxy()
该方法用于设置代理。
参数：
- proxy: 代理网址和端口，如 127.0.0.1:1080
返回：`None`
## set_user_agent()
该方法用于设置 user agent。
参数：
- user_agent：user agent文本
返回：`None`
## as_dict()
该方法以`dict`方式返回所有配置信息。
参数：无
返回：配置信息
# 简单示例
```python
from DrissionPage import MixPage
from DrissionPage.config import DriverOptions
# 创建配置对象（默认从 ini 文件中读取配置）
do = DriverOptions()
# 设置不加载图片、静音
do.set_no_imgs(True).set_mute(True)
# 以该配置创建页面对象
page = MixPage(driver_options=do)
```

265
docs/MixPage使用方法/启动配置/使用配置文件.md
View File

@ -1,265 +0,0 @@
本库使用 ini 文件记录浏览器或`Session`对象的启动配置。便于配置复用，免于在代码中加入繁琐的配置信息。
默认情况下，`MixPage`对象启动时自动加载文件中的配置信息。
也可以在默认配置基础上用简单的方法再次修改，再保存到 ini 文件。
也可以保存多个 ini 文件，按不同项目须要调用。
!> **注意：** <br>
ini 文件仅用于管理启动配置，浏览器或`Session`创建后再修改 ini 文件内容是没有效果的。 <br>
如果是接管已打开的浏览器，这些设置也没有用。 <br>
每次升级本库，ini 文件都会被重置，可另存到其它路径以免重置。
# ini 文件内容
ini 文件默认拥有三部分配置：`paths`、`chrome_options`、`session_options`，初始内容如下。
```
[paths]
; chromedriver.exe路径
chromedriver_path =
; 临时文件夹路径，暂时没有实际作用
tmp_path =
[chrome_options]
; 浏览器默认地址和端口，程序会启动或接管这个端口的浏览器进程，设为 '' 则用 selenium 普通方式启动浏览器
debugger_address = 127.0.0.1:9222
; chrome.exe路径
binary_location =
; 配置信息
arguments = [
; 静音
'--mute-audio',
; 不使用沙盒
'--no-sandbox',
; 谷歌文档提到需要加上这个属性来规避bug
'--disable-gpu',
; 忽略警告
'ignore-certificate-errors',
; 不显示信息栏
'--disable-infobars'
]
; 插件
extensions = []
; 实验性配置
experimental_options = {
'prefs': {
; 下载不弹出窗口
'profile.default_content_settings.popups': 0,
; 无弹窗
'profile.default_content_setting_values': {'notifications': 2},
; 禁用PDF插件
'plugins.plugins_list': [{"enabled": False, "name": "Chrome PDF Viewer"}]
},
; 设置为开发者模式，防反爬虫
'excludeSwitches': ["enable-automation"],
'useAutomationExtension': False
}
[session_options]
headers = {
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/603.3.8 (KHTML, like Gecko) Version/10.1.2 Safari/603.3.8",
"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"Connection": "keep-alive",
"Accept-Charset": "utf-8;q=0.7,*;q=0.7"
}
```
# 文件位置
默认配置文件存放在库文件夹下，文件名为 configs.ini。
用户可另存其它配置文件，或从另存的文件读取配置，但默认文件的位置和名称不会改变。
# 使用默认配置文件启动
## 使用`MixPage`对象自动加载
这是默认启动方式。
```python
from DrissionPage import MixPage
page = MixPage()
```
## 使用配置对象加载
这种方式一般用于加载配置后须要进一步修改。
```python
from Drission.config import DriverOptions, SessionOptions
do = DriverOptions()
so = SessionOptions()
page = MixPaage(driver_options=do, session_option=so)
```
## 使用 Drission 对象加载
这种方式一般用于加载非默认配置文件，或须在多个页面对象间传递`Drission`对象的情况。
```python
from DrissionPage import MixPage, Drission
ds = Drission(ini_path=r'D:\config1.ini')
page = MixPage(drission=ds)
```
# 保存/另存 ini 文件
```python
from DrissionPage.config import DriverOptions
do = DriverOptions()
# 设置不加载图片
do.set_no_imgs()
# 保存到默认 ini 文件
do.save()
# 保存到其它位置的配置文件
do.save(r'D:\config1.ini')
```
# easy_set 方法
Chrome 浏览器的配置繁琐且难以记忆，本库提供一些常用功能的快速设置方法，调用即可修改 ini 文件中该部分内容。
!> **注意：** <br>
easy_set 方法仅用于设置 ini 文件，浏览器或 Session 创建后再调用没有效果的。 <br>
如果是接管已打开的浏览器，这些设置也没有用。
## 简单示例
```python
# 导入
from DrissionPage.easy_set import set_headless
# 设置无头模式
set_headless(True)
```
## show_settings()
该方法用于打印 ini 文件内容。
参数：
- ini_path：ini 文件路径，默认读取默认 ini 文件
返回：`None`
## set_paths()
该方法用于设置浏览器用到的几种路径信息，设置后可检查 driver 是否和浏览器匹配。
参数：
- driver_path：chromedriver.exe 路径
- chrome_path：chrome.exe 路径
- local_port：本地端口号
- debugger_address：调试浏览器地址，会覆盖 local_port 设置，例：127.0.0.1:9222
- download_path：下载文件路径
- tmp_path：临时文件夹路径，暂时没有作用
- user_data_path：用户数据路径
- cache_path：缓存路径
- ini_path：要修改的 ini 文件路径，默认设置默认 ini 文件
- check_version：是否检查 chromedriver 和 Chrome 是否匹配
返回：`None`
## set_headless()
该方法用于设置是否已无头模式启动浏览器。
参数：
- on_off：`bool`类型，表示开或关
- ini_path: 要修改的 ini 文件路径，默认设置默认 ini 文件
返回：`None`
## set_no_imgs()
该方法用于设置是否禁止加载图片。
参数：
- on_off：`bool`类型，表示开或关
- ini_path: 要修改的 ini 文件路径，默认设置默认 ini 文件
返回：`None`
## set_mute()
该方法用于设置是否静音。
参数：
- on_off：`bool`类型，表示开或关
- ini_path: 要修改的 ini 文件路径，默认设置默认 ini 文件
返回：`None`
## set_proxy()
该方法用于设置代理。
参数：
- proxy: 代理网址和端口，如 127.0.0.1:1080
- ini_path: 要修改的 ini 文件路径，默认设置默认 ini 文件
返回：`None`
## set_user_agent()
该方法用于设置 user agent。
参数：
- user_agent：user agent文本
- ini_path: 要修改的 ini 文件路径，默认设置默认 ini 文件
返回：`None`
## set_argument()
该方法用于设置浏览器配置 argument 属性。
参数：
- arg：属性名
- value：属性值，有值的属性传入值。没有的传入`bool`表示开或关
- ini_path：要修改的 ini 文件路径，默认设置默认 ini 文件
返回：`None`
## check_driver_version()
该方法用于检查传入的 chrome 和 chromedriver 是否匹配。
参数：
- driver_path：chromedriver.exe 路径
- chrome_path：chrome.exe 路径
返回：`bool`类型，表示是否匹配
## get_match_drive()
该方法用于自动识别 chrome 版本并下载匹配的 driver。
参数：
- ini_path：要读取和修改的 ini 文件路径
- save_path：chromedriver 保存路径
- chrome_path：指定 chrome.exe 位置，不指定会自动依次在 ini 文件、注册表、系统路径中查找
- show_msg：是否打印信息
- check_version：是否检查版本匹配
返回：成功返回 driver 路径，失败返回`None`

10
docs/MixPage使用方法/对接selenium及requests代码.md
View File

@ -1,7 +1,7 @@
DrissionPage 代码可无缝拼接 selenium 及 requests 代码。既可直接使用 selenium 的`WebDriver`对象，也可导出自身的`WebDriver`给 selenium 代码使用。requests 的 DrissionPage 代码可无缝拼接 selenium 及 requests 代码。既可直接使用 selenium 的`WebDriver`对象，也可导出自身的`WebDriver`给 selenium 代码使用。requests 的
`Session`对象也可直接传递。便于已有项目的迁移。 `Session`对象也可直接传递。便于已有项目的迁移。
# selenium 转 DrissionPage # ✔️ selenium 转 DrissionPage
```python ```python
from selenium import webdriver from selenium import webdriver
@ -17,7 +17,7 @@ page = MixPage(drission=drission)
print(page.title) print(page.title)
``` ```
# DrissionPage 转 selenium # ✔️ DrissionPage 转 selenium
```python ```python
page = MixPage() page = MixPage()
@ -31,9 +31,9 @@ print(driver.title)
element = driver.find_element(By.XPATH, '//div') element = driver.find_element(By.XPATH, '//div')
``` ```
# requests 转 DrissionPage # ✔️ requests 转 DrissionPage
``` python ```python
from requests import Session from requests import Session
session = requets.Session() session = requets.Session()
@ -45,7 +45,7 @@ page = MixPage('s', drission=drission)
page.get('https://www.baidu.com') page.get('https://www.baidu.com')
``` ```
# DrissionPage 转 requests # ✔️ DrissionPage 转 requests
```python ```python
from DrissionPage import MixPage from DrissionPage import MixPage

54
docs/MixPage使用方法/打包程序.md
View File

@ -1,54 +0,0 @@
# 注意事项
程序如直接打包为 exe 文件，运行会遇到报错。这是可能因为程序在默认路径找不到 ini 文件引起的。解决的方法有两种：
1. **把 ini 文件放到打包的程序文件夹**
这样程序运行时会根据相对路径查找 ini 文件，避免找不到默认文件的问题
```python
from DrissionPage import Drission, MixPage
drission = Drission(ini_path=r'.\configs.ini') # ini文件放在程序相同路径下
page = MixPage(drission=drission)
```
2. **把配置写到程序中，不使用 ini 文件**
```python
from DrissionPage.config import DriverOptions, SessionOptions
from DrissionPage import MixPage
do = DriverOptions(read_file=False)
so = SessionOptions(read_file=False)
page = MixPage(driver_options=do, session_options=so)
```
!> **注意** <br>这个时候`Drission`的两个参数都要输入内容，如果其中一个不需要设置可以输入`False`.
如：
```python
drission = Drission(driver_or_options=do, session_or_options=False)
```
# 实用示例
通常，我会把一个绿色浏览器和打包后的 exe 文件放在一起，程序中用相对路径指向该浏览器，这样拿到别的电脑也可以正常实用。
```python
from DrissionPage import MixPage
from DrissionPage.config import DriverOptions
do = DriverOptions(read_file=False).set_paths(local_port='9888',
chrome_path=r'.\Chrome\chrome.exe',
driver_path=r'.\Chrome\chromedriver.exe',
user_data_path=r'.\Chrome\userData')
page = MixPage(driver_options=do, session_options=False)
page.get('https://www.baidu.com')
```
注意以下两点，程序就会跳过读取 ini 文件：
- `DriverOptions()`里要设置`read_file=False`
- 如果不传入某个模式的配置（示例中为 s 模式），要在`MixPage()`初始化是设置对应参数为`False`

297
docs/MixPage使用方法/查找页面元素.md
View File

@ -11,9 +11,9 @@
d 模式的元素还有专门用于处理 shadow dom 的`shadow_root`属性。获取到的元素可继续用这些方法获取后代元素，使用方法和普通元素一致。 d 模式的元素还有专门用于处理 shadow dom 的`shadow_root`属性。获取到的元素可继续用这些方法获取后代元素，使用方法和普通元素一致。
# 示例 # ✔️ 示例
## 简单示例 ## 📍 简单示例
```html ```html
<html> <html>
@ -61,7 +61,7 @@ parent = p1.parent()
div2 = p1.after(1, 'tag:div') div2 = p1.after(1, 'tag:div')
``` ```
## 实际示例 ## 📍 实际示例
复制此代码可直接运行查看结果。 复制此代码可直接运行查看结果。
@ -93,17 +93,17 @@ IOT/物联网/边缘计算
# 查找元素方法 # 查找元素方法
## ele() ## 📍 `ele()`
此方法用于查找并返回第一个匹配的元素，d 模式下返回`DriverElement`，s 模式下返回`SessionElement`，用 xpath 获取元素属性时，直接返回属性文本。查找不到结果则返回`None`。 此方法用于查找并返回第一个匹配的元素，d 模式下返回`DriverElement`，s 模式下返回`SessionElement`，用 xpath 获取元素属性时，直接返回属性文本。查找不到结果则返回`None`。
参数： **参数：**
- loc_or_str（元素对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串 - `loc_or_str`（元素对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串
- loc_or_ele（页面对象拥有）：元素的定位信息，可以是元素对象，loc 元组，或查询字符串 - `loc_or_ele`（页面对象拥有）：元素的定位信息，可以是元素对象，loc 元组，或查询字符串
- timeout：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 - `timeout`：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效
返回：s 模式下返回`SessionElement`，d 模式下返回`DriverElement`，或用 xpath 获取到的属性值 **返回：** s 模式下返回`SessionElement`，d 模式下返回`DriverElement`，或用 xpath 获取到的属性值
```python ```python
# 在页面内查找元素 # 在页面内查找元素
@ -117,16 +117,16 @@ ele2 = ele1.ele('search text')
class = ele1.ele('xpath://div/@class') class = ele1.ele('xpath://div/@class')
``` ```
## eles() ## 📍 `eles()`
此方法与`ele()`相似，但返回的是匹配到的所有元素组成的列表，用 xpath 获取元素属性时，返回属性文本组成的列表。 此方法与`ele()`相似，但返回的是匹配到的所有元素组成的列表，用 xpath 获取元素属性时，返回属性文本组成的列表。
参数： **参数：**
- loc_or_str：元素的定位信息，可以是 loc 元组，或查询字符串 - `loc_or_str`：元素的定位信息，可以是 loc 元组，或查询字符串
- timeout：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 - `timeout`：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效
返回：s 模式下返回`SessionElement`组成的列表，d 模式下返回`DriverElement`组成的列表，或用 xpath 获取到的属性值组成的列表 **返回：** s 模式下返回`SessionElement`组成的列表，d 模式下返回`DriverElement`组成的列表，或用 xpath 获取到的属性值组成的列表
```python ```python
# 获取 ele 元素内的所有 p 元素 # 获取 ele 元素内的所有 p 元素
@ -135,7 +135,7 @@ p_eles = ele.eles('tag:p')
print(p_eles[0]) print(p_eles[0])
``` ```
## s_ele() ## 📍 `s_ele()`
此方法用于在一个元素下查找后代元素，以`SessionElement`形式返回结果（xpath 获取属性值时依然是返回`str`），也可以直接将一个元素或页面转换为`SessionElement`版本。 此方法用于在一个元素下查找后代元素，以`SessionElement`形式返回结果（xpath 获取属性值时依然是返回`str`），也可以直接将一个元素或页面转换为`SessionElement`版本。
@ -143,12 +143,12 @@ print(p_eles[0])
s 模式下这个方法和`ele()`是一样的。 s 模式下这个方法和`ele()`是一样的。
参数： **参数：**
- loc_or_str（元素对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前元素的`SessionElemnet`版本 - `loc_or_str`（元素对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前元素的`SessionElemnet`版本
- loc_or_ele（页面对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前页面的 `SessionElemnet`版本 - `loc_or_ele`（页面对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前页面的 `SessionElemnet`版本
返回：`SessionElement`，或用 xpath 获取到的属性值 **返回：**`SessionElement`，或用 xpath 获取到的属性值
```python ```python
# 获取元素或页面的的 SessionElement 版本 # 获取元素或页面的的 SessionElement 版本
@ -162,17 +162,17 @@ ele2 = ele1.s_ele('search text')
ele = page.s_ele('search text') ele = page.s_ele('search text')
``` ```
## s_eles() ## 📍 `s_eles()`
此方法与`s_ele()`相似，但返回的是匹配到的所有元素组成的列表，或属性值组成的列表。 此方法与`s_ele()`相似，但返回的是匹配到的所有元素组成的列表，或属性值组成的列表。
参数： **参数：**
- loc_or_str：元素的定位信息，可以是 loc 元组，或查询字符串（必填） - `loc_or_str`：元素的定位信息，可以是 loc 元组，或查询字符串（必填）
返回：`SessionElement`组成的列表，或用 xpath 获取到的属性值组成的列表 **返回：**`SessionElement`组成的列表，或用 xpath 获取到的属性值组成的列表
## active_ele ## 📍 `active_ele`
该属性返回当前页面焦点所在元素。d 模式独有。 该属性返回当前页面焦点所在元素。d 模式独有。
@ -180,7 +180,7 @@ ele = page.s_ele('search text')
ele = page.active_ele ele = page.active_ele
``` ```
## shadow_root ## 📍 `shadow_root`
`DriverElement`元素除了以上方法和属性外，还有`shadow_root`属性，用于获取其内部的 shadow_root 元素。 `DriverElement`元素除了以上方法和属性外，还有`shadow_root`属性，用于获取其内部的 shadow_root 元素。
该属性返回的是一个`ShadowRootElement`，类似于`DriverElement`，功能比`DriverElement`少。但也有`ele()`和`eles()`方法，可直接搜索其下的元素，返回 `DriverElement` 该属性返回的是一个`ShadowRootElement`，类似于`DriverElement`，功能比`DriverElement`少。但也有`ele()`和`eles()`方法，可直接搜索其下的元素，返回 `DriverElement`
@ -202,17 +202,17 @@ ele1.click()
**匹配模式** 指字符串是否完全匹配，有以下两种： **匹配模式** 指字符串是否完全匹配，有以下两种：
## `=` ## 📍 `=`
表示精确匹配，匹配完全符合的文本或属性。 表示精确匹配，匹配完全符合的文本或属性。
## `:` ## 📍 `:`
表示模糊匹配，匹配含有某个字符串的文本或属性。 表示模糊匹配，匹配含有某个字符串的文本或属性。
**关键字** 是出现在定位语句最左边，用于指明该语句以哪种方式去查找元素，有以下这些： **关键字** 是出现在定位语句最左边，用于指明该语句以哪种方式去查找元素，有以下这些：
## `#` ## 📍 `#`
表示`id`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。 表示`id`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。
@ -224,7 +224,7 @@ ele1 = page.ele('#ele_id')
ele2 = ele1.ele('#:ele_id') ele2 = ele1.ele('#:ele_id')
``` ```
## `.` ## 📍 `.`
表示`class`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。 表示`class`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。
@ -236,7 +236,7 @@ ele2 = ele1.ele('.ele_class')
ele2 = ele1.ele('.:ele_class') ele2 = ele1.ele('.:ele_class')
``` ```
## `@` ## 📍 `@`
表示某个属性，只匹配一个属性。 表示某个属性，只匹配一个属性。
`@`关键字只有一个简单功能，就是匹配`@`后面的内容，不再对后面的字符串进行解析。因此即使后面的字符串也存在`@`或`@@`，也作为要匹配的内容对待。 `@`关键字只有一个简单功能，就是匹配`@`后面的内容，不再对后面的字符串进行解析。因此即使后面的字符串也存在`@`或`@@`，也作为要匹配的内容对待。
@ -264,7 +264,7 @@ ele2 = ele1.ele('@email=abc@def.com')
ele2 = ele1.ele('css:div[abc\@def="v"]') ele2 = ele1.ele('css:div[abc\@def="v"]')
``` ```
## `@@` ## 📍 `@@`
表示某个属性，多属性匹配时使用，个数不限。还能匹配要忽略的元素，匹配文本时也和`@`不一样。 表示某个属性，多属性匹配时使用，个数不限。还能匹配要忽略的元素，匹配文本时也和`@`不一样。
`@@`后跟 - 时，表示 not。如： `@@`后跟 - 时，表示 not。如：
@ -293,7 +293,7 @@ ele2 = ele1.ele('@@-class')
ele2 = ele1.ele('@@-name:ele_name') ele2 = ele1.ele('@@-name:ele_name')
``` ```
## `text` ## 📍 `text`
要匹配的文本，查询字符串如开头没有任何关键字，也表示根据传入的文本作模糊查找。 要匹配的文本，查询字符串如开头没有任何关键字，也表示根据传入的文本作模糊查找。
如果元素内有多个直接的文本节点，精确查找时可匹配所有文本节点拼成的字符串，模糊查找时可匹配每个文本节点。 如果元素内有多个直接的文本节点，精确查找时可匹配所有文本节点拼成的字符串，模糊查找时可匹配每个文本节点。
@ -315,7 +315,7 @@ ele2 = ele1.ele('some text')
ele2 = page.ele('text:text:') ele2 = page.ele('text:text:')
``` ```
## `text()` ## 📍 `text()`
作为查找属性时使用的文本关键字，必须与`@`或`@@`配合使用。 作为查找属性时使用的文本关键字，必须与`@`或`@@`配合使用。
与`@`配合和与`@@`配合使用时，`text()`的意义是有差别的。 与`@`配合和与`@@`配合使用时，`text()`的意义是有差别的。
@ -343,7 +343,7 @@ ele = page.ele('text:some text')
ele = page.ele('@@text():some text') ele = page.ele('@@text():some text')
``` ```
## `tag` ## 📍 `tag`
表示元素的标签，只在语句最前面且单独使用时生效，可与`@`或`@@`配合使用。`tag:`与`tag=`效果一致。 表示元素的标签，只在语句最前面且单独使用时生效，可与`@`或`@@`配合使用。`tag:`与`tag=`效果一致。
@ -367,10 +367,9 @@ ele2 = ele1.ele('tag:div@text():text')
ele2 = ele1.ele('tag:div@@text():text') ele2 = ele1.ele('tag:div@@text():text')
``` ```
?> **Tips:** <br> ?> **Tips:** <br>注意， `tag:div@text():text` 和 `tag:div@@text():text` 是有区别的，前者只在`div`的直接文本节点搜索，后者搜索`div`的整个内部。
注意， `tag:div@text():text` 和 `tag:div@@text():text` 是有区别的，前者只在`div`的直接文本节点搜索，后者搜索`div`的整个内部。
## `css` ## 📍 `css`
表示用 css selector 方式查找元素。`css:`与`css=`效果一致。 表示用 css selector 方式查找元素。`css:`与`css=`效果一致。
@ -382,7 +381,7 @@ ele2 = ele1.ele('css:.div')
ele2 = ele1.ele('css:>div') ele2 = ele1.ele('css:>div')
``` ```
## `xpath` ## 📍 `xpath`
表示用 xpath 方式查找元素。`xpath:`与`xpath=`效果一致。 表示用 xpath 方式查找元素。`xpath:`与`xpath=`效果一致。
该方法支持完整的 xpath 语法，能使用 xpath 直接获取元素属性，selenium 不支持这种用法。 该方法支持完整的 xpath 语法，能使用 xpath 直接获取元素属性，selenium 不支持这种用法。
@ -398,11 +397,10 @@ ele2 = ele1.ele('xpath://div')
txt = ele1.ele('xpath://div/@class') txt = ele1.ele('xpath://div/@class')
``` ```
?> **Tips:** <br> ?> **Tips:** <br>查找元素的后代时，selenium 原生代码要求 xpath 前面必须加`.`，否则会变成在全个页面中查找。笔者觉得这个设计是画蛇添足，既然已经通过元素查找了，自然应该只查找这个元素内部的元素。所以，用 xpath
查找元素的后代时，selenium 原生代码要求 xpath 前面必须加`.`，否则会变成在全个页面中查找。笔者觉得这个设计是画蛇添足，既然已经通过元素查找了，自然应该只查找这个元素内部的元素。所以，用 xpath
在元素下查找时，最前面`//`或`/`前面的`.`可以省略。 在元素下查找时，最前面`//`或`/`前面的`.`可以省略。
## selenium 的 loc 元组 ## 📍 selenium 的 loc 元组
查找方法能直接接收 selenium 原生定位元组进行查找，s 模式下也支持这种写法。 查找方法能直接接收 selenium 原生定位元组进行查找，s 模式下也支持这种写法。
@ -418,7 +416,7 @@ loc2 = (By.XPATH, '//div[@class="ele_class"]'
ele = page.ele(loc2) ele = page.ele(loc2)
``` ```
# 等待 # ✔️ 等待
d 模式下所有查找元素操作都自带等待，默认为跟随元素所在页面`timeout`属性（默认 10 秒），也可以在每次查找时单独设置，单独设置的等待时间不会改变页面原来设置。 d 模式下所有查找元素操作都自带等待，默认为跟随元素所在页面`timeout`属性（默认 10 秒），也可以在每次查找时单独设置，单独设置的等待时间不会改变页面原来设置。
@ -438,20 +436,20 @@ ele2 = ele1.ele('some text')
ele2 = ele1.ele('some text', timeout=1) ele2 = ele1.ele('some text', timeout=1)
``` ```
# DOM 内相对定位 # ✔️ DOM 内相对定位
以下方法可以以某元素为基准，在 DOM 中按照条件获取其兄弟元素、祖先元素、文档前后元素。 以下方法可以以某元素为基准，在 DOM 中按照条件获取其兄弟元素、祖先元素、文档前后元素。
除获取元素外，还能通过 xpath 获取任意节点内容，如文本节点、注释节点。这在处理元素和文本节点混排的时候非常有用。 除获取元素外，还能通过 xpath 获取任意节点内容，如文本节点、注释节点。这在处理元素和文本节点混排的时候非常有用。
## parent() ## 📍 `parent()`
此方法获取当前元素某一级父元素，可指定筛选条件或层数。 此方法获取当前元素某一级父元素，可指定筛选条件或层数。
参数： **参数：**
- level_or_loc：第几级父元素，或定位符 - `level_or_loc`：第几级父元素，或定位符
返回： **返回：** 某层父元素
```python ```python
# 获取 ele1 的第二层父元素 # 获取 ele1 的第二层父元素
@ -461,17 +459,17 @@ ele2 = ele1.parent(2)
ele2 = ele1.parent('#id1') ele2 = ele1.parent('#id1')
``` ```
## next() ## 📍 `next()`
此方法返回当前元素后面的某一个兄弟元素，可指定筛选条件和第几个。 此方法返回当前元素后面的某一个兄弟元素，可指定筛选条件和第几个。
参数： **参数：**
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素后面某个兄弟元素或节点文本 **返回：** 本元素后面某个兄弟元素或节点文本
```python ```python
# 获取 ele1 后面第一个兄弟元素 # 获取 ele1 后面第一个兄弟元素
@ -487,16 +485,16 @@ ele2 = ele1.next(3, 'tag:div')
txt = ele1.next(1, 'xpath:text()') txt = ele1.next(1, 'xpath:text()')
``` ```
## nexts() ## 📍 `nexts()`
此方法返回后面全部符合条件的兄弟元素或节点组成的列表，可用查询语法筛选。 此方法返回后面全部符合条件的兄弟元素或节点组成的列表，可用查询语法筛选。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面符合条件的兄弟元素或节点文本组成的列表 **返回：** 本元素前面符合条件的兄弟元素或节点文本组成的列表
```python ```python
# 获取 ele1 后面所有兄弟元素 # 获取 ele1 后面所有兄弟元素
@ -509,17 +507,17 @@ divs = ele1.nexts('tag:div')
txts = ele1.nexts('xpath:text()') txts = ele1.nexts('xpath:text()')
``` ```
## prev() ## 📍 `prev()`
此方法返回当前元素前面的某一个兄弟元素，可指定筛选条件和第几个。 此方法返回当前元素前面的某一个兄弟元素，可指定筛选条件和第几个。
参数： **参数：**
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面某个兄弟元素或节点文本 **返回：** 本元素前面某个兄弟元素或节点文本
```python ```python
# 获取 ele1 前面第一个兄弟元素 # 获取 ele1 前面第一个兄弟元素
@ -535,16 +533,16 @@ ele2 = ele1.prev(3, 'tag:div')
txt = ele1.prev(1, 'xpath:text()') txt = ele1.prev(1, 'xpath:text()')
``` ```
## prevs() ## 📍 `prevs()`
此方法返回前面全部符合条件的兄弟元素或节点组成的列表，可用查询语法筛选。 此方法返回前面全部符合条件的兄弟元素或节点组成的列表，可用查询语法筛选。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面符合条件的兄弟元素或节点文本组成的列表 **返回：** 本元素前面符合条件的兄弟元素或节点文本组成的列表
```python ```python
# 获取 ele1 前面所有兄弟元素 # 获取 ele1 前面所有兄弟元素
@ -554,17 +552,17 @@ eles = ele1.prevs()
divs = ele1.prevs('tag:div') divs = ele1.prevs('tag:div')
``` ```
## after() ## 📍 `after()`
此方法返回当前元素后面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 此方法返回当前元素后面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。
参数： **参数：**
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素后面某个元素或节点 **返回：** 本元素后面某个元素或节点
```python ```python
# 获取 ele1 后面第 3 个元素 # 获取 ele1 后面第 3 个元素
@ -577,16 +575,16 @@ ele2 = ele1.after(3, 'tag:div')
txt = ele1.after(1, 'xpath:text()') txt = ele1.after(1, 'xpath:text()')
``` ```
## afters() ## 📍 `afters()`
此方法返回后面符合条件的全部元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 此方法返回后面符合条件的全部元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素后面符合条件的元素或节点组成的列表 **返回：** 本元素后面符合条件的元素或节点组成的列表
```python ```python
# 获取 ele1 后所有元素 # 获取 ele1 后所有元素
@ -596,17 +594,17 @@ eles = ele1.afters()
divs = ele1.afters('tag:div') divs = ele1.afters('tag:div')
``` ```
## before() ## 📍 `before()`
此方法返回当前元素前面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 此方法返回当前元素前面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。
参数： **参数：**
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面某个元素或节点 **返回：** 本元素前面某个元素或节点
```python ```python
# 获取 ele1 前面第 3 个元素 # 获取 ele1 前面第 3 个元素
@ -619,16 +617,16 @@ ele2 = ele1.before(3, 'tag:div')
txt = ele1.before(1, 'xpath:text()') txt = ele1.before(1, 'xpath:text()')
``` ```
## befores() ## 📍 `befores()`
此方法返回前面全部符合条件的元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 此方法返回前面全部符合条件的元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面符合条件的元素或节点组成的列表 **返回：** 本元素前面符合条件的元素或节点组成的列表
```python ```python
# 获取 ele1 前面所有元素 # 获取 ele1 前面所有元素
@ -638,22 +636,22 @@ eles = ele1.befores()
divs = ele1.befores('tag:div') divs = ele1.befores('tag:div')
``` ```
# 页面布局相对定位 # ✔️ 页面布局相对定位
以下方法用于在页面上根据显示位置定位元素。只能有在 d 模式，selenium4 版本，且 driver 版本较新的情况下才能使用。 以下方法用于在页面上根据显示位置定位元素。只能有在 d 模式，selenium4 版本，且 driver 版本较新的情况下才能使用。
与上面通过 DOM 定位的方法不同，这些方法只能获取元素，不能获取节点。 与上面通过 DOM 定位的方法不同，这些方法只能获取元素，不能获取节点。
获取多个元素时，元素由近到远排列。 获取多个元素时，元素由近到远排列。
## left() ## 📍 `left()`
此方法返回当前元素左边的某一个元素，可指定筛选条件和第几个。 此方法返回当前元素左边的某一个元素，可指定筛选条件和第几个。
参数： **参数：**
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：本元素左边的某个元素 **返回：** 本元素左边的某个元素
```python ```python
# 获取 ele1 左边第 3 个元素 # 获取 ele1 左边第 3 个元素
@ -663,15 +661,15 @@ ele2 = ele1.left(3)
ele2 = ele1.left(3, 'tag:div') ele2 = ele1.left(3, 'tag:div')
``` ```
## lefts() ## 📍 `lefts()`
此方法返回左边全部符合条件的元素组成的列表，可用查询语法筛选。 此方法返回左边全部符合条件的元素组成的列表，可用查询语法筛选。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：本元素左边符合条件的元素组成的列表 **返回：** 本元素左边符合条件的元素组成的列表
```python ```python
# 获取 ele1 左边所有元素 # 获取 ele1 左边所有元素
@ -681,16 +679,16 @@ eles = ele1.lefts()
divs = ele1.lefts('tag:div') divs = ele1.lefts('tag:div')
``` ```
## right() ## 📍 `right()`
此方法返回当前元素左边的某一个元素，可指定筛选条件和第几个。 此方法返回当前元素左边的某一个元素，可指定筛选条件和第几个。
参数： **参数：**
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：本元素左边的某个元素 **返回：** 本元素左边的某个元素
```python ```python
# 获取 ele1 左边第 3 个元素 # 获取 ele1 左边第 3 个元素
@ -700,15 +698,15 @@ ele2 = ele1.right(3)
ele2 = ele1.right(3, 'tag:div') ele2 = ele1.right(3, 'tag:div')
``` ```
## rights() ## 📍 `rights()`
此方法返回右边全部符合条件的元素组成的列表，可用查询语法筛选。 此方法返回右边全部符合条件的元素组成的列表，可用查询语法筛选。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：本元素右边符合条件的元素组成的列表 **返回：** 本元素右边符合条件的元素组成的列表
```python ```python
# 获取 ele1 右边所有元素 # 获取 ele1 右边所有元素
@ -718,16 +716,16 @@ eles = ele1.rights()
divs = ele1.rights('tag:div') divs = ele1.rights('tag:div')
``` ```
## below() ## 📍 `below()`
此方法返回当前元素下边的某一个元素，可指定筛选条件和第几个。 此方法返回当前元素下边的某一个元素，可指定筛选条件和第几个。
参数： **参数：**
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：本元素下边的某个元素 **返回：** 本元素下边的某个元素
```python ```python
# 获取 ele1 下边第 3 个元素 # 获取 ele1 下边第 3 个元素
@ -737,15 +735,15 @@ ele2 = ele1.below(3)
ele2 = ele1.below(3, 'tag:div') ele2 = ele1.below(3, 'tag:div')
``` ```
## belows() ## 📍 `belows()`
此方法返回下边全部符合条件的元素组成的列表，可用查询语法筛选。 此方法返回下边全部符合条件的元素组成的列表，可用查询语法筛选。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：本元素下边符合条件的元素组成的列表 **返回：** 本元素下边符合条件的元素组成的列表
```python ```python
# 获取 ele1 下边所有元素 # 获取 ele1 下边所有元素
@ -755,16 +753,16 @@ eles = ele1.belows()
divs = ele1.belows('tag:div') divs = ele1.belows('tag:div')
``` ```
## above() ## 📍 `above()`
此方法返回当前元素上边的某一个元素，可指定筛选条件和第几个。 此方法返回当前元素上边的某一个元素，可指定筛选条件和第几个。
参数： **参数：**
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：本元素上边的某个元素 **返回：** 本元素上边的某个元素
```python ```python
# 获取 ele1 上边第 3 个元素 # 获取 ele1 上边第 3 个元素
@ -774,15 +772,15 @@ ele2 = ele1.above(3)
ele2 = ele1.above(3, 'tag:div') ele2 = ele1.above(3, 'tag:div')
``` ```
## aboves() ## 📍 `aboves()`
此方法返回上边全部符合条件的元素组成的列表，可用查询语法筛选。 此方法返回上边全部符合条件的元素组成的列表，可用查询语法筛选。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：本元素上边符合条件的元素组成的列表 **返回：** 本元素上边符合条件的元素组成的列表
```python ```python
# 获取 ele1 上边所有元素 # 获取 ele1 上边所有元素
@ -792,16 +790,16 @@ eles = ele1.aboves()
divs = ele1.aboves('tag:div') divs = ele1.aboves('tag:div')
``` ```
## near() ## 📍 `near()`
此方法返回最接近当前元素的某一个元素，可指定筛选条件和第几个。 此方法返回最接近当前元素的某一个元素，可指定筛选条件和第几个。
参数： **参数：**
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：最接近本元素的某个元素 **返回：** 最接近本元素的某个元素
```python ```python
# 获取最接近 ele1 的第 3 个元素 # 获取最接近 ele1 的第 3 个元素
@ -811,15 +809,15 @@ ele2 = ele1.near(3)
ele2 = ele1.near(3, 'tag:div') ele2 = ele1.near(3, 'tag:div')
``` ```
## nears() ## 📍 `nears()`
此方法返回该元素附近全部符合条件的元素组成的列表，可用查询语法筛选。 此方法返回该元素附近全部符合条件的元素组成的列表，可用查询语法筛选。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
返回：本元素附近符合条件的元素组成的列表 **返回：** 本元素附近符合条件的元素组成的列表
```python ```python
# 获取 ele1 附近所有元素 # 获取 ele1 附近所有元素
@ -829,13 +827,12 @@ eles = ele1.nears()
divs = ele1.nears('tag:div') divs = ele1.nears('tag:div')
``` ```
# `ShadowRootElement`相关查找 # ✔️ `ShadowRootElement`相关查找
本库把 shadow-root 也作为元素对象看待，是为`ShadowRootElement`对象。对`ShadowRootElement`对象可与普通元素一样查找下级元素和 DOM 内相对定位，但不能用页面布局相对定位。 本库把 shadow-root 也作为元素对象看待，是为`ShadowRootElement`对象。对`ShadowRootElement`对象可与普通元素一样查找下级元素和 DOM 内相对定位，但不能用页面布局相对定位。
对`ShadowRootElement`对象进行相对定位时，把它看作其父对象内部的第一个对象，其余定位逻辑与普通对象一致。 对`ShadowRootElement`对象进行相对定位时，把它看作其父对象内部的第一个对象，其余定位逻辑与普通对象一致。
!> **注意：** <br> !> **注意：** <br>如果`ShadowRootElement`元素的下级元素中有其它`ShadowRootElement`元素，那这些下级`ShadowRootElement`
如果`ShadowRootElement`元素的下级元素中有其它`ShadowRootElement`元素，那这些下级`ShadowRootElement`
元素内部是无法直接通过定位语句查找到的，只能先定位到其父元素，再用`shadow-root`属性获取。 元素内部是无法直接通过定位语句查找到的，只能先定位到其父元素，再用`shadow-root`属性获取。
```python ```python
@ -855,7 +852,7 @@ eles = sr_ele.nexts('tag:div')
sr_ele2 = sr_ele.ele('tag:div').shadow_root sr_ele2 = sr_ele.ele('tag:div').shadow_root
``` ```
# 简化写法 # ✔️ 简化写法
为进一步精简代码，对语法进行了精简 为进一步精简代码，对语法进行了精简
@ -881,16 +878,16 @@ ele2 = ele1('x://div[@class="ele_class"]')
简化写法对应列表 简化写法对应列表
| 原写法 | 简化写法 | | 原写法 | 简化写法 |
|:-----------:|:----:| |:-------------:|:------:|
| text | tx | | `text` | `tx` |
| text() | tx() | | `text()` | `tx()` |
| tag | t | | `tag` | `t` |
| xpath | x | | `xpath` | `x` |
| css | c | | `css` | `c` |
| shadow_root | sr | | `shadow_root` | `sr` |
# Tips # ✔️ Tips
- 从一个`DriverElement`元素获取到的`SessionElement`版本，依然能够使用相对定位方法定位祖先或兄弟元素。 - 从一个`DriverElement`元素获取到的`SessionElement`版本，依然能够使用相对定位方法定位祖先或兄弟元素。
- `SessionElement`和`SessionPage`的`ele()`和`eles()`方法也有`timeout`参数，但它是不生效的，仅用于保持与 d 模式元素书写一致，便于无差别的调用。 - `SessionElement`和`SessionPage`的`ele()`和`eles()`方法也有`timeout`参数，但它是不生效的，仅用于保持与 d 模式元素书写一致，便于无差别的调用。

116
docs/MixPage使用方法/获取元素信息.md
View File

@ -5,7 +5,7 @@
`ShadowRootElement`由于是 shadow dom 元素，属性比较其余两种少，下文单独介绍。 `ShadowRootElement`由于是 shadow dom 元素，属性比较其余两种少，下文单独介绍。
# 示例 # ✔️ 示例
```python ```python
from DrissionPage import MixPage from DrissionPage import MixPage
@ -29,7 +29,7 @@ a 车载应用 https://gitee.com/explore/vehicle
""" """
``` ```
# 两种模式共有属性 # ✔️ 两种模式共有属性
假设`ele`为以下`div`元素的对象： 假设`ele`为以下`div`元素的对象：
@ -40,7 +40,7 @@ a 车载应用 https://gitee.com/explore/vehicle
</div> </div>
``` ```
## html ## 📍 `html`
此属性返回元素的`outerHTML`文本。 此属性返回元素的`outerHTML`文本。
@ -54,7 +54,7 @@ html = ele.html
""" """
``` ```
## inner_html ## 📍 `inner_html`
此属性返回元素的`innerHTML`文本。 此属性返回元素的`innerHTML`文本。
@ -67,7 +67,7 @@ Hello World!
""" """
``` ```
## tag ## 📍 `tag`
此属性返回元素的标签名。 此属性返回元素的标签名。
@ -76,7 +76,7 @@ tag = ele.tag
# 返回：div # 返回：div
``` ```
## text ## 📍 `text`
此属性返回元素内所有文本组合成的字符串。 此属性返回元素内所有文本组合成的字符串。
该字符串已格式化，即已转码，已去除多余换行符，符合人读取习惯，便于直接使用。无须重复写处理代码。 该字符串已格式化，即已转码，已去除多余换行符，符合人读取习惯，便于直接使用。无须重复写处理代码。
@ -89,7 +89,7 @@ Hello World!
""" """
``` ```
## raw_text ## 📍 `raw_text`
此属性返回元素内原始文本。 此属性返回元素内原始文本。
@ -103,15 +103,15 @@ Hello World!
""" """
``` ```
## texts() ## 📍 `texts()`
此方法返回元素内所有直接子节点的文本，包括元素和文本节点。 它有一个参数`text_node_only`，为`True`时则只获取只返回文本节点。这个方法适用于获取文本节点和元素节点混排的情况。 此方法返回元素内所有直接子节点的文本，包括元素和文本节点。 它有一个参数`text_node_only`，为`True`时则只获取只返回文本节点。这个方法适用于获取文本节点和元素节点混排的情况。
参数： **参数：**
- text_node_only：是否只返回文本节点 - `text_node_only`：是否只返回文本节点
返回：文本列表 **返回：** 文本列表
```python ```python
texts = ele.texts() texts = ele.texts()
@ -122,14 +122,14 @@ print(e.texts())
# 输出：['Hello World!'] # 输出：['Hello World!']
``` ```
## comments ## 📍 `comments`
```python ```python
comments = ele.comments comments = ele.comments
# 返回：[<!--这是注释-->] # 返回：[<!--这是注释-->]
``` ```
## attrs ## 📍 `attrs`
此属性以字典形式返回元素所有属性及值。 此属性以字典形式返回元素所有属性及值。
@ -138,23 +138,23 @@ attrs = ele.attrs
# 返回：{'id': 'div1'} # 返回：{'id': 'div1'}
``` ```
## attr() ## 📍 `attr()`
此方法返回元素某个`attribute`属性值。它接收一个字符串参数`attr`，返回该属性值文本，无该属性时返回`None`。 此方法返回元素某个`attribute`属性值。它接收一个字符串参数`attr`，返回该属性值文本，无该属性时返回`None`。
此属性返回的`src`、`href`属性为已补充完整的路径。`text`属性为已格式化文本，`innerText`属性为未格式化文本。 此属性返回的`src`、`href`属性为已补充完整的路径。`text`属性为已格式化文本，`innerText`属性为未格式化文本。
参数： **参数：**
- attr：属性名称 - `attr`：属性名称
返回：属性值文本 **返回：** 属性值文本
```python ```python
ele_id = ele.attr('id') ele_id = ele.attr('id')
# 返回：div1 # 返回：div1
``` ```
## link ## 📍 `link`
此方法返回元素的 href 属性或 src 属性，没有这两个属性则返回`None`。 此方法返回元素的 href 属性或 src 属性，没有这两个属性则返回`None`。
@ -169,7 +169,7 @@ link = a_ele.link
# 返回：http://www.baidu.com # 返回：http://www.baidu.com
``` ```
## page ## 📍 `page`
此属性返回元素所在的页面对象。 此属性返回元素所在的页面对象。
@ -180,7 +180,7 @@ link = a_ele.link
page = ele.page page = ele.page
``` ```
## inner_ele ## 📍 `inner_ele`
此属性返回被当前元素包装的对应模式原本的元素对象。 此属性返回被当前元素包装的对应模式原本的元素对象。
d 模式包装的是一个 selenium 的`WebElement`对象，s 模式包装的是一个 lxml 的`HtmlElement`对象。 d 模式包装的是一个 selenium 的`WebElement`对象，s 模式包装的是一个 lxml 的`HtmlElement`对象。
@ -193,7 +193,7 @@ web_ele = ele.inner_ele
web_ele.find_element(By.ID, 'ele_id').click() web_ele.find_element(By.ID, 'ele_id').click()
``` ```
## xpath ## 📍 `xpath`
此属性返回当前元素在页面中 xpath 的绝对路径。 此属性返回当前元素在页面中 xpath 的绝对路径。
@ -202,7 +202,7 @@ xpath = ele.xpath
# 返回：/html/body/div # 返回：/html/body/div
``` ```
## css_path ## 📍 `css_path`
此属性返回当前元素在页面中 css selector 的绝对路径。 此属性返回当前元素在页面中 css selector 的绝对路径。
@ -211,21 +211,21 @@ css = ele.css_path
# 返回：:nth-child(1)>:nth-child(1)>:nth-child(1) # 返回：:nth-child(1)>:nth-child(1)>:nth-child(1)
``` ```
## is_valid() ## 📍 `is_valid()`
此方法返回当前元素是否可用。`SessionElement`始终返回`True`，`DriverElement`视乎元素是否还在 DOM 内返回布尔值。 此方法返回当前元素是否可用。`SessionElement`始终返回`True`，`DriverElement`视乎元素是否还在 DOM 内返回布尔值。
参数：无 **参数：** 无
返回：`bool`类型 **返回：**`bool`类型
```python ```python
is_valid = ele.is_valid() is_valid = ele.is_valid()
``` ```
# DriverElement 独有属性 # ✔️ DriverElement 独有属性
## size ## 📍 `size`
此属性以字典形式返回元素的大小。 此属性以字典形式返回元素的大小。
@ -234,7 +234,7 @@ size = ele.size
# 返回：{'height': 50, 'width': 50} # 返回：{'height': 50, 'width': 50}
``` ```
## location ## 📍 `location`
此属性以字典形式返回元素坐标。 此属性以字典形式返回元素坐标。
@ -243,7 +243,7 @@ loc = ele.location
# 返回：{'x': 50, 'y': 50} # 返回：{'x': 50, 'y': 50}
``` ```
## pseudo_before ## 📍 `pseudo_before`
此属性以文本形式返回当前元素的`::before`伪元素内容。 此属性以文本形式返回当前元素的`::before`伪元素内容。
@ -251,7 +251,7 @@ loc = ele.location
before_txt = ele.pseudo_before before_txt = ele.pseudo_before
``` ```
## pseudo_after ## 📍 `pseudo_after`
此属性以文本形式返回当前元素的`::after`伪元素内容。 此属性以文本形式返回当前元素的`::after`伪元素内容。
@ -259,16 +259,16 @@ before_txt = ele.pseudo_before
after_txt = ele.pseudo_after after_txt = ele.pseudo_after
``` ```
## style() ## 📍 `style()`
该方法返回元素 css 样式属性值，可获取伪元素的属性。它有两个参数，`style`参数输入样式属性名称，`pseudo_ele`参数输入伪元素名称，省略则获取普通元素的 css 样式属性。 该方法返回元素 css 样式属性值，可获取伪元素的属性。它有两个参数，`style`参数输入样式属性名称，`pseudo_ele`参数输入伪元素名称，省略则获取普通元素的 css 样式属性。
参数： **参数：**
- style：样式名称 - `style`：样式名称
- pseudo_ele: 伪元素名称（如有） - `pseudo_ele`：伪元素名称（如有）
返回：样式属性值 **返回：** 样式属性值
```python ```python
# 获取 css 属性的 color 值 # 获取 css 属性的 color 值
@ -278,92 +278,92 @@ prop = ele.style('color')
prop = ele.style('content', 'after') prop = ele.style('content', 'after')
``` ```
## prop() ## 📍 `prop()`
此方法返回`property`属性值。它接收一个字符串参数，返回该参数的属性值。 此方法返回`property`属性值。它接收一个字符串参数，返回该参数的属性值。
参数： **参数：**
- prop：属性名称 - `prop`：属性名称
返回：属性值 **返回：** 属性值
```python ```python
prop = ele.prop('value') prop = ele.prop('value')
``` ```
## select ## 📍 `select`
此属性返回 `select` 元素用于处理下拉列表的 Select 类（“[元素操作](元素操作.md)”章节说明），非下拉列表元素返回`False`。 此属性返回 `select` 元素用于处理下拉列表的 Select 类（“[元素操作](元素操作.md)”章节说明），非下拉列表元素返回`False`。
## is_selected() ## 📍 `is_selected()`
此方法以布尔值返回元素是否选中。 此方法以布尔值返回元素是否选中。
参数：无 **参数：** 无
返回：布尔值 **返回：** `bool`
```python ```python
selected = ele.is_selected() selected = ele.is_selected()
``` ```
## is_enabled() ## 📍 `is_enabled()`
此方法以布尔值返回元素是否可用。 此方法以布尔值返回元素是否可用。
参数：无 **参数：** 无
返回：布尔值 **返回：**`bool`
```python ```python
enable = ele.is_enabled() enable = ele.is_enabled()
``` ```
## is_displayed() ## 📍 `is_displayed()`
此方法以布尔值返回元素是否可见。 此方法以布尔值返回元素是否可见。
参数：无 **参数：** 无
返回：布尔值 **返回：**`bool`
```python ```python
displayed = ele.is_displayed() displayed = ele.is_displayed()
``` ```
# `ShadowRootElement`属性与方法 # ✔️ `ShadowRootElement`属性与方法
本库把 shadow dom 的`root`看作一个元素处理，可以获取属性，也可以执行其下级的查找，但其属性比较少。有如下这些： 本库把 shadow dom 的`root`看作一个元素处理，可以获取属性，也可以执行其下级的查找，但其属性比较少。有如下这些：
## tag ## 📍 `tag`
此属性返回元素标签名，即`'shadow-root'`。 此属性返回元素标签名，即`'shadow-root'`。
## html ## 📍 `html`
此属性返回`shadow_root`的 html 文本，由`<shadow_root></shadow_root>` 标签包裹。 此属性返回`shadow_root`的 html 文本，由`<shadow_root></shadow_root>` 标签包裹。
## inner_html ## 📍 `inner_html`
此属性返回`shadow_root`内部的 html 文本。 此属性返回`shadow_root`内部的 html 文本。
## page ## 📍 `page`
此属性返回元素所在页面对象。 此属性返回元素所在页面对象。
## inner_ele ## 📍 `inner_ele`
此属性返回对象中保存的`shadow-root`元素。 此属性返回对象中保存的`shadow-root`元素。
## parent_ele ## 📍 `parent_ele`
这是`ShadowRootElement`独有的属性，返回它所依附的普通元素对象。 这是`ShadowRootElement`独有的属性，返回它所依附的普通元素对象。
## is_enabled() ## 📍 `is_enabled()`
与`DriverElement`一致。 与`DriverElement`一致。
## is_valid() ## 📍 `is_valid()`
与`DriverElement`一致。 与`DriverElement`一致。

66
docs/MixPage使用方法/获取网页信息.md
View File

@ -1,42 +1,42 @@
本节介绍获取页面对象各种信息的属性和方法。 本节介绍获取页面对象各种信息的属性和方法。
# 两种模式共有属性 # ✔️ 两种模式共有属性
## url ## 📍 `url`
此属性返回当前访问的 url。 此属性返回当前访问的 url。
## mode ## 📍 `mode`
此属性返回当前页面对象的模式，`'s'`或`'d'`。 此属性返回当前页面对象的模式，`'s'`或`'d'`。
## drission ## 📍 `drission`
此属性返回当前页面对象使用的`Drission`对象。 此属性返回当前页面对象使用的`Drission`对象。
## driver ## 📍 `driver`
此属性返回当前页面对象使用的`WebDriver`对象。访问时会自动切换到 d 模式。 此属性返回当前页面对象使用的`WebDriver`对象。访问时会自动切换到 d 模式。
## session ## 📍 `session`
此属性返回当前页面对象使用的`Session`对象。访问时不会切换模式。 此属性返回当前页面对象使用的`Session`对象。访问时不会切换模式。
## cookies ## 📍 `cookies`
此属性以`dict`方式返回当前页面所使用的 cookies。 此属性以`dict`方式返回当前页面所使用的 cookies。
d 模式只返回当前标签页的 cookies，s 模式则只返回当前访问的 url 的`cookies`。 d 模式只返回当前标签页的 cookies，s 模式则只返回当前访问的 url 的`cookies`。
## get_cookies() ## 📍 `get_cookies()`
此方法获取 cookies 并以 cookie 组成的`list`形式返回。 此方法获取 cookies 并以 cookie 组成的`list`形式返回。
参数： **参数：**
- as_dict：是否以字典方式返回，为`False`返回`cookie`组成的`list` - `as_dict`：是否以字典方式返回，为`False`返回`cookie`组成的`list`
- all_domains：是否返回所有域的`cookies`，只有 s 模式下生效 - `all_domains`：是否返回所有域的`cookies`，只有 s 模式下生效
返回：`cookies`信息 **返回：**`cookies`信息
```python ```python
from DrissionPage import MixPage from DrissionPage import MixPage
@ -58,15 +58,15 @@ for i in p.get_cookies(as_dict=False, all_domains=True):
...... ......
``` ```
## html ## 📍 `html`
此属性返回当前页面 html 文本。 此属性返回当前页面 html 文本。
## title ## 📍 `title`
此属性返回当前页面`title`文本。 此属性返回当前页面`title`文本。
## timeout ## 📍 `timeout`
s 模式下，此属性代表网络请求超时时间。 s 模式下，此属性代表网络请求超时时间。
d 模式下，此属性为元素查找、点击、处理提示框等操作的超时时间。 d 模式下，此属性为元素查找、点击、处理提示框等操作的超时时间。
@ -80,7 +80,7 @@ page = MixPage(timeout=5)
page.timeout = 20 page.timeout = 20
``` ```
## retry_times ## 📍 `retry_times`
此参数为网络连接失败时的重试次数。默认为 3，可对其赋值。 此参数为网络连接失败时的重试次数。默认为 3，可对其赋值。
@ -89,7 +89,7 @@ page.timeout = 20
page.retry_times = 5 page.retry_times = 5
``` ```
## retry_interval ## 📍 `retry_interval`
此参数为网络连接失败时的重试等待间隔秒数。默认为 2，可对其赋值。 此参数为网络连接失败时的重试等待间隔秒数。默认为 2，可对其赋值。
@ -98,15 +98,15 @@ page.retry_times = 5
page.retry_interval = 1.5 page.retry_interval = 1.5
``` ```
## url_available ## 📍 `url_available`
此属性以布尔值返回当前链接是否可用。 此属性以布尔值返回当前链接是否可用。
s 模式下根据`Response`对象的`status_code`判断。 s 模式下根据`Response`对象的`status_code`判断。
d 模式根据`check_page()`方法返回值判断。 d 模式根据`check_page()`方法返回值判断。
# s 模式独有属性 # ✔️ s 模式独有属性
## response ## 📍 `response`
此属性为 s 模式请求网站后生成的`Response`对象，本库没实现的功能可直接获取此属性调用 requests 库的原生功能。 此属性为 s 模式请求网站后生成的`Response`对象，本库没实现的功能可直接获取此属性调用 requests 库的原生功能。
@ -116,15 +116,15 @@ r = page.response
print(r.status_code) print(r.status_code)
``` ```
## json ## 📍 `json`
此属性把请求内容解析成 json。 此属性把请求内容解析成 json。
比如请求接口时，返回内容是 json 格式，那就可以用这个属性获取。 比如请求接口时，返回内容是 json 格式，那就可以用这个属性获取。
事实上，用 html 属性获取也是可以的，不过 html 属性没有对文本进行解析。 事实上，用 html 属性获取也是可以的，不过 html 属性没有对文本进行解析。
# d 模式独有属性 # ✔️ d 模式独有属性
## timeouts ## 📍 `timeouts`
此属性以字典方式返回三种超时时间，selenium 4 以上版本可用。 此属性以字典方式返回三种超时时间，selenium 4 以上版本可用。
`'implicit'`用于元素查找、点击重试、输入文本重试、处理弹出框重试等； `'implicit'`用于元素查找、点击重试、输入文本重试、处理弹出框重试等；
@ -141,41 +141,41 @@ print(page.timeouts)
{'implicit': 10, 'pageLoad': 30.0, 'script': 30.0} {'implicit': 10, 'pageLoad': 30.0, 'script': 30.0}
``` ```
## tabs_count ## 📍 `tabs_count`
此属性返回当前浏览器标签页数量。 此属性返回当前浏览器标签页数量。
## tab_handles ## 📍 `tab_handles`
此属性以列表形式返回当前浏览器所有标签页的 handle。 此属性以列表形式返回当前浏览器所有标签页的 handle。
!> **注意：** !> **注意：**
以下情况会导致获取到的顺序与视觉效果不一致：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 以下情况会导致获取到的顺序与视觉效果不一致：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。
## current_tab_index ## 📍 `current_tab_index`
此属性返回当前标签页的序号。 此属性返回当前标签页的序号。
!> **注意：** <br>以下情况会导致获取到的排序号与视觉效果不一致：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 !> **注意：** <br>以下情况会导致获取到的排序号与视觉效果不一致：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。
## current_tab_handle ## 📍 `current_tab_handle`
此属性返回当前标签页的 handle。 此属性返回当前标签页的 handle。
## active_ele ## 📍 `active_ele`
此属性返回当前页面上焦点所在元素。类型为`DriverElement`。 此属性返回当前页面上焦点所在元素。类型为`DriverElement`。
## wait_obj ## 📍 `wait_obj`
此属性返回当前页面对象用于等待的对象。 此属性返回当前页面对象用于等待的对象。
## chrome_downloading() ## 📍 `chrome_downloading()`
此方法返回浏览器下载中的文件列表。 此方法返回浏览器下载中的文件列表。
参数： **参数：**
- path: 下载文件夹路径，默认从配置信息读取 - `path:` 下载文件夹路径，默认从配置信息读取
返回：下载中的文件列表 **返回：** 下载中的文件列表

38
docs/MixPage使用方法/访问网页.md
View File

@ -1,23 +1,23 @@
操作页面前通常要先跳转到目标 url（接管现有浏览器除外），本库访问网页主要支持`get()`和`post()`两种方式，还支持自动重试。 操作页面前通常要先跳转到目标 url（接管现有浏览器除外），本库访问网页主要支持`get()`和`post()`两种方式，还支持自动重试。
# get() # ✔️ `get()`
该方法在 d 模式和 s 模式下都可用，用于跳转到一个网址。 该方法在 d 模式和 s 模式下都可用，用于跳转到一个网址。
当连接失败时，程序默认重试 3 次，每次间隔 2 秒，也可以通过参数设置重试次数和间隔。 当连接失败时，程序默认重试 3 次，每次间隔 2 秒，也可以通过参数设置重试次数和间隔。
在 s 模式下，可传入连接参数，语法与 requests 的`get()`方法一致。 在 s 模式下，可传入连接参数，语法与 requests 的`get()`方法一致。
方法返回是否连接成功的布尔值，s 模式下根据`Response`对象的`status_code`参数决定，d 模式下根据浏览器的状态，还可以通过重写`check_page()`方法实现自定义检查方式。 方法返回是否连接成功的布尔值，s 模式下根据`Response`对象的`status_code`参数决定，d 模式下根据浏览器的状态，还可以通过重写`check_page()`方法实现自定义检查方式。
参数： **参数：**
- url：目标 url - `url`：目标 url
- show_errmsg：是否显示和抛出异常，默认不抛出，连接错误会返回`None` - `show_errmsg`：是否显示和抛出异常，默认不抛出，连接错误会返回`None`
- retry：重试次数，与页面对象的设置一致，默认 3 次 - `retry`：重试次数，与页面对象的设置一致，默认 3 次
- interval：重试间隔（秒），与页面对象的设置一致，默认 2 秒 - `interval`：重试间隔（秒），与页面对象的设置一致，默认 2 秒
- **kwargs：连接参数，s 模式专用，与 requests 的使用方法一致 - `**kwargs`：连接参数，s 模式专用，与 requests 的使用方法一致
返回：`bool`类型，表示是否连接成功，d 模式下如返回`None`表示不确定 **返回：**`bool`类型，表示是否连接成功，d 模式下如返回`None`表示不确定
## d 模式 ## 📍 d 模式
```python ```python
from DrissionPage import MixPage from DrissionPage import MixPage
@ -26,7 +26,7 @@ page = MixPage('d')
page.get('https://www.baidu.com') page.get('https://www.baidu.com')
``` ```
## s 模式 ## 📍 s 模式
s 模式的`**kwargs`参数与 requests 中该参数使用方法一致，但有一个特点，如果该参数中设置了某一项（如`headers`），该项中的每个项会覆盖从配置中读取的同名项，而不会整个覆盖。 s 模式的`**kwargs`参数与 requests 中该参数使用方法一致，但有一个特点，如果该参数中设置了某一项（如`headers`），该项中的每个项会覆盖从配置中读取的同名项，而不会整个覆盖。
就是说，如果想继续使用配置中的`headers`信息，而只想修改其中一项，只需要传入该项的值即可。这样可以简化代码逻辑。 就是说，如果想继续使用配置中的`headers`信息，而只想修改其中一项，只需要传入该项的值即可。这样可以简化代码逻辑。
@ -48,19 +48,19 @@ proxies = {'http': '127.0.0.1:1080', 'https': '127.0.0.1:1080'}
page.get(url, headers=headers, cookies=cookies, proxies=proxies) page.get(url, headers=headers, cookies=cookies, proxies=proxies)
``` ```
# post() # ✔️ `post()`
此方法是用 post 方式请求页面。大致用法与`get()`一致，但增加一个`data`参数。 此方法是用 post 方式请求页面。大致用法与`get()`一致，但增加一个`data`参数。
此方法只有 s 模式拥有，调用时，页面对象会自动切换到 s 模式。 此方法只有 s 模式拥有，调用时，页面对象会自动切换到 s 模式。
参数： **参数：**
- url：目标 url - `url`：目标 url
- data：提交的数据，可以是`dict`或`str`类型 - `data`：提交的数据，可以是`dict`或`str`类型
- show_errmsg：是否显示和抛出异常，默认不抛出，连接错误会返回 None - `show_errmsg`：是否显示和抛出异常，默认不抛出，连接错误会返回 None
- retry：重试次数，与页面对象的设置一致，默认 3 次 - `retry`：重试次数，与页面对象的设置一致，默认 3 次
- interval：重试间隔（秒），与页面对象的设置一致，默认 2 秒 - `interval`：重试间隔（秒），与页面对象的设置一致，默认 2 秒
- **kwargs：连接参数，s 模式专用 - `**kwargs`：连接参数，s 模式专用
?> **Tips:** <br>虽然参数里没有`json`参数，但也和 requests 一样可以对`json`参数传值。 ?> **Tips:** <br>虽然参数里没有`json`参数，但也和 requests 一样可以对`json`参数传值。
@ -91,7 +91,7 @@ page.post(url, json='xxx')
page.post(url, json={'xxx': 'xxx'}) page.post(url, json={'xxx': 'xxx'})
``` ```
# 其它请求方式 # ✔️ 其它请求方式
本库只针对常用的 get 和 post 方式作了优化，但也可以通过提取页面对象内的`Session`对象以原生 requests 代码方式执行其它请求方式。当然，它们工作在 s 模式。 本库只针对常用的 get 和 post 方式作了优化，但也可以通过提取页面对象内的`Session`对象以原生 requests 代码方式执行其它请求方式。当然，它们工作在 s 模式。

351
docs/MixPage使用方法/页面操作.md
View File

@ -1,28 +1,24 @@
本节介绍页面对象可以使用的方法，有些方法是两种模式共有的，有些只有某种模式可以使用。当调用独有方法时，会自动切换到该模式。如调用`post()`方法时，会先切换到 s 模式，并同步登录信息。 本节介绍页面对象可以使用的方法，有些方法是两种模式共有的，有些只有某种模式可以使用。当调用独有方法时，会自动切换到该模式。如调用`post()`方法时，会先切换到 s 模式，并同步登录信息。
# 两种模式共有的方法 # ✔️ 两种模式共有的方法
## get() ## 📍 `get()`
此方法用于跳转到一个 url，详细用法见“[使用方法 -> 访问网页](使用方法/访问网页.md)”章节。 此方法用于跳转到一个 url，详细用法见“访问网页”章节。
## ele()、eles()、s_ele()、s_eles() ## 📍 `change_mode()`
这些方法用于在页面中查找元素，详细用法见“[使用方法 -> 查找页面元素](使用方法/查找页面元素)”章节。
## change_mode()
此方法用于转换`MixPage`对象的模式。 此方法用于转换`MixPage`对象的模式。
切换后默认在目标模式重新跳转到原模式所在 url。 切换后默认在目标模式重新跳转到原模式所在 url。
!> **注意：** <br>s 模式转 d 模式时，若浏览器当前网址域名和 s 模式不一样，必定会跳转。 !> **注意：** <br>s 模式转 d 模式时，若浏览器当前网址域名和 s 模式不一样，必定会跳转。
参数： **参数：**
- mode：目标模式字符串，`'s'`或`'d'`，默认转换到另一种 - `mode`：目标模式字符串，`'s'`或`'d'`，默认转换到另一种
- go：转换后是否跳转到原模式所在 url - `go`：转换后是否跳转到原模式所在 url
返回：`None` **返回：**`None`
```python ```python
from DrissionPage import MixPage from DrissionPage import MixPage
@ -60,106 +56,106 @@ print('登录后title：', page.title)
登录后title： 个人资料 - 码云 Gitee.com 登录后title： 个人资料 - 码云 Gitee.com
``` ```
## set_cookies() ## 📍 `set_cookies()`
此方法用于设置`cookies`。 此方法用于设置`cookies`。
可以接收`CookieJar`、`list`、`tuple`、`str`、`dict`格式的`cookies`。 可以接收`CookieJar`、`list`、`tuple`、`str`、`dict`格式的`cookies`。
参数： **参数：**
- cookies：`cookies`信息 - `cookies`：`cookies`信息
- refresh：设置`cookies`后是否刷新页面 - `refresh`：设置`cookies`后是否刷新页面
返回：`None` **返回：**`None`
```python ```python
cookies = {'name': 'abc'} cookies = {'name': 'abc'}
page.set_cookies(cookies) page.set_cookies(cookies)
``` ```
## cookies_to_session() ## 📍 `cookies_to_session()`
此方法用于从`WebDriver`对象复制`cookies`到`Session`对象。 此方法用于从`WebDriver`对象复制`cookies`到`Session`对象。
参数： **参数：**
- copy_user_agent：是否同时复制 user agent 信息 - `copy_user_agent`：是否同时复制 user agent 信息
返回：`None` **返回：**`None`
## cookies_to_driver() ## 📍 `cookies_to_driver()`
此方法用于从`Session`对象复制`cookies`到`WebDriver`对象。 此方法用于从`Session`对象复制`cookies`到`WebDriver`对象。
参数： **参数：**
- url：指定 url，默认用当前 url - `url`：指定 url，默认用当前 url
返回：`None` **返回：**`None`
## download() ## 📍 `download()`
此方法用于下载文件，详细用法见“[使用方法 -> 下载文件](下载文件.md)”章节。 此方法用于下载文件，详细用法见“下载文件”章节。
## close_driver() ## 📍 `close_driver()`
此方法用于关闭`WebDriver`对象和浏览器。 此方法用于关闭`WebDriver`对象和浏览器。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## close_session() ## 📍 `close_session()`
此方法用于关闭`Session`对象。 此方法用于关闭`Session`对象。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
# s 模式独有方法 # ✔️ s 模式独有方法
## post() ## 📍 `post()`
此方法用于以 post 方式访问 url，具体用法见“[使用方法 -> 访问网页](访问网页.md)”章节。 此方法用于以 post 方式访问 url，具体用法见“访问网页”章节。
# d 模式独有方法 # ✔️ d 模式独有方法
## hide_browser() ## 📍 `hide_browser()`
此方法用于隐藏浏览器进程窗口，非最小化，任务栏上也可隐藏。 此方法用于隐藏浏览器进程窗口，非最小化，任务栏上也可隐藏。
但若操作过程中有新增标签页，浏览器会重新出现。 只支持 Windows 系统，且只有设置了`local_port`或`debugger_address`时生效。 但若操作过程中有新增标签页，浏览器会重新出现。 只支持 Windows 系统，且只有设置了`local_port`或`debugger_address`时生效。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## show_browser() ## 📍 `show_browser()`
此方法用于显示被隐藏的浏览器进程。 此方法用于显示被隐藏的浏览器进程。
只支持 Windows 系统，且只有设置了`local_port`或`debugger_address`时生效。 只支持 Windows 系统，且只有设置了`local_port`或`debugger_address`时生效。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## wait_ele() ## 📍 `wait_ele()`
此方法用于等待元素到达某种状态。 此方法用于等待元素到达某种状态。
调用此方法返回一个`ElementWaiter`对象，调用该对象方法实现各种方式的等待。 调用此方法返回一个`ElementWaiter`对象，调用该对象方法实现各种方式的等待。
参数： **参数：**
- loc_or_ele：要等待的元素，可以是元素或定位符 - `loc_or_ele`：要等待的元素，可以是元素或定位符
- timeout：等待超时时间，默认使用页面超时时间 - `timeout`：等待超时时间，默认使用页面超时时间
方法： **方法：**
| 方法 | 参数说明 | 功能 | | 方法 | 参数说明 | 功能 |
|:---------:|:----:|:------------:| |:-----------:|:----:|:------------:|
| display() | 无 | 等待元素从 DOM 显示 | | `display()` | 无 | 等待元素从 DOM 显示 |
| hidden() | 无 | 等待元素从 DOM 隐藏 | | `hidden()` | 无 | 等待元素从 DOM 隐藏 |
| delete() | 无 | 等待元素从 DOM 删除 | | `delete()` | 无 | 等待元素从 DOM 删除 |
这些方法返回布尔值，代表是否等待成功。 这些方法返回布尔值，代表是否等待成功。
@ -175,148 +171,148 @@ ele = page.ele('#div1')
paeg.wait_ele(ele).hidden() paeg.wait_ele(ele).hidden()
``` ```
## run_script() ## 📍 `run_script()`
此方法用于执行 js 脚本。 此方法用于执行 js 脚本。
参数： **参数：**
- script：js 脚本文本 - `script`：js 脚本文本
- *args：传入的参数 - `*args`：传入的参数
返回：脚本执行结果 **返回：** 脚本执行结果
```python ```python
# 执行 js 脚本显示弹出框显示 Hello world! # 执行 js 脚本显示弹出框显示 Hello world!
page.run_script('alert(arguments[0]+arguments[1])', 'Hello', ' world!') page.run_script('alert(arguments[0]+arguments[1])', 'Hello', ' world!')
``` ```
## run_async_script() ## 📍 `run_async_script()`
此方法用于以异步方式执行 js 脚本。 此方法用于以异步方式执行 js 脚本。
参数： **参数：**
- script：js 脚本文本 - `script`：js 脚本文本
- *args：传入的参数 - `*args`：传入的参数
返回：脚本执行结果 **返回：** 脚本执行结果
## run_cdp() ## 📍 `run_cdp()`
此方法用于执行 Chrome DevTools Protocol 语句。cdp 此方法用于执行 Chrome DevTools Protocol 语句。cdp
用法详见[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)。 用法详见[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)。
参数： **参数：**
- cmd：协议项目方法 - `cmd`：协议项目方法
- **cmd_args：项目参数 - `**cmd_args`：项目参数
返回：该语句返回的值 **返回：** 该语句返回的值
```python ```python
# 停止页面加载 # 停止页面加载
page.run_cdp('Page.stopLoading') page.run_cdp('Page.stopLoading')
``` ```
## set_timeouts() ## 📍 `set_timeouts()`
此方法用于设置三种超时时间，selenium 4 以上版本生效。 此方法用于设置三种超时时间，selenium 4 以上版本生效。
参数： **参数：**
- implicit：查找元素超时时间 - `implicit`：查找元素超时时间
- pageLoad：页面加载超时时间 - `pageLoad`：页面加载超时时间
- script：脚本运行超时时间 - `script`：脚本运行超时时间
返回：`None` **返回：**`None`
## set_ua_to_tab() ## 📍 `set_ua_to_tab()`
此方法用于为当前 tab 设置 user agent，只在当前 tab 有效。 此方法用于为当前 tab 设置 user agent，只在当前 tab 有效。
参数： **参数：**
- ua：user agent字符串 - `ua`：user agent字符串
返回：None **返回：**`None`
## get_session_storage() ## 📍 `get_session_storage()`
此方法用于获取 sessionStorage 信息，可获取全部或单个项。 此方法用于获取 sessionStorage 信息，可获取全部或单个项。
参数： **参数：**
- item：要获取的项，不设置则返回全部 - `item`：要获取的项，不设置则返回全部
返回：sessionStorage 一个或所有项内容 **返回：** sessionStorage 一个或所有项内容
## get_local_storage() ## 📍 `get_local_storage()`
此方法用于获取 localStorage 信息，可获取全部或单个项。 此方法用于获取 localStorage 信息，可获取全部或单个项。
参数： **参数：**
- item：要获取的项，不设置则返回全部 - `item`：要获取的项，不设置则返回全部
返回：localStorage 一个或所有项内容 **返回：** localStorage 一个或所有项内容
## set_session_storage() ## 📍 `set_session_storage()`
此方法用于设置或删除某项 sessionStorage 信息。 此方法用于设置或删除某项 sessionStorage 信息。
参数： **参数：**
- item：要设置的项 - `item`：要设置的项
- value：项的值，设置为False时，删除该项 - `value`：项的值，设置为False时，删除该项
返回：`None` **返回：**`None`
## set_local_storage() ## 📍 `set_local_storage()`
此方法用于设置或删除某项 localStorage 信息。 此方法用于设置或删除某项 localStorage 信息。
参数： **参数：**
- item：要设置的项 - `item`：要设置的项
- value：项的值，设置为False时，删除该项 - `value`：项的值，设置为False时，删除该项
返回：`None` **返回：**`None`
## clean_cache() ## 📍 clean_cache()
此方法用于清除缓存，可选要清除的项。 此方法用于清除缓存，可选要清除的项。
参数： **参数：**
- session_storage：是否清除 sessionstorage - `session_storage`：是否清除 sessionstorage
- local_storage：是否清除 localStorage - `local_storage`：是否清除 localStorage
- cache：是否清除 cache - `cache`：是否清除 cache
- cookies：是否清除 cookies - `cookies`：是否清除 cookies
返回：`None` **返回：**`None`
## to_frame ## 📍 `to_frame`
此属性用于将页面焦点移到某个`frame`或`iframe`。 此属性用于将页面焦点移到某个`frame`或`iframe`。
调用此属性返回一个`ToFrame`对象，调用该对象的方法实现焦点转移。 调用此属性返回一个`ToFrame`对象，调用该对象的方法实现焦点转移。
这些方法返回值为当前页面对象，可实现下一步的链式操作。 这些方法返回值为当前页面对象，可实现下一步的链式操作。
| 方法 | 参数说明 | 功能 | | 方法 | 参数说明 | 功能 |
|:---------------:|:-------:|:----------------:| |:-----------------:|:-------:|:----------------:|
| main() | 无 | 切换到顶层框架 | | `main()` | 无 | 切换到顶层框架 |
| parent(level) | 第几层上级框架 | 切换到上级框架，可指定多层 | | `parent(level)` | 第几层上级框架 | 切换到上级框架，可指定多层 |
| by_id(id) | id 属性 | 切换到`id`为该参数的框架 | | `by_id(id)` | id 属性 | 切换到`id`为该参数的框架 |
| by_name(name) | name 属性 | 切换到`name`为该参数的框架 | | `by_name(name)` | name 属性 | 切换到`name`为该参数的框架 |
| by_index(index) | 序号 | 切换到页面第几个框架，0 开始 | | `by_index(index)` | 序号 | 切换到页面第几个框架，0 开始 |
| by_loc(loc) | 定位符 | 切换到定位符所指框架 | | `by_loc(loc)` | 定位符 | 切换到定位符所指框架 |
| by_ele(ele) | 框架元素 | 传入框架元素，切换到该框架 | | `by_ele(ele)` | 框架元素 | 传入框架元素，切换到该框架 |
```python ```python
# 切换到主框架 # 切换到主框架
@ -362,18 +358,17 @@ iframe = page.ele('tag:iframe')
page.to_frame(iframe) page.to_frame(iframe)
``` ```
!> **注意：** <br> !> **注意：**<br>新版本删除了`to_frame('main')`和`to_frame('parent')`的用法。 <br>请改用`page.to_frame.main()`和`page.to_frame.parent()`的写法。
新版本删除了`to_frame('main')`和`to_frame('parent')`的用法。 <br>请改用`page.to_frame.main()`和`page.to_frame.parent()`的写法。
## to_tab() ## 📍 `to_tab()`
此方法把焦点定位到某个标签页。 此方法把焦点定位到某个标签页。
参数： **参数：**
- num_or_handle：标签页序号或 handle 字符串，序号第一个为 0，最后为 -1 - `num_or_handle`：标签页序号或 handle 字符串，序号第一个为 0，最后为 -1
返回：None **返回：**`None`
!> **注意：** <br>以下情况会导致获取到的排序号与视觉效果不一致：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 !> **注意：** <br>以下情况会导致获取到的排序号与视觉效果不一致：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。
@ -385,31 +380,31 @@ page.to_tab(0)
page.to_tab('xxxxxxxxxxxxxxxxxxxx') page.to_tab('xxxxxxxxxxxxxxxxxxxx')
``` ```
## create_tab() ## 📍 `create_tab()`
此方法用于新建并定位到一个标签页,该标签页在最后面。可指定跳转到一个 url。 此方法用于新建并定位到一个标签页,该标签页在最后面。可指定跳转到一个 url。
参数： **参数：**
- url：新标签页跳转到的 url - `url`：新标签页跳转到的 url
返回：`None` **返回：**`None`
```python ```python
page.create_tab('http://www.baidu.com') page.create_tab('http://www.baidu.com')
``` ```
## close_tabs() ## 📍 `close_tabs()`
此方法用于关闭指定的标签页，标签页可以是序号或 handle 值，可关闭多个。默认关闭当前的。 此方法用于关闭指定的标签页，标签页可以是序号或 handle 值，可关闭多个。默认关闭当前的。
!> **注意：** <br>以下情况会导致获取到的排序号与视觉效果不一致，不能按序号关闭：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 !> **注意：** <br>以下情况会导致获取到的排序号与视觉效果不一致，不能按序号关闭：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。
参数： **参数：**
- num_or_handles：要保留的标签页序号或 handle，可传入 list 或 tuple，为None时关闭当前页 - `num_or_handles`：要保留的标签页序号或 handle，可传入 list 或 tuple，为None时关闭当前页
返回：`None` **返回：**`None`
```python ```python
# 关闭当前标签页 # 关闭当前标签页
@ -419,17 +414,17 @@ page.close_tabs()
page.close_tabs((0, 2)) page.close_tabs((0, 2))
``` ```
## close_other_tabs() ## 📍 `close_other_tabs()`
此方法用于关闭指定标签页以外的标签页，标签页可以是序号或 handle 值，可保留多个。默认保留当前的。 此方法用于关闭指定标签页以外的标签页，标签页可以是序号或 handle 值，可保留多个。默认保留当前的。
!> **注意：** <br>以下情况会导致获取到的排序号与视觉效果不一致，不能按序号关闭：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 !> **注意：** <br>以下情况会导致获取到的排序号与视觉效果不一致，不能按序号关闭：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。
参数： **参数：**
- num_or_handles：要保留的标签页序号或 handle，可传入`list`或`tuple`，为`None`时关闭当前页 - `num_or_handles`：要保留的标签页序号或 handle，可传入`list`或`tuple`，为`None`时关闭当前页
返回：`None` **返回：**`None`
```python ```python
# 关闭除当前标签页外的所有标签页 # 关闭除当前标签页外的所有标签页
@ -443,23 +438,23 @@ reserve_list = ('aaaaa', 'bbbbb')
page.close_other_tabs(reserve_list) page.close_other_tabs(reserve_list)
``` ```
## scroll ## 📍 `scroll`
此属性用于以某种方式滚动页面。 此属性用于以某种方式滚动页面。
调用此属性返回一个`Scroll`对象，调用该对象方法实现各种方式的滚动。 调用此属性返回一个`Scroll`对象，调用该对象方法实现各种方式的滚动。
| 方法 | 参数说明 | 功能 | | 方法 | 参数说明 | 功能 |
|:-----------------:|:------:|:----------------:| |:-------------------:|:------:|:----------------:|
| to_top() | 无 | 滚动到顶端，水平位置不变 | | `to_top()` | 无 | 滚动到顶端，水平位置不变 |
| to_bottom() | 无 | 滚动到底端，水平位置不变 | | `to_bottom()` | 无 | 滚动到底端，水平位置不变 |
| to_half() | 无 | 滚动到垂直中间位置，水平位置不变 | | `to_half()` | 无 | 滚动到垂直中间位置，水平位置不变 |
| to_rightmost() | 无 | 滚动到最右边，垂直位置不变 | | `to_rightmost()` | 无 | 滚动到最右边，垂直位置不变 |
| to_leftmost() | 无 | 滚动到最左边，垂直位置不变 | | `to_leftmost()` | 无 | 滚动到最左边，垂直位置不变 |
| to_location(x, y) | 滚动条坐标值 | 滚动到指定位置 | | `to_location(x, y)` | 滚动条坐标值 | 滚动到指定位置 |
| up(pixel) | 滚动的像素 | 向上滚动若干像素，水平位置不变 | | `up(pixel)` | 滚动的像素 | 向上滚动若干像素，水平位置不变 |
| down(pixel) | 滚动的像素 | 向下滚动若干像素，水平位置不变 | | `down(pixel)` | 滚动的像素 | 向下滚动若干像素，水平位置不变 |
| right(pixel) | 滚动的像素 | 向左滚动若干像素，垂直位置不变 | | `right(pixel)` | 滚动的像素 | 向左滚动若干像素，垂直位置不变 |
| left(pixel) | 滚动的像素 | 向右滚动若干像素，垂直位置不变 | | `left(pixel)` | 滚动的像素 | 向右滚动若干像素，垂直位置不变 |
```python ```python
# 页面滚动到底部 # 页面滚动到底部
@ -475,15 +470,15 @@ page.scroll.down(200)
page.scroll.to_location(100, 300) page.scroll.to_location(100, 300)
``` ```
## scroll_to_see() ## 📍 `scroll_to_see()`
此方法用于滚动页面直到元素可见。 此方法用于滚动页面直到元素可见。
参数： **参数：**
- loc_or_ele：元素的定位信息，可以是元素、定位符 - `loc_or_ele`：元素的定位信息，可以是元素、定位符
返回：`None` **返回：**`None`
```python ```python
# 滚动到某个已获取到的元素 # 滚动到某个已获取到的元素
@ -497,68 +492,68 @@ page.scroll_to_see('tag:div')
page.scroll_to_see((By.XPATH, '//div')) page.scroll_to_see((By.XPATH, '//div'))
``` ```
## refresh() ## 📍 `refresh()`
此方法用于刷新当前页面。 此方法用于刷新当前页面。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## stop_loading() ## 📍 `stop_loading()`
此方法用于强制当前页面加载。 此方法用于强制当前页面加载。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## back() ## 📍 `back()`
此方法用于在浏览历史中后退一步。 此方法用于在浏览历史中后退一步。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## forward() ## 📍 `forward()`
此方法用于在浏览历史中前进一步。 此方法用于在浏览历史中前进一步。
参数：无 **参数：** 无
返回：`None` **返回：**`None`
## screenshot() ## 📍 `screenshot()`
此方法用于生成页面可见范围截图。图片为 png 格式。 此方法用于生成页面可见范围截图。图片为 png 格式。
此方法能够自动处理文件重命名的情况，给新文件后面增加序号。 此方法能够自动处理文件重命名的情况，给新文件后面增加序号。
也可以返回图片的二进制文本。 也可以返回图片的二进制文本。
参数： **参数：**
- path：图片保存路径 - `path`：图片保存路径
- filename：图片文件名，可不写后缀，不传入时以页面 title 命名 - `filename`：图片文件名，可不写后缀，不传入时以页面 title 命名
- as_bytes：是否已字节形式返回图片，为True时上面两个参数失效 - `as_bytes`：是否已字节形式返回图片，为True时上面两个参数失效
返回：图片完整路径或字节文本 **返回：** 图片完整路径或字节文本
```python ```python
path = page.screenshot(r'D:\tmp', 'img1') # 保存到路径，文件名为img1.png path = page.screenshot(r'D:\tmp', 'img1') # 保存到路径，文件名为img1.png
bytes = page.screenshot(as_bytes=True) # 返回截图二进制文本 bytes = page.screenshot(as_bytes=True) # 返回截图二进制文本
``` ```
## set_window_size() ## 📍 `set_window_size()`
此方法用于设置浏览器窗口大小。 此方法用于设置浏览器窗口大小。
默认最大化，任一参数为 0 最小化。 默认最大化，任一参数为 0 最小化。
参数： **参数：**
- height：浏览器窗口高度 - `height`：浏览器窗口高度
- width：浏览器窗口宽度 - `width`：浏览器窗口宽度
返回：None **返回：**`None`
```python ```python
# 窗口最大化 # 窗口最大化
@ -571,19 +566,19 @@ page.set_window_size(0)
page.set_window_size(800, 600) page.set_window_size(800, 600)
``` ```
## process_alert() ## 📍 `process_alert()`
此方法 用于处理提示框。 此方法 用于处理提示框。
它能够设置等待时间，等待提示框出现才进行处理，若超时没等到提示框，返回`None`。 它能够设置等待时间，等待提示框出现才进行处理，若超时没等到提示框，返回`None`。
它可只获取提示框文本而不处理提示框。 它可只获取提示框文本而不处理提示框。
参数： **参数：**
- ok：`True`表示确认，`False`表示取消，其它值不会按按钮但依然返回文本值 - `ok`：`True`表示确认，`False`表示取消，其它值不会按按钮但依然返回文本值
- send：处理 prompt 提示框时可输入文本 - `send`：处理 prompt 提示框时可输入文本
- timeout：等待提示框出现的超时时间 - `timeout`：等待提示框出现的超时时间
返回：提示框内容文本，未等到提示框则返回`None` **返回：** 提示框内容文本，未等到提示框则返回`None`
```python ```python
# 确认提示框并获取提示框文本 # 确认提示框并获取提示框文本
@ -599,7 +594,7 @@ paeg.process_alert(True, 'some text')
txt = page.process_alert(None) txt = page.process_alert(None)
``` ```
## check_page() ## 📍 `check_page()`
此方法用于检查页面是否符合预期，它默认返回`None`，须由子类实现其功能。 此方法用于检查页面是否符合预期，它默认返回`None`，须由子类实现其功能。
用于 POM 模式时，可派生各种页面子类，从而实现检查页面的功能。 用于 POM 模式时，可派生各种页面子类，从而实现检查页面的功能。

2
docs/README.md
View File

@ -96,4 +96,4 @@ DrissionPage，即 driver 和 session 组合而成的 page。
如果本项目对您有所帮助，不妨请作者我喝杯咖啡 ：） 如果本项目对您有所帮助，不妨请作者我喝杯咖啡 ：）
![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/code.jpg) ![](imgs/code.jpg)

26
docs/Tips大集合.md
View File

@ -1,26 +0,0 @@
## 全局
- 切换模式时会自动复制`cookies`到目标模式，并在目标模式下重新访问当前网址，可在参数中禁止自动访问。
- 访问网址时如遇到异常，会自动重试 3 次，也可在对象属性或连接参数里设置重试次数和间隔时间。d 模式这个功能要重载了`check_page()`方法才有效。
- 获取到的文本会自动替换`&nbsp;`为空格。
- 可以在元素下直接使用`>`以 css selector 方式获取当前元素直接子元素。如`ele1.ele('css:>div')`。原生不支持这种写法。
- 用 xpath 获取元素的子元素时，可省略前面的`.`。如`ele1.ele('div')`和`ele1.ele('.//div'）`是一致的。
- 保存空的配置对象时，如没有指定路径，会保存到默认 ini 文件。
- `download()`方法会自动创建`goal_path`参数的文件夹，因此可直接传入不存在的文件夹路径。
- `set_cookies()`可以接收`RequestsCookieJar`、`list`、`tuple`、`str`、`dict`，只要格式对扔进去它会自动调整。其中`list`和`tuple`的内容可为`Cookie`、`dict`、`str`。
## s 模式
- 在创建`MixPage`对象时传入的`Session`配置是全局有效的，一般无须每次连接传入。
- ini 文件里设置了默认 s 模式的`headers`，一般情况可直接使用，也可手动设置。
- s 模式访问网页时会自动纠正编码，具体为先从`headers`获取，再从页面`meta`标签获取，都找不到就执行`r.apparent_encoding`。因此无须手动设置。
- 如果没有传入`referer`和`host`值，s 模式在连接时会自动根据当前域名自动填写`Host`和`Referer`属性。
## d 模式
- d 模式查找元素默认设置等待超时 10 秒，10 秒内找到立即返回元素，超时返回`None`。也可指定超时时间。
- `cilck()`方法用 selenium 点击失败时会用 js 方式重试，也可在参数里指定直接用 js 或不用 js 重试。
- `click()`方法可设置`timeout`参数，在时间内会不断重试点击目标，`click(by_js=False)`可用于等待覆盖在元素上的遮罩层消失。
- 可以用 xpath 直接获取元素属性或文本节点内容，如`ele1.ele('xpath://div/@class')`或`ele1.ele('xpath://div/text()[2]')`。原生不支持这种用法。
- 在`MixPage`对象设置`timeout`后，该页面下所有元素的查找都会遵循该设置，该值默认为 10。也可以每次查找元素时单独设置，单独设置不影响页面对象的`timeout`属性。
- 若设置了`local_port`或`debugger_address`，创建 driver 时程序会自动检测该端口，如为空，则自动在该端口启动一个浏览器进程并接入。程序完毕该浏览器不自动关闭，以便后续使用。

90
docs/WebPage使用方法/3.10动作链.md
View File

@ -99,30 +99,118 @@ ac.up(50) # 鼠标向上移动 50 像素
**返回：**`ActionChains`对象自己 **返回：**`ActionChains`对象自己
# ✔ 点击鼠标 # ✔ 鼠标按键
## 📍 `click()` ## 📍 `click()`
此方法用于单击鼠标左键，单击前可先移动到元素上。
**参数：**
- `on_ele`：`ChromiumElement`元素
**返回：**`ActionChains`对象自己
## 📍 `r_click()` ## 📍 `r_click()`
此方法用于单击鼠标右键，单击前可先移动到元素上。
**参数：**
- `on_ele`：`ChromiumElement`元素
**返回：**`ActionChains`对象自己
## 📍 `hold()` ## 📍 `hold()`
此方法用于按住鼠标左键不放，按住前可先移动到元素上。
**参数：**
- `on_ele`：`ChromiumElement`元素
**返回：**`ActionChains`对象自己
## 📍 `release()` ## 📍 `release()`
此方法用于释放鼠标左键，释放前可先移动到元素上。
**参数：**
- `on_ele`：`ChromiumElement`元素
**返回：**`ActionChains`对象自己
# ✔ 滚动滚轮 # ✔ 滚动滚轮
## 📍 `scroll()` ## 📍 `scroll()`
此方法用于滚动鼠标滚轮，滚动前可先移动到元素上。
**参数：**
- `delta_x`：滚轮变化值 x
- `delta_y`：滚轮变化值 y
- `on_ele`：`ChromiumElement`元素
**返回：**`ActionChains`对象自己
# ✔ 键盘按键 # ✔ 键盘按键
## 📍 `key_down()` ## 📍 `key_down()`
此方法用于按下键盘按键。
**参数：**
- `key`：按键键值，特殊字符见 Keys
**返回：**`ActionChains`对象自己
```python
from DrissionPage.keys import Keys
ac.key_down(Keys.CTRL) # 按下 ctrl 键
```
## 📍 `key_up()` ## 📍 `key_up()`
此方法用于提起键盘按键。
**参数：**
- `key`：按键键值，特殊字符见 Keys
**返回：**`ActionChains`对象自己
# ✔ 等待 # ✔ 等待
## 📍 `wait()` ## 📍 `wait()`
此方法用于在动作链中插入停顿。
**参数：**
- `second`：秒数
**返回：**`ActionChains`对象自己
```python
ac.wait(3) # 停顿 3 秒
```
# ✔ 链式操作 # ✔ 链式操作
以上操作皆能实现链式操作。且最后无需`perform()`。
```python
from DrissionPage import ChromiumPage, ActionChains
page = ChromiumPage()
ac = ActionCHains(page)
# 链式操作
ac.move_to('tag:h1').right(30).click().key_down('a').key_up('a')
```

168
docs/WebPage使用方法/3.3查找元素.md
View File

@ -105,13 +105,13 @@ d 模式下返回`ChromiumElement`对象，s 模式下返回`SessionElement`对
在元素下查找子元素时，还可以用 xpath 获取元素属性，直接返回属性文本。 在元素下查找子元素时，还可以用 xpath 获取元素属性，直接返回属性文本。
页面对象和元素对象的`ele()`方法参数名称稍有不同，但用法一样。 页面对象和元素对象的`ele()`方法参数名称稍有不同，但用法一样。
参数： **参数：**
- loc_or_str（元素对象）：元素的定位信息，可以是 loc 元组，或查询字符串 - `loc_or_str`（元素对象）：元素的定位信息，可以是 loc 元组，或查询字符串
- loc_or_ele（页面对象）：元素的定位信息，可以是元素对象，loc 元组，或查询字符串 - `loc_or_ele`（页面对象）：元素的定位信息，可以是元素对象，loc 元组，或查询字符串
- timeout：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 - `timeout`：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效
返回：s 模式下返回`SessionElement`，d 模式下返回`ChromiumElement`；或用 xpath 获取到的属性值 **返回：** s 模式下返回`SessionElement`，d 模式下返回`ChromiumElement`；或用 xpath 获取到的属性值
```python ```python
from DrissionPage import WebPage from DrissionPage import WebPage
@ -134,12 +134,12 @@ ele_class = ele1.ele('xpath://div/@class')
此方法与`ele()`相似，但返回的是匹配到的所有元素组成的列表，用 xpath 获取元素属性时，返回属性文本组成的列表。 此方法与`ele()`相似，但返回的是匹配到的所有元素组成的列表，用 xpath 获取元素属性时，返回属性文本组成的列表。
参数： **参数：**
- loc_or_str：元素的定位信息，可以是 loc 元组，或查询字符串 - `loc_or_str`：元素的定位信息，可以是 loc 元组，或查询字符串
- timeout：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 - `timeout`：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效
返回：s 模式下返回`SessionElement`组成的列表，d 模式下返回`ChromiumElement`组成的列表；或用 xpath 获取到的属性值组成的列表 **返回：** s 模式下返回`SessionElement`组成的列表，d 模式下返回`ChromiumElement`组成的列表；或用 xpath 获取到的属性值组成的列表
```python ```python
# 获取 ele 元素内的所有 p 元素 # 获取 ele 元素内的所有 p 元素
@ -167,12 +167,12 @@ s 模式下，所有元素本身就是静态元素，d 模式下，用`s_ele()`
s 模式下这个方法和`ele()`是一样的。 s 模式下这个方法和`ele()`是一样的。
参数： **参数：**
- loc_or_str（元素对象）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前元素的`SessionElemnet`版本 - `loc_or_str`（元素对象）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前元素的`SessionElemnet`版本
- loc_or_ele（页面对象）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前页面的 `SessionElemnet`版本 - `loc_or_ele`（页面对象）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前页面的 `SessionElemnet`版本
返回：`SessionElement`，或用 xpath 获取到的属性值 **返回：**`SessionElement`，或用 xpath 获取到的属性值
!>**注意：**<br>页面对象和元素对象的`s_ele()`方法不能搜索到在 frame 里的元素，页面对象的静态版本也不能搜索 frame 里的元素。要使用 frame 里元素的静态版本，可先获取该元素，再转换。而使用`ChromiumFrame`对象，则可以直接用`s_ele()`查找元素，这在后面章节再讲述。 !>**注意：**<br>页面对象和元素对象的`s_ele()`方法不能搜索到在 frame 里的元素，页面对象的静态版本也不能搜索 frame 里的元素。要使用 frame 里元素的静态版本，可先获取该元素，再转换。而使用`ChromiumFrame`对象，则可以直接用`s_ele()`查找元素，这在后面章节再讲述。
@ -205,11 +205,11 @@ ele4 = s_ele.ele('search text')
此方法与`s_ele()`相似，但返回的是匹配到的所有元素组成的列表，或属性值组成的列表。 此方法与`s_ele()`相似，但返回的是匹配到的所有元素组成的列表，或属性值组成的列表。
参数： **参数：**
- loc_or_str：元素的定位信息，可以是 loc 元组，或查询字符串（必填） - `loc_or_str`：元素的定位信息，可以是 loc 元组，或查询字符串（必填）
返回：`SessionElement`组成的列表，或用 xpath 获取到的属性值组成的列表 **返回：**`SessionElement`组成的列表，或用 xpath 获取到的属性值组成的列表
```python ```python
from DrissionPage import WebPage from DrissionPage import WebPage
@ -248,17 +248,17 @@ ele1.click()
**匹配模式** 指字符串是否完全匹配，有以下两种： **匹配模式** 指字符串是否完全匹配，有以下两种：
## 📍 精确匹配符`=` ## 📍 精确匹配符 `=`
表示精确匹配，匹配完全符合的文本或属性。 表示精确匹配，匹配完全符合的文本或属性。
## 📍 模糊匹配符`:` ## 📍 模糊匹配符 `:`
表示模糊匹配，匹配含有某个字符串的文本或属性。 表示模糊匹配，匹配含有某个字符串的文本或属性。
**关键字** 是出现在定位语句最左边，用于指明该语句以哪种方式去查找元素，有以下这些： **关键字** 是出现在定位语句最左边，用于指明该语句以哪种方式去查找元素，有以下这些：
## 📍 id 匹配符`#` ## 📍 id 匹配符 `#`
表示`id`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。 表示`id`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。
@ -270,7 +270,7 @@ ele1 = page.ele('#ele_id')
ele2 = ele1.ele('#:ele_id') ele2 = ele1.ele('#:ele_id')
``` ```
## 📍 class 匹配符`.` ## 📍 class 匹配符 `.`
表示`class`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。 表示`class`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。
@ -310,7 +310,7 @@ ele2 = ele1.ele('@email=abc@def.com')
ele2 = ele1.ele('css:div[abc\@def="v"]') ele2 = ele1.ele('css:div[abc\@def="v"]')
``` ```
## 📍 多属性匹配符`@@` ## 📍 多属性匹配符 `@@`
表示某个属性，多属性匹配时使用，个数不限。还能匹配要忽略的元素，匹配文本时也和`@`不一样。 表示某个属性，多属性匹配时使用，个数不限。还能匹配要忽略的元素，匹配文本时也和`@`不一样。
`@@`后跟 - 时，表示 not。如： `@@`后跟 - 时，表示 not。如：
@ -338,7 +338,7 @@ ele2 = ele1.ele('@@-class')
ele2 = ele1.ele('@@-name:ele_name') ele2 = ele1.ele('@@-name:ele_name')
``` ```
## 📍 文本匹配符`text` ## 📍 文本匹配符 `text`
要匹配的文本，查询字符串如开头没有任何关键字，也表示根据传入的文本作模糊查找。 要匹配的文本，查询字符串如开头没有任何关键字，也表示根据传入的文本作模糊查找。
如果元素内有多个直接的文本节点，精确查找时可匹配所有文本节点拼成的字符串，模糊查找时可匹配每个文本节点。 如果元素内有多个直接的文本节点，精确查找时可匹配所有文本节点拼成的字符串，模糊查找时可匹配每个文本节点。
@ -360,12 +360,9 @@ ele2 = ele1.ele('some text')
ele2 = page.ele('text:text:') ele2 = page.ele('text:text:')
``` ```
## 📍 文本匹配符`text()` ## 📍 文本匹配符 `text()`
作为查找属性时使用的文本关键字，必须与`@`或`@@`配合使用。 作为查找属性时使用的文本关键字，必须与`@`或`@@`配合使用。
与`@`配合和与`@@`配合使用时，`text()`的意义是有差别的。
`@text()`表示在元素的直接子文本节点中匹配，且多个节点不能合并匹配。 `@@text()`表示在元素内部所有文本中匹配，且会把元素内部所有文本拼成一个总字符串再进行匹配，因此可以模糊匹配元素里面任意文本。
```python ```python
# 查找文本为 some text 的元素 # 查找文本为 some text 的元素
@ -388,7 +385,11 @@ ele = page.ele('text:some text')
ele = page.ele('@@text():some text') ele = page.ele('@@text():some text')
``` ```
## 📍 类型匹配符`tag` 须要注意的是，`'text=xxxx'`与`'@text()=xxxx'`使用上是有细微差别的。
`text=`表示在元素的直接子文本节点中匹配，`@text()=`会忽略一些文本标签，在整个元素的内容里匹配。
## 📍 类型匹配符 `tag`
表示元素的标签，只在语句最前面且单独使用时生效，可与`@`或`@@`配合使用。`tag:`与`tag=`效果一致。 表示元素的标签，只在语句最前面且单独使用时生效，可与`@`或`@@`配合使用。`tag:`与`tag=`效果一致。
@ -412,10 +413,9 @@ ele2 = ele1.ele('tag:div@text():text')
ele2 = ele1.ele('tag:div@@text():text') ele2 = ele1.ele('tag:div@@text():text')
``` ```
?> **Tips:** <br> ?> **Tips:** <br>注意， `tag:div@text():text` 和 `tag:div@@text():text` 是有区别的，前者只在`div`的直接文本节点搜索，后者搜索`div`的整个内部。
注意， `tag:div@text():text` 和 `tag:div@@text():text` 是有区别的，前者只在`div`的直接文本节点搜索，后者搜索`div`的整个内部。
## 📍 css selector 匹配符`css` ## 📍 css selector 匹配符 `css`
表示用 css selector 方式查找元素。`css:`与`css=`效果一致。 表示用 css selector 方式查找元素。`css:`与`css=`效果一致。
@ -427,7 +427,7 @@ ele2 = ele1.ele('css:.div')
ele2 = ele1.ele('css:>div') ele2 = ele1.ele('css:>div')
``` ```
## 📍 xpath 匹配符`xpath` ## 📍 xpath 匹配符 `xpath`
表示用 xpath 方式查找元素。`xpath:`与`xpath=`效果一致。 表示用 xpath 方式查找元素。`xpath:`与`xpath=`效果一致。
该方法支持完整的 xpath 语法，能使用 xpath 直接获取元素属性，selenium 不支持这种用法。 该方法支持完整的 xpath 语法，能使用 xpath 直接获取元素属性，selenium 不支持这种用法。
@ -498,13 +498,13 @@ ele2 = ele1.ele('some text', timeout=1)
- `loc_or_ele`：要等待的元素，可以是元素或定位符 - `loc_or_ele`：要等待的元素，可以是元素或定位符
- `timeout`：等待超时时间，默认使用页面超时时间 - `timeout`：等待超时时间，默认使用页面超时时间
方法： **方法：**
| 方法 | 参数 | 功能 | | 方法 | 参数 | 功能 |
| --------- | --- | ------------ | | ----------- | --- | ------------ |
| display() | 无 | 等待元素从 DOM 显示 | | `display()` | 无 | 等待元素从 DOM 显示 |
| hidden() | 无 | 等待元素从 DOM 隐藏 | | `hidden()` | 无 | 等待元素从 DOM 隐藏 |
| delete() | 无 | 等待元素从 DOM 删除 | | `delete()` | 无 | 等待元素从 DOM 删除 |
**返回：** 这些方法返回布尔值，代表是否等待成功。 **返回：** 这些方法返回布尔值，代表是否等待成功。
@ -529,11 +529,11 @@ ele1.wait_ele(ele2).hidden()
`parent()`方法获取当前元素某一级父元素，可指定筛选条件或层数。 `parent()`方法获取当前元素某一级父元素，可指定筛选条件或层数。
参数： **参数：**
- level_or_loc：第几级父元素，或定位符 - `level_or_loc`：第几级父元素，或定位符
返回： **返回：** 某层父级元素
```python ```python
# 获取 ele1 的第二层父元素 # 获取 ele1 的第二层父元素
@ -547,13 +547,13 @@ ele2 = ele1.parent('#id1')
`next()`方法返回当前元素后面的某一个同级元素，可指定筛选条件和第几个。 `next()`方法返回当前元素后面的某一个同级元素，可指定筛选条件和第几个。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素后面某个兄弟元素或节点文本 **返回：** 本元素后面某个兄弟元素或节点文本
```python ```python
# 获取 ele1 后面第一个兄弟元素 # 获取 ele1 后面第一个兄弟元素
@ -573,12 +573,12 @@ txt = ele1.next('xpath:text()', 1)
`nexts()`方法返回当前元素后面全部符合条件的同级元素或节点组成的列表，可用查询语法筛选。 `nexts()`方法返回当前元素后面全部符合条件的同级元素或节点组成的列表，可用查询语法筛选。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面符合条件的兄弟元素或节点文本组成的列表 **返回：** 本元素前面符合条件的兄弟元素或节点文本组成的列表
```python ```python
# 获取 ele1 后面所有兄弟元素 # 获取 ele1 后面所有兄弟元素
@ -595,13 +595,13 @@ txts = ele1.nexts('xpath:text()')
`prev()`方法返回当前元素前面的某一个同级元素，可指定筛选条件和第几个。 `prev()`方法返回当前元素前面的某一个同级元素，可指定筛选条件和第几个。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面某个兄弟元素或节点文本 **返回：** 本元素前面某个兄弟元素或节点文本
```python ```python
# 获取 ele1 前面第一个兄弟元素 # 获取 ele1 前面第一个兄弟元素
@ -621,12 +621,12 @@ txt = ele1.prev(1, 'xpath:text()')
`prevs()`方法返回当前元素前面全部符合条件的同级元素或节点组成的列表，可用查询语法筛选。 `prevs()`方法返回当前元素前面全部符合条件的同级元素或节点组成的列表，可用查询语法筛选。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面符合条件的兄弟元素或节点文本组成的列表 **返回：** 本元素前面符合条件的兄弟元素或节点文本组成的列表
```python ```python
# 获取 ele1 前面所有兄弟元素 # 获取 ele1 前面所有兄弟元素
@ -640,13 +640,13 @@ divs = ele1.prevs('tag:div')
`after()`方法返回当前元素后面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 `after()`方法返回当前元素后面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素后面某个元素或节点 **返回：** 本元素后面某个元素或节点
```python ```python
# 获取 ele1 后面第 3 个元素 # 获取 ele1 后面第 3 个元素
@ -663,12 +663,12 @@ txt = ele1.after('xpath:text()', 1)
`afters()`方法返回当前元素后面符合条件的全部元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 `afters()`方法返回当前元素后面符合条件的全部元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素后面符合条件的元素或节点组成的列表 **返回：** 本元素后面符合条件的元素或节点组成的列表
```python ```python
# 获取 ele1 后所有元素 # 获取 ele1 后所有元素
@ -682,13 +682,13 @@ divs = ele1.afters('tag:div')
`before()`方法返回当前元素前面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 `before()`方法返回当前元素前面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- index：查询结果中的第几个 - `index`：查询结果中的第几个
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面某个元素或节点 **返回：** 本元素前面某个元素或节点
```python ```python
# 获取 ele1 前面第 3 个元素 # 获取 ele1 前面第 3 个元素
@ -705,12 +705,12 @@ txt = ele1.before('xpath:text()', 1)
`befores()`方法返回当前元素前面全部符合条件的元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 `befores()`方法返回当前元素前面全部符合条件的元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。
参数： **参数：**
- filter_loc：用于筛选元素的查询语法 - `filter_loc`：用于筛选元素的查询语法
- timeout：查找元素的超时时间 - `timeout`：查找元素的超时时间
返回：本元素前面符合条件的元素或节点组成的列表 **返回：** 本元素前面符合条件的元素或节点组成的列表
```python ```python
# 获取 ele1 前面所有元素 # 获取 ele1 前面所有元素
@ -814,14 +814,14 @@ ele2 = ele1('x://div[@class="ele_class"]')
简化写法对应列表 简化写法对应列表
| 原写法 | 简化写法 | | 原写法 | 简化写法 |
|:-----------:|:----:| |:-------------:|:------:|
| text | tx | | `text` | `tx` |
| text() | tx() | | `text()` | `tx()` |
| tag | t | | `tag` | `t` |
| xpath | x | | `xpath` | `x` |
| css | c | | `css` | `c` |
| shadow_root | sr | | `shadow_root` | `sr` |
# ✔️ Tips # ✔️ Tips

3
docs/_navbar.md
View File

@ -1,5 +1,2 @@
* [DataRecorder](https://gitee.com/g1879/DataRecorder) * [DataRecorder](https://gitee.com/g1879/DataRecorder)
* [ListPage](https://gitee.com/g1879/ListPage)
* [DownloadKit](https://gitee.com/g1879/DownloadKit)
* [FlowViewer](http://g1879.gitee.io/flowviewer) * [FlowViewer](http://g1879.gitee.io/flowviewer)
* [Demos](https://gitee.com/g1879/DrissionPage-demos)

47
docs/_sidebar.md
View File

@ -10,6 +10,7 @@
* [🌿 模式切换](入门指南\特性演示\模式切换.md) * [🌿 模式切换](入门指南\特性演示\模式切换.md)
* [🌿 获取并打印元素属性](入门指南\特性演示\获取并打印元素属性.md) * [🌿 获取并打印元素属性](入门指南\特性演示\获取并打印元素属性.md)
* [🌿 下载文件](入门指南\特性演示\下载文件.md) * [🌿 下载文件](入门指南\特性演示\下载文件.md)
* [💖 2.4 贴心设计](入门指南\贴心设计.md)
* [🛠 3 WebPage 使用方法](#) * [🛠 3 WebPage 使用方法](#)
@ -33,29 +34,35 @@
* [🔨 4.5 元素操作](MixPage使用方法\元素操作.md) * [🔨 4.5 元素操作](MixPage使用方法\元素操作.md)
* [🔨 4.6 获取网页信息](MixPage使用方法\获取网页信息.md) * [🔨 4.6 获取网页信息](MixPage使用方法\获取网页信息.md)
* [🔨 4.7 页面操作](MixPage使用方法\页面操作.md) * [🔨 4.7 页面操作](MixPage使用方法\页面操作.md)
* [🔨 4.8 启动配置](#) * [🔨 4.8 下载文件](MixPage使用方法\下载文件.md)
* [🔧 概述](MixPage使用方法\启动配置\概述.md) * [🔨 4.9 监听浏览器网络数据](MixPage使用方法\监听浏览器网络数据.md)
* [🔧 Chrome 启动配置](MixPage使用方法\启动配置\Chrome启动配置.md) * [🔨 4.10 cookies 的使用](MixPage使用方法\cookies的使用.md)
* [🔧 Session 启动配置](MixPage使用方法\启动配置\Session启动配置.md) * [🔨 4.11 Drission 对象](MixPage使用方法\Drission对象.md)
* [🔧 使用配置文件](MixPage使用方法\启动配置\使用配置文件.md) * [🔨 4.12 对接 selenium 及 requests 代码](MixPage使用方法\对接selenium及requests代码.md)
* [🔨 4.9 下载文件](MixPage使用方法\下载文件.md) * [🔨 4.13 使用其它系统或浏览器](MixPage使用方法\使用其它系统或浏览器.md)
* [🔨 4.10 监听浏览器网络数据](MixPage使用方法\监听浏览器网络数据.md) * [🔨 4.14 DriverPage 和 SessionPage](MixPage使用方法\DriverPage和SessionPage.md)
* [🔨 4.11 cookies 的使用](MixPage使用方法\cookies的使用.md) * [🔨 4.15 打包程序](MixPage使用方法\打包程序.md)
* [🔨 4.12 Drission 对象](MixPage使用方法\Drission对象.md)
* [🔨 4.13 对接 selenium 及 requests 代码](MixPage使用方法\对接selenium及requests代码.md)
* [🔨 4.14 使用其它系统或浏览器](MixPage使用方法\使用其它系统或浏览器.md)
* [🔨 4.15 DriverPage 和 SessionPage](MixPage使用方法\DriverPage和SessionPage.md)
* [🔨 4.16 打包程序](MixPage使用方法\打包程序.md)
* [💖 5 实用示例](#) * [🛠 5 启动配置](#)
* [🧡 自动登录码云](实用示例\自动登录码云.md) * [🔨 5.1 概述](启动配置\概述.md)
* [🧡 获取各国疫情排名](实用示例\获取各国疫情排名.md) * [🔨 5.2 浏览器启动配置](启动配置\浏览器启动配置.md)
* [🧡 下载星巴克产品图片](实用示例\下载星巴克产品图片.md) * [🔨 5.3 Session 启动配置](启动配置\Session启动配置.md)
* [🧡 同时操作多个浏览器](实用示例\同时操作多个浏览器.md) * [🔨 5.4 使用配置文件](启动配置\使用配置文件.md)
* [⚡️ 6 Tips大集合](Tips大集合.md) * [🧰 6 进阶使用](#)
* [🎯️ 7 版本历史](版本历史.md) * [⚙️ 6.1 打包程序](进阶使用\打包程序.md)
* [⚙️ 6.2 监听浏览器网络](进阶使用\监听浏览器网络.md)
* [⚙️ 6.3 下载文件](进阶使用\下载文件.md)
* [⚡️ 7 实用示例](#)
* [🌠 自动登录码云](实用示例\自动登录码云.md)
* [🌠 获取各国疫情排名](实用示例\获取各国疫情排名.md)
* [🌠 下载星巴克产品图片](实用示例\下载星巴克产品图片.md)
* [🌠 同时操作多个浏览器](实用示例\同时操作多个浏览器.md)
* [🔖 9 版本历史](版本历史.md)
* [💐 鸣谢](鸣谢.md) * [💐 鸣谢](鸣谢.md)

BIN
docs/imgs/code.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 176 KiB

BIN
docs/imgs/mixpage.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 80 KiB

BIN
docs/imgs/webpage.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 62 KiB

8
docs/入门指南/基本概念.md
View File

@ -176,15 +176,17 @@ page = MixPage()
## 📍 `WebPage`结构图 ## 📍 `WebPage`结构图
待更新。 `WebPage`继承自`ChromiumPage`和`SessionPage`，前者负责控制浏览器，后者负责数据包收发。
![](../imgs/webpage.jpg)
## 📍 `MixPage`结构图 ## 📍 `MixPage`结构图
如图所示，`Drission`对象负责链接的创建、共享登录状态等工作，类似 selenium 中 driver 的概念。 `Drission`对象负责链接的创建、共享登录状态等工作，类似 selenium 中 driver 的概念。
`MixPage`对象负责对获取到的页面进行解析、操作。 `MixPage`对象负责对获取到的页面进行解析、操作。
`DriverElement`和`SessionElement`则是从页面对象中获取到的元素对象。负责对元素进行解析和操作。 `DriverElement`和`SessionElement`则是从页面对象中获取到的元素对象。负责对元素进行解析和操作。
![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/20201118170751.jpg) ![](../imgs/mixpage.jpg)
# ✔️ 配置管理 # ✔️ 配置管理

99
docs/入门指南/贴心设计.md Normal file
View File

@ -0,0 +1,99 @@
这里介绍一些本库内置了人性化设计。
# ✔️ 无处不在的等待
网络环境不稳定，很多时候程序须要稍微等待一下才能继续运行。等待太少，会导致程序出错，等待太多，又会浪费时间。为了解决这些问题，本库在大量须要等待的部分内置了超时功能，并且可以随时灵活设置，大幅降低程序复杂性。
- 查找元素内置等待。可以为每次查找元素单独设定等待时间。有些页面会不定期出现提示信息，如果一律等待会太浪费时间，可以独立设置一个很短的超时时间，避免浪费。
- 等待下拉列表选项。很多下拉列表使用 js 加载，本库选择下拉列表时，会自动等待列表项出现。
- 等待弹窗。有时预期的 alert 未必立刻出现，本库处理 弹窗消息时也可以设置等待。
- 等待元素状态改变。使用`wait_ele()`方法可等待元素出现、消失、删除等状态。
- 点击功能也内置等待，如遇元素被遮挡可不断重试点击。
- 设置页面加载时限及加载策略。有时不需要完整加载页面资源，可根据实际须要设置加载策略。
# ✔️ 自动重试连接
在访问网站时，由于网络不稳定可能导致连接异常。本库设置了连接自动重试功能，当网页连接异常，会默认重试 3 次。当然也可以手动设置次数和间隔。
```python
page.get('xxxxxx', retry=5, interval=3) # 出错是重试 5 次，每次间隔 3 秒
```
# ✔️ 极简的定位语法
本库制定了一套简洁高效的查找元素语法，支持链式操作，支持相对定位。与 selenium 繁琐的语法相比简直不要太方便。
而且每次查找内置等待，可以独立设置每次查找超时时间。
同是设置了超时等待的查找，对比一下：
```python
# 使用 selenium：
element = WebDriverWait(driver, 10).until(ec.presence_of_element_located((By.XPATH, '//*[contains(text(), "some text")]')))
# 使用 DrissionPage：
element = page('some text', timeout=10)
```
# ✔️ 无需切入切出，逻辑清晰
使用过 selenium 的人都知道，selenium 同一时间只能操作一个标签页或`<iframe>`元素，要操作其它标签页，或`<iframe>`元素，须要用`switch_to()`方法切换，操作后还要切换回来。如果是多级`<iframe>`，还要逐级切入，相当麻烦。
DrissionPage 则无需这些麻烦的操作，它把每个标签页和`<iframe>`都看作独立的对象，可以同时并发操作，而且可以直接跨多层`<iframe>`获取里面的元素，然后直接处理，非常方便。
对比一下，获取 2 层`<iframe>`内一个 id 为`'div1'`的元素：
```python
# 使用 selenium
driver.switch_to.frame(0)
driver.switch_to.frame(0)
ele = driver.find_element(By.ID, 'div1')
driver.switch_to.default_content()
# 使用 DrissionPage
ele = page('#div1')
```
多标签页同时操作，selenium 无此功能：
```python
tab1 = page.get_tab(page.tabs[0])
tab2 = page.get_tab(page.tabs[1])
tab1.get('https://www.baidu.com')
tab2.get('https://www.163.com')
```
# ✔️ 高度集成的便利功能
很多操作方法集成了常用功能，如`chick()`中内置`by_js`参数，可以直接改用 js 方式点击，而无需写独立的 js 语句。
# ✔️ 强大的下载功能
DrissionPage 内置一个下载工具，可实现大文件分块多线程下载文件。并且可以直接读取缓存数据保存图片，而无需控制页面作另存操作。
```python
img = page('tag:img')
img.save('img.png') # 直接保存图片到文件夹
```
# ✔️ 更多便捷的功能
- 可对整个网页截图，包括视口外的部分
- 每次运行程序可以反复使用已经打开的浏览器，无需每次从头运行
- s 模式访问网页时会自动纠正编码，无须手动设置
- s 模式在连接时会自动根据当前域名自动填写`Host`和`Referer`属性
- 下载工具支持多种方式处理文件名冲突、自动创建目标路径、断链重试等
- `MixPage`可自动下载合适版本的 chromedriver，免去麻烦的配置
- 支持直接获取`after`和`before`伪元素的内容

95
docs/MixPage使用方法/启动配置/Session启动配置.md → docs/启动配置/Session启动配置.md
View File

@ -3,40 +3,40 @@
!> **注意：** <br>`SessionOptions`仅用于管理启动配置，程序启动后再修改无效。 !> **注意：** <br>`SessionOptions`仅用于管理启动配置，程序启动后再修改无效。
# `SessionOptions`类 # ✔️ `SessionOptions`类
`SessionOptions`对象创建时默认读取默认 ini 文件配置信息，也可手动设置所需信息。 `SessionOptions`对象创建时默认读取默认 ini 文件配置信息，也可手动设置所需信息。
该类的方法支持链式操作。 该类的方法支持链式操作。
初始化参数： **初始化参数：**
- read_file：是否从默认 ini 文件中读取配置信息 - `read_file`：是否从默认 ini 文件中读取配置信息
- ini_path：ini 文件路径，为`None`则读取默认 ini 文件 - `ini_path`：ini 文件路径，为`None`则读取默认 ini 文件
## headers ## 📍 `headers`
该属性返回`headers`设置信息，可传入字典赋值。 该属性返回`headers`设置信息，可传入字典赋值。
## set_headers() ## 📍 `set_headers()`
该方法与`headers`参数赋值功能一致。 该方法与`headers`参数赋值功能一致。
参数： **参数：**
- headers：`headers`字典 - `headers`：`headers`字典
返回：当前对象 **返回：** 当前对象
## set_a_header() ## 📍 `set_a_header()`
该方法用于设置`headers`中的一个项。 该方法用于设置`headers`中的一个项。
参数： **参数：**
- attr：设置项名称 - `attr`：设置项名称
- value：设置值 - `value`：设置值
返回：当前对象 **返回：** 当前对象
```python ```python
so = SessionOptions() so = SessionOptions()
@ -52,103 +52,102 @@ print(so.headers)
{'accept': 'text/html', 'accept-charset': 'GB2312'} {'accept': 'text/html', 'accept-charset': 'GB2312'}
``` ```
## remove_a_header() ## 📍 `remove_a_header()`
此方法用于从`headers`中移除一个设置项。 此方法用于从`headers`中移除一个设置项。
参数： **参数：**
- attr：要删除的设置名称 - `attr`：要删除的设置名称
返回：当前对象 **返回：** 当前对象
## cookies ## 📍 `cookies`
此属性返回`cookies`设置信息，可赋值。 此属性返回`cookies`设置信息，可赋值。
可接收`dict`、`list`、`tuple`、`str`、`RequestsCookieJar`等格式的信息。 可接收`dict`、`list`、`tuple`、`str`、`RequestsCookieJar`等格式的信息。
## proxies ## 📍 `proxies`
此属性返回代理信息，可赋值。可传入字典类型。 此属性返回代理信息，可赋值。可传入字典类型。
格式：{'http': 'http://xx.xx.xx.xx:xxxx', 'https': 'http://xx.xx.xx.xx:xxxx'} **格式：**{'http': 'http://xx.xx.xx.xx:xxxx', 'https': 'http://xx.xx.xx.xx:xxxx'}
## set_proxies() ## 📍 `set_proxies()`
此方法与`proxies`属性赋值功能一致。 此方法与`proxies`属性赋值功能一致。
参数： **参数：**
- `dict`格式的代理参数 - `proxies`：`dict`格式的代理参数
返回：当前对象 **返回：** 当前对象
## auth ## 📍 `auth`
此属性用于返回和设置`auth`参数，接收`tuple`类型参数。 此属性用于返回和设置`auth`参数，接收`tuple`类型参数。
## hooks ## 📍 `hooks`
此属性用于返回和设置`hooks`参数，接收`dict`类型参数。 此属性用于返回和设置`hooks`参数，接收`dict`类型参数。
## params ## 📍 `params`
此属性用于返回和设置`params`参数，接收`dict`类型参数。 此属性用于返回和设置`params`参数，接收`dict`类型参数。
## verify ## 📍 `verify`
此属性用于返回和设置`verify`参数，接收`bool`类型参数。 此属性用于返回和设置`verify`参数，接收`bool`类型参数。
## cert ## 📍 `cert`
此属性用于返回和设置`cert`参数，接收`str`或`tuple`类型参数。 此属性用于返回和设置`cert`参数，接收`str`或`tuple`类型参数。
## adapters ## 📍 `adapters`
此属性用于返回和设置`adapters`参数。 此属性用于返回和设置`adapters`参数。
## stream ## 📍 `stream`
此属性用于返回和设置`stream`参数，接收`bool`类型参数。 此属性用于返回和设置`stream`参数，接收`bool`类型参数。
## trust_env ## 📍 `trust_env`
此属性用于返回和设置`trust_env`参数，接收`bool`类型参数。 此属性用于返回和设置`trust_env`参数，接收`bool`类型参数。
## max_redirects ## 📍 `max_redirects`
此属性用于返回和设置`max_redirects`参数，接收`int`类型参数。 此属性用于返回和设置`max_redirects`参数，接收`int`类型参数。
## save() ## 📍 `save()`
此方法用于保存当前配置对象的信息到配置文件。 此方法用于保存当前配置对象的信息到配置文件。
参数： **参数：**
- path：配置文件的路径，默认保存到当前读取的配置文件，传入`'default'`保存到默认 ini 文件 - `path`：配置文件的路径，默认保存到当前读取的配置文件，传入`'default'`保存到默认 ini 文件
返回：配置文件绝对路径 **返回：** 配置文件绝对路径
## save_to_default() ## 📍 `save_to_default()`
此方法用于保存当前配置对象的信息到默认 ini 文件。 此方法用于保存当前配置对象的信息到默认 ini 文件。
参数：无 **参数：** 无
返回：配置文件绝对路径 **返回：** 配置文件绝对路径
## as_dict() ## 📍 `as_dict()`
该方法以`dict`方式返回所有配置信息。 该方法以`dict`方式返回所有配置信息。
参数：无 **参数：** 无
返回：配置信息 **返回：** 配置信息
# 简单示例 # ✔️ 简单示例
```python ```python
from DrissionPage.config import SessionOptions from DrissionPage import WebPage, SessionOptions
from DrissionPage import MixPage
# 创建配置对象（默认从 ini 文件中读取配置） # 创建配置对象（默认从 ini 文件中读取配置）
so = SessionOptions() so = SessionOptions()
@ -158,5 +157,5 @@ so.cookies = ['key1=val1; domain=xxxx', 'key2=val2; domain=xxxx']
so.set_a_header('Connection', 'keep-alive') so.set_a_header('Connection', 'keep-alive')
# 以该配置创建页面对象 # 以该配置创建页面对象
page = MixPage(mode='s', session_options=so) page = WenPage(mode='s', session_or_options=so)
``` ```

270
docs/启动配置/使用配置文件.md Normal file
View File

@ -0,0 +1,270 @@
本库使用 ini 文件记录浏览器或`Session`对象的启动配置。便于配置复用，免于在代码中加入繁琐的配置信息。
默认情况下，页面对象启动时自动加载文件中的配置信息。
也可以在默认配置基础上用简单的方法再次修改，再保存到 ini 文件。
也可以保存多个 ini 文件，按不同项目须要调用。
!> **注意：** <br>ini 文件仅用于管理启动配置，浏览器或`Session`创建后再修改 ini 文件内容是没有效果的。 <br>如果是接管已打开的浏览器，这些设置也没有用。 <br>每次升级本库，ini 文件都会被重置，可另存到其它路径以免重置。
# ✔️ ini 文件内容
ini 文件默认拥有三部分配置：`paths`、`chrome_options`、`session_options`，初始内容如下。
```
[paths]
; chromedriver.exe路径
chromedriver_path =
; 临时文件夹路径，暂时没有实际作用
tmp_path =
[chrome_options]
; 浏览器默认地址和端口，程序会启动或接管这个端口的浏览器进程
debugger_address = 127.0.0.1:9222
; 浏览器可执行文件路径
binary_location =
; 配置信息
arguments = [
; 屏蔽欢迎页面
            '--no-first-run',
; 不使用沙盒
'--no-sandbox',
; 谷歌文档提到需要加上这个属性来规避bug
'--disable-gpu',
; 忽略警告
'ignore-certificate-errors',
; 不显示信息栏
'--disable-infobars',
            ; 允许弹窗
            '--disable-popup-blocking'
]
; 插件
extensions = []
; 实验性配置
experimental_options = {
'prefs': {
; 下载不弹出窗口
'profile.default_content_settings.popups': 0,
; 无弹窗
'profile.default_content_setting_values': {'notifications': 2},
; 禁用PDF插件
'plugins.plugins_list': [{"enabled": False, "name": "Chrome PDF Viewer"}]
},
; 设置为开发者模式
'excludeSwitches': ["enable-automation"],
'useAutomationExtension': False
}
; 超时设置
timeouts = {'implicit': 10.0, 'pageLoad': 30.0, 'script': 30.0}
; 页面加载策略
page_load_strategy = normal
[session_options]
headers = {
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/603.3.8 (KHTML, like Gecko) Version/10.1.2 Safari/603.3.8",
"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
"Connection": "keep-alive",
"Accept-Charset": "utf-8;q=0.7,*;q=0.7"
}
```
# ✔️ 文件位置
默认配置文件存放在库文件夹下，文件名为 configs.ini。
用户可另存其它配置文件，或从另存的文件读取配置，但默认文件的位置和名称不会改变。
# ✔️ 使用默认配置文件启动
## 📍 使用页面对象自动加载
这是默认启动方式。
```python
from DrissionPage import WebPage
page = WebPage()
```
## 📍 使用配置对象加载
这种方式一般用于加载配置后须要进一步修改。
```python
from DrissionPage import DriverOptions, SessionOptions, WebPage
do = DriverOptions(ini_path='D:\\setting.ini')
so = SessionOptions(ini_path='D:\\setting.ini')
page = WebPage(driver_or_options=do, session_or_option=so)
```
## 📍 使用 Drission 对象加载
这种方式一般用于加载非默认配置文件，或须在多个页面对象间传递`Drission`对象的情况。
这是`MixPage`独有的加载方式。
```python
from DrissionPage import MixPage, Drission
ds = Drission(ini_path=r'D:\config1.ini')
page = MixPage(drission=ds)
```
# ✔️ 保存/另存 ini 文件
```python
from DrissionPage import DriverOptions
do = DriverOptions()
# 设置不加载图片
do.set_no_imgs()
# 保存到默认 ini 文件
do.save()
# 保存到其它位置的配置文件
do.save(r'D:\config1.ini')
```
# ✔️ easy_set 方法
Chrome 浏览器的配置繁琐且难以记忆，本库提供一些常用功能的快速设置方法，调用即可修改 ini 文件中该部分内容。
!> **注意：** <br>easy_set 方法仅用于设置 ini 文件，浏览器或 Session 创建后再调用没有效果的。 <br>如果是接管已打开的浏览器，这些设置也没有用。<br>这些方法只是便于修改 ini 文件，不要写在正式代码中。
## 📍 简单示例
```python
# 导入
from DrissionPage.easy_set import set_headless
# 设置无头模式
set_headless(True)
```
## 📍 `show_settings()`
该方法用于打印 ini 文件内容。
**参数：**
- `ini_path`：ini 文件路径，默认读取默认 ini 文件
**返回：**`None`
## 📍 `set_paths()`
该方法用于设置浏览器用到的几种路径信息，设置后可检查 driver 是否和浏览器匹配。
**参数：**
- `driver_path`：chromedriver.exe 路径
- `chrome_path`：chrome.exe 路径
- `local_port`：本地端口号
- `debugger_address`：调试浏览器地址，会覆盖 local_port 设置，例：127.0.0.1:9222
- `download_path`：下载文件路径
- `tmp_path`：临时文件夹路径，暂时没有作用
- `user_data_path`：用户数据路径
- `cache_path`：缓存路径
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
- `check_version`：是否检查 chromedriver 和 Chrome 是否匹配
**返回：**`None`
## 📍 `set_headless()`
该方法用于设置是否已无头模式启动浏览器。
**参数：**
- `on_off`：`bool`类型，表示开或关
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
**返回：**`None`
## 📍 `set_no_imgs()`
该方法用于设置是否禁止加载图片。
**参数：**
- `on_off`：`bool`类型，表示开或关
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
**返回：**`None`
## 📍 `set_mute()`
该方法用于设置是否静音。
**参数：**
- `on_off`：`bool`类型，表示开或关
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
**返回：**`None`
## 📍 `set_proxy()`
该方法用于设置代理。
**参数：**
- `proxy`: 代理网址和端口，如 127.0.0.1:1080
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
**返回：**`None`
## 📍 `set_user_agent()`
该方法用于设置 user agent。
**参数：**
- `user_agent`：user agent 文本
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
**返回：**`None`
## 📍 `set_argument()`
该方法用于设置浏览器配置 argument 属性。
**参数：**
- `arg`：属性名
- `value`：属性值，有值的属性传入值。没有的传入`bool`表示开或关
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
**返回：**`None`
## 📍 `check_driver_version()`
该方法用于检查传入的 chrome 和 chromedriver 是否匹配。
**参数：**
- `driver_path`：chromedriver.exe 路径
- `chrome_path`：chrome.exe 路径
**返回：**`bool`类型，表示是否匹配
## 📍 `get_match_drive()`
该方法用于自动识别 chrome 版本并下载匹配的 driver。
**参数：**
- `ini_path`：要读取和修改的 ini 文件路径
- `save_path`：chromedriver 保存路径
- `chrome_path`：指定 chrome.exe 位置，不指定会自动依次在 ini 文件、注册表、系统路径中查找
- `show_msg`：是否打印信息
- `check_version`：是否检查版本匹配
**返回：** 成功返回 driver 路径，失败返回`None`

4
docs/MixPage使用方法/启动配置/概述.md → docs/启动配置/概述.md
View File

@ -2,6 +2,6 @@
因此，本库提供了一些方法简化其使用。 因此，本库提供了一些方法简化其使用。
- 使用 ini 文件记录常用配置，使配置便于复用，无须在代码中编写繁琐的配置。 - 使用 ini 文件记录常用配置，使配置便于复用，无须在代码中编写繁琐的配置。
- 使用`DriverOptions`对象管理浏览器配置，它继承自 selenium 原生的`Options`对象，加入更多便捷的功能。 - 使用`DriverOptions`对象管理浏览器配置。
- 增加专门用于管理连接配置的`SessionOptions`。 - 使用`SessionOptions`对象管理`Session`对象配置。
- 提供 easy_set 方法，专门用于对 ini 文件中常用配置进行管理，简化配置操作。 - 提供 easy_set 方法，专门用于对 ini 文件中常用配置进行管理，简化配置操作。

179
docs/启动配置/浏览器启动配置.md Normal file
View File

@ -0,0 +1,179 @@
为使浏览器设置更便利，本库使用`DriverOptions`类，专门用于管理浏览器的启动配置。
!> **注意：** <br>1、`DriverOptions`仅用于管理启动配置，浏览器启动后再修改无效。 <br>2、若接管已打开的浏览器，则所有启动配置均无效。
# ✔️ `DriverOptions`类
`DriverOptions`类继承自 selenium 的`Options` 类，保留了原来所有功能，原生功能不在这里叙述，只介绍增加的功能。
对象创建时，可从配置文件中读取配置来进行初始化，不从文件读取则创建一个空配置对象。
该类绝大部分方法都支持链式操作。
**初始化参数：**
- `read_file`：是否从默认 ini 文件中读取配置信息
- `ini_path`：ini 文件路径，为`None`则读取默认 ini 文件
## 📍 `driver_path`
此属性返回 chromedriver 文件路径。`MixPage`使用，`WebPage`不需要。
## 📍 `chrome_path`
此属性返回 Chrome 浏览器启动文件路径，为空时程序会根据注册表或系统路径查找。
## 📍 `set_paths()`
该方法用于设置浏览器用到的几种路径信息。
**参数：**
- `driver_path`：chromedriver.exe 路径
- `chrome_path`：chrome.exe 路径
- `local_port`：本地端口号
- `debugger_address`：调试浏览器地址，会覆盖`local_port`设置，例：127.0.0.1:9222
- `download_path`：下载文件路径
- `user_data_path`：用户数据路径
- `cache_path`：缓存路径
**返回：**`None`
## 📍 `save()`
此方法用于保存当前配置对象的信息到配置文件。
**参数：**
- `path`：配置文件的路径，默认保存到当前读取的配置文件，传入`'default'`保存到默认 ini 文件
**返回：**配置文件绝对路径
## 📍 `save_to_default()`
此方法用于保存当前配置对象的信息到默认 ini 文件。
**参数：** 无
**返回：** 配置文件绝对路径
## 📍 `remove_argument()`
此方法用于移除一个`argument`项。
**参数：**
- `value`：设置项名称，带有值的设置项传入设置名称即可
**返回：** 当前对象
## 📍 `remove_experimental_option()`
此方法用于移除一个实验设置，传入 key 值删除。
**参数：**
- `key`：实验设置的名称
**返回：** 当前对象
## 📍 `remove_all_extensions()`
此方法用于移除所有插件。
**参数：** 无
**返回：** 当前对象
## 📍 `set_argument()`
此方法用于设置浏览器配置的`argument`属性。
**参数：**
- `arg`：属性名
- `value`：属性值，有值的属性传入值，没有的传入`bool`类型表示开关
**返回：** 当前对象
## 📍 `set_timeouts()`
此方法用于设置三种超时时间。
**参数：**
- `implicit`：查找元素超时时间
- `pageLoad`：页面加载超时时间
- `script`：脚本运行超时时间
**返回：** 当前对象
## 📍 `set_headless()`
该方法用于设置是否已无头模式启动浏览器。
**参数：**
- `on_off`：`bool`类型，表示开或关
**返回：**`None`
## 📍 `set_no_imgs()`
该方法用于设置是否禁止加载图片。
**参数：**
- `on_off`：`bool`类型，表示开或关
**返回：**`None`
## 📍 `set_mute()`
该方法用于设置是否静音。
**参数：**
- `on_off`：`bool`类型，表示开或关
**返回：**`None`
## 📍 `set_proxy()`
该方法用于设置代理。
**参数：**
- `proxy`：代理网址和端口，如 127.0.0.1:1080
**返回：**`None`
## 📍 `set_user_agent()`
该方法用于设置 user agent。
**参数：**
- `user_agent`：user agent 文本
**返回：**`None`
## 📍 `as_dict()`
该方法以`dict`方式返回所有配置信息。
**参数：** 无
**返回：** 配置信息
# ✔️ 简单示例
```python
from DrissionPage import WebPage, DriverOptions
# 创建配置对象（默认从 ini 文件中读取配置）
do = DriverOptions()
# 设置不加载图片、静音
do.set_no_imgs(True).set_mute(True)
# 以该配置创建页面对象
page = WebPage(driver_or_options=do)
```

2
docs/版本历史.md
View File

@ -1,4 +1,4 @@
# v3.0.27 # v3.0.28
- 各种大小、位置信息从`dict`改为用`tuple`返回 - 各种大小、位置信息从`dict`改为用`tuple`返回

102
docs/MixPage使用方法/下载文件.md → docs/进阶使用/下载文件.md
View File

@ -1,10 +1,10 @@
selenium 缺乏对浏览器下载文件的有效管理，难以进行检测下载状态、重命名、失败管理。 浏览器缺乏对下载文件的有效管理，难以进行检测下载状态、重命名、失败管理。
使用 requests 下载文件能较好实现以上功能，但代码较为繁琐。 使用 requests 下载文件能较好实现以上功能，但代码较为繁琐。
因此 DrissionPage 提供了高效可靠的下载工具，整合了两者优点，可从 selenium 获取登录信息，用 requests 进行下载。弥补了 selenium 的不足，使下载简洁高效。 因此 DrissionPage 提供了高效可靠的下载工具，整合了两者优点，可从浏览器获取登录信息，用 requests 进行下载。弥补了浏览器对下载支持的不足，使下载简洁高效。
?> 为了增强灵活性，该工具现在独立打包成一个库，叫 DownloadKit，详细用法见：[DownloadKit](https://gitee.com/g1879/DownloadKit) ?> 为了增强灵活性，该工具现在独立打包成一个库，叫 DownloadKit，详细用法见：[DownloadKit](https://gitee.com/g1879/DownloadKit)
# 功能 # ✔️ 功能
- 支持多线程同时下载多个文件 - 支持多线程同时下载多个文件
- 大文件自动分块使用多线程下载 - 大文件自动分块使用多线程下载
@ -19,27 +19,27 @@ selenium 缺乏对浏览器下载文件的有效管理，难以进行检测下
- 支持自定义连接参数 - 支持自定义连接参数
- 任务失败自动重试 - 任务失败自动重试
# 单线程下载方式 # ✔️ 单线程下载方式
`MixPage`对象的`download`属性是一个`DownloadKit`对象，为尽量与旧版兼容，该属性可直接调用。如`page.download(url, save_path)` 页面对象的`download`属性是一个`DownloadKit`对象，为尽量与旧版兼容，该属性可直接调用。如`page.download(url, save_path)`
?> 使用这个方式时效果与旧版一致，下载一个文件时会阻塞程序，因此更加建议用后文讲述的多线程方法。 ?> 使用这个方式时效果与旧版一致，下载一个文件时会阻塞程序，因此更加建议用后文讲述的多线程方法。
参数： **参数：**
- file_ur：文件 url - `file_ur`：文件 url
- goal_path：存放路径，填写到文件夹，不填写文件名 - `goal_path`：存放路径，填写到文件夹，不填写文件名
- rename：重命名文件，可不写扩展名，不输入则用网络文件原名 - `rename`：重命名文件，可不写扩展名，不输入则用网络文件原名
- file_exists：若存在同名文件，可选择`'rename'`,`'overwrite'`,`'skip'`方式处理，若选择重命名，会在文件名后面添加序号 - `file_exists`：若存在同名文件，可选择`'rename'`,`'overwrite'`,`'skip'`方式处理，若选择重命名，会在文件名后面添加序号
- post_data：post 方式的数据，这个参数不为`None`时自动转成 post 方式 - `post_data`：post 方式的数据，这个参数不为`None`时自动转成 post 方式
- show_msg：是否显示下载信息和进度 - `show_msg`：是否显示下载信息和进度
- **kwargs：连接参数，与 requests 的一致 - `**kwargs`：连接参数，与 requests 的一致
返回：下载是否成功和状态信息的元组。 **返回：** 下载是否成功和状态信息的元组。
```python ```python
from DrissionPage import MixPage from DrissionPage import WebPage
page = MixPage() page = WebPage()
# 文件 url # 文件 url
url = 'https://www.baidu.com/img/flexible/logo/pc/result.png' url = 'https://www.baidu.com/img/flexible/logo/pc/result.png'
# 存放路径 # 存放路径
@ -62,31 +62,31 @@ url：https://www.baidu.com/img/flexible/logo/pc/result.png
(True, 'C:\\download\\img.png') (True, 'C:\\download\\img.png')
``` ```
# 多线程并发下载方式 # ✔️ 多线程并发下载方式
你可以往`DownloadKit`对象添加个数不限的下载任务，它会自动调配线程去完成这些任务。 你可以往`DownloadKit`对象添加个数不限的下载任务，它会自动调配线程去完成这些任务。
默认为 10 个线程。 默认为 10 个线程。
## 添加任务 ## 📍 添加任务
使用`add()`方法添加任务 使用`add()`方法添加任务
参数： **参数：**
- file_ur：文件 url - `file_ur`：文件 url
- goal_path：存放路径，填写到文件夹，不填写文件名 - `goal_path`：存放路径，填写到文件夹，不填写文件名
- session：可指定使用的`Session`对象，默认使用`MixPage`内置的`Session`对象 - `session`：可指定使用的`Session`对象，默认使用`MixPage`内置的`Session`对象
- rename：重命名文件，可不写扩展名，不输入则用网络文件原名 - `rename`：重命名文件，可不写扩展名，不输入则用网络文件原名
- file_exists：若存在同名文件，可选择`'rename'`,`'overwrite'`,`'skip'`方式处理，若选择重命名，会在文件名后面添加序号 - `file_exists`：若存在同名文件，可选择`'rename'`,`'overwrite'`,`'skip'`方式处理，若选择重命名，会在文件名后面添加序号
- post_data：post 方式的数据，这个参数不为`None`时自动转成 post 方式 - `post_data`：post 方式的数据，这个参数不为`None`时自动转成 post 方式
- **kwargs：连接参数，与 requests 的一致 - `**kwargs`：连接参数，与 requests 的一致
返回：任务对象，可通过任务对象查看任务状态和结果 **返回：** 任务对象，可通过任务对象查看任务状态和结果
```python ```python
from DrissionPage import MixPage from DrissionPage import WebPage
page = MixPage('s') page = WebPage('s')
# 文件 url # 文件 url
url = 'https://www.baidu.com/img/flexible/logo/pc/result.png' url = 'https://www.baidu.com/img/flexible/logo/pc/result.png'
# 存放路径 # 存放路径
@ -105,18 +105,18 @@ print(mission.rate, mission.info)
90% '下载中' 90% '下载中'
``` ```
## 实时查看所有线程进度 ## 📍 实时查看所有线程进度
多线程方式不会实时显示下载进度，可用`show()`方法把下载进度打印出来。 多线程方式不会实时显示下载进度，可用`show()`方法把下载进度打印出来。
!> **注意：** <br> 若使用 pyCharm 运行，须在运行配置里勾选“模拟输出控制台中的终端”才能正常显示输出。 !> **注意：** <br>若使用 pyCharm 运行，须在运行配置里勾选“模拟输出控制台中的终端”才能正常显示输出。
参数： **参数：**
- asyn：是否异步进行 - `asyn`：是否异步进行
- keep：任务全部完成后是否保持显示 - `keep`：任务全部完成后是否保持显示
返回：None **返回：**`None`
```python ```python
url = 'https://example.com/file/abc.zip' url = 'https://example.com/file/abc.zip'
@ -136,21 +136,21 @@ page.download.show()
?> **Tips：** <br> `keep`参数为`True`时，即使所有任务都已结束仍会一直打印进度，可以按`enter`结束。 ?> **Tips：** <br> `keep`参数为`True`时，即使所有任务都已结束仍会一直打印进度，可以按`enter`结束。
## 等待任务结束 ## 📍 等待任务结束
有时须要等待任务结束，以便获取结果，可用`wait()`方法。 当传入任务时，等待该任务结束并返回结果。不传入参数时等待所有任务结束，与`show()`方法一致。 有时须要等待任务结束，以便获取结果，可用`wait()`方法。 当传入任务时，等待该任务结束并返回结果。不传入参数时等待所有任务结束，与`show()`方法一致。
参数： **参数：**
- mission：任务对象或任务`id`，为`None`时等待所有任务结束 - `mission`：任务对象或任务 id，为`None`时等待所有任务结束
- show：是否显示进度 - `show`：是否显示进度
返回： **返回：**
- 指定任务时，返回任务结果和信息组成的两位 tuple。`True`表示成功，`False`表示失败，`None`表示跳过。 - 指定任务时，返回任务结果和信息组成的两位 tuple。`True`表示成功，`False`表示失败，`None`表示跳过。
- 不指定任务时，返回`None` - 不指定任务时，返回`None`
!> **注意：** <br> 若使用 pyCharm 运行，须在运行配置里勾选“模拟输出控制台中的终端”才能正常显示输出。 !> **注意：** <br>若使用 pyCharm 运行，须在运行配置里勾选“模拟输出控制台中的终端”才能正常显示输出。
```python ```python
url = 'https://www.baidu.com/img/PCfb_5bf082d29588c07f842ccde3f97243ea.png' url = 'https://www.baidu.com/img/PCfb_5bf082d29588c07f842ccde3f97243ea.png'
@ -167,20 +167,20 @@ url：https://www.baidu.com/img/PCfb_5bf082d29588c07f842ccde3f97243ea.png
100% 下载完成 D:\files\PCfb_5bf082d29588c07f842ccde3f97243ea_4.png 100% 下载完成 D:\files\PCfb_5bf082d29588c07f842ccde3f97243ea_4.png
``` ```
## 获取某个任务结果 ## 📍 获取某个任务结果
从`add()`方法返回的`Mission`对象，可查看该任务执行情况。 从`add()`方法返回的`Mission`对象，可查看该任务执行情况。
`Mission`对象属性： `Mission`对象属性：
- id：任务 id - `id`：任务 id
- file_name：要保存的文件名 - `file_name`：要保存的文件名
- path：要保存的路径 - `path`：要保存的路径
- data：任务数据 - `data`：任务数据
- state：任务状态，有`'waiting'`、`'running'`、`'done'`三种 - `state`：任务状态，有`'waiting'`、`'running'`、`'done'`三种
- rate：任务进度，以百分比显示 - `rate`：任务进度，以百分比显示
- info：任务信息，成功会返回文件绝对路径，失败会显示原因 - `info`：任务信息，成功会返回文件绝对路径，失败会显示原因
- result：任务结果，`True`表示成功，`False`表示失败，`None`表示跳过 - `result`：任务结果，`True`表示成功，`False`表示失败，`None`表示跳过
```python ```python
mission = page.download.add(url) mission = page.download.add(url)
@ -193,7 +193,7 @@ print(mission.state)
running running
``` ```
## 下载设置 ## 📍 下载设置
可使用以下属性进行配置： 可使用以下属性进行配置：

87
docs/进阶使用/打包程序.md Normal file
View File

@ -0,0 +1,87 @@
本节介绍打包程序须要注意的事项。
因为程序用到 ini 文件，而打包时不会自动带上，因此直接打包是会导致运行出错。
解决办法：
- 手动带上 ini 文件，并在程序中指定路径
- 把配置信息写在程序中，不带 ini 文件
# ✔️ 手动带上 ini
在程序中用相对路径方式指定 ini 文件，并且打包后手动把 ini 文件复制到程序文件夹。
`WebPage`：
```python
from DrissionPage import WebPage, DriverOptions, SessionOptions
do = DriverOptions(ini_path=r'.\configs.ini')
so = SessionOptions(ini_path=r'.\configs.ini')
page = WebPage(driver_or_options=do, session_or_options=so)
```
`MixPage`：
```python
from DrissionPage import Drission, MixPage
drission = Drission(ini_path=r'.\configs.ini') # ini文件放在程序相同路径下
page = MixPage(drission=drission)
```
# ✔️ 不使用 ini
这种方法须把所有配置信息写到代码里。
`WebPage`：
```python
from DrissionPage import WebPage, DriverOptions, SessionOptions
do = DriverOptions(read_file=False) # 不读取文件方式新建配置对象
so = SessionOptions(read_file=False)
do.set_paths(chrome_path=r'.\chrome.exe') # 输入配置信息
page = WebPage(driver_or_options=do, session_or_options=so)
```
`MixPage`：
```python
from DrissionPage import MixPage, DriverOptions, SessionOptions
do = DriverOptions(read_file=False)
so = SessionOptions(read_file=False)
page = MixPage(driver_options=do, session_options=so)
```
!> **注意** <br>这个时候 driver 和 session 两个参数都要输入内容，如果其中一个不需要设置可以输入`False`。
如：
```python
page = WebPage(driver_or_options=do, session_or_options=False)
```
# ✔️ 实用示例
通常，我会把一个绿色浏览器和打包后的 exe 文件放在一起，程序中用相对路径指向该浏览器，这样拿到别的电脑也可以正常实用。
```python
from DrissionPage import WebPage, DriverOptions
do = DriverOptions(read_file=False).set_paths(local_port='9888',
chrome_path=r'.\Chrome\chrome.exe',
user_data_path=r'.\Chrome\userData')
page = WebPage(driver_or_options=do, session_or_options=False)
# 注意：session_or_options=False
page.get('https://www.baidu.com')
```
注意以下两点，程序就会跳过读取 ini 文件：
- `DriverOptions()`里要设置`read_file=False`
- 如果不传入某个模式的配置（示例中为 s 模式），要在`MixPage()`初始化是设置对应参数为`False`

10
docs/MixPage使用方法/监听浏览器网络数据.md → docs/进阶使用/监听浏览器网络.md
View File

@ -1,5 +1,3 @@
# 监听浏览器网络数据
许多网页的数据来自接口，在网站使用过程中动态加载，如使用 JS 加载内容的翻页列表。 许多网页的数据来自接口，在网站使用过程中动态加载，如使用 JS 加载内容的翻页列表。
这些数据通常以 json 形式发送，浏览器接收后，对其进行解析，再加载到 DOM 相应位置。 这些数据通常以 json 形式发送，浏览器接收后，对其进行解析，再加载到 DOM 相应位置。
@ -10,11 +8,11 @@
由于该工具不依赖 DrissionPage，现已独立发布为一个库，但仍然可以在 DrissionPage 中导入。 由于该工具不依赖 DrissionPage，现已独立发布为一个库，但仍然可以在 DrissionPage 中导入。
!> 为了便于维护，该工具用法请异步 [FlowViewer](https://gitee.com/g1879/FlowViewer) 查看。 !> 为了便于维护，该工具用法请移步 [FlowViewer](https://gitee.com/g1879/FlowViewer) 查看。
#
# 简单示例
# ✔️ 简单示例
```python ```python
from DrissionPage.tools import Listener from DrissionPage.tools import Listener
@ -29,5 +27,3 @@ for i in listener.steps():
listener.stop() #停止监听 listener.stop() #停止监听
``` ```

2
setup.py
View File

@ -6,7 +6,7 @@ with open("README.md", "r", encoding='utf-8') as fh:
setup( setup(
name="DrissionPage", name="DrissionPage",
version="3.0.27", version="3.0.28",
author="g1879", author="g1879",
author_email="g1879@qq.com", author_email="g1879@qq.com",
description="A module that integrates selenium and requests session, encapsulates common page operations.", description="A module that integrates selenium and requests session, encapsulates common page operations.",