diff --git a/docs/入门指南/准备工作.md b/docs/入门指南/准备工作.md index bf4b4af..953681d 100644 --- a/docs/入门指南/准备工作.md +++ b/docs/入门指南/准备工作.md @@ -4,6 +4,8 @@ 如果要控制浏览器，须设置浏览器路径。程序默认设置控制 Chrome，所以以下用 Chrome 作为演示。如果要使用 Edge 或其它 Chromium 内核浏览器，设置方法是一样的。 +作者发现 92 版的 Chrome 存在一些奇怪的问题，导致有些电脑环境下不能启动，请尽量避免使用。 + # ✔️ 执行步骤 ## 📍 关闭已打开的 Chrome diff --git a/docs/入门指南/安装和导入.md b/docs/入门指南/安装和导入.md index 6576edd..9fb49fa 100644 --- a/docs/入门指南/安装和导入.md +++ b/docs/入门指南/安装和导入.md @@ -24,7 +24,7 @@ pip install DrissionPage --upgrade ## 📍 页面类 -页面类用于控制浏览器，或收发数据包，是最主要的工具。`DrissionPage`包含三种主要页面类。根据须要在其中选择使用。 +页面类用于控制浏览器，或收发数据包，是最主要的工具。DrissionPage 包含三种主要页面类。根据须要在其中选择使用。 `WebPage`是功能最全面的页面类，既可控制浏览器，也可收发数据包： diff --git a/docs/启动配置/Session启动配置.md b/docs/启动配置/Session启动配置.md index 7bd6ff0..ca7593b 100644 --- a/docs/启动配置/Session启动配置.md +++ b/docs/启动配置/Session启动配置.md @@ -352,7 +352,7 @@ so.save(path=r'D:\tmp\settings.ini') ## 📍 `save_to_default()` -此方法用于保存配置项到固定的默认 ini 文件。默认 ini 文件是指随`DrissionPage`内置的那个。 +此方法用于保存配置项到固定的默认 ini 文件。默认 ini 文件是指随 DrissionPage 内置的那个。 **参数：** 无 diff --git a/docs/启动配置/easy_set方法.md b/docs/启动配置/easy_set方法.md index 701dd4d..7edcbb1 100644 --- a/docs/启动配置/easy_set方法.md +++ b/docs/启动配置/easy_set方法.md @@ -1,134 +1,169 @@ -Chrome 浏览器的配置繁琐且难以记忆，本库提供一些常用功能的快速设置方法，调用即可修改 ini 文件中该部分内容。 +Chrome 浏览器的配置繁琐且难以记忆，本库提供一些常用功能的快速设置方法，调用即可修改 ini 文件中该部分内容。对于简单的设置，使用可以使代码更整洁。这些方法统称 easy_set 方法。 -!> **注意：** <br>easy_set 方法仅用于设置 ini 文件，浏览器或 Session 创建后再调用没有效果的。 <br>如果是接管已打开的浏览器，这些设置也没有用。<br>这些方法只是便于修改 ini 文件，不要写在正式代码中。 +!>**注意：**<br>- easy_set 方法仅用于设置 ini 文件，浏览器或 Session 创建后再调用没有效果的。 <br>- 如果是接管已打开的浏览器，这些设置也没有用。<br>- 虽然能简化代码，但会修改 ini +文件，只适合在单页面对象时使用。 -## 📍 简单示例 +# ✔️ 导入 + +easy_set 方法存放在`DrissionPage.easy_set`路径中，可用以下方法按需导入： + +```python +from DrissionPage.easy_set import set_headless, set_paths +``` + +# ✔️ 简单示例 + +由于 easy_set 方法会直接修改 ini 文件内容，而`ChromiumPage`创建时会默认读取 ini 文件，所以代码看上去比较简洁。 + +但如果要创建多个页面对象，就要避免用这种方法，否则会造成冲突。 ```python -# 导入 from DrissionPage.easy_set import set_headless +from DrissionPage import ChromiumPage # 设置无头模式 set_headless(True) + +# 启动浏览器 +page = ChromiumPage() ``` -## 📍 `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 是否匹配 +| 参数名称 | 类型 | 默认值 | 说明 | +|:------------------:|:---------------:|:-------:| -------------------------------------------------------------- | +| `driver_path` | `str`<br>`Path` | `None` | chromdriver 的路径，只`MixPage`和`DriverPage`需要使用 | +| `chrome_path` | `str`<br>`Path` | `None` | 浏览器可执行文件路径，为向后兼容保留，建议用`browser_path`代替 | +| `browser_path` | `str`<br>`Path` | `None` | 浏览器可执行文件路径，与`chrome_path`同时设置时会覆盖`chrome_path` | +| `local_port` | `str`<br>`int` | `None` | 浏览器使用的本地端口号 | +| `debugger_address` | `str` | `None` | 调试浏览器地址，格式 ip: port，例：`'127.0.0.1:9222'` | +| `download_path` | `str`<br>`Path` | `None` | 下载文件默认保存路径 | +| `user_data_path` | `str`<br>`Path` | `None` | 用户数据文件夹路径 | +| `cache_path` | `str`<br>`Path` | `None` | 缓存路径 | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | +| `check_version` | `bool` | `False` | 是否检查设置的 chromedriver 和 Chrome 是否匹配，只`MixPage`和`DriverPage`需要使用 | **返回：**`None` -## 📍 `set_headless()` +*** -该方法用于设置是否已无头模式启动浏览器。 +## 📍 `use_auto_port()` -**参数：** +此方法用于设置是否使用自动分配的端口和临时文件夹。 -- `on_off`：`bool`类型，表示开或关 -- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件 +设置为`True`时，浏览器每次会用可用的端口和临时文件夹保存用户数据，而无视已经保存的端口和路径。 + +| 参数名称 | 类型 | 默认值 | 说明 | +|:----------:|:---------------:|:------:| --------------------------- | +| `on_off` | `bool` | `True` | `bool`表示开或关 | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | **返回：**`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 文件 +| 参数名称 | 类型 | 默认值 | 说明 | +|:----------:|:---------------:|:------:| --------------------------- | +| `arg` | `str` | `True` | 属性名 | +| `value` | `str` | `True` | 属性值，有值的属性传入值，没有的传入`None` | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | **返回：**`None` -## 📍 `check_driver_version()` +*** -该方法用于检查传入的 chrome 和 chromedriver 是否匹配。 +## 📍 `set_user_agent()` -**参数：** +此方法用于设置 user agent。 -- `driver_path`：chromedriver.exe 路径 -- `chrome_path`：chrome.exe 路径 +| 参数名称 | 类型 | 默认值 | 说明 | +|:------------:|:---------------:|:------:| --------------------------- | +| `user_agent` | `str` | 无 | user agent文本 | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | -**返回：**`bool`类型，表示是否匹配 +**返回：**`None` -## 📍 `get_match_drive()` +*** -该方法用于自动识别 chrome 版本并下载匹配的 driver。 +## 📍 `set_proxy()` -**参数：** +此方法用于设置浏览器代理。注意此方法只能设置浏览器代理，不能设置`Session`对象代理。 -- `ini_path`：要读取和修改的 ini 文件路径 -- `save_path`：chromedriver 保存路径 -- `chrome_path`：指定 chrome.exe 位置，不指定会自动依次在 ini 文件、注册表、系统路径中查找 -- `show_msg`：是否打印信息 -- `check_version`：是否检查版本匹配 +| 参数名称 | 类型 | 默认值 | 说明 | +|:----------:|:---------------:|:------:| ----------------------------------- | +| `proxy` | `str` | 无 | 代理网址和端口，例：`'http://localhost:1080'` | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | -**返回：** 成功返回 driver 路径，失败返回`None` +**返回：**`None` + +*** + +## 📍 `set_headless()` + +此方法用于设置浏览器是否使用无界面模式。 + +| 参数名称 | 类型 | 默认值 | 说明 | +|:----------:|:---------------:|:------:| --------------------------- | +| `on_off` | `bool` | `True` | `bool`表示开或关 | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | + +**返回：**`None` + +*** + +## 📍 `set_no_imgs()` + +此方法用于设置浏览器是否禁止加载图像。 + +| 参数名称 | 类型 | 默认值 | 说明 | +|:----------:|:---------------:|:------:| --------------------------- | +| `on_off` | `bool` | `True` | `bool`表示开或关 | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | + +**返回：**`None` + +*** + +## 📍 `set_no_js()` + +此方法用于设置浏览器是否禁用 JavaScript。 + +| 参数名称 | 类型 | 默认值 | 说明 | +|:----------:|:---------------:|:------:| --------------------------- | +| `on_off` | `bool` | `True` | `bool`表示开或关 | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | + +**返回：**`None` + +*** + +## 📍 `set_mute()` + +此方法用于设置浏览器是否静音。 + +| 参数名称 | 类型 | 默认值 | 说明 | +|:----------:|:---------------:|:------:| --------------------------- | +| `on_off` | `bool` | `True` | `bool`表示开或关 | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | + +**返回：**`None` + +*** + +## 📍 `show_settings()` + +此方法用于打印 ini 文件内容。 + +| 参数名称 | 类型 | 默认值 | 说明 | +|:----------:|:---------------:|:------:| --------------------------- | +| `ini_path` | `str`<br>`Path` | `None` | 要修改的ini文件路径，为`None`表示默认配置文件 | + +**返回：**`None` diff --git a/docs/启动配置/浏览器启动配置.md b/docs/启动配置/浏览器启动配置.md index bce01fb..dc169b4 100644 --- a/docs/启动配置/浏览器启动配置.md +++ b/docs/启动配置/浏览器启动配置.md @@ -496,7 +496,7 @@ co.save(path=r'D:\tmp\settings.ini') ## 📍 `save_to_default()` -此方法用于保存配置项到固定的默认 ini 文件。默认 ini 文件是指随`DrissionPage`内置的那个。 +此方法用于保存配置项到固定的默认 ini 文件。默认 ini 文件是指随 DrissionPage 内置的那个。 **参数：** 无