3.1.0

2024-12-10 04:00:23 +08:00 · 2023-01-27 23:54:45 +08:00 · 2023-01-27 23:54:45 +08:00 · 207a420453
commit 207a420453
parent 3afa6236fa
17 changed files with 1190 additions and 337 deletions
--- a/DrissionPage/configs/chromium_options.py
+++ b/DrissionPage/configs/chromium_options.py
@ -274,10 +274,9 @@ class ChromiumOptions(object):

    def set_page_load_strategy(self, value):
        """设置page_load_strategy，可接收 'normal', 'eager', 'none'
-        selenium4以上版本才支持此功能
        normal：默认情况下使用, 等待所有资源下载完成
        eager：DOM访问已准备就绪, 但其他资源 (如图像) 可能仍在加载中
-        none：完全不阻塞WebDriver
+        none：完全不阻塞
        :param value: 可接收 'normal', 'eager', 'none'
        :return: 当前对象
        """
--- a/MANIFEST.in
+++ b/MANIFEST.in
@ -1,6 +1,4 @@
 include DrissionPage/configs/configs.ini
 include DrissionPage/*.pyi
-include DrissionPage/configs/*.py
-include DrissionPage/configs/*.pyi
-include DrissionPage/functions/*.py
-include DrissionPage/functions/*.pyi
+include DrissionPage/*/*.py
+include DrissionPage/*/*.pyi
--- a/docs/README.md
+++ b/docs/README.md
@ -10,6 +10,16 @@ DrissionPage 是一个基于 python 的网页自动化工具。

 它的语法简洁而优雅，代码量少，对新手友好。

+***
+
+支持系统：Windows、Linux、Mac
+
+python 版本：3.6 及以上
+
+支持浏览器：Chromium 内核（如 Chrome 和 edge）
+
+*** 
+
 <a href='https://gitee.com/g1879/DrissionPage/stargazers'><img src='https://gitee.com/g1879/DrissionPage/badge/star.svg?theme=dark' alt='star'></img></a> <a href='https://gitee.com/g1879/DrissionPage/members'><img src='https://gitee.com/g1879/DrissionPage/badge/fork.svg?theme=dark' alt='fork'></img></a>

 项目地址：[gitee](https://gitee.com/g1879/DrissionPage)    |    [github](https://github.com/g1879/DrissionPage)
@ -24,8 +34,9 @@ DrissionPage 是一个基于 python 的网页自动化工具。
 使用浏览器，可以很大程度上绕过这些坑，但浏览器运行效率不高。

 因此，这个库设计初衷，是将它们合而为一，能够在不同须要时切换相应模式，并提供一种人性化的使用方法，提高开发和运行效率。  
-除了合并两者，本库还以网页为单位封装了常用功能，提供非常简便的操作和语句，在用于网页自动化操作时，减少考虑细节，专注功能实现，使用更方便。  
-一切从简，尽量提供简单直接的使用方法，对新手更友好。
+除了合并两者，本库还以网页为单位封装了常用功能，提供非常简便的操作和语句，在用于网页自动化操作时，减少考虑细节，专注功能实现，使用更方便。 一切从简，尽量提供简单直接的使用方法，使代码更优雅。
+
+以前的版本是对 selenium 进行重新封装实现的。从 3.0 开始，作者另起炉灶，对底层进行了重新开发，摆脱对 selenium 的依赖，增强了功能，提升了运行效率。

 # 💡 理念

--- a/docs/WebPage使用方法/3.10动作链.md
+++ b/docs/WebPage使用方法/3.10动作链.md
@ -32,13 +32,9 @@ from DrissionPage import ActionChains

 创建动作链对象非常简单，只要把`WebPage`对象或`ChromiumPage`对象传入即可。动作链只在这个页面上生效。

-**◽ 参数：**
-
-| 名称     | 类型                           | 默认  | 说明           |
-| ------ | ---------------------------- | --- | ------------ |
-| `page` | `WebPage`对象或`ChromiumPage`对象 | 无   | 动作链要操作的浏览器页面 |
-
-**◽ 示例：**
+| 初始化参数  | 类型                          | 默认值 | 说明           |
+|:------:|:---------------------------:|:---:| ------------ |
+| `page` | `WebPage`<br>`ChromiumPage` | 无   | 动作链要操作的浏览器页面 |

 ```python
 from DrissionPage import WebPage, ActionChains
@ -53,215 +49,215 @@ ac = ActionChains(page)

 此方法用于移动鼠标到元素中点，或页面上的某个绝对坐标。可设置偏移量，当带偏移量时，偏移量相对于元素左上角坐标。

-**◽ 参数：**
+| 初始化参数        | 类型                                              | 默认值 | 说明                                      |
+|:------------:|:-----------------------------------------------:|:---:| --------------------------------------- |
+| `ele_or_loc` | `ChrmoiumElement`<br>`str`<br>`Tuple[int, int]` | 无   | 元素对象、文本定位符或绝对坐标，坐标为`tuple`(int, int) 形式 |
+| `offset_x`   | `int`                                           | 0   | x 轴偏移量，向右为正，向左为负                        |
+| `offset_y`   | `int`                                           | 0   | y 轴偏移量，向下为正，向上为负                        |

-| 名称           | 类型                                        | 默认  | 说明                                      |
-| ------------ | ----------------------------------------- | --- | --------------------------------------- |
-| `ele_or_loc` | `ChrmoiumElement`、`str`、`Tuple[int, int]` | 无   | 元素对象、文本定位符或绝对坐标，坐标为`tuple`(int, int) 形式 |
-| `offset_x`   | `int`                                     | 0   | x 轴偏移量，向右为正，向左为负                        |
-| `offset_y`   | `int`                                     | 0   | y 轴偏移量，向下为正，向上为负                        |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

-**◽ 示例：**
+**示例：** 使鼠标移动到 ele 元素上

 ```python
 ele = page('tag:a')
-ac.move_to(ele_or_loc=ele)  # 使鼠标移动过到 ele 元素上
+ac.move_to(ele_or_loc=ele)
 ```

 ## 📍 `move()`

 此方法用于使鼠标相对当前位置移动若干距离。

-**◽ 参数：**
-
-| 名称         | 类型    | 默认  | 说明               |
-| ---------- | ----- | --- | ---------------- |
+| 参数名称       | 类型    | 默认值 | 说明               |
+|:----------:|:-----:|:---:| ---------------- |
 | `offset_x` | `int` | 0   | x 轴偏移量，向右为正，向左为负 |
 | `offset_y` | `int` | 0   | y 轴偏移量，向下为正，向上为负 |

-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

-**◽ 示例：**
+**示例：** 鼠标向右移动 300 像素

 ```python
-ac.move(300, 0)  # 鼠标向右移动 300 像素
+ac.move(300, 0)
 ```

 ## 📍 `up()`

 此方法用于使鼠标相对当前位置向上移动若干距离。

-**◽ 参数：**
-
-| 名称      | 类型    | 默认  | 说明       |
-| ------- | ----- | --- | -------- |
+| 参数名称    | 类型    | 默认值 | 说明       |
+|:-------:|:-----:|:---:| -------- |
 | `pixel` | `int` | 无   | 鼠标移动的像素值 |

-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

-**◽ 示例：**
+**示例：** 鼠标向上移动 50 像素

 ```python
-ac.up(50)  # 鼠标向上移动 50 像素
+ac.up(50)
 ```

 ## 📍 `down()`

 此方法用于使鼠标相对当前位置向下移动若干距离。

-**◽ 参数：**
-
-| 名称      | 类型    | 默认  | 说明       |
-| ------- | ----- | --- | -------- |
+| 参数名称    | 类型    | 默认值 | 说明       |
+|:-------:|:-----:|:---:| -------- |
 | `pixel` | `int` | 无   | 鼠标移动的像素值 |

-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：**
+
+```python
+ac.down(50)
+```
+
 ## 📍 `left()`

 此方法用于使鼠标相对当前位置向左移动若干距离。

-**◽ 参数：**
-
-| 名称      | 类型    | 默认  | 说明       |
-| ------- | ----- | --- | -------- |
+| 参数名称    | 类型    | 默认值 | 说明       |
+|:-------:|:-----:|:---:| -------- |
 | `pixel` | `int` | 无   | 鼠标移动的像素值 |

-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：**
+
+```python
+ac.left(50)
+```
+
 ## 📍 `right()`

 此方法用于使鼠标相对当前位置向右移动若干距离。

-**◽ 参数：**
-
-| 名称      | 类型    | 默认  | 说明       |
-| ------- | ----- | --- | -------- |
+| 参数名称    | 类型    | 默认值 | 说明       |
+|:-------:|:-----:|:---:| -------- |
 | `pixel` | `int` | 无   | 鼠标移动的像素值 |

-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：**
+
+```python
+ac.right(50)
+```
+
 # ✔ 鼠标按键

 ## 📍 `click()`

 此方法用于单击鼠标左键，单击前可先移动到元素上。

-**◽ 参数：**
+| 参数名称     | 类型                         | 默认值    | 说明             |
+|:--------:|:--------------------------:|:------:| -------------- |
+| `on_ele` | `ChromiumElement`<br>`str` | `None` | 要点击的元素对象或文本定位符 |

-| 名称       | 类型                      | 默认     | 说明             |
-| -------- | ----------------------- | ------ | -------------- |
-| `on_ele` | `ChromiumElement`、`str` | `None` | 要点击的元素对象或文本定位符 |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：**
+
+```python
+ac.click('#div1')
+```
+
 ## 📍 `r_click()`

 此方法用于单击鼠标右键，单击前可先移动到元素上。

-**◽ 参数：**
+| 参数名称     | 类型                         | 默认值    | 说明             |
+|:--------:|:--------------------------:|:------:| -------------- |
+| `on_ele` | `ChromiumElement`<br>`str` | `None` | 要点击的元素对象或文本定位符 |

-| 名称       | 类型                      | 默认     | 说明             |
-| -------- | ----------------------- | ------ | -------------- |
-| `on_ele` | `ChromiumElement`、`str` | `None` | 要点击的元素对象或文本定位符 |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：**
+
+```python
+ac.r_click('#div1')
+```
+
 ## 📍 `m_click()`

 此方法用于单击鼠标中键，单击前可先移动到元素上。

-**◽ 参数：**
+| 参数名称     | 类型                         | 默认值    | 说明             |
+|:--------:|:--------------------------:|:------:| -------------- |
+| `on_ele` | `ChromiumElement`<br>`str` | `None` | 要点击的元素对象或文本定位符 |

-| 名称       | 类型                      | 默认     | 说明             |
-| -------- | ----------------------- | ------ | -------------- |
-| `on_ele` | `ChromiumElement`、`str` | `None` | 要点击的元素对象或文本定位符 |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：**
+
+```python
+ac.m_click('#div1')
+```
+
 ## 📍 `hold()`

 此方法用于按住鼠标左键不放，按住前可先移动到元素上。

-**◽ 参数：**
+| 参数名称     | 类型                         | 默认值    | 说明             |
+|:--------:|:--------------------------:|:------:| -------------- |
+| `on_ele` | `ChromiumElement`<br>`str` | `None` | 要按住的元素对象或文本定位符 |

-| 名称       | 类型                      | 默认     | 说明             |
-| -------- | ----------------------- | ------ | -------------- |
-| `on_ele` | `ChromiumElement`、`str` | `None` | 要按住的元素对象或文本定位符 |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：**
+
+```python
+ac.hold('#div1')
+```
+
 ## 📍 `release()`

 此方法用于释放鼠标左键，释放前可先移动到元素上。

-**◽ 参数：**
+| 参数名称     | 类型                         | 默认值    | 说明             |
+|:--------:|:--------------------------:|:------:| -------------- |
+| `on_ele` | `ChromiumElement`<br>`str` | `None` | 要释放的元素对象或文本定位符 |

-| 名称       | 类型                      | 默认     | 说明             |
-| -------- | ----------------------- | ------ | -------------- |
-| `on_ele` | `ChromiumElement`、`str` | `None` | 要释放的元素对象或文本定位符 |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：** 移动到某元素上然后释放鼠标左键
+
+```python
+ac.release('#div1')
+```
+
 ## 📍 `r_hold()`

 此方法用于按住鼠标右键不放，按住前可先移动到元素上。

-**◽ 参数：**
+| 参数名称     | 类型                         | 默认值    | 说明             |
+|:--------:|:--------------------------:|:------:| -------------- |
+| `on_ele` | `ChromiumElement`<br>`str` | `None` | 要按住的元素对象或文本定位符 |

-| 名称       | 类型                      | 默认     | 说明             |
-| -------- | ----------------------- | ------ | -------------- |
-| `on_ele` | `ChromiumElement`、`str` | `None` | 要按住的元素对象或文本定位符 |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

@ -269,15 +265,11 @@ ac.up(50)  # 鼠标向上移动 50 像素

 此方法用于释放鼠标右键，释放前可先移动到元素上。

-**◽ 参数：**
+| 参数名称     | 类型                         | 默认值    | 说明             |
+|:--------:|:--------------------------:|:------:| -------------- |
+| `on_ele` | `ChromiumElement`<br>`str` | `None` | 要释放的元素对象或文本定位符 |

-| 名称       | 类型                      | 默认     | 说明             |
-| -------- | ----------------------- | ------ | -------------- |
-| `on_ele` | `ChromiumElement`、`str` | `None` | 要释放的元素对象或文本定位符 |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

@ -285,15 +277,11 @@ ac.up(50)  # 鼠标向上移动 50 像素

 此方法用于按住鼠标中键不放，按住前可先移动到元素上。

-**◽ 参数：**
+| 参数名称     | 类型                         | 默认值    | 说明             |
+|:--------:|:--------------------------:|:------:| -------------- |
+| `on_ele` | `ChromiumElement`<br>`str` | `None` | 要按住的元素对象或文本定位符 |

-| 名称       | 类型                      | 默认     | 说明             |
-| -------- | ----------------------- | ------ | -------------- |
-| `on_ele` | `ChromiumElement`、`str` | `None` | 要按住的元素对象或文本定位符 |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

@ -301,13 +289,9 @@ ac.up(50)  # 鼠标向上移动 50 像素

 此方法用于释放鼠标中键，释放前可先移动到元素上。

-**◽ 参数：**
-
-| 名称       | 类型                      | 默认     | 说明             |
-| -------- | ----------------------- | ------ | -------------- |
-| `on_ele` | `ChromiumElement`、`str` | `None` | 要释放的元素对象或文本定位符 |
-
-**◽ 返回：**
+| 参数名称     | 类型                         | 默认值    | 说明             |
+|:--------:|:--------------------------:|:------:| -------------- |
+| `on_ele` | `ChromiumElement`<br>`str` | `None` | 要释放的元素对象或文本定位符 |

 | 类型             | 说明      |
 | -------------- | ------- |
@ -319,17 +303,13 @@ ac.up(50)  # 鼠标向上移动 50 像素

 此方法用于滚动鼠标滚轮，滚动前可先移动到元素上。

-**◽ 参数：**
+| 参数名称      | 类型                         | 默认值    | 说明                  |
+|:---------:|:--------------------------:|:------:| ------------------- |
+| `delta_x` | `int`                      | 0      | 滚轮 x 轴变化值，向右为正，向左为负 |
+| `delta_y` | `str`                      | 0      | 滚轮 y 轴变化值，向下为正，向上为负 |
+| `on_ele`  | `ChromiumElement`<br>`str` | `None` | 要滚动的元素对象或文本定位符      |

-| 名称        | 类型                      | 默认     | 说明                  |
-| --------- | ----------------------- | ------ | ------------------- |
-| `delta_x` | `int`                   | 0      | 滚轮 x 轴变化值，向右为正，向左为负 |
-| `delta_y` | `str`                   | 0      | 滚轮 y 轴变化值，向下为正，向上为负 |
-| `on_ele`  | `ChromiumElement`、`str` | `None` | 要滚动的元素对象或文本定位符      |
-
-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

@ -339,80 +319,78 @@ ac.up(50)  # 鼠标向上移动 50 像素

 此方法用于按下键盘按键，特殊字符见 Keys。

-**◽ 参数：**
-
-| 名称    | 类型    | 默认  | 说明   |
-| ----- | ----- | --- | ---- |
+| 参数名称  | 类型    | 默认值 | 说明   |
+|:-----:|:-----:|:---:| ---- |
 | `key` | `str` | 无   | 按键键值 |

-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

-**◽ 示例：**
+**示例：** 按下 ctrl 键

 ```python
 from DrissionPage.keys import Keys

-ac.key_down(Keys.CTRL)  # 按下 ctrl 键
+ac.key_down(Keys.CTRL)
 ```

 ## 📍 `key_up()`

 此方法用于提起键盘按键，特殊字符见 Keys。

-**◽ 参数：**
-
-| 名称    | 类型    | 默认  | 说明   |
-| ----- | ----- | --- | ---- |
+| 参数名称  | 类型    | 默认值 | 说明   |
+|:-----:|:-----:|:---:| ---- |
 | `key` | `str` | 无   | 按键键值 |

-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：** 提起 ctrl 键
+
+```python
+from DrissionPage.keys import Keys
+
+ac.key_up(Keys.CTRL)
+```
+
 ## 📍 `type()`

 此方法用于输入一段文本。

-**◽ 参数：**
-
-| 名称     | 类型    | 默认  | 说明     |
-| ------ | ----- | --- | ------ |
+| 参数名称   | 类型    | 默认值 | 说明     |
+|:------:|:-----:|:---:| ------ |
 | `text` | `str` | 无   | 要输入的文本 |

-**◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

+**示例：**
+
+```python
+ac.type('text')
+```
+
 # ✔ 等待

 ## 📍 `wait()`

 此方法用于在动作链中插入停顿。

-**◽ 参数：**
-
-| 名称       | 类型      | 默认  | 说明   |
-| -------- | ------- | --- | ---- |
+| 参数名称     | 类型      | 默认值 | 说明   |
+|:--------:|:-------:|:---:| ---- |
 | `second` | `float` | 无   | 等待秒数 |

- **◽ 返回：**
-
-| 类型             | 说明      |
+| 返回类型           | 说明      |
 | -------------- | ------- |
 | `ActionChains` | 动作链对象本身 |

-**◽ 示例：**
+**示例：** 停顿 3 秒

 ```python
-ac.wait(3)  # 停顿 3 秒
+ac.wait(3)
 ```

 # ✔ 示例
@ -420,8 +398,7 @@ ac.wait(3)  # 停顿 3 秒
 ## 📍 模拟输入 ctrl+a

 ```python
-from DrissionPage import ChromiumPage, ActionChains
-from DrissionPage.keys import Keys
+from DrissionPage import ChromiumPage, ActionChains, Keys

 # 创建页面
 page = ChromiumPage()
@ -440,11 +417,18 @@ ac.type('a')
 ac.key_up(Keys.CTRL)
 ```

+链式写法：
+
+```python
+ac.click('tag:input').key_down(Keys.CTRL).type('a').key_up(Keys.CTRL)
+```
+
 ## 📍 拖拽元素

+把一个元素向右拖拽 300 像素：
+
 ```python
 from DrissionPage import ChromiumPage, ActionChains
-from DrissionPage.keys import Keys

 # 创建页面
 page = ChromiumPage()
@ -458,3 +442,9 @@ ac.right(300)
 # 释放左键
 ac.release()
 ```
+
+把一个元素拖拽到另一个元素上：
+
+```python
+ac.hold('#div1').release('#div2')
+```
--- a/docs/WebPage使用方法/3.1创建页面对象.md
+++ b/docs/WebPage使用方法/3.1创建页面对象.md
@ -43,9 +43,7 @@ page = SessionPage()

 `DriverOptions`用于管理创建浏览器时的配置，内置了常用的配置，并能实现链式操作。详细使用方法见“启动配置”一节。

-**◽ 初始化参数：**
-
-| 名称          | 类型     | 默认     | 说明                       |
+| 初始化参数       | 类型     | 默认值    | 说明                       |
 | ----------- | ------ | ------ | ------------------------ |
 | `read_file` | `bool` | `True` | 是否从 ini 文件中读取配置信息        |
 | `ini_path`  | `str`  | `None` | 文件路径，为`None`则读取默认 ini 文件 |
@ -66,9 +64,7 @@ page = WebPage(driver_or_options=do)

 `SessionOptions`用于管理创建`Session`对象时的配置，内置了常用的配置，并能实现链式操作。详细使用方法见“启动配置”一节。

-**◽ 初始化参数：**
-
-| 名称          | 类型     | 默认     | 说明                       |
+| 初始化参数       | 类型     | 默认值    | 说明                       |
 | ----------- | ------ | ------ | ------------------------ |
 | `read_file` | `bool` | `True` | 是否从 ini 文件中读取配置信息        |
 | `ini_path`  | `str`  | `None` | 文件路径，为`None`则读取默认 ini 文件 |
@ -77,7 +73,7 @@ page = WebPage(driver_or_options=do)

 ```python
 # 导入 SessionOptions
-from DrissionPage import SessionPage， SessionOptions
+from DrissionPage import SessionPage, SessionOptions

 proxies = {'http': 'http://127.0.0.1:1080',
           'https': 'http://127.0.0.1:1080'}
@ -121,10 +117,34 @@ page = WebPage(driver_or_options=do)

 当须要使用多个页面对象共同操作一个页面时，可在对象间传递驱动器。

-```python
-from DrissionPage import WebPage
+这也可以实现多个页面对象共同控制一个浏览器。

-# 创建第一个页面
+## 📍 `ChromiumPage`传递驱动器
+
+```python
+# 创建一个页面
+page1 = ChormiumPage()
+# 获取页面对象的浏览器控制器
+driver = page1.driver
+# 把控制器对象在第二个页面对象初始化时传递进去
+page2 = ChormiumPage(driver_or_options=driver)
+```
+
+## 📍 `SessionPage`传递`Session`对象
+
+```python
+# 创建一个页面
+page1 = SessionPage()
+# 获取页面对象内置的Session对象
+session = page1.session
+# 在第二个页面对象初始化时传递该对象
+page2 = SessionPage(session_or_options=session)
+```
+
+## 📍 `WebPage`传递两种模式控制权
+
+```python
+# 创建一个页面
 page1 = WebPage()
 # 获取页面对象的浏览器控制器
 driver = page1.driver
@ -240,7 +260,7 @@ from DrissionPage import ChromiumPage, DriverOptions
 do1 = DriverOptions().set_paths(local_port=9111)
 do2 = DriverOptions().set_paths(local_port=9222)

-page1 = ChromiumPage(driver_or_options=do1)
+page1 = ChromiumPage(addr_driver_opts=do1)
 page2 = ChromiumPage(driver_or_options=do2)
 ```

@ -250,38 +270,32 @@ page2 = ChromiumPage(driver_or_options=do2)

 `ChroumiumPage`对象纯粹用于操作浏览器，不能切换模式。一个该对象对应的是浏览器上一个标签页。

-**◽ 初始化参数：**
-
-| 名称                 | 类型                                     | 默认     | 说明                                                                                                    |
-| ------------------ | -------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
-| `addr_driver_opts` | `str`、`ChromiumDriver`、`DriverOptions` | `None` | 浏览器启动配置或接管信息；传入' ip:port' 字符串或`ChromiumDriver`时接管浏览器，传入`DriverOptions`时按配置启动浏览器，为`None`时使用配置文件配置启动浏览器 |
-| `tab_id`           | `str`                                  | `None` | 要控制的标签页id，用于 d 模式，为`None`则控制激活的标签页                                                                    |
-| `timeout`          | `float`                                | `None` | 整体超时时间，为`None`则从配置文件中读取                                                                               |
+| 初始化参数              | 类型                                           | 默认值    | 说明                                                                                                    |
+| ------------------ | -------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
+| `addr_driver_opts` | `str`<br>`ChromiumDriver`<br>`DriverOptions` | `None` | 浏览器启动配置或接管信息。传入' ip:port' 字符串或`ChromiumDriver`时接管浏览器；传入`DriverOptions`时按配置启动浏览器；为`None`时使用配置文件配置启动浏览器 |
+| `tab_id`           | `str`                                        | `None` | 要控制的标签页id，用于 d 模式，为`None`则控制激活的标签页                                                                    |
+| `timeout`          | `float`                                      | `None` | 整体超时时间，为`None`则从配置文件中读取                                                                               |

 ## 📍 `SessionPage`

 `SessionPage`对象纯粹用于收发数据包，不能切换模式，产生的元素对象为`SessionElement`。

-**◽ 初始化参数：**
-
-| 名称                   | 类型                         | 默认     | 说明                                                              |
-| -------------------- | -------------------------- | ------ | --------------------------------------------------------------- |
-| `session_or_options` | `Session`、`SessionOptions` | `None` | 传入`Session`对象时使用该对象收发数据包；传入`SessionOptions`对象时用该配置创建`Session`对象 |
-| `timeout`            | `float`                    | `None` | 连接超时时间，                                                         |
+| 初始化参数                | 类型                            | 默认值    | 说明                                                              |
+| -------------------- | ----------------------------- | ------ | --------------------------------------------------------------- |
+| `session_or_options` | `Session`<br>`SessionOptions` | `None` | 传入`Session`对象时使用该对象收发数据包；传入`SessionOptions`对象时用该配置创建`Session`对象 |
+| `timeout`            | `float`                       | `None` | 连接超时时间，为`None`则从配置文件中读取                                         |

 ## 📍 `WebPage`

 `WebPage`对象封装了常用的网页操作，并实现在浏览器和 requests 两种模式之间的切换。

-**◽ 初始化参数：**
-
-| 名称                   | 类型                                      | 默认     | 说明                                                               |
-| -------------------- | --------------------------------------- | ------ | ---------------------------------------------------------------- |
-| `mode`               | `str`                                   | `'d'`  | 启动时的模式，只能传入`'d'`或`'s'`                                           |
-| `timeout`            | `float`                                 | `None` | 整体超时时间，为`None`则从配置文件中读取                                          |
-| `tab_id`             | `str`                                   | `None` | 要控制的标签页id，用于 d 模式，为`None`则控制激活的标签页                               |
-| `driver_or_options`  | `ChromiumDriver`、`DriverOptions`、`bool` | `None` | 浏览器控制对象或浏览器启动配置对象；为`None`时使用 ini 文件配置；为`False`时不读取 ini 文件。       |
-| `session_or_options` | `Session`、`SessionOptions`、`bool`       | `None` | 收发数据包对象或`Session`启动配置对象；为`None`时使用 ini 文件配置；为`False`时不读取 ini 文件。 |
+| 初始化参数                | 类型                                            | 默认值    | 说明                                                               |
+| -------------------- | --------------------------------------------- | ------ | ---------------------------------------------------------------- |
+| `mode`               | `str`                                         | `'d'`  | 启动时的模式，只能传入`'d'`或`'s'`                                           |
+| `timeout`            | `float`                                       | `None` | 整体超时时间，为`None`则从配置文件中读取                                          |
+| `tab_id`             | `str`                                         | `None` | 要控制的标签页id，用于 d 模式，为`None`则控制激活的标签页                               |
+| `driver_or_options`  | `ChromiumDriver`<br>`DriverOptions`<br>`bool` | `None` | 浏览器控制对象或浏览器启动配置对象；为`None`时使用 ini 文件配置；为`False`时不读取 ini 文件。       |
+| `session_or_options` | `Session`<br>`SessionOptions`<br>`bool`       | `None` | 收发数据包对象或`Session`启动配置对象；为`None`时使用 ini 文件配置；为`False`时不读取 ini 文件。 |

 **◽ 说明：**

--- a/docs/WebPage使用方法/下载文件.md
+++ b/docs/WebPage使用方法/下载文件.md
@ -0,0 +1,429 @@
+浏览器没有为下载功能提供方便的程序接口，难以实现有效的下载管理，如检测下载状态、重命名、失败管理等。使用 requests 下载文件能较好实现以上功能，但代码较为繁琐。  
+因此 DrissionPage 内置了高效可靠的下载工具，提供任务管理、多线程、大文件分块、自动重连、文件名冲突处理等功能。
+
+无论是控制浏览器，还是收发数据包的场景，都可以使用它。甚至可以拦截浏览器的下载动作，转用内置下载器进行下载。使用方式简洁高效。
+
+?> 该工具名为 DownloadKit，现已独立打包成一个库，详细用法见：[DownloadKit](https://gitee.com/g1879/DownloadKit)。这里只介绍和页面对象有关的用法。
+
+# ✔️ 功能简介
+
+`SessionPage`、`ChromiumPage`、`WebPage`都可以使用`download()`方法进行下载，还可以使用`download_set`属性对下载参数进行配置。内置下载器功能如下：
+
+- 支持多线程同时下载多个文件
+- 大文件自动分块使用多线程下载
+- 可拦截浏览器下载动作，自动调用下载器下载
+- 自动创建目标路径
+- 自动去除路径中的非法字符
+- 下载时支持文件重命名
+- 自动处理文件名冲突
+- 自动去除文件名非法字符
+- 支持 post 方式
+- 支持自定义连接参数
+- 任务失败自动重试
+
+# ✔️ 简单示例
+
+下载一个文件（单线程）：
+
+```python
+page.download('https://xxxxxx/file.pdf')
+```
+
+添加下载任务，以多线程方式下载：
+
+```python
+page.download.add('https://xxxxxx/file.pdf')
+```
+
+拦截浏览器下载动作，改用 DwonloadKit 下载：
+
+```python
+page.download_set.by_DownloadKit()
+page('#download_btn').click()
+```
+
+下载设置：
+
+```python
+# 设置默认保存路径
+page.download_set.save_path('...')
+# 设置存在同名文件时处理方式
+page.download_set.if_file_exists.skip()
+# 设置使用浏览器或DownloadKit下载
+page.download_set.by_DownloadKit()
+page.download_set.by_browser()
+# 设置使用DownloadKit下载时是否允许多线程同时下载一个文件
+page.download_set.split(True)
+```
+
+# ✔️ 单线程下载
+
+直接调用页面对象的`download()`方法，可下载一个文件，该方法是阻塞式的，会等待下载完成再往下操作。下载时默认打印下载进度。
+
+### 🔸 `download()`
+
+| 参数名称          | 类型              | 默认值    | 说明                                               |
+|:-------------:|:---------------:|:------:| ------------------------------------------------ |
+| `file_url`    | `str`           | 无      | 文件网址                                             |
+| `goal_path`   | `str`<br>`Path` | `None` | 保存文件夹路径，为`None`则保存在当前目录                          |
+| `rename`      | `str`           | `None` | 重命名文件名，可不包含后缀                                    |
+| `file_exists` | `str`           | `None` | 遇到同名文件时的处理方式，可选`'skip'`、`'overwrite'`、`'rename'` |
+| `data`        | `str`<br>`dict` | `None` | post 方式使用的数据，如不为`None`，使用 post 方式发送请求            |
+| `show_msg`    | `bool`          | `True` | 是否显示下载进度                                         |
+| `**kwargs`    | -               | 无      | requests的`get()`方法参数                             |
+
+| 返回类型    | 返回格式         | 说明                  |
+|:-------:|:------------:| ------------------- |
+| `tuple` | (任务结果, 任务信息) | 返回任务结果和信息组成的`tuple` |
+
+任务结果可能出现以下值：
+
+- `'success'`：表示下载成功
+
+- `'skip'`：表示存在同名文件，跳过任务
+
+- `'cancel'`：表示任务下载途中被取消
+
+- `False`：表示下载失败
+
+任务信息成功时返回文件绝对路径，其它情况返回相应说明。
+
+**示例：**
+
+```python
+from DrissionPage import WebPage
+
+page = WebPage('s')
+# 文件 url
+url = 'https://www.baidu.com/img/flexible/logo/pc/result.png'  
+# 存放路径
+save_path = r'C:\download'  
+
+# 重命名为img.png，存在重名时自动在文件名末尾加上序号，显示下载进度
+res = page.download(url, save_path, 'img', 'rename', show_msg=True)
+# 打印结果
+print(res)
+```
+
+显示：
+
+```shell
+url：https://www.baidu.com/img/flexible/logo/pc/result.png
+文件名：img.png
+目标路径：C:\download
+100% 下载完成 C:\download\img.png
+
+('success', 'C:\\download\\img.png')
+```
+
+# ✔️ 多线程并发下载
+
+您可以添加数量不限的下载任务，程序会自动调配线程去完成这些任务。
+
+默认设置下，页面对象最多使用 10 个下载线程，如进程已满，新任务会进入等待队列排队，待有空线程时自动开始。
+
+添加多线程任务的方法是调用页面对象`donwload`属性的`add()`方法。
+
+### 🔸 `download.add()`
+
+| 参数名称          | 类型              | 默认值    | 说明                                                                |
+|:-------------:|:---------------:|:------:| ----------------------------------------------------------------- |
+| `file_url`    | `str`           | 无      | 文件网址                                                              |
+| `goal_path`   | `str`<br>`Path` | `None` | 保存文件夹路径，为`None`则保存在当前目录                                           |
+| `rename`      | `str`           | `None` | 重命名文件名，可不包含后缀                                                     |
+| `file_exists` | `str`           | `None` | 遇到同名文件时的处理方式，可选`'skip'`、`'overwrite'`、`'rename'`                  |
+| `data`        | `str`<br>`dict` | `None` | post 方式使用的数据，如不为`None`，使用 post 方式发送请求                             |
+| `split`       | `bool`          | `None` | 是否允许多线程分块下载，为`None`则使用下载器内置设置，默认为`True`<br>默认大于 50MB 的文件使用多线程分块下载 |
+| `**kwargs`    | -               | 无      | requests的`get()`方法参数                                              |
+
+| 返回类型      | 说明                                                                           |
+|:---------:| ---------------------------------------------------------------------------- |
+| `Mission` | 返回任务对象，任务对象具体属性及方法详见 [DownloadKit](https://gitee.com/g1879/DownloadKit) 相关说明 |
+
+**示例：**
+
+```python
+from DrissionPage import WebPage
+
+page = WebPage('s')
+# 文件 url
+url = 'https://www.baidu.com/img/flexible/logo/pc/result.png'  
+# 存放路径
+save_path = r'C:\download'  
+
+# 返回一个任务对象
+mission = page.download.add(url, save_path)
+
+# 通过任务对象查看状态
+print(mission.rate, mission.info)
+```
+
+输出：
+
+```shell
+90% '下载中'
+```
+
+# ✔️ 接管浏览器下载任务
+
+## 📍 切换下载方式
+
+很多时候，网站会用某些非显式的方式触发浏览器下载，因此不能很好地获取文件 url，下载依赖浏览器功能。，页面对象可以设置用`DownloadKit`拦截浏览器的下载任务，使下载更快，下载过程更可控。
+
+方法是使用`download_set.by_DownloadKit()`方法，指定使用`DownloadKit`接管浏览器的下载动作。
+
+```python
+page.download_set.by_DownloadKit()
+```
+
+事实上，页面对象创建时就默认开启了此功能，如果想用浏览器本身的下载功能，可以这样写：
+
+```python
+page.download_set.by_browser()
+```
+
+!>**注意：**<br>接管浏览器下载任务后会使用 get 方式下载，如果是需要 post 的请求，可能不能正确下载。
+
+## 📍 等待下载开始
+
+在浏览器中点击下载按钮后，有时下载不会立即触发，这时如果过快进行其它操作，可能导致一些意想不到的问题。因此设计了`wait_download_begin()`
+方法，用于等待下载动作的开始，以便正确接管。可控制浏览器的页面对象`ChromiumPage`和`WebPage`拥有此方法。
+
+### 🔸 `wait_download_begin()`
+
+此方法会阻塞程序，等待下载动作触发。如到达超时时间仍未触发，则返回`False`。
+
+| 参数名称      | 类型               | 默认值    | 说明                                    |
+|:---------:|:----------------:|:------:| ------------------------------------- |
+| `timeout` | `int`<br>`float` | `None` | 等待下载开始的超时时间，为`None`则使用页面对象`timeout`属性 |
+
+| 返回类型   | 说明       |
+| ------ | -------- |
+| `bool` | 是否等到下载开始 |
+
+**示例：**
+
+```python
+page('#download_btn').click()
+page.wait_download_begin()
+```
+
+# ✔️ 查看任务信息
+
+用单线程方式下载，会阻塞程序直到下载完成，因此无须查看任务信息。
+
+用多线程或接管浏览器下载任务的方式下载，可用以下方式查看任务信息。
+
+## 📍 获取单个任务对象
+
+使用`download.add()`
+添加任务时，会返回一个任务对象，后续程序可以使用该对象查询该任务下载进度、结果，也可以取消任务。这里不对该对象作详细说明，详情请移步：[DownloadKit](https://gitee.com/g1879/DownloadKit)。
+
+**示例：**
+
+```python
+mission = page.download.add('http://xxxx.pdf')
+print(mission.id)  # 获取任务id
+print(mission.rate)  # 打印下载进度（百分比）
+print(mission.state)  # 打印任务状态，'waiting'、'running'、'done'
+print(mission.info)  # 打印任务信息
+print(mission.result)  # 打印任务结果，'success'表示成功，False表示失败，'skip'表示跳过，'cancel'表示取消
+```
+
+除添加任务时获取对象，也可以使用`download.get_mission()`获取。在上一个示例中可以看到，任务对象有`id`属性，把任务的`id`传入此方法，会返回该任务对象。
+
+**示例：**
+
+```python
+mission_id = mission.id
+mission = page.download.get_mission(mission_id)
+```
+
+## 📍 获取全部任务对象
+
+使用页面对象的`download.missions`属性，可以获取所有下载任务。该属性返回一个`dict`，保存了所有下载任务。以任务对象的`id`为 key。
+
+```python
+page.download_set.save_path(r'D:\download')
+page.download('http://xxxxx/xxx1.pdf')
+page.download('http://xxxxx/xxx1.pdf')
+print(page.download.missions)
+```
+
+输出：
+
+```
+{
+    1: <Mission 1 D:\download\xxx1.pdf xxx1.pdf>
+    2: <Mission 2 D:\download\xxx1_1.pdf xxx1_1.pdf>
+    ...
+}
+```
+
+## 📍 获取下载失败的任务
+
+使用`download.get_failed_missions()`方法，可以获取下载失败的任务列表。
+
+```python
+page.download_set.save_path(r'D:\download')
+page.download('http://xxxxx/xxx1.pdf')
+page.download('http://xxxxx/xxx1.pdf')
+print(page.download.get_failed_missions()
+```
+
+输出：
+
+```
+[
+    <Mission 1 状态码：404 None>,
+    <Mission 2 状态码：404 None>
+    ...
+]
+```
+
+?>**Tips：**<br>获取失败任务对象后，可从其`data`属性读取任务内容，以便记录日志或择机重试。
+
+# ✔️ 下载设置
+
+主要的下载设置使用`download_set`内置方法进行，更多运行参数使用`download`属性的子属性进行。
+
+## 📍 设置文件保存路径
+
+### 🔸 `download_set.save_path()`
+
+此方法用于设置文件下载默认保存路径。
+
+| 参数名称   | 类型              | 默认值 | 说明                 |
+|:------:|:---------------:|:---:| ------------------ |
+| `path` | `str`<br>`Path` | 无   | 文件保存路径，绝对路径和相对路径均可 |
+
+**返回：**`None`
+
+**示例：**
+
+```python
+page.download_set.save_path(r'D:\tmp')
+```
+
+?>**Tips：**<br>- 保存路径可指定不存在的文件夹，程序会自动创建。<br>- 设置默认保存路径后，每个任务仍可在创建时指定自己的保存路径，以覆盖默认设置。
+
+## 📍 设置下载方式
+
+### 🔸 `download_set.by_DownloadKit()`
+
+此方法用于设置当前页面对象使用`DownloadKit`下载文件。
+
+### 🔸 `download_set.by_browser()`
+
+此方法用于设置当前页面对象使用浏览器下载工具下载文件。
+
+## 📍 设置重名文件处理方法
+
+下载过程中可能遇到保存路径已存在同名文件，`DownloadKit`提供 3 种处理方法。
+
+!>**注意：**<br>这个设置只有在使用`DownloadKit`作为下载工具时有效。
+
+### 🔸 `download_set.if_file_exists.rename()`
+
+此方式会对新文件进行重命名，在文件名后加上序号。
+
+假如，保存路径已存在`abc.txt`文件，新的`abc.txt`文件会自动重命名为`abc_1.txt`，再下载一个`abc.txt`时，会命名为`abc_2.txt`，如此类推。
+
+**示例：** 3 次下载同一个文件
+
+```python
+page.download_set.if_file_exists.rename()
+page.download('http://xxxxx/xxx.pdf')
+page.download('http://xxxxx/xxx.pdf')
+page.download('http://xxxxx/xxx.pdf')
+```
+
+在文件夹会生成如下 3 个文件：
+
+```
+xxx.pdf
+xxx_1.pdf
+xxx_2.pdf
+```
+
+### 🔸 `download_set.if_file_exists.skip()`
+
+遇到同名文件时，跳过。同时任务对象的`result`属性设置为`'skip'`。
+
+**示例：** 3 次下载同一个文件
+
+```python
+page.download_set.if_file_exists.skip()
+page.download('http://xxxxx/xxx.pdf')
+page.download('http://xxxxx/xxx.pdf')
+page.download('http://xxxxx/xxx.pdf')
+```
+
+在文件夹只会生成如下 1 个文件：
+
+```
+xxx.pdf
+```
+
+### 🔸 `download_set.if_file_exists.overwrite()`
+
+遇到同名文件时，覆盖。
+
+!>**注意：**<br>这个方式在多线程下载时要慎用，万一多个任务下载多个同名文件，会导致互相覆盖的现象。
+
+?>**Tips：**<br>除了整体设置，还可以在创建任务时单独设置该任务的处理方式。
+
+?>**Tips：**<br>文件名如遇到`'?'`、`'\'`等非法字符，会自动替换为空格。
+
+## 📍 设置大文件是否分块
+
+`DownloadKit`具备多线程下载大文件功能，在文件超过指定大小时（默认 50MB），可对文件进行多线程分块下载，每个线程负责 50MB 的下载，以提高下载速度。这个功能默认是关闭的，您可以设置是否开启。
+
+!>**注意：**  
+这个设置只有在使用`DownloadKit`作为下载工具时有效。
+
+### 🔸 `download_set.split()`
+
+```python
+# 使用分块下载
+page.download_set.split(on_off=True)
+# 禁用分块下载
+page.download_set.split(on_off=False)
+```
+
+?>**Tips：**  
+除了整体设置，还可以在创建任务时单独设置该任务是否使用分块下载。
+
+## 📍运行参数设置
+
+运行参数主要包括可使用线程上限、连接失败重试次数、重试间隔。
+
+### 🔸 `download.roads`
+
+此参数设置整个`DownloadKit`对象允许使用的线程数上限，默认为 10。
+
+默认设置下，页面对象最多使用 10 个下载线程，如进程已满，新任务会进入等待队列排队，待有空线程时自动开始。
+
+这个属性只能在没有任务在运行的时候设置。
+
+```python
+page.download.roads = 20  # 允许最多使用20个线程进行下载
+```
+
+### 🔸 `download.retry`
+
+此属性用于设置连接失败时重试次数，默认为 3。
+
+```python
+page.download.roads = 5  # 设置连接失败时重试5次
+```
+
+### 🔸 `download.interval`
+
+此属性用于设置连接失败时重试间隔，默认为 5 秒。
+
+```python
+page.download.interval = 10  # 设置连接失败时等待10秒再重试
+```
+
+?> **Tips：**<br> 重试次数和间隔在初始化时继承页面对象的`retry_times`和`retry_interval`属性，可用上面例子的方法对下载的重试次数和间隔进行设置，设置后不会影响页面对象的设置。
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@ -33,6 +33,7 @@
  * [🔨 4.8 标签页操作](WebPage使用方法\3.8标签页操作.md)
  * [🔨 4.9 iframe操作](WebPage使用方法\3.9iframe操作.md)
  * [🔨 4.10 动作链](WebPage使用方法\3.10动作链.md)
+  * [🔨 4.11 下载文件](WebPage使用方法\下载文件.md)

 * [📝 5 启动配置](#)
  
--- a/docs/index.html
+++ b/docs/index.html
@ -8,6 +8,7 @@
    <meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible"/>
    <meta content="Description" name="description">
    <meta content="width=device-width, initial-scale=1.0, minimum-scale=1.0" name="viewport">
+    <meta content="DrissionPage,文档,使用文档,教程,用户手册,api" name="Keywords">
    <!--    <link href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" rel="stylesheet">-->

    <!-- Theme: Simple Dark -->
--- a/docs/scripts/theme-simple-dark.css
+++ b/docs/scripts/theme-simple-dark.css
--- a/docs/入门指南/安装和导入.md
+++ b/docs/入门指南/安装和导入.md
@ -1,16 +1,10 @@
 # ✔️运行环境

-## 📍 操作系统
+操作系统：Windows、Linux 或 Mac。

-Windows 或 Linux。
+python 版本：3.6 及以上

-作者没有 Mac，没测试过，估计是可以的。
-
-
-
-## 📍 python 版本
-
-支持 python 3.6 及以上版本。
+支持浏览器：Chromium 内核（如 Chrome 和 edge）

 # ✔️ 安装

--- a/docs/启动配置/Session启动配置.md
+++ b/docs/启动配置/Session启动配置.md
@ -62,6 +62,16 @@ print(so.headers)

 **返回：** 当前对象

+## 📍 `set_timeout()`
+
+此方法用于设置超时属性。
+
+**参数：**
+
+- `second`：秒数
+
+**返回：** 当前对象
+
 ## 📍 `cookies`

 此属性返回`cookies`设置信息，可赋值。  
--- a/docs/启动配置/使用配置文件.md
+++ b/docs/启动配置/使用配置文件.md
@ -71,6 +71,7 @@ headers = {
          "Connection": "keep-alive",
          "Accept-Charset": "utf-8;q=0.7,*;q=0.7"
          }
+timeout = 10
 ```

 # ✔️ 文件位置
--- a/docs/启动配置/浏览器启动配置.md
+++ b/docs/启动配置/浏览器启动配置.md
@ -1,179 +1,523 @@
-为使浏览器设置更便利，本库使用`DriverOptions`类，专门用于管理浏览器的启动配置。
+浏览器的启动配置非常繁杂，本库使用`ChromiumOptions`类管理启动配置，并且内置了常用配置的设置接口。

-!> **注意：** <br>1、`DriverOptions`仅用于管理启动配置，浏览器启动后再修改无效。  <br>2、若接管已打开的浏览器，则所有启动配置均无效。
+需要注意的是，该对象只能用于浏览器的启动，浏览器启动后，再修改该配置没有任何效果。接管已打开的浏览器时，启动配置也是无效的。

-# ✔️ `DriverOptions`类
+# ✔️ 创建对象

-`DriverOptions`类继承自 selenium 的`Options` 类，保留了原来所有功能，原生功能不在这里叙述，只介绍增加的功能。  
-对象创建时，可从配置文件中读取配置来进行初始化，不从文件读取则创建一个空配置对象。  
-该类绝大部分方法都支持链式操作。
+## 📍 导入

-**初始化参数：**
+```python
+from DrissionPage import ChromiumOptions
+```

- `read_file`：是否从默认 ini 文件中读取配置信息
- `ini_path`：ini 文件路径，为`None`则读取默认 ini 文件
+## 📍 `ChromiumOptions`

-## 📍 `driver_path`
+`ChromiumOptions`对象用于管理浏览器初始化配置。可从配置文件中读取配置来进行初始化。

-此属性返回 chromedriver 文件路径。`MixPage`使用，`WebPage`不需要。
+| 初始化参数       | 类型              | 默认值    | 说明                                 |
+|:-----------:|:---------------:|:------:| ---------------------------------- |
+| `read_file` | `bool`          | `True` | 是否从 ini 文件中读取配置信息，为`False`则用默认配置创建 |
+| `ini_path`  | `Path`<br>`str` | `None` | 指定 ini 文件路径，为`None`则读取内置 ini 文件    |

-## 📍 `chrome_path`
+创建配置对象：

-此属性返回 Chrome 浏览器启动文件路径，为空时程序会根据注册表或系统路径查找。
+```python
+from DrissionPage import ChromiumOptions

-## 📍 `set_paths()`
+co = ChromiumOptions()
+```

-该方法用于设置浏览器用到的几种路径信息。
+默认情况下，`ChromiumOptions`对象会从 ini 文件中读取配置信息，当指定`read_file`参数为`False`时，则以默认配置创建。

-**参数：**
+*** 

- `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()`
+```python
+from DrissionPage import WebPage, ChromiumOptions

-此方法用于保存当前配置对象的信息到配置文件。
+# 创建配置对象（默认从 ini 文件中读取配置）
+co = ChromiumOptions()
+# 设置不加载图片、静音
+co.set_no_imgs(True).set_mute(True)

-**参数：**
+# 以该配置创建页面对象
+page = WebPage(driver_or_options=co)
+```

- `path`：配置文件的路径，默认保存到当前读取的配置文件，传入`'default'`保存到默认 ini 文件
+***

-**返回：**配置文件绝对路径
+# ✔️ 浏览器地址

-## 📍 `save_to_default()`
+## 📍 `debugger_address`

-此方法用于保存当前配置对象的信息到默认 ini 文件。
+该属性为要控制的浏览器地址，格式为 ip:port，默认为`'127.0.0.0:9222'`。可对其赋值进行设置。也可以用后文介绍的`set_paths()`方法设置。

-**参数：** 无
+```python
+co.debugger_address = 'localhost:9333'
+```

-**返回：** 配置文件绝对路径
+***

-## 📍 `remove_argument()`
+# ✔️ 启动参数配置

-此方法用于移除一个`argument`项。
+Chromium 内核浏览器有一系列的启动配置，以`--`开头，可在浏览器创建时传入。如`--headless`无界面模式，`--disable-images`禁用图像等。有些参数只有参数名，有些会带有值。

-**参数：**
+启动参数非常多，详见：[List of Chromium Command Line Switches « Peter Beverloo](https://peter.sh/experiments/chromium-command-line-switches/)

- `value`：设置项名称，带有值的设置项传入设置名称即可
-
-**返回：** 当前对象
-
-## 📍 `remove_experimental_option()`
-
-此方法用于移除一个实验设置，传入 key 值删除。
-
-**参数：**
-
- `key`：实验设置的名称
-
-**返回：** 当前对象
-
-## 📍 `remove_all_extensions()`
-
-此方法用于移除所有插件。
-
-**参数：** 无
-
-**返回：** 当前对象
+`set_argument()`和`remove_argument()`方法用于设置浏览器启动命令行参数。

 ## 📍 `set_argument()`

-此方法用于设置浏览器配置的`argument`属性。
+此方法用于设置启动参数，带值和不带值的参数项都可以。

-**参数：**
+| 参数名称    | 类型                         | 默认值    | 说明                                                |
+|:-------:|:--------------------------:|:------:| ------------------------------------------------- |
+| `arg`   | `str`                      | 无      | 启动参数名称                                            |
+| `value` | `str`<br>`None`<br>`False` | `None` | 参数的值。带值的参数传入属性值，没有的传入`None`。<br>如传入`False`，删除该参数。 |

- `arg`：属性名
- `value`：属性值，有值的属性传入值，没有的传入`bool`类型表示开关
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |

-**返回：** 当前对象
+**示例：** 无值和有值的参数设置
+
+```python
+# 设置用无头模式启动浏览器
+co.set_argument('--headless')
+# 设置浏览器默认 user agent
+co.set_argument('--user-agent', 'Mozilla/5.0 (Macintos.....')
+```
+
+***
+
+## 📍 `remove_argument()`
+
+此方法用于在启动配置中删除一个启动参数，只要传入参数名称即可，不需要传入值。
+
+| 参数名称  | 类型    | 默认值 | 说明                  |
+|:-----:|:-----:|:---:| ------------------- |
+| `arg` | `str` | 无   | 参数名称，有值的设置项传入设置名称即可 |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象自身 |
+
+**示例：** 删除无值和有值的参数设置
+
+```python
+# 删除--headless参数
+co.remove_argument('--headless')
+# 删除--user-agent参数
+co.remove_argument('--user-agent')
+```
+
+***
+
+# ✔️ 插件配置
+
+`add_extension()`和`remove_extensions()`用于设置浏览器启动时要加载的插件。可以指定数量不限的插件。
+
+## 📍 `add_extension()`
+
+此方法用于添加一个插件到浏览器。
+
+| 参数名称   | 类型              | 默认值 | 说明   |
+|:------:|:---------------:|:---:| ---- |
+| `path` | `str`<br>`Path` | 无   | 插件路径 |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+?>**Tips：**<br>根据作者的经验，把插件文件解压到一个独立文件夹，然后把插件路径指向这个文件夹，会比较稳定。
+
+**示例：**
+
+```python
+co.add_extension(r'D:\SwitchyOmega')
+```
+
+***
+
+## 📍 `remove_extensions()`
+
+此方法用于移除配置对象中保存的所有插件路径。如须移除部分插件，请移除全部后再重新添加需要的插件。
+
+**参数：** 无
+
+**返回：** 配置对象自身
+
+```python
+co.remove_extensions()
+```
+
+***
+
+# ✔️ 用户文件配置
+
+除了启动参数，还有大量配置信息保存在 preferences 文件，以下方法用于对用户文件进行设置。
+
+## 📍 `set_user()`
+
+Chromium 浏览器支持多用户配置，我们可以选择使用哪一个。默认为`'Default'`。
+
+| 参数名称   | 类型    | 默认值         | 说明        |
+|:------:|:-----:|:-----------:| --------- |
+| `user` | `str` | `'Default'` | 用户配置文件夹名称 |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+**示例：**
+
+```python
+co.set_user(user='Profile 1')
+```
+
+***
+
+## 📍 `set_pref()`
+
+此方法用于设置用户配置文件里的一个配置项。
+
+在哪里可以查到所有的配置项？作者也没找到，知道的请告知。谢谢。
+
+| 参数名称    | 类型    | 默认值 | 说明    |
+|:-------:|:-----:|:---:| ----- |
+| `arg`   | `str` | 无   | 设置项名称 |
+| `value` | `str` | 无   | 设置项值  |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+**示例：**
+
+```python
+co.set_pref(arg='profile.default_content_settings.popups', value='0')
+```
+
+***
+
+## 📍 `remove_pref()`
+
+此方法用于在当前配置对象中删除一个`pref`配置项。
+
+| 参数名称  | 类型    | 默认值 | 说明    |
+|:-----:|:-----:|:---:| ----- |
+| `arg` | `str` | 无   | 设置项名称 |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+**示例：**
+
+```python
+co.remove_pref(arg='profile.default_content_settings.popups')
+```
+
+***
+
+## 📍 `remove_pref_from_file()`
+
+此方法用于在用户配置文件删除一个配置项。注意与上一个方法不一样，如果用户配置文件中已经存在某个项，用`remove_pref()`是不能删除的，只能用`remove_pref_from_file()`删除。
+
+| 参数名称  | 类型    | 默认值 | 说明    |
+|:-----:|:-----:|:---:| ----- |
+| `arg` | `str` | 无   | 设置项名称 |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+**示例：**
+
+```python
+co.remove_pref_from_file(arg='profile.default_content_settings.popups')
+```
+
+***
+
+# ✔️ 运行参数配置
+
+页面对象运行时需要用到的参数，也可以在`ChromiumOptions`中设置。
+
+## 📍 `set_paths()`
+
+此方法用于设置各种路径信息。对有传入值的路径进行设置，为`None`的则无视。
+
+| 参数名称               | 类型              | 默认值    | 说明                                                          |
+|:------------------:|:---------------:|:------:| ----------------------------------------------------------- |
+| `browser_path`     | `str`<br>`Path` | `None` | 浏览器可执行文件路径                                                  |
+| `local_port`       | `str`<br>`int`  | `None` | 浏览器要使用的本地端口号                                                |
+| `debugger_address` | `str`           | `None` | 浏览器地址，例：127.0.0.1:9222，如与`local_port`一起设置，会覆盖`local_port`的值 |
+| `download_path`    | `str`<br>`Path` | `None` | 下载文件默认保存路径                                                  |
+| `user_data_path`   | `str`<br>`Path` | `None` | 用户数据文件夹路径                                                   |
+| `cache_path`       | `str`<br>`Path` | `None` | 缓存路径                                                        |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+**示例：**
+
+```python
+co.set_paths(local_port=9333, user_data_path=r'D:\tmp')
+```
+
+***
+
+## 📍 `auto_port()`
+
+此方法用于设置是否使用自动分配的端口。
+
+如果设置为`True`，程序会自动寻找一个可用端口，并在系统临时文件夹创建一个文件夹，用于储存浏览器数据。由于端口和用户文件夹都是唯一的，所以用这种方式启动的浏览器不会产生冲突，但也无法多次启动程序时重复接管同一个浏览器。
+
+`set_paths()`方法中`local_port`和`user_data_path`参数，会和`auto_port()`互相覆盖，即以后调用的为准。
+
+| 参数名称     | 类型     | 默认值    | 说明               |
+|:--------:|:------:|:------:| ---------------- |
+| `on_off` | `bool` | `True` | 是否开启自动分配端口和用户文件夹 |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+**示例：**
+
+```python
+co.auto_port(True)
+```
+
+!>**注意：**<br>启用此功能后即会获取端口和新建临时用户数据文件夹，若此时用`save()`方法保存配置到 ini 文件，ini 文件中的设置会被该端口和文件夹路径覆盖。这个覆盖对使用并没有很大影响。
+
+***

 ## 📍 `set_timeouts()`

-此方法用于设置三种超时时间。
+此方法用于设置几种超时时间，以秒为单位。超时用法详见使用方法章节。

-**参数：**
+| 参数名称       | 类型               | 默认值    | 说明                                                            |
+|:----------:|:----------------:|:------:| ------------------------------------------------------------- |
+| `implicit` | `int`<br>`float` | `None` | 默认超时时间，用于元素等待、alert 等待、`WebPage`的 s 模式连接等等，除以下两个参数的场景，都使用这个设置 |
+| `pageLoad` | `int`<br>`float` | `None` | 页面加载超时时间                                                      |
+| `script`   | `int`<br>`float` | `None` | JavaScript 运行超时时间                                             |

- `implicit`：查找元素超时时间
- `pageLoad`：页面加载超时时间
- `script`：脚本运行超时时间
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |

-**返回：** 当前对象
+**示例：**
+
+```python
+co.set_timeouts(implicit=10)
+```
+
+***
+
+## 📍 `set_page_load_strategy()`
+
+此方法用于设置网页加载策略。
+
+加载策略是指强制页面停止加载的时机，如加载完 DOM 即停止，不加载图片资源等，以提高自动化效率。
+
+无论设置哪种策略，加载时间都不会超过`set_timeouts()`中`pageLoad`参数设置的时间。
+
+加载策略：
+
+- `'normal'`：阻塞进程，等待所有资源下载完成（默认）
+
+- `'eager'`：DOM 就绪即停止加载
+
+- `'none'`：网页连接成功即停止加载
+
+| 参数名称    | 类型    | 默认值 | 说明                               |
+|:-------:|:-----:|:---:| -------------------------------- |
+| `value` | `str` | 无   | 可接收`'normal'`、`'eager'`、`'none'` |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+**示例：**
+
+```python
+co.set_page_load_strategy('eager')
+```
+
+***
+
+## 📍 `set_proxy()`
+
+该方法用于设置浏览器代理。
+
+| 参数名称    | 类型    | 默认值 | 说明                                      |
+|:-------:|:-----:|:---:| --------------------------------------- |
+| `proxy` | `str` | 无   | 格式：协议://ip:port<br>当不指定协议时，默认使用 http 代理 |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+**示例：**
+
+```python
+co.set_proxy('http://localhost:1080')
+```
+
+***
+
+# ✔️ 其它配置
+
+作者将一些常用的配置封装成方法，可以直接调用。

 ## 📍 `set_headless()`

-该方法用于设置是否已无头模式启动浏览器。
+该方法用于设置是否已无界面模式启动浏览器。

-**参数：**
+| 参数名称     | 类型     | 默认值    | 说明                  |
+|:--------:|:------:|:------:| ------------------- |
+| `on_off` | `bool` | `True` | `True`和`False`表示开或关 |

- `on_off`：`bool`类型，表示开或关
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |

-**返回：**`None`
+**示例：**
+
+```python
+co.set_headless(True)
+```
+
+!>**注意：**<br>经实测，Chrome 使用无界面模式时，由 js 生成的元素可能不能加载。
+
+***

 ## 📍 `set_no_imgs()`

 该方法用于设置是否禁止加载图片。

-**参数：**
+| 参数名称     | 类型     | 默认值    | 说明                  |
+|:--------:|:------:|:------:| ------------------- |
+| `on_off` | `bool` | `True` | `True`和`False`表示开或关 |

- `on_off`：`bool`类型，表示开或关
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |

-**返回：**`None`
+**示例：**
+
+```python
+co.set_no_imgs(True)
+```
+
+***
+
+## 📍 `set_no_js()`
+
+该方法用于设置是否禁用 JavaScript。
+
+| 参数名称     | 类型     | 默认值    | 说明                  |
+|:--------:|:------:|:------:| ------------------- |
+| `on_off` | `bool` | `True` | `True`和`False`表示开或关 |
+
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |
+
+**示例：**
+
+```python
+co.set_no_js(True)
+```
+
+***

 ## 📍 `set_mute()`

 该方法用于设置是否静音。

-**参数：**
+| 参数名称     | 类型     | 默认值    | 说明                  |
+|:--------:|:------:|:------:| ------------------- |
+| `on_off` | `bool` | `True` | `True`和`False`表示开或关 |

- `on_off`：`bool`类型，表示开或关
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |

-**返回：**`None`
+**示例：**

-## 📍 `set_proxy()`
+```python
+co.set_mute(True)
+```

-该方法用于设置代理。
-
-**参数：**
-
- `proxy`：代理网址和端口，如 127.0.0.1:1080
-
-**返回：**`None`
+***

 ## 📍 `set_user_agent()`

 该方法用于设置 user agent。

-**参数：**
+| 参数名称         | 类型    | 默认值 | 说明           |
+|:------------:|:-----:|:---:| ------------ |
+| `user_agent` | `str` | 无   | user agent文本 |

- `user_agent`：user agent 文本
+| 返回类型              | 说明     |
+| ----------------- | ------ |
+| `ChromiumOptions` | 配置对象本身 |

-**返回：**`None`
+**示例：**

-## 📍 `as_dict()`
+```python
+co.set_user_agent(user_agent='Mozilla/5.0 (Macintos.....')
+```

-该方法以`dict`方式返回所有配置信息。
+***
+
+# ✔️ 保存设置到文件
+
+您可以把不同的配置保存到各自的 ini 文件，以便适应不同的场景。
+
+## 📍 `save()`
+
+此方法用于保存配置项到一个 ini 文件。
+
+| 参数名称   | 类型              | 默认值    | 说明                              |
+|:------:|:---------------:|:------:| ------------------------------- |
+| `path` | `str`<br>`Path` | `None` | ini 文件的路径， 传入`None`保存到当前读取的配置文件 |
+
+| 返回类型  | 说明             |
+| ----- | -------------- |
+| `str` | 保存的 ini 文件绝对路径 |
+
+**示例：**
+
+```python
+# 保存当前读取的ini文件
+co.save()
+
+# 把当前配置保存到指定的路径
+co.save(path=r'D:\tmp')
+```
+
+***
+
+## 📍 `save_to_default()`
+
+此方法用于保存配置项到固定的默认 ini 文件。默认 ini 文件是指随`DrissionPage`内置的那个。

 **参数：** 无

-**返回：** 配置信息
+| 返回类型  | 说明             |
+| ----- | -------------- |
+| `str` | 保存的 ini 文件绝对路径 |

-# ✔️ 简单示例
+**示例：**

 ```python
-from DrissionPage import WebPage, DriverOptions
-
-# 创建配置对象（默认从 ini 文件中读取配置）
-do = DriverOptions()
-# 设置不加载图片、静音
-do.set_no_imgs(True).set_mute(True)
-
-# 以该配置创建页面对象
-page = WebPage(driver_or_options=do)
+co.save_to_default()
 ```
--- a/docs/版本历史.md
+++ b/docs/版本历史.md
@ -1,14 +1,71 @@
-# v3.0.33
+# v3.1.0
+
+- 增强下载功能
+
+  - `ChromiumPage`也可以使用内置下载器下载文件
+
+  - 可拦截并接管浏览器下载任务
+
+  - 新增`download_set`属性对下载参数进行设置
+
+  - 增加`wait_download_begin()`方法
+
+  - 重构部分代码
+
+- 改进浏览器启动设置
+
+  - 优化 ini 文件结构
+
+  - 新增`ChromiumOptions`取代`DriverOptions`，完全摆脱对 selenium 的依赖
+
+  - 新增自动分配端口功能
+
+  - 优化`SessionOptions`设计，增加一系列设置参数的方法
+
+  - 改进对用户配置文件的设置
+
+- 对部分代码进行重构
+
+  - 优化页面对象启动逻辑
+
+  - 优化配置类逻辑
+
+  - 优化项目结构
+
+- 细节
+
+  - 上传文件时支持传入相对路径
+
+- bug 修复
+
+  - 修复`get_tab()`出错问题
+
+  - 修复新浏览器第一次新建标签页时不正确切换的问题
+
+  - 修复关闭当前标签页出错问题
+
+  - 修复改变浏览器窗口大小出错问题
+
+# v3.0.34

 - `WebPage`删除`check_page()`方法
+
 - `DriverOptions`和`easy_set`的`set_paths()`增加`browser_path`参数
+
 - `DriverOptions`增加`browser_path`属性
+
 - `ChromiumFrame`现在支持页面滚动
+
 - 改进滚动到元素功能
+
 - 修改`SessionElement`相对定位参数顺序
+
 - `SessionPage`也可以从 ini 文件读取 timeout 设置
- ini 文件中`session_options`增加`timeout`项 
- `SessionOptions`增加`timeout`属性
+
+- ini 文件中`session_options`增加`timeout`项
+
+- `SessionOptions`增加`timeout`属性、`set_timeout()`方法
+
 - 优化和修复一些问题

 # v3.0.31
@ -72,8 +129,8 @@
 # v2.7.1

 - DriverPage
-    - 增加`get_session_storage()`、`get_local_storage()`、`set_session_storage()`、`set_local_storage()`、`clean_cache()`方法
-    - `run_cdp()`的`cmd_args`参数改为`**cmd_args`
+  - 增加`get_session_storage()`、`get_local_storage()`、`set_session_storage()`、`set_local_storage()`、`clean_cache()`方法
+  - `run_cdp()`的`cmd_args`参数改为`**cmd_args`
 - 关闭 driver 时会主动关闭 chromedriver.exe 的进程
 - 优化关闭浏览器进程逻辑

@ -85,9 +142,9 @@
 # v2.6.0

 - 新增`Listener`类
-    - 可监听浏览器数据包
-    - 可异步监听
-    - 可实现每监听到若干数据包执行操作
+  - 可监听浏览器数据包
+  - 可异步监听
+  - 可实现每监听到若干数据包执行操作
 - 放弃对selenium4.1以下的支持
 - 解决使用新版浏览器时出现的一些问题

--- a/docs/进阶使用/加速浏览器数据采集.md
+++ b/docs/进阶使用/加速浏览器数据采集.md
--- a/requirements.txt
+++ b/requirements.txt
@ -3,6 +3,6 @@ requests
 tldextract
 lxml
 cssselect
-DownloadKit>=0.4.4
+DownloadKit>=0.5.0
 FlowViewer>=0.2.1
 websocket-client
--- a/setup.py
+++ b/setup.py
@ -22,7 +22,7 @@ setup(
        "lxml",
        "tldextract",
        "requests",
-        "DownloadKit>=0.4.4",
+        "DownloadKit>=0.5.0",
        "FlowViewer",
        "websocket-client"
    ],