diff --git a/docs/MixPage使用方法/Drission对象.md b/docs/MixPage使用方法/Drission对象.md index ff31f33..0674004 100644 --- a/docs/MixPage使用方法/Drission对象.md +++ b/docs/MixPage使用方法/Drission对象.md @@ -2,14 +2,14 @@ 可直接读取 ini 文件配置信息创建，也可以在初始化时传入配置信息。 在“[使用方法->创建页面对象](创建页面对象.md)”章节已经涉及过`Drission`的用法，这里介绍属性和方法。 -# `Drission`类 +# ✔️ `Drission`类 -初始化参数： +**初始化参数：** -- driver_or_options：`WebDriver`对象或`DriverOptions`、`Options`类，传入`False`则创建空配置对象 -- session_or_options：`Session`对象或设置字典，传入`False`则创建空配置对象 -- ini_path：ini 文件路径 -- proxy：代理设置，`dict`类型。格式：{'http': '127.0.0.1:1080', 'https': '127.0.0.1:1080'} +- `driver_or_options`：`WebDriver`对象或`DriverOptions`、`Options`类，传入`False`则创建空配置对象 +- `session_or_options`：`Session`对象或设置字典，传入`False`则创建空配置对象 +- `ini_path`：ini 文件路径 +- `proxy`：代理设置，`dict`类型。格式：{'http': '127.0.0.1:1080', 'https': '127.0.0.1:1080'} 前两个参数可直接接收`WebDriver`和`Session`对象，这时后面两个参数无效。 若接收配置对象，则按照配置创建`WebDriver`和`Session`对象。 @@ -35,117 +35,117 @@ do = DriverOptions() drission = Drission(driver_options=do) ``` -## session +## 📍 `session` 此属性返回该对象管理的`Session`对象。 -## driver +## 📍 `driver` 此属性返回该对象管理的`WebDriver`对象。 -## driver_options +## 📍 `driver_options` 此属性返回用于创建`WebDriver`对象的`DriverOptions`对象。 -## session_options +## 📍 `session_options` 此属性以`dict`形式返回用于创建 Session 对象的配置参数。可传入`dict`或`SessionOptions`赋值。 -## proxy +## 📍 `proxy` 此属性返回代理信息，`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。 -参数：无 +**参数：** 无 -返回：`None` +**返回：**`None` -## hide_browser() +## 📍 `hide_browser()` 此方法用于隐藏浏览器进程窗口。 -参数：无 +**参数：** 无 -返回： `None` +**返回：**`None` -## show_browser() +## 📍 `show_browser()` 此方法用于显示浏览器进程窗口。 -参数：无 +**参数：** 无 -返回： `None` +**返回：**`None` -## set_cookies() +## 📍 `set_cookies()` 此方法用于设置`cookies`。可选择对某个对象设置。 -参数： +**参数：** -- cookies：`cookies`信息，可为`CookieJar`,`list`,`tuple`,`str`,`dict` -- set_session：是否设置`Session`对象的`cookies` -- set_driver：是否设置浏览器的`cookies` +- `cookies`：`cookies`信息，可为`CookieJar`,`list`,`tuple`,`str`,`dict` +- `set_session`：是否设置`Session`对象的`cookies` +- `set_driver`：是否设置浏览器的`cookies` -返回：None +**返回：**`None` -## cookies_to_session() +## 📍 `cookies_to_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`对象。 复制`cookies`到浏览器必须指定域名。 -参数： +**参数：** -- url：作用域 +- `url`：作用域 -返回：`None` +**返回：**`None` -## close_driver() +## 📍 `close_driver()` 此方法用于关闭`WebDriver`对象，可选择是否关闭浏览器进程。 -参数： +**参数：** -- kill：是否关闭浏览器进程 +- `kill`：是否关闭浏览器进程 -返回：None +**返回：**`None` -## close_session() +## 📍 `close_session()` 此方法用于关闭`Session`对象。 -参数：无 +**参数：** 无 -返回：`None` +**返回：**`None` -## close() +## 📍 `close()` 此方法用于关闭`Session`和`WebDriver`对象。 -参数：无 +**参数：** 无 -返回：`None` \ No newline at end of file +**返回：**`None` \ No newline at end of file diff --git a/docs/MixPage使用方法/DriverPage和SessionPage.md b/docs/MixPage使用方法/DriverPage和SessionPage.md index 9221712..c581a7f 100644 --- a/docs/MixPage使用方法/DriverPage和SessionPage.md +++ b/docs/MixPage使用方法/DriverPage和SessionPage.md @@ -1,7 +1,7 @@ 如果无须切换模式，可根据需要只使用 DriverPage 或 SessionPage。 分别对应 d 和 s 模式，用法和 MixPage 相似。 -# SessionPage +# ✔️ SessionPage ```python from DrissionPage.session_page import SessionPage @@ -18,7 +18,7 @@ page.get('http://www.baidu.com') print(page.ele('#su').text) ``` -# DriverPage +# ✔️ DriverPage ```python from DrissionPage.driver_page import DriverPage @@ -34,4 +34,3 @@ page.get('http://www.baidu.com') # 输出：百度一下 print(page.ele('#su').text) ``` - diff --git a/docs/MixPage使用方法/cookies的使用.md b/docs/MixPage使用方法/cookies的使用.md index 64d14d0..54ea8a9 100644 --- a/docs/MixPage使用方法/cookies的使用.md +++ b/docs/MixPage使用方法/cookies的使用.md @@ -14,7 +14,4 @@ page.get_cookies(all_domains=True) page.set_cookies(cookies) ``` -?> **Tips:**
-d 模式设置`cookies`后要刷新页面才能看到效果。
-s 模式可在 ini 文件、`SessionOptions`、配置字典中设置`cookies`，在`MixPage`初始化时即可传入，d 模式只能用`set_cookies()`函数设置。 - +?> **Tips:**
d 模式设置`cookies`后要刷新页面才能看到效果。
s 模式可在 ini 文件、`SessionOptions`、配置字典中设置`cookies`，在`MixPage`初始化时即可传入，d 模式只能用`set_cookies()`函数设置。 diff --git a/docs/MixPage使用方法/元素操作.md b/docs/MixPage使用方法/元素操作.md index a270dc2..ffdb328 100644 --- a/docs/MixPage使用方法/元素操作.md +++ b/docs/MixPage使用方法/元素操作.md @@ -1,8 +1,8 @@ d 模式下的`DriverElement`对象可以对浏览器相应元素进行控制。 -# 元素操作方法 +# ✔️ 元素操作方法 -## click() +## 📍 `click()` 此方法用于点击元素。可以选择是否用 js 方式点击，可以在点击失败时自动重试。默认情况下，使用 selenium 原生的点击方法，如果重试超过限定时间，自动改用 js 方式点击。可通过`by_js`参数设置点击方式。 此设计除了可保证点击成功，还可以用于检测页面上的遮罩层是否消失。遮罩层经常出现在 js 方式翻页的时候，它出现的时候会阻碍 selenium @@ -11,12 +11,12 @@ d 模式下的`DriverElement`对象可以对浏览器相应元素进行控制。 !> 注意：
使用 js 方式点击时，是不会进行重试的。 -参数： +**参数：** -- by_js：是否用 js 方式点击，为`None`时先用 selenium 原生方法点击，重试失败超时后改为用 js 点击；为`True`时直接用 js 点击；为`False`时即使重试超时也不会改用 js。 -- timeout：点击失败重试超时时间，为`None`时使用父页面`timeout`设置。 +- `by_js`：是否用 js 方式点击，为`None`时先用 selenium 原生方法点击，重试失败超时后改为用 js 点击；为`True`时直接用 js 点击；为`False`时即使重试超时也不会改用 js。 +- `timeout`：点击失败重试超时时间，为`None`时使用父页面`timeout`设置。 -返回：`bool`，表示是否点击成功。 +**返回：**`bool`，表示是否点击成功。 ```python # 点击一个元素，重试超时根据所在页面元素而定，都失败就改用 js 点击 @@ -30,19 +30,19 @@ ele.click(timeout = 10) # 不断重试点击，直到遮罩层消失，或到 ele.click(by_js=True) # 无视遮罩层，直接用 js 点击下方元素 ``` -## click_at() +## 📍 `click_at()` 此方法用于带偏移量点击元素，偏移量相对于元素左上角坐标。不传入`x`或`y`值时点击元素中点。可选择是否用 js 方式点击，但不会进行重试。 可用于点击一些奇怪的东西，比如用伪元素表示的控件。 点击的目标不一定在元素上，可以传入负值，或大于元素大小的值，点击元素附近的区域。向右和向下为正值，向左和向上为负值。 -参数： +**参数：** -- x：相对元素左上角坐标的 x 轴偏移量 -- y：相对元素左上角坐标的 y 轴偏移量 -- by_js：是否用 js 点击 +- `x`：相对元素左上角坐标的 x 轴偏移量 +- `y`：相对元素左上角坐标的 y 轴偏移量 +- `by_js`：是否用 js 点击 -返回：`None` +**返回：**`None` ```python # 点击元素右上方 50*50 的位置 @@ -55,35 +55,35 @@ ele.click_at(x=50) ele.click_at() ``` -## r_click() +## 📍 `r_click()` 此方法实现右键单击元素。 -参数：无 +**参数：** 无 -返回：`None` +**返回：**`None` ```python ele.r_click() ``` -## r_click_at() +## 📍 `r_click_at()` 此方法用于带偏移量右键点击元素，用法和`click_at()`相似，但没有`by_js`参数。 -参数： +**参数：** -- x：相对元素左上角坐标的x轴偏移量 -- y：相对元素左上角坐标的y轴偏移量 +- `x`：相对元素左上角坐标的x轴偏移量 +- `y`：相对元素左上角坐标的y轴偏移量 -返回：`None` +**返回：** `None` ```python # 点击距离元素左上角 50*50 的位置（位于元素内部） ele.r_click_at(50, 50) ``` -## input() +## 📍 `input()` 此方法用于向元素输入文本或组合键，也可用于输入文件路径到`input`元素（文件间用`\n`间隔）。可选择输入前是否清空元素。 insure 参数为 `True` 时可自动确保输入正确。该功能是为了应对 selenium 原生输入在某些i情况下会失效的问题。但只能用于 input 元素且 `type` 为 `text` 的情况。 接收组合键的时候可接收 @@ -91,14 +91,14 @@ selenium 的 `Keys` 对象的值。组合键要放在一个 `tuple` 中传入。 !> **注意：**
`insure` 为 `True` 时不能用于接收组合键。 ?> **Tips:**
- 有些文本框可以接收回车代替点击按钮，可以直接在文本末尾加上`'\n'`。
- 非传入`tuple`时，会自动把非`str`转换为`str`。 -参数： +**参数：** -- vals：文本值或按键组合 -- clear：输入前是否清空文本框 -- insure：是否确保输入正确，不能用于输入组合键 -- timeout：尝试输入的超时时间，不指定则使用父页面的超时时间，只在 `insure_input` 参数为 `True` 时生效 +- `vals`：文本值或按键组合 +- `clear`：输入前是否清空文本框 +- `insure`：是否确保输入正确，不能用于输入组合键 +- `timeout`：尝试输入的超时时间，不指定则使用父页面的超时时间，只在 `insure_input` 参数为 `True` 时生效 -返回：`bool`类型，表示是否成功输入。`insure` 为 `False` 时始终返回 `True`。 +**返回：**`bool`类型，表示是否成功输入。`insure` 为 `False` 时始终返回 `True`。 ```python # 输入文本 @@ -116,47 +116,47 @@ ele.input((Keys.CONTROL, 'a'), insure=False) ele.input('D:\\test1.txt\nD:\\test2.txt') ``` -## clear() +## 📍 `clear()` 此方法用于清空元素文本，可使用确保清空的方式，若元素是不可编辑的，返回`None`。 -参数： +**参数：** -- insure：是否确保清空。为`True`则用`input()`确保值变成`''`，为`False`则用 selenium 元素`clear()`方法 +- `insure`：是否确保清空。为`True`则用`input()`确保值变成`''`，为`False`则用 selenium 元素`clear()`方法 -返回：`bool`，是否清空成功，不能清空的元素返回`None` +**返回：**`bool`，是否清空成功，不能清空的元素返回`None` ```python ele.clear() ``` -## run_script() +## 📍 `run_script()` 此方法用于对元素执行 js 代码，代码中用`arguments[0]`表示自己。 -参数： +**参数：** -- script：js 文本 -- *args：传入 js 的参数 +- `script`：js 文本 +- `*args`：传入 js 的参数 -返回：js 执行的结果 +**返回：** js 执行的结果 ```python # 用执行 js 的方式点击元素 ele.run_script('arguments[0].click()') ``` -## wait_ele() +## 📍 `wait_ele()` 此方法用于等待当前元素的某个下级元素到达某种状态。 调用此方法返回一个`ElementWaiter`对象，调用该对象方法实现各种方式的等待。 -参数： +**参数：** -- loc_or_ele：要等待的元素，可以是元素或定位符 -- timeout：等待超时时间，默认使用页面超时时间 +- `loc_or_ele`：要等待的元素，可以是元素或定位符 +- `timeout`：等待超时时间，默认使用页面超时时间 -方法： +**方法：** | 方法 | 参数说明 | 功能 | |:---------:|:----:|:------------:| @@ -178,111 +178,111 @@ ele2 = ele1.ele('#div1') ele1.wait_ele(ele2).hidden() ``` -## screenshot() +## 📍 `screenshot()` 此方法用于对元素进行截图。 如果是图片元素，会自动等待加载结束才截图。 此方法能自动获取能够使用的文件名，避免重名覆盖原有文件。并返回保存路径。 保存格式为 png，也可以返回图片的二进制文本。 -参数： +**参数：** -- path：图片保持路径 -- filename：图片文件名，不传入时以元素`tag`标签命名 -- as_bytes：是否已字节形式返回图片，为True时上面两个参数失效 +- `path`：图片保持路径 +- `filename`：图片文件名，不传入时以元素`tag`标签命名 +- `as_bytes`：是否已字节形式返回图片，为True时上面两个参数失效 -返回：图片完整路径或字节文本 +**返回：** 图片完整路径或字节文本 ```python path = ele.screenshot(r'D:\tmp', 'img1') # 保存到路径，文件名为img1.png bytes = ele.screenshot(as_bytes=True) # 返回截图二进制文本 ``` -## set_prop() +## 📍 `set_prop()` 此方法用于设置元素`property`属性。 -参数： +**参数：** -- prop： 属性名 -- value： 属性值 +- `prop`： 属性名 +- `value`： 属性值 -返回：`bool`，是否设置成功 +**返回：**`bool`，是否设置成功 ```python ele.set_prop('value', 'Hello world!') ``` -## set_attr() +## 📍 `set_attr()` 此方法用于设置元素`attribute`属性。 -参数： +**参数：** -- attr：属性名 -- value：属性值 +- `attr`：属性名 +- `value`：属性值 -返回：`bool`，是否设置成功 +**返回：**`bool`，是否设置成功 ```python ele.set_attr('href', 'http://www.gitee.com') ``` -## remove_attr() +## 📍 `remove_attr()` 此方法用于删除元素`attribute`属性。 -参数： +**参数：** -- attr：属性名 +- `attr`：属性名 -返回：`bool`，是否删除成功 +**返回：**`bool`，是否删除成功 ```python ele.remove_attr('href') ``` -## submit() +## 📍 `submit()` 此方法用于提交表单，若元素不在表单内，返回`None`，否则返回`True`。 -参数：无 +**参数：** 无 -返回：`True`或`None` +**返回：**`True`或`None` ```python ele.submit() ``` -## drag() +## 📍 `drag()` 此方法用于拖拽元素到相对于当前的一个新位置，可以设置速度，可以选择是否随机抖动。 -参数： +**参数：** -- x：x 变化值 -- y：y 变化值 -- speed：拖动的速度，传入 0 即瞬间到达 -- shake：是否随机抖动 +- `x`：x 变化值 +- `y`：y 变化值 +- `speed`：拖动的速度，传入 0 即瞬间到达 +- `shake`：是否随机抖动 -返回：None +**返回：**`None` ```python # 拖动当前元素到距离 50*50 的位置，速度为 100，不随机抖动 ele.drag(50, 50, 100, False) ``` -## drag_to() +## 📍 `drag_to()` 此方法用于拖拽元素到另一个元素上或一个坐标上。 -参数： +**参数：** -- ele_or_loc： 另一个元素或坐标元组，接收元素时坐标是元素中点的坐标。可接收 selenium 的`WebElement`或本库的`DriverElement` -- speed： 拖动的速度，传入 0 即瞬间到达 -- shake： 是否随机抖动 +- `ele_or_loc`： 另一个元素或坐标元组，接收元素时坐标是元素中点的坐标。可接收 selenium 的`WebElement`或本库的`DriverElement` +- `speed`： 拖动的速度，传入 0 即瞬间到达 +- `shake`： 是否随机抖动 -返回：None +**返回：**`None` ```python # 把 ele1 拖拽到 ele2 上 @@ -294,7 +294,7 @@ ele1.drag_to(ele2) ele1.drag_to((50, 50)) ``` -## scroll +## 📍 `scroll` 此属性用于以某种方式滚动元素中的滚动条。 调用此属性返回一个`Scroll`对象，调用该对象方法实现各种方式的滚动。 @@ -326,16 +326,16 @@ ele.scroll.down(200) ele.scroll.to_location(100, 300) ``` -## hover() +## 📍 `hover()` 此方法用于模拟鼠标悬停在元素上，可接受偏移量，偏移量相对于元素左上角坐标。不传入`x`或`y`值时悬停在元素中点。`x`和`y`值可接受负值。 -参数： +**参数：** -- x：相对元素左上角坐标的 x 轴偏移量 -- y：相对元素左上角坐标的 y 轴偏移量 +- `x`：相对元素左上角坐标的 x 轴偏移量 +- `y`：相对元素左上角坐标的 y 轴偏移量 -返回：`None` +**返回：**`None` ```python # 悬停在元素右上方 50*50 的位置 @@ -348,7 +348,7 @@ ele.hover(x=50) ele.hover() ``` -# `Select`类 +# ✔️ `Select`类 `select`元素的操作较为复杂，因此专门做了一个类用于处理它。每个`DriverElement`都有`select`属性，如果是`select`元素，该属性是一个`Select`类，否则该属性为`False`。 `select`元素要操作列表时，实际上是对这个`Select`对象进行操作。 @@ -359,9 +359,9 @@ ele.select ?> **Tips:**
网页操作中经常遇到动态变化的表单，这时需要等待列表项加载。`Select`类内置等待功能，默认为页面等待时间。 -## 属性 +## 📍 属性 -### is_multi +### 📎 `is_multi` 该属性表示当前`select`元素是否多选列表。 @@ -369,7 +369,7 @@ ele.select ele.select.is_multi ``` -### options +### 📎 `options` 该属性以列表形式返回当前`select`元素下所有列表项元素对象，这些对象是`DriverElement`。 @@ -377,7 +377,7 @@ ele.select.is_multi options = ele.select.options ``` -### selected_option +### 📎 `selected_option` 该属性返回第一个被选中的元素对象。 @@ -385,7 +385,7 @@ options = ele.select.options 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 ``` -## 方法 +## 📍 方法 -### select() +### 📎 `select()` 该方法用于选定下拉列表中子元素。 接收`int`类型时根据序号选择，接收`str`类型时根据文本选择。 接收`list`或`tuple`时同时选择多个项，多项可序号和文本混排。只能在多选列表使用。 Select 类的`__call__()`方法直接调用这个方法，因此可以直接`ele.select()`来替代这个方法。写法更直观。 -参数： +**参数：** -- text_or_index：根据文本或序号择选项，若允许多选，传入`list`或`tuple`可多选 -- timeout：等待列表项出现的时间 +- `text_or_index`：根据文本或序号择选项，若允许多选，传入`list`或`tuple`可多选 +- `timeout`：等待列表项出现的时间 -返回：是否选择成功 +**返回：** 是否选择成功 ```python # 根据文本选择下拉列表项，等待1秒 @@ -426,14 +426,14 @@ ele.select((0, 2)) ele.select(('text1', 2)) ``` -### select_by_value() +### 📎 `select_by_value()` -参数： +**参数：** -- value：`value`属性值，若允许多选，传入`list`或`tuple`可多选 -- timeout：等待列表项出现的时间 +- `value`：`value`属性值，若允许多选，传入`list`或`tuple`可多选 +- `timeout`：等待列表项出现的时间 -返回：是否选择成功 +**返回：** 是否选择成功 此方法用于根据`value`值选择项。当元素是多选列表时，可以接受`list`或`tuple`，同时选择多个项，可和序号混排。 @@ -445,16 +445,16 @@ ele.select.select_by_value('value1') ele.select.select_by_value(('value1', 2)) ``` -### deselect() +### 📎 `deselect()` 此方法用于取消选定下拉列表中子元素。当元素是多选列表时，可以接受`list`或`tuple`，同时取消选择多个项。 -参数： +**参数：** -- text_or_index：根据文本、值选或序号择选项，若允许多选，传入`list`或`tuple`可多选 -- timeout：等待列表项出现的时间 +- `text_or_index`：根据文本、值选或序号择选项，若允许多选，传入`list`或`tuple`可多选 +- `timeout`：等待列表项出现的时间 -返回：是否取消选择成功 +**返回：** 是否取消选择成功 ```python # 根据文本取消选择下拉列表项 @@ -473,16 +473,16 @@ ele.select.deselect((0, 1)) ele.select.deselect(('text1', 2)) ``` -### deselect_by_value() +### 📎 `deselect_by_value()` 此方法用于根据`value`值取消选择项。当元素是多选列表时，可以接受`list`或`tuple`，同时取消选择多个项，可和序号混排。 -参数： +**参数：** -- value：`value`属性值，若允许多选，传入`list`或`tuple`可取消多项 -- timeout：等待列表项出现的时间 +- `value`：`value`属性值，若允许多选，传入`list`或`tuple`可取消多项 +- `timeout`：等待列表项出现的时间 -返回：是否取消选择成功 +**返回：** 是否取消选择成功 ```python # 根据 value 值取消选择列表项 @@ -492,27 +492,27 @@ ele.select.deselect_by_value('value1') ele.select.deselect_by_value(('value1', 2)) ``` -## 多项列表独有功能 +## 📍 多项列表独有功能 -### clear() +### 📎 `clear()` 此方法用于清空多选列表选项。 -参数：无 +**参数：** 无 -返回：`None` +**返回：**`None` ```python ele.select.clear() ``` -### invert() +### 📎 `invert()` 此方法用于反选多选列表选项。 -参数：无 +**参数：** 无 -返回：`None` +**返回：**`None` ```python ele.select.invert() diff --git a/docs/MixPage使用方法/创建页面对象.md b/docs/MixPage使用方法/创建页面对象.md index 3be9ea3..2eedbce 100644 --- a/docs/MixPage使用方法/创建页面对象.md +++ b/docs/MixPage使用方法/创建页面对象.md @@ -3,22 +3,22 @@ 可以通过指定配置信息创建须要的页面对象，如无界面的浏览器、是否加载插件、是否接管已打开的浏览器、设置`headers`、设置代理等等。 这些配置信息，可以通过几种方式设置。配置的详细用法后文再讲。本节先了解创建页面对象的几种方式。 -# `MixPage`类 +# ✔️ `MixPage`类 `MixPage`页面对象封装了常用的网页操作，并实现在两种模式之间的切换。 `MixPage`须控制一个`Drission`对象并使用其中的`WebDriver`或`Session`对象来实现。对浏览器或网络连接的操作。如没有传入，`MixPage`会自己创建一个（使用传入的配置信息或从默认 ini 文件读取）。 -初始化参数： +**初始化参数：** -- mode：初始化时模式，`'d'`或`'s'`，默认为`'d'` -- drission：Drission 对象，不传入时会自动创建 -- timeout：超时时间，s 模式时为连接时间，d 模式时为查找元素、处理弹出框、输入文本等超时时间 -- driver_options：浏览器设置，没传入`drission`参数时会用这个设置新建`Drission`对象中的`WebDriver`对象，传入`False`则不创建 -- session_options：requests 设置，没传入`drission`参数时会用这个设置新建`Drission`对象中的`Session`对象，传入`False`则不创建 +- `mode`：初始化时模式，`'d'`或`'s'`，默认为`'d'` +- `drission`：Drission 对象，不传入时会自动创建 +- `timeout`：超时时间，s 模式时为连接时间，d 模式时为查找元素、处理弹出框、输入文本等超时时间 +- `driver_options`：浏览器设置，没传入`drission`参数时会用这个设置新建`Drission`对象中的`WebDriver`对象，传入`False`则不创建 +- `session_options`：requests 设置，没传入`drission`参数时会用这个设置新建`Drission`对象中的`Session`对象，传入`False`则不创建 !> **注意：**
有传入`drission`参数时，`driver_options`和`session_options`参数无效 -# 直接创建 +# ✔️ 直接创建 这种方式代码最简洁，程序会从配置文件中读取配置，自动生成页面对象。可以保持代码简洁。 在基本概念一节我们提到过，本库使用配置文件记录常用配置信息，也可以直接把配置写在代码里。 @@ -31,20 +31,20 @@ page = MixPage('d') page = MixPage('s') ``` -# 通过配置信息创建 +# ✔️ 通过配置信息创建 本库有两种管理配置信息的对象，分别是`DriverOptions`和`SessionOptions`，对应 d 模式和 s 模式的配置。 须要时，可以创建相应的配置对象进行设置。 -## `DriverOptions`类 +## 📍 `DriverOptions`类 `DriverOptions`用于管理创建浏览器时的配置，浏览器创建后再修改这个配置是没有效果的。 `DriverOptions`对象能实现链式操作。 -初始化参数： +**初始化参数：** -- read_file：是否从 ini 文件中读取配置信息 -- ini_path：ini 文件路径，为`None`则读取默认 ini 文件 +- `read_file`：是否从 ini 文件中读取配置信息 +- `ini_path`：ini 文件路径，为`None`则读取默认 ini 文件 ```python # 导入 DriverOptions @@ -56,14 +56,14 @@ do = DriverOptions().set_mute().set_no_imgs() page = MixPage(driver_options=do) ``` -## `SessionOptions`类 +## 📍 `SessionOptions`类 `SessionOptions`用于管理创建`Session`对象时的配置，内置了常用的配置，并能实现链式操作。详细使用方法见“启动配置”一节。 -初始化参数： +**初始化参数：** -- read_file：是否从 ini 文件中读取配置信息 -- ini_path：ini 文件路径，为`None`则读取默认 ini 文件 +- `read_file`：是否从 ini 文件中读取配置信息 +- `ini_path`：ini 文件路径，为`None`则读取默认 ini 文件 !>**注意：**
`Session`对象创建后再修改这个配置是没有效果的。 @@ -86,7 +86,7 @@ d 模式的配置和 s 模式的配置是可以同时使用的，不会互相影 page = MixPage(mode='s', session_options=so, driver_options=do) ``` -# 传入`Drission`对象创建 +# ✔️ 传入`Drission`对象创建 在入门指南的基本概念一节里，我们讲过`Drission`对象相当于驱动器的角色。事实上，上述两种方式，`MixPage`都会自动创建一个`Drission`对象用于管理与网站或浏览器的连接，我们当然也可以手动创建并传入`MixPage`。 `Drission`一般是不用手动创建的，要手动创建的时候，一般是用于i以下几种情况： @@ -95,16 +95,16 @@ page = MixPage(mode='s', session_options=so, driver_options=do) - 在不同`MixPage`间传递驱动器 - 与 selenium 或 requests 原生代码拼接，用于兼容这两者的代码 -## `Drission`类 +## 📍 `Drission`类 -初始化参数： +**初始化参数：** -- driver_or_options：`WebDriver`对象、`DriverOptions`对象或`Options`对象。传入`False`时自动创建一个空配置对象。 -- session_or_options：`Session`对象、`SessionOptions`对象、`Options`对象或设置字典。传入`False`时自动创建一个空配置对象。 -- ini_path：要使用的 ini 文件的路径 -- proxy：初始化时设置代理 +- `driver_or_options`：`WebDriver`对象、`DriverOptions`对象或`Options`对象。传入`False`时自动创建一个空配置对象。 +- `session_or_options`：`Session`对象、`SessionOptions`对象、`Options`对象或设置字典。传入`False`时自动创建一个空配置对象。 +- `ini_path`：要使用的 ini 文件的路径 +- `proxy`：初始化时设置代理 -## 使用其它 ini 文件创建 +## 📍 使用其它 ini 文件创建 ```python from DrissionPage import MixPage, Drission @@ -113,7 +113,7 @@ d = Drission(ini_path=r'./config1.ini') page = MixPage(drission=d) ``` -## 传递驱动器 +## 📍 传递驱动器 多页面对象间共用驱动器，如多个`MixPage`控制一个浏览器： @@ -125,7 +125,7 @@ d = page1.drission page2 = MixPage(drission=d) ``` -## 从 selenium 和 requests 代码传入 +## 📍 从 selenium 和 requests 代码传入 DrissionPage 的代码能和 selenium 及 requests 代码兼容，便于不同程序间的对接。 只需把`WebDriver`对象或`Session`传入`Drission`对象即可。 @@ -143,7 +143,7 @@ page = MixPage(drission=d) page.get('https://www.baidu.com') ``` -## 用配置信息创建 +## 📍 用配置信息创建 因为`MixPage`创建时能直接接收配置信息，所以这个方法基本不需要用到，写出来只是表示有这个功能。 @@ -157,7 +157,7 @@ d = Drission(driver_or_options=do, session_or_options=so) page = MixPage(drission=d) ``` -# 接管手动打开的浏览器 +# ✔️ 接管手动打开的浏览器 如果须要手动打开浏览器，手动操作后再接管，可以这样做： @@ -184,7 +184,7 @@ page = MixPage(driver_options=do) ?>**Tips：**
接管使用 bat 文件打开的浏览器也是一样做法做法。
接管浏览器时只有`local_port`、`debugger_address`、`driver_path`参数是有效的。 -# 多 Chrome 浏览器共存 +# ✔️ 多 Chrome 浏览器共存 如果想要同时操作多个 Chrome 浏览器，或者自己在使用 Chrome 上网，同时控制另外几个跑自动化，就须要给这些被程序控制的浏览器设置单独的端口和用户文件夹，否则会造成冲突。具体用`DriverOptions`对象进行设置，示例如下： @@ -223,19 +223,19 @@ page2 = MixPage(driver_options=do2) ?> **Tips：**
使用 bat 文件打开浏览器再接管操作是一样的。 -# 一些技巧 +# ✔️ 一些技巧 事实上，本库默认启动浏览器的方式是先通过程序在 9222（或用户指定的）端口运行一个浏览器进程，然后通过程序接管。这种做法有很多好处： -## 可重复使用的浏览器对象 +## 📍 可重复使用的浏览器对象 当程序运行完毕，浏览器不会主动关闭，下次再运行的时候可以直接在当前状态下继续运行。于是无须每次打开新的浏览器对象，无须从最开始步骤重新运行整个程序，一些前置条件（如登录）也无须每次运行，大大提高开发效率。 -## 简便的调试方式 +## 📍 简便的调试方式 通过重复使用浏览器对象，用户可以把浏览器页面调整到某个状态再用程序接管，对调试某个特定问题效率极高。比如有些通过很多步骤才能到达的页面，如果每次重新运行会花费大量时间，而将页面固定再由程序接管，测试各种细节非常方便快捷。 -## 一行代码传递登录状态到 requests +## 📍 一行代码传递登录状态到 requests 本库的一个特点是打通了浏览器和`requests`之间的登录状态，我们可以手动登录浏览器，再用程序接管，然后切换到 s 模式，这时 s 模式的`Session`对象即已活动浏览器的登录信息，无须用`requests` 处理登录过程，极大地简化了开发复杂程度。示例： diff --git a/docs/MixPage使用方法/启动配置/Chrome启动配置.md b/docs/MixPage使用方法/启动配置/Chrome启动配置.md deleted file mode 100644 index 1310406..0000000 --- a/docs/MixPage使用方法/启动配置/Chrome启动配置.md +++ /dev/null @@ -1,185 +0,0 @@ -为使浏览器设置更便利，本库扩展了`selenium.webdriver.chrome.options`的`Options`对象功能，创建了`DriverOptions`类，专门用于管理浏览器的启动配置。 - -!> **注意：**
-1、`DriverOptions`仅用于管理启动配置，浏览器启动后再修改无效。
-2、若设置了`local_port`或`debugger_address`且浏览器未启动，则只有`arguments`、`driver_path`、`chrome_path`参数生效。
-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) -``` - diff --git a/docs/MixPage使用方法/启动配置/使用配置文件.md b/docs/MixPage使用方法/启动配置/使用配置文件.md deleted file mode 100644 index d11271a..0000000 --- a/docs/MixPage使用方法/启动配置/使用配置文件.md +++ /dev/null @@ -1,265 +0,0 @@ -本库使用 ini 文件记录浏览器或`Session`对象的启动配置。便于配置复用，免于在代码中加入繁琐的配置信息。 -默认情况下，`MixPage`对象启动时自动加载文件中的配置信息。 -也可以在默认配置基础上用简单的方法再次修改，再保存到 ini 文件。 -也可以保存多个 ini 文件，按不同项目须要调用。 - -!> **注意：**
-ini 文件仅用于管理启动配置，浏览器或`Session`创建后再修改 ini 文件内容是没有效果的。
-如果是接管已打开的浏览器，这些设置也没有用。
-每次升级本库，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 文件中该部分内容。 - -!> **注意：**
-easy_set 方法仅用于设置 ini 文件，浏览器或 Session 创建后再调用没有效果的。
-如果是接管已打开的浏览器，这些设置也没有用。 - -## 简单示例 - -```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` diff --git a/docs/MixPage使用方法/对接selenium及requests代码.md b/docs/MixPage使用方法/对接selenium及requests代码.md index 0150f76..c87607c 100644 --- a/docs/MixPage使用方法/对接selenium及requests代码.md +++ b/docs/MixPage使用方法/对接selenium及requests代码.md @@ -1,7 +1,7 @@ DrissionPage 代码可无缝拼接 selenium 及 requests 代码。既可直接使用 selenium 的`WebDriver`对象，也可导出自身的`WebDriver`给 selenium 代码使用。requests 的 `Session`对象也可直接传递。便于已有项目的迁移。 -# selenium 转 DrissionPage +# ✔️ selenium 转 DrissionPage ```python from selenium import webdriver @@ -17,7 +17,7 @@ page = MixPage(drission=drission) print(page.title) ``` -# DrissionPage 转 selenium +# ✔️ DrissionPage 转 selenium ```python page = MixPage() @@ -31,9 +31,9 @@ print(driver.title) element = driver.find_element(By.XPATH, '//div') ``` -# requests 转 DrissionPage +# ✔️ requests 转 DrissionPage -``` python +```python from requests import Session session = requets.Session() @@ -45,7 +45,7 @@ page = MixPage('s', drission=drission) page.get('https://www.baidu.com') ``` -# DrissionPage 转 requests +# ✔️ DrissionPage 转 requests ```python from DrissionPage import MixPage diff --git a/docs/MixPage使用方法/打包程序.md b/docs/MixPage使用方法/打包程序.md deleted file mode 100644 index da248a6..0000000 --- a/docs/MixPage使用方法/打包程序.md +++ /dev/null @@ -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) -``` - -!> **注意**
这个时候`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` diff --git a/docs/MixPage使用方法/查找页面元素.md b/docs/MixPage使用方法/查找页面元素.md index c08ec9a..614382b 100644 --- a/docs/MixPage使用方法/查找页面元素.md +++ b/docs/MixPage使用方法/查找页面元素.md @@ -11,9 +11,9 @@ d 模式的元素还有专门用于处理 shadow dom 的`shadow_root`属性。获取到的元素可继续用这些方法获取后代元素，使用方法和普通元素一致。 -# 示例 +# ✔️ 示例 -## 简单示例 +## 📍 简单示例 ```html @@ -61,7 +61,7 @@ parent = p1.parent() div2 = p1.after(1, 'tag:div') ``` -## 实际示例 +## 📍 实际示例 复制此代码可直接运行查看结果。 @@ -93,17 +93,17 @@ IOT/物联网/边缘计算 # 查找元素方法 -## ele() +## 📍 `ele()` 此方法用于查找并返回第一个匹配的元素，d 模式下返回`DriverElement`，s 模式下返回`SessionElement`，用 xpath 获取元素属性时，直接返回属性文本。查找不到结果则返回`None`。 -参数： +**参数：** -- loc_or_str（元素对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串 -- loc_or_ele（页面对象拥有）：元素的定位信息，可以是元素对象，loc 元组，或查询字符串 -- timeout：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 +- `loc_or_str`（元素对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串 +- `loc_or_ele`（页面对象拥有）：元素的定位信息，可以是元素对象，loc 元组，或查询字符串 +- `timeout`：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 -返回：s 模式下返回`SessionElement`，d 模式下返回`DriverElement`，或用 xpath 获取到的属性值 +**返回：** s 模式下返回`SessionElement`，d 模式下返回`DriverElement`，或用 xpath 获取到的属性值 ```python # 在页面内查找元素 @@ -117,16 +117,16 @@ ele2 = ele1.ele('search text') class = ele1.ele('xpath://div/@class') ``` -## eles() +## 📍 `eles()` 此方法与`ele()`相似，但返回的是匹配到的所有元素组成的列表，用 xpath 获取元素属性时，返回属性文本组成的列表。 -参数： +**参数：** -- loc_or_str：元素的定位信息，可以是 loc 元组，或查询字符串 -- timeout：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 +- `loc_or_str`：元素的定位信息，可以是 loc 元组，或查询字符串 +- `timeout`：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 -返回：s 模式下返回`SessionElement`组成的列表，d 模式下返回`DriverElement`组成的列表，或用 xpath 获取到的属性值组成的列表 +**返回：** s 模式下返回`SessionElement`组成的列表，d 模式下返回`DriverElement`组成的列表，或用 xpath 获取到的属性值组成的列表 ```python # 获取 ele 元素内的所有 p 元素 @@ -135,7 +135,7 @@ p_eles = ele.eles('tag:p') print(p_eles[0]) ``` -## s_ele() +## 📍 `s_ele()` 此方法用于在一个元素下查找后代元素，以`SessionElement`形式返回结果（xpath 获取属性值时依然是返回`str`），也可以直接将一个元素或页面转换为`SessionElement`版本。 @@ -143,12 +143,12 @@ print(p_eles[0]) s 模式下这个方法和`ele()`是一样的。 -参数： +**参数：** -- loc_or_str（元素对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前元素的`SessionElemnet`版本 -- loc_or_ele（页面对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前页面的 `SessionElemnet`版本 +- `loc_or_str`（元素对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前元素的`SessionElemnet`版本 +- `loc_or_ele`（页面对象拥有）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前页面的 `SessionElemnet`版本 -返回：`SessionElement`，或用 xpath 获取到的属性值 +**返回：**`SessionElement`，或用 xpath 获取到的属性值 ```python # 获取元素或页面的的 SessionElement 版本 @@ -162,17 +162,17 @@ ele2 = ele1.s_ele('search text') ele = page.s_ele('search text') ``` -## s_eles() +## 📍 `s_eles()` 此方法与`s_ele()`相似，但返回的是匹配到的所有元素组成的列表，或属性值组成的列表。 -参数： +**参数：** -- loc_or_str：元素的定位信息，可以是 loc 元组，或查询字符串（必填） +- `loc_or_str`：元素的定位信息，可以是 loc 元组，或查询字符串（必填） -返回：`SessionElement`组成的列表，或用 xpath 获取到的属性值组成的列表 +**返回：**`SessionElement`组成的列表，或用 xpath 获取到的属性值组成的列表 -## active_ele +## 📍 `active_ele` 该属性返回当前页面焦点所在元素。d 模式独有。 @@ -180,7 +180,7 @@ ele = page.s_ele('search text') ele = page.active_ele ``` -## shadow_root +## 📍 `shadow_root` `DriverElement`元素除了以上方法和属性外，还有`shadow_root`属性，用于获取其内部的 shadow_root 元素。 该属性返回的是一个`ShadowRootElement`，类似于`DriverElement`，功能比`DriverElement`少。但也有`ele()`和`eles()`方法，可直接搜索其下的元素，返回 `DriverElement` @@ -202,17 +202,17 @@ ele1.click() **匹配模式** 指字符串是否完全匹配，有以下两种： -## `=` +## 📍 `=` 表示精确匹配，匹配完全符合的文本或属性。 -## `:` +## 📍 `:` 表示模糊匹配，匹配含有某个字符串的文本或属性。 **关键字** 是出现在定位语句最左边，用于指明该语句以哪种方式去查找元素，有以下这些： -## `#` +## 📍 `#` 表示`id`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。 @@ -224,7 +224,7 @@ ele1 = page.ele('#ele_id') ele2 = ele1.ele('#:ele_id') ``` -## `.` +## 📍 `.` 表示`class`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。 @@ -236,7 +236,7 @@ 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"]') ``` -## `@@` +## 📍 `@@` 表示某个属性，多属性匹配时使用，个数不限。还能匹配要忽略的元素，匹配文本时也和`@`不一样。 `@@`后跟 - 时，表示 not。如： @@ -293,7 +293,7 @@ ele2 = ele1.ele('@@-class') ele2 = ele1.ele('@@-name:ele_name') ``` -## `text` +## 📍 `text` 要匹配的文本，查询字符串如开头没有任何关键字，也表示根据传入的文本作模糊查找。 如果元素内有多个直接的文本节点，精确查找时可匹配所有文本节点拼成的字符串，模糊查找时可匹配每个文本节点。 @@ -315,7 +315,7 @@ ele2 = ele1.ele('some text') ele2 = page.ele('text:text:') ``` -## `text()` +## 📍 `text()` 作为查找属性时使用的文本关键字，必须与`@`或`@@`配合使用。 与`@`配合和与`@@`配合使用时，`text()`的意义是有差别的。 @@ -343,7 +343,7 @@ ele = page.ele('text:some text') ele = page.ele('@@text():some text') ``` -## `tag` +## 📍 `tag` 表示元素的标签，只在语句最前面且单独使用时生效，可与`@`或`@@`配合使用。`tag:`与`tag=`效果一致。 @@ -367,10 +367,9 @@ ele2 = ele1.ele('tag:div@text():text') ele2 = ele1.ele('tag:div@@text():text') ``` -?> **Tips:**
-注意， `tag:div@text():text` 和 `tag:div@@text():text` 是有区别的，前者只在`div`的直接文本节点搜索，后者搜索`div`的整个内部。 +?> **Tips:**
注意， `tag:div@text():text` 和 `tag:div@@text():text` 是有区别的，前者只在`div`的直接文本节点搜索，后者搜索`div`的整个内部。 -## `css` +## 📍 `css` 表示用 css selector 方式查找元素。`css:`与`css=`效果一致。 @@ -382,7 +381,7 @@ ele2 = ele1.ele('css:.div') ele2 = ele1.ele('css:>div') ``` -## `xpath` +## 📍 `xpath` 表示用 xpath 方式查找元素。`xpath:`与`xpath=`效果一致。 该方法支持完整的 xpath 语法，能使用 xpath 直接获取元素属性，selenium 不支持这种用法。 @@ -398,11 +397,10 @@ ele2 = ele1.ele('xpath://div') txt = ele1.ele('xpath://div/@class') ``` -?> **Tips:**
-查找元素的后代时，selenium 原生代码要求 xpath 前面必须加`.`，否则会变成在全个页面中查找。笔者觉得这个设计是画蛇添足，既然已经通过元素查找了，自然应该只查找这个元素内部的元素。所以，用 xpath +?> **Tips:**
查找元素的后代时，selenium 原生代码要求 xpath 前面必须加`.`，否则会变成在全个页面中查找。笔者觉得这个设计是画蛇添足，既然已经通过元素查找了，自然应该只查找这个元素内部的元素。所以，用 xpath 在元素下查找时，最前面`//`或`/`前面的`.`可以省略。 -## selenium 的 loc 元组 +## 📍 selenium 的 loc 元组 查找方法能直接接收 selenium 原生定位元组进行查找，s 模式下也支持这种写法。 @@ -418,7 +416,7 @@ loc2 = (By.XPATH, '//div[@class="ele_class"]' ele = page.ele(loc2) ``` -# 等待 +# ✔️ 等待 d 模式下所有查找元素操作都自带等待，默认为跟随元素所在页面`timeout`属性（默认 10 秒），也可以在每次查找时单独设置，单独设置的等待时间不会改变页面原来设置。 @@ -438,20 +436,20 @@ ele2 = ele1.ele('some text') ele2 = ele1.ele('some text', timeout=1) ``` -# DOM 内相对定位 +# ✔️ DOM 内相对定位 以下方法可以以某元素为基准，在 DOM 中按照条件获取其兄弟元素、祖先元素、文档前后元素。 除获取元素外，还能通过 xpath 获取任意节点内容，如文本节点、注释节点。这在处理元素和文本节点混排的时候非常有用。 -## parent() +## 📍 `parent()` 此方法获取当前元素某一级父元素，可指定筛选条件或层数。 -参数： +**参数：** -- level_or_loc：第几级父元素，或定位符 +- `level_or_loc`：第几级父元素，或定位符 -返回： +**返回：** 某层父元素 ```python # 获取 ele1 的第二层父元素 @@ -461,17 +459,17 @@ ele2 = ele1.parent(2) ele2 = ele1.parent('#id1') ``` -## next() +## 📍 `next()` 此方法返回当前元素后面的某一个兄弟元素，可指定筛选条件和第几个。 -参数： +**参数：** -- index：查询结果中的第几个 -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `index`：查询结果中的第几个 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素后面某个兄弟元素或节点文本 +**返回：** 本元素后面某个兄弟元素或节点文本 ```python # 获取 ele1 后面第一个兄弟元素 @@ -487,16 +485,16 @@ ele2 = ele1.next(3, 'tag:div') txt = ele1.next(1, 'xpath:text()') ``` -## nexts() +## 📍 `nexts()` 此方法返回后面全部符合条件的兄弟元素或节点组成的列表，可用查询语法筛选。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素前面符合条件的兄弟元素或节点文本组成的列表 +**返回：** 本元素前面符合条件的兄弟元素或节点文本组成的列表 ```python # 获取 ele1 后面所有兄弟元素 @@ -509,17 +507,17 @@ divs = ele1.nexts('tag:div') txts = ele1.nexts('xpath:text()') ``` -## prev() +## 📍 `prev()` 此方法返回当前元素前面的某一个兄弟元素，可指定筛选条件和第几个。 -参数： +**参数：** -- index：查询结果中的第几个 -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `index`：查询结果中的第几个 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素前面某个兄弟元素或节点文本 +**返回：** 本元素前面某个兄弟元素或节点文本 ```python # 获取 ele1 前面第一个兄弟元素 @@ -535,16 +533,16 @@ ele2 = ele1.prev(3, 'tag:div') txt = ele1.prev(1, 'xpath:text()') ``` -## prevs() +## 📍 `prevs()` 此方法返回前面全部符合条件的兄弟元素或节点组成的列表，可用查询语法筛选。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素前面符合条件的兄弟元素或节点文本组成的列表 +**返回：** 本元素前面符合条件的兄弟元素或节点文本组成的列表 ```python # 获取 ele1 前面所有兄弟元素 @@ -554,17 +552,17 @@ eles = ele1.prevs() divs = ele1.prevs('tag:div') ``` -## after() +## 📍 `after()` 此方法返回当前元素后面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 -参数： +**参数：** -- index：查询结果中的第几个 -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `index`：查询结果中的第几个 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素后面某个元素或节点 +**返回：** 本元素后面某个元素或节点 ```python # 获取 ele1 后面第 3 个元素 @@ -577,16 +575,16 @@ ele2 = ele1.after(3, 'tag:div') txt = ele1.after(1, 'xpath:text()') ``` -## afters() +## 📍 `afters()` 此方法返回后面符合条件的全部元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素后面符合条件的元素或节点组成的列表 +**返回：** 本元素后面符合条件的元素或节点组成的列表 ```python # 获取 ele1 后所有元素 @@ -596,17 +594,17 @@ eles = ele1.afters() divs = ele1.afters('tag:div') ``` -## before() +## 📍 `before()` 此方法返回当前元素前面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 -参数： +**参数：** -- index：查询结果中的第几个 -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `index`：查询结果中的第几个 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素前面某个元素或节点 +**返回：** 本元素前面某个元素或节点 ```python # 获取 ele1 前面第 3 个元素 @@ -619,16 +617,16 @@ ele2 = ele1.before(3, 'tag:div') txt = ele1.before(1, 'xpath:text()') ``` -## befores() +## 📍 `befores()` 此方法返回前面全部符合条件的元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素前面符合条件的元素或节点组成的列表 +**返回：** 本元素前面符合条件的元素或节点组成的列表 ```python # 获取 ele1 前面所有元素 @@ -638,22 +636,22 @@ eles = ele1.befores() divs = ele1.befores('tag:div') ``` -# 页面布局相对定位 +# ✔️ 页面布局相对定位 以下方法用于在页面上根据显示位置定位元素。只能有在 d 模式，selenium4 版本，且 driver 版本较新的情况下才能使用。 与上面通过 DOM 定位的方法不同，这些方法只能获取元素，不能获取节点。 获取多个元素时，元素由近到远排列。 -## left() +## 📍 `left()` 此方法返回当前元素左边的某一个元素，可指定筛选条件和第几个。 -参数： +**参数：** -- index：查询结果中的第几个 -- filter_loc：用于筛选元素的查询语法 +- `index`：查询结果中的第几个 +- `filter_loc`：用于筛选元素的查询语法 -返回：本元素左边的某个元素 +**返回：** 本元素左边的某个元素 ```python # 获取 ele1 左边第 3 个元素 @@ -663,15 +661,15 @@ ele2 = ele1.left(3) ele2 = ele1.left(3, 'tag:div') ``` -## lefts() +## 📍 `lefts()` 此方法返回左边全部符合条件的元素组成的列表，可用查询语法筛选。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 +- `filter_loc`：用于筛选元素的查询语法 -返回：本元素左边符合条件的元素组成的列表 +**返回：** 本元素左边符合条件的元素组成的列表 ```python # 获取 ele1 左边所有元素 @@ -681,16 +679,16 @@ eles = ele1.lefts() divs = ele1.lefts('tag:div') ``` -## right() +## 📍 `right()` 此方法返回当前元素左边的某一个元素，可指定筛选条件和第几个。 -参数： +**参数：** -- index：查询结果中的第几个 -- filter_loc：用于筛选元素的查询语法 +- `index`：查询结果中的第几个 +- `filter_loc`：用于筛选元素的查询语法 -返回：本元素左边的某个元素 +**返回：** 本元素左边的某个元素 ```python # 获取 ele1 左边第 3 个元素 @@ -700,15 +698,15 @@ ele2 = ele1.right(3) ele2 = ele1.right(3, 'tag:div') ``` -## rights() +## 📍 `rights()` 此方法返回右边全部符合条件的元素组成的列表，可用查询语法筛选。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 +- `filter_loc`：用于筛选元素的查询语法 -返回：本元素右边符合条件的元素组成的列表 +**返回：** 本元素右边符合条件的元素组成的列表 ```python # 获取 ele1 右边所有元素 @@ -718,16 +716,16 @@ eles = ele1.rights() divs = ele1.rights('tag:div') ``` -## below() +## 📍 `below()` 此方法返回当前元素下边的某一个元素，可指定筛选条件和第几个。 -参数： +**参数：** -- index：查询结果中的第几个 -- filter_loc：用于筛选元素的查询语法 +- `index`：查询结果中的第几个 +- `filter_loc`：用于筛选元素的查询语法 -返回：本元素下边的某个元素 +**返回：** 本元素下边的某个元素 ```python # 获取 ele1 下边第 3 个元素 @@ -737,15 +735,15 @@ ele2 = ele1.below(3) ele2 = ele1.below(3, 'tag:div') ``` -## belows() +## 📍 `belows()` 此方法返回下边全部符合条件的元素组成的列表，可用查询语法筛选。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 +- `filter_loc`：用于筛选元素的查询语法 -返回：本元素下边符合条件的元素组成的列表 +**返回：** 本元素下边符合条件的元素组成的列表 ```python # 获取 ele1 下边所有元素 @@ -755,16 +753,16 @@ eles = ele1.belows() divs = ele1.belows('tag:div') ``` -## above() +## 📍 `above()` 此方法返回当前元素上边的某一个元素，可指定筛选条件和第几个。 -参数： +**参数：** -- index：查询结果中的第几个 -- filter_loc：用于筛选元素的查询语法 +- `index`：查询结果中的第几个 +- `filter_loc`：用于筛选元素的查询语法 -返回：本元素上边的某个元素 +**返回：** 本元素上边的某个元素 ```python # 获取 ele1 上边第 3 个元素 @@ -774,15 +772,15 @@ ele2 = ele1.above(3) ele2 = ele1.above(3, 'tag:div') ``` -## aboves() +## 📍 `aboves()` 此方法返回上边全部符合条件的元素组成的列表，可用查询语法筛选。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 +- `filter_loc`：用于筛选元素的查询语法 -返回：本元素上边符合条件的元素组成的列表 +**返回：** 本元素上边符合条件的元素组成的列表 ```python # 获取 ele1 上边所有元素 @@ -792,16 +790,16 @@ eles = ele1.aboves() divs = ele1.aboves('tag:div') ``` -## near() +## 📍 `near()` 此方法返回最接近当前元素的某一个元素，可指定筛选条件和第几个。 -参数： +**参数：** -- index：查询结果中的第几个 -- filter_loc：用于筛选元素的查询语法 +- `index`：查询结果中的第几个 +- `filter_loc`：用于筛选元素的查询语法 -返回：最接近本元素的某个元素 +**返回：** 最接近本元素的某个元素 ```python # 获取最接近 ele1 的第 3 个元素 @@ -811,15 +809,15 @@ ele2 = ele1.near(3) ele2 = ele1.near(3, 'tag:div') ``` -## nears() +## 📍 `nears()` 此方法返回该元素附近全部符合条件的元素组成的列表，可用查询语法筛选。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 +- `filter_loc`：用于筛选元素的查询语法 -返回：本元素附近符合条件的元素组成的列表 +**返回：** 本元素附近符合条件的元素组成的列表 ```python # 获取 ele1 附近所有元素 @@ -829,13 +827,12 @@ eles = ele1.nears() divs = ele1.nears('tag:div') ``` -# `ShadowRootElement`相关查找 +# ✔️ `ShadowRootElement`相关查找 本库把 shadow-root 也作为元素对象看待，是为`ShadowRootElement`对象。对`ShadowRootElement`对象可与普通元素一样查找下级元素和 DOM 内相对定位，但不能用页面布局相对定位。 对`ShadowRootElement`对象进行相对定位时，把它看作其父对象内部的第一个对象，其余定位逻辑与普通对象一致。 -!> **注意：**
-如果`ShadowRootElement`元素的下级元素中有其它`ShadowRootElement`元素，那这些下级`ShadowRootElement` +!> **注意：**
如果`ShadowRootElement`元素的下级元素中有其它`ShadowRootElement`元素，那这些下级`ShadowRootElement` 元素内部是无法直接通过定位语句查找到的，只能先定位到其父元素，再用`shadow-root`属性获取。 ```python @@ -855,7 +852,7 @@ eles = sr_ele.nexts('tag:div') sr_ele2 = sr_ele.ele('tag:div').shadow_root ``` -# 简化写法 +# ✔️ 简化写法 为进一步精简代码，对语法进行了精简 @@ -881,16 +878,16 @@ ele2 = ele1('x://div[@class="ele_class"]') 简化写法对应列表 -| 原写法 | 简化写法 | -|:-----------:|:----:| -| text | tx | -| text() | tx() | -| tag | t | -| xpath | x | -| css | c | -| shadow_root | sr | +| 原写法 | 简化写法 | +|:-------------:|:------:| +| `text` | `tx` | +| `text()` | `tx()` | +| `tag` | `t` | +| `xpath` | `x` | +| `css` | `c` | +| `shadow_root` | `sr` | -# Tips +# ✔️ Tips - 从一个`DriverElement`元素获取到的`SessionElement`版本，依然能够使用相对定位方法定位祖先或兄弟元素。 - `SessionElement`和`SessionPage`的`ele()`和`eles()`方法也有`timeout`参数，但它是不生效的，仅用于保持与 d 模式元素书写一致，便于无差别的调用。 diff --git a/docs/MixPage使用方法/获取元素信息.md b/docs/MixPage使用方法/获取元素信息.md index 193a3df..12baffb 100644 --- a/docs/MixPage使用方法/获取元素信息.md +++ b/docs/MixPage使用方法/获取元素信息.md @@ -5,7 +5,7 @@ `ShadowRootElement`由于是 shadow dom 元素，属性比较其余两种少，下文单独介绍。 -# 示例 +# ✔️ 示例 ```python from DrissionPage import MixPage @@ -29,7 +29,7 @@ a 车载应用 https://gitee.com/explore/vehicle """ ``` -# 两种模式共有属性 +# ✔️ 两种模式共有属性 假设`ele`为以下`div`元素的对象： @@ -40,7 +40,7 @@ a 车载应用 https://gitee.com/explore/vehicle ``` -## html +## 📍 `html` 此属性返回元素的`outerHTML`文本。 @@ -54,7 +54,7 @@ html = ele.html """ ``` -## inner_html +## 📍 `inner_html` 此属性返回元素的`innerHTML`文本。 @@ -67,7 +67,7 @@ Hello World! """ ``` -## tag +## 📍 `tag` 此属性返回元素的标签名。 @@ -76,7 +76,7 @@ tag = ele.tag # 返回：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：是否只返回文本节点 +- `text_node_only`：是否只返回文本节点 -返回：文本列表 +**返回：** 文本列表 ```python texts = ele.texts() @@ -122,14 +122,14 @@ print(e.texts()) # 输出：['Hello World!'] ``` -## comments +## 📍 `comments` ```python comments = ele.comments # 返回：[] ``` -## attrs +## 📍 `attrs` 此属性以字典形式返回元素所有属性及值。 @@ -138,23 +138,23 @@ attrs = ele.attrs # 返回：{'id': 'div1'} ``` -## attr() +## 📍 `attr()` 此方法返回元素某个`attribute`属性值。它接收一个字符串参数`attr`，返回该属性值文本，无该属性时返回`None`。 此属性返回的`src`、`href`属性为已补充完整的路径。`text`属性为已格式化文本，`innerText`属性为未格式化文本。 -参数： +**参数：** -- attr：属性名称 +- `attr`：属性名称 -返回：属性值文本 +**返回：** 属性值文本 ```python ele_id = ele.attr('id') # 返回：div1 ``` -## link +## 📍 `link` 此方法返回元素的 href 属性或 src 属性，没有这两个属性则返回`None`。 @@ -169,7 +169,7 @@ link = a_ele.link # 返回：http://www.baidu.com ``` -## page +## 📍 `page` 此属性返回元素所在的页面对象。 @@ -180,7 +180,7 @@ link = a_ele.link page = ele.page ``` -## inner_ele +## 📍 `inner_ele` 此属性返回被当前元素包装的对应模式原本的元素对象。 d 模式包装的是一个 selenium 的`WebElement`对象，s 模式包装的是一个 lxml 的`HtmlElement`对象。 @@ -193,7 +193,7 @@ web_ele = ele.inner_ele web_ele.find_element(By.ID, 'ele_id').click() ``` -## xpath +## 📍 `xpath` 此属性返回当前元素在页面中 xpath 的绝对路径。 @@ -202,7 +202,7 @@ xpath = ele.xpath # 返回：/html/body/div ``` -## css_path +## 📍 `css_path` 此属性返回当前元素在页面中 css selector 的绝对路径。 @@ -211,21 +211,21 @@ css = ele.css_path # 返回：:nth-child(1)>:nth-child(1)>:nth-child(1) ``` -## is_valid() +## 📍 `is_valid()` 此方法返回当前元素是否可用。`SessionElement`始终返回`True`，`DriverElement`视乎元素是否还在 DOM 内返回布尔值。 -参数：无 +**参数：** 无 -返回：`bool`类型 +**返回：**`bool`类型 ```python is_valid = ele.is_valid() ``` -# DriverElement 独有属性 +# ✔️ DriverElement 独有属性 -## size +## 📍 `size` 此属性以字典形式返回元素的大小。 @@ -234,7 +234,7 @@ size = ele.size # 返回：{'height': 50, 'width': 50} ``` -## location +## 📍 `location` 此属性以字典形式返回元素坐标。 @@ -243,7 +243,7 @@ loc = ele.location # 返回：{'x': 50, 'y': 50} ``` -## pseudo_before +## 📍 `pseudo_before` 此属性以文本形式返回当前元素的`::before`伪元素内容。 @@ -251,7 +251,7 @@ loc = ele.location before_txt = ele.pseudo_before ``` -## pseudo_after +## 📍 `pseudo_after` 此属性以文本形式返回当前元素的`::after`伪元素内容。 @@ -259,16 +259,16 @@ before_txt = ele.pseudo_before after_txt = ele.pseudo_after ``` -## style() +## 📍 `style()` 该方法返回元素 css 样式属性值，可获取伪元素的属性。它有两个参数，`style`参数输入样式属性名称，`pseudo_ele`参数输入伪元素名称，省略则获取普通元素的 css 样式属性。 -参数： +**参数：** -- style：样式名称 -- pseudo_ele: 伪元素名称（如有） +- `style`：样式名称 +- `pseudo_ele`：伪元素名称（如有） -返回：样式属性值 +**返回：** 样式属性值 ```python # 获取 css 属性的 color 值 @@ -278,92 +278,92 @@ prop = ele.style('color') prop = ele.style('content', 'after') ``` -## prop() +## 📍 `prop()` 此方法返回`property`属性值。它接收一个字符串参数，返回该参数的属性值。 -参数： +**参数：** -- prop：属性名称 +- `prop`：属性名称 -返回：属性值 +**返回：** 属性值 ```python prop = ele.prop('value') ``` -## select +## 📍 `select` 此属性返回 `select` 元素用于处理下拉列表的 Select 类（“[元素操作](元素操作.md)”章节说明），非下拉列表元素返回`False`。 -## is_selected() +## 📍 `is_selected()` 此方法以布尔值返回元素是否选中。 -参数：无 +**参数：** 无 -返回：布尔值 +**返回：** `bool` ```python selected = ele.is_selected() ``` -## is_enabled() +## 📍 `is_enabled()` 此方法以布尔值返回元素是否可用。 -参数：无 +**参数：** 无 -返回：布尔值 +**返回：**`bool` ```python enable = ele.is_enabled() ``` -## is_displayed() +## 📍 `is_displayed()` 此方法以布尔值返回元素是否可见。 -参数：无 +**参数：** 无 -返回：布尔值 +**返回：**`bool` ```python displayed = ele.is_displayed() ``` -# `ShadowRootElement`属性与方法 +# ✔️ `ShadowRootElement`属性与方法 本库把 shadow dom 的`root`看作一个元素处理，可以获取属性，也可以执行其下级的查找，但其属性比较少。有如下这些： -## tag +## 📍 `tag` 此属性返回元素标签名，即`'shadow-root'`。 -## html +## 📍 `html` 此属性返回`shadow_root`的 html 文本，由`` 标签包裹。 -## inner_html +## 📍 `inner_html` 此属性返回`shadow_root`内部的 html 文本。 -## page +## 📍 `page` 此属性返回元素所在页面对象。 -## inner_ele +## 📍 `inner_ele` 此属性返回对象中保存的`shadow-root`元素。 -## parent_ele +## 📍 `parent_ele` 这是`ShadowRootElement`独有的属性，返回它所依附的普通元素对象。 -## is_enabled() +## 📍 `is_enabled()` 与`DriverElement`一致。 -## is_valid() +## 📍 `is_valid()` 与`DriverElement`一致。 diff --git a/docs/MixPage使用方法/获取网页信息.md b/docs/MixPage使用方法/获取网页信息.md index 2498d03..1613dd7 100644 --- a/docs/MixPage使用方法/获取网页信息.md +++ b/docs/MixPage使用方法/获取网页信息.md @@ -1,42 +1,42 @@ 本节介绍获取页面对象各种信息的属性和方法。 -# 两种模式共有属性 +# ✔️ 两种模式共有属性 -## url +## 📍 `url` 此属性返回当前访问的 url。 -## mode +## 📍 `mode` 此属性返回当前页面对象的模式，`'s'`或`'d'`。 -## drission +## 📍 `drission` 此属性返回当前页面对象使用的`Drission`对象。 -## driver +## 📍 `driver` 此属性返回当前页面对象使用的`WebDriver`对象。访问时会自动切换到 d 模式。 -## session +## 📍 `session` 此属性返回当前页面对象使用的`Session`对象。访问时不会切换模式。 -## cookies +## 📍 `cookies` 此属性以`dict`方式返回当前页面所使用的 cookies。 d 模式只返回当前标签页的 cookies，s 模式则只返回当前访问的 url 的`cookies`。 -## get_cookies() +## 📍 `get_cookies()` 此方法获取 cookies 并以 cookie 组成的`list`形式返回。 -参数： +**参数：** -- as_dict：是否以字典方式返回，为`False`返回`cookie`组成的`list` -- all_domains：是否返回所有域的`cookies`，只有 s 模式下生效 +- `as_dict`：是否以字典方式返回，为`False`返回`cookie`组成的`list` +- `all_domains`：是否返回所有域的`cookies`，只有 s 模式下生效 -返回：`cookies`信息 +**返回：**`cookies`信息 ```python from DrissionPage import MixPage @@ -58,15 +58,15 @@ for i in p.get_cookies(as_dict=False, all_domains=True): ...... ``` -## html +## 📍 `html` 此属性返回当前页面 html 文本。 -## title +## 📍 `title` 此属性返回当前页面`title`文本。 -## timeout +## 📍 `timeout` s 模式下，此属性代表网络请求超时时间。 d 模式下，此属性为元素查找、点击、处理提示框等操作的超时时间。 @@ -80,7 +80,7 @@ page = MixPage(timeout=5) page.timeout = 20 ``` -## retry_times +## 📍 `retry_times` 此参数为网络连接失败时的重试次数。默认为 3，可对其赋值。 @@ -89,7 +89,7 @@ page.timeout = 20 page.retry_times = 5 ``` -## retry_interval +## 📍 `retry_interval` 此参数为网络连接失败时的重试等待间隔秒数。默认为 2，可对其赋值。 @@ -98,15 +98,15 @@ page.retry_times = 5 page.retry_interval = 1.5 ``` -## url_available +## 📍 `url_available` 此属性以布尔值返回当前链接是否可用。 s 模式下根据`Response`对象的`status_code`判断。 d 模式根据`check_page()`方法返回值判断。 -# s 模式独有属性 +# ✔️ s 模式独有属性 -## response +## 📍 `response` 此属性为 s 模式请求网站后生成的`Response`对象，本库没实现的功能可直接获取此属性调用 requests 库的原生功能。 @@ -116,15 +116,15 @@ r = page.response print(r.status_code) ``` -## json +## 📍 `json` 此属性把请求内容解析成 json。 比如请求接口时，返回内容是 json 格式，那就可以用这个属性获取。 事实上，用 html 属性获取也是可以的，不过 html 属性没有对文本进行解析。 -# d 模式独有属性 +# ✔️ d 模式独有属性 -## timeouts +## 📍 `timeouts` 此属性以字典方式返回三种超时时间，selenium 4 以上版本可用。 `'implicit'`用于元素查找、点击重试、输入文本重试、处理弹出框重试等； @@ -141,41 +141,41 @@ print(page.timeouts) {'implicit': 10, 'pageLoad': 30.0, 'script': 30.0} ``` -## tabs_count +## 📍 `tabs_count` 此属性返回当前浏览器标签页数量。 -## tab_handles +## 📍 `tab_handles` 此属性以列表形式返回当前浏览器所有标签页的 handle。 !> **注意：** 以下情况会导致获取到的顺序与视觉效果不一致：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 -## current_tab_index +## 📍 `current_tab_index` 此属性返回当前标签页的序号。 !> **注意：**
以下情况会导致获取到的排序号与视觉效果不一致：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 -## current_tab_handle +## 📍 `current_tab_handle` 此属性返回当前标签页的 handle。 -## active_ele +## 📍 `active_ele` 此属性返回当前页面上焦点所在元素。类型为`DriverElement`。 -## wait_obj +## 📍 `wait_obj` 此属性返回当前页面对象用于等待的对象。 -## chrome_downloading() +## 📍 `chrome_downloading()` 此方法返回浏览器下载中的文件列表。 -参数： +**参数：** -- path: 下载文件夹路径，默认从配置信息读取 +- `path:` 下载文件夹路径，默认从配置信息读取 -返回：下载中的文件列表 +**返回：** 下载中的文件列表 diff --git a/docs/MixPage使用方法/访问网页.md b/docs/MixPage使用方法/访问网页.md index 80edb2c..6b5192e 100644 --- a/docs/MixPage使用方法/访问网页.md +++ b/docs/MixPage使用方法/访问网页.md @@ -1,23 +1,23 @@ 操作页面前通常要先跳转到目标 url（接管现有浏览器除外），本库访问网页主要支持`get()`和`post()`两种方式，还支持自动重试。 -# get() +# ✔️ `get()` 该方法在 d 模式和 s 模式下都可用，用于跳转到一个网址。 当连接失败时，程序默认重试 3 次，每次间隔 2 秒，也可以通过参数设置重试次数和间隔。 在 s 模式下，可传入连接参数，语法与 requests 的`get()`方法一致。 方法返回是否连接成功的布尔值，s 模式下根据`Response`对象的`status_code`参数决定，d 模式下根据浏览器的状态，还可以通过重写`check_page()`方法实现自定义检查方式。 -参数： +**参数：** -- url：目标 url -- show_errmsg：是否显示和抛出异常，默认不抛出，连接错误会返回`None` -- retry：重试次数，与页面对象的设置一致，默认 3 次 -- interval：重试间隔（秒），与页面对象的设置一致，默认 2 秒 -- **kwargs：连接参数，s 模式专用，与 requests 的使用方法一致 +- `url`：目标 url +- `show_errmsg`：是否显示和抛出异常，默认不抛出，连接错误会返回`None` +- `retry`：重试次数，与页面对象的设置一致，默认 3 次 +- `interval`：重试间隔（秒），与页面对象的设置一致，默认 2 秒 +- `**kwargs`：连接参数，s 模式专用，与 requests 的使用方法一致 -返回：`bool`类型，表示是否连接成功，d 模式下如返回`None`表示不确定 +**返回：**`bool`类型，表示是否连接成功，d 模式下如返回`None`表示不确定 -## d 模式 +## 📍 d 模式 ```python from DrissionPage import MixPage @@ -26,7 +26,7 @@ page = MixPage('d') page.get('https://www.baidu.com') ``` -## s 模式 +## 📍 s 模式 s 模式的`**kwargs`参数与 requests 中该参数使用方法一致，但有一个特点，如果该参数中设置了某一项（如`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) ``` -# post() +# ✔️ `post()` 此方法是用 post 方式请求页面。大致用法与`get()`一致，但增加一个`data`参数。 此方法只有 s 模式拥有，调用时，页面对象会自动切换到 s 模式。 -参数： +**参数：** -- url：目标 url -- data：提交的数据，可以是`dict`或`str`类型 -- show_errmsg：是否显示和抛出异常，默认不抛出，连接错误会返回 None -- retry：重试次数，与页面对象的设置一致，默认 3 次 -- interval：重试间隔（秒），与页面对象的设置一致，默认 2 秒 -- **kwargs：连接参数，s 模式专用 +- `url`：目标 url +- `data`：提交的数据，可以是`dict`或`str`类型 +- `show_errmsg`：是否显示和抛出异常，默认不抛出，连接错误会返回 None +- `retry`：重试次数，与页面对象的设置一致，默认 3 次 +- `interval`：重试间隔（秒），与页面对象的设置一致，默认 2 秒 +- `**kwargs`：连接参数，s 模式专用 ?> **Tips:**
虽然参数里没有`json`参数，但也和 requests 一样可以对`json`参数传值。 @@ -91,7 +91,7 @@ page.post(url, json='xxx') page.post(url, json={'xxx': 'xxx'}) ``` -# 其它请求方式 +# ✔️ 其它请求方式 本库只针对常用的 get 和 post 方式作了优化，但也可以通过提取页面对象内的`Session`对象以原生 requests 代码方式执行其它请求方式。当然，它们工作在 s 模式。 diff --git a/docs/MixPage使用方法/页面操作.md b/docs/MixPage使用方法/页面操作.md index a927a77..c4da87f 100644 --- a/docs/MixPage使用方法/页面操作.md +++ b/docs/MixPage使用方法/页面操作.md @@ -1,28 +1,24 @@ 本节介绍页面对象可以使用的方法，有些方法是两种模式共有的，有些只有某种模式可以使用。当调用独有方法时，会自动切换到该模式。如调用`post()`方法时，会先切换到 s 模式，并同步登录信息。 -# 两种模式共有的方法 +# ✔️ 两种模式共有的方法 -## get() +## 📍 `get()` -此方法用于跳转到一个 url，详细用法见“[使用方法 -> 访问网页](使用方法/访问网页.md)”章节。 +此方法用于跳转到一个 url，详细用法见“访问网页”章节。 -## ele()、eles()、s_ele()、s_eles() - -这些方法用于在页面中查找元素，详细用法见“[使用方法 -> 查找页面元素](使用方法/查找页面元素)”章节。 - -## change_mode() +## 📍 `change_mode()` 此方法用于转换`MixPage`对象的模式。 切换后默认在目标模式重新跳转到原模式所在 url。 !> **注意：**
s 模式转 d 模式时，若浏览器当前网址域名和 s 模式不一样，必定会跳转。 -参数： +**参数：** -- mode：目标模式字符串，`'s'`或`'d'`，默认转换到另一种 -- go：转换后是否跳转到原模式所在 url +- `mode`：目标模式字符串，`'s'`或`'d'`，默认转换到另一种 +- `go`：转换后是否跳转到原模式所在 url -返回：`None` +**返回：**`None` ```python from DrissionPage import MixPage @@ -60,106 +56,106 @@ print('登录后title：', page.title) 登录后title： 个人资料 - 码云 Gitee.com ``` -## set_cookies() +## 📍 `set_cookies()` 此方法用于设置`cookies`。 可以接收`CookieJar`、`list`、`tuple`、`str`、`dict`格式的`cookies`。 -参数： +**参数：** -- cookies：`cookies`信息 -- refresh：设置`cookies`后是否刷新页面 +- `cookies`：`cookies`信息 +- `refresh`：设置`cookies`后是否刷新页面 -返回：`None` +**返回：**`None` ```python cookies = {'name': 'abc'} page.set_cookies(cookies) ``` -## cookies_to_session() +## 📍 `cookies_to_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`对象。 -参数： +**参数：** -- url：指定 url，默认用当前 url +- `url`：指定 url，默认用当前 url -返回：`None` +**返回：**`None` -## download() +## 📍 `download()` -此方法用于下载文件，详细用法见“[使用方法 -> 下载文件](下载文件.md)”章节。 +此方法用于下载文件，详细用法见“下载文件”章节。 -## close_driver() +## 📍 `close_driver()` 此方法用于关闭`WebDriver`对象和浏览器。 -参数：无 +**参数：** 无 -返回：`None` +**返回：**`None` -## close_session() +## 📍 `close_session()` 此方法用于关闭`Session`对象。 -参数：无 +**参数：** 无 -返回：`None` +**返回：**`None` -# s 模式独有方法 +# ✔️ s 模式独有方法 -## post() +## 📍 `post()` -此方法用于以 post 方式访问 url，具体用法见“[使用方法 -> 访问网页](访问网页.md)”章节。 +此方法用于以 post 方式访问 url，具体用法见“访问网页”章节。 -# d 模式独有方法 +# ✔️ d 模式独有方法 -## hide_browser() +## 📍 `hide_browser()` 此方法用于隐藏浏览器进程窗口，非最小化，任务栏上也可隐藏。 但若操作过程中有新增标签页，浏览器会重新出现。 只支持 Windows 系统，且只有设置了`local_port`或`debugger_address`时生效。 -参数：无 +**参数：** 无 -返回：`None` +**返回：**`None` -## show_browser() +## 📍 `show_browser()` 此方法用于显示被隐藏的浏览器进程。 只支持 Windows 系统，且只有设置了`local_port`或`debugger_address`时生效。 -参数：无 +**参数：** 无 -返回：`None` +**返回：**`None` -## wait_ele() +## 📍 `wait_ele()` 此方法用于等待元素到达某种状态。 调用此方法返回一个`ElementWaiter`对象，调用该对象方法实现各种方式的等待。 -参数： +**参数：** -- loc_or_ele：要等待的元素，可以是元素或定位符 -- timeout：等待超时时间，默认使用页面超时时间 +- `loc_or_ele`：要等待的元素，可以是元素或定位符 +- `timeout`：等待超时时间，默认使用页面超时时间 -方法： +**方法：** -| 方法 | 参数说明 | 功能 | -|:---------:|:----:|:------------:| -| display() | 无 | 等待元素从 DOM 显示 | -| hidden() | 无 | 等待元素从 DOM 隐藏 | -| delete() | 无 | 等待元素从 DOM 删除 | +| 方法 | 参数说明 | 功能 | +|:-----------:|:----:|:------------:| +| `display()` | 无 | 等待元素从 DOM 显示 | +| `hidden()` | 无 | 等待元素从 DOM 隐藏 | +| `delete()` | 无 | 等待元素从 DOM 删除 | 这些方法返回布尔值，代表是否等待成功。 @@ -175,148 +171,148 @@ ele = page.ele('#div1') paeg.wait_ele(ele).hidden() ``` -## run_script() +## 📍 `run_script()` 此方法用于执行 js 脚本。 -参数： +**参数：** -- script：js 脚本文本 -- *args：传入的参数 +- `script`：js 脚本文本 +- `*args`：传入的参数 -返回：脚本执行结果 +**返回：** 脚本执行结果 ```python # 执行 js 脚本显示弹出框显示 Hello world! page.run_script('alert(arguments[0]+arguments[1])', 'Hello', ' world!') ``` -## run_async_script() +## 📍 `run_async_script()` 此方法用于以异步方式执行 js 脚本。 -参数： +**参数：** -- script：js 脚本文本 -- *args：传入的参数 +- `script`：js 脚本文本 +- `*args`：传入的参数 -返回：脚本执行结果 +**返回：** 脚本执行结果 -## run_cdp() +## 📍 `run_cdp()` 此方法用于执行 Chrome DevTools Protocol 语句。cdp 用法详见[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)。 -参数： +**参数：** -- cmd：协议项目方法 +- `cmd`：协议项目方法 -- **cmd_args：项目参数 +- `**cmd_args`：项目参数 -返回：该语句返回的值 +**返回：** 该语句返回的值 ```python # 停止页面加载 page.run_cdp('Page.stopLoading') ``` -## set_timeouts() +## 📍 `set_timeouts()` 此方法用于设置三种超时时间，selenium 4 以上版本生效。 -参数： +**参数：** -- implicit：查找元素超时时间 -- pageLoad：页面加载超时时间 -- script：脚本运行超时时间 +- `implicit`：查找元素超时时间 +- `pageLoad`：页面加载超时时间 +- `script`：脚本运行超时时间 -返回：`None` +**返回：**`None` -## set_ua_to_tab() +## 📍 `set_ua_to_tab()` 此方法用于为当前 tab 设置 user agent，只在当前 tab 有效。 -参数： +**参数：** -- ua：user agent字符串 +- `ua`：user agent字符串 -返回：None +**返回：**`None` -## get_session_storage() +## 📍 `get_session_storage()` 此方法用于获取 sessionStorage 信息，可获取全部或单个项。 -参数： +**参数：** -- item：要获取的项，不设置则返回全部 +- `item`：要获取的项，不设置则返回全部 -返回：sessionStorage 一个或所有项内容 +**返回：** sessionStorage 一个或所有项内容 -## get_local_storage() +## 📍 `get_local_storage()` 此方法用于获取 localStorage 信息，可获取全部或单个项。 -参数： +**参数：** -- item：要获取的项，不设置则返回全部 +- `item`：要获取的项，不设置则返回全部 -返回：localStorage 一个或所有项内容 +**返回：** localStorage 一个或所有项内容 -## set_session_storage() +## 📍 `set_session_storage()` 此方法用于设置或删除某项 sessionStorage 信息。 -参数： +**参数：** -- item：要设置的项 +- `item`：要设置的项 -- value：项的值，设置为False时，删除该项 +- `value`：项的值，设置为False时，删除该项 -返回：`None` +**返回：**`None` -## set_local_storage() +## 📍 `set_local_storage()` 此方法用于设置或删除某项 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`。 调用此属性返回一个`ToFrame`对象，调用该对象的方法实现焦点转移。 这些方法返回值为当前页面对象，可实现下一步的链式操作。 -| 方法 | 参数说明 | 功能 | -|:---------------:|:-------:|:----------------:| -| main() | 无 | 切换到顶层框架 | -| parent(level) | 第几层上级框架 | 切换到上级框架，可指定多层 | -| by_id(id) | id 属性 | 切换到`id`为该参数的框架 | -| by_name(name) | name 属性 | 切换到`name`为该参数的框架 | -| by_index(index) | 序号 | 切换到页面第几个框架，0 开始 | -| by_loc(loc) | 定位符 | 切换到定位符所指框架 | -| by_ele(ele) | 框架元素 | 传入框架元素，切换到该框架 | +| 方法 | 参数说明 | 功能 | +|:-----------------:|:-------:|:----------------:| +| `main()` | 无 | 切换到顶层框架 | +| `parent(level)` | 第几层上级框架 | 切换到上级框架，可指定多层 | +| `by_id(id)` | id 属性 | 切换到`id`为该参数的框架 | +| `by_name(name)` | name 属性 | 切换到`name`为该参数的框架 | +| `by_index(index)` | 序号 | 切换到页面第几个框架，0 开始 | +| `by_loc(loc)` | 定位符 | 切换到定位符所指框架 | +| `by_ele(ele)` | 框架元素 | 传入框架元素，切换到该框架 | ```python # 切换到主框架 @@ -362,18 +358,17 @@ iframe = page.ele('tag:iframe') page.to_frame(iframe) ``` -!> **注意：**
-新版本删除了`to_frame('main')`和`to_frame('parent')`的用法。
请改用`page.to_frame.main()`和`page.to_frame.parent()`的写法。 +!> **注意：**
新版本删除了`to_frame('main')`和`to_frame('parent')`的用法。
请改用`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` !> **注意：**
以下情况会导致获取到的排序号与视觉效果不一致：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 @@ -385,31 +380,31 @@ page.to_tab(0) page.to_tab('xxxxxxxxxxxxxxxxxxxx') ``` -## create_tab() +## 📍 `create_tab()` 此方法用于新建并定位到一个标签页,该标签页在最后面。可指定跳转到一个 url。 -参数： +**参数：** -- url：新标签页跳转到的 url +- `url`：新标签页跳转到的 url -返回：`None` +**返回：**`None` ```python page.create_tab('http://www.baidu.com') ``` -## close_tabs() +## 📍 `close_tabs()` 此方法用于关闭指定的标签页，标签页可以是序号或 handle 值，可关闭多个。默认关闭当前的。 !> **注意：**
以下情况会导致获取到的排序号与视觉效果不一致，不能按序号关闭：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 -参数： +**参数：** -- num_or_handles：要保留的标签页序号或 handle，可传入 list 或 tuple，为None时关闭当前页 +- `num_or_handles`：要保留的标签页序号或 handle，可传入 list 或 tuple，为None时关闭当前页 -返回：`None` +**返回：**`None` ```python # 关闭当前标签页 @@ -419,17 +414,17 @@ page.close_tabs() page.close_tabs((0, 2)) ``` -## close_other_tabs() +## 📍 `close_other_tabs()` 此方法用于关闭指定标签页以外的标签页，标签页可以是序号或 handle 值，可保留多个。默认保留当前的。 !> **注意：**
以下情况会导致获取到的排序号与视觉效果不一致，不能按序号关闭：1、自动化过程中手动点击标签页；2、浏览器被接管时已打开一个以上标签页。 -参数： +**参数：** -- num_or_handles：要保留的标签页序号或 handle，可传入`list`或`tuple`，为`None`时关闭当前页 +- `num_or_handles`：要保留的标签页序号或 handle，可传入`list`或`tuple`，为`None`时关闭当前页 -返回：`None` +**返回：**`None` ```python # 关闭除当前标签页外的所有标签页 @@ -443,23 +438,23 @@ reserve_list = ('aaaaa', 'bbbbb') page.close_other_tabs(reserve_list) ``` -## scroll +## 📍 `scroll` 此属性用于以某种方式滚动页面。 调用此属性返回一个`Scroll`对象，调用该对象方法实现各种方式的滚动。 -| 方法 | 参数说明 | 功能 | -|:-----------------:|:------:|:----------------:| -| to_top() | 无 | 滚动到顶端，水平位置不变 | -| to_bottom() | 无 | 滚动到底端，水平位置不变 | -| to_half() | 无 | 滚动到垂直中间位置，水平位置不变 | -| to_rightmost() | 无 | 滚动到最右边，垂直位置不变 | -| to_leftmost() | 无 | 滚动到最左边，垂直位置不变 | -| to_location(x, y) | 滚动条坐标值 | 滚动到指定位置 | -| up(pixel) | 滚动的像素 | 向上滚动若干像素，水平位置不变 | -| down(pixel) | 滚动的像素 | 向下滚动若干像素，水平位置不变 | -| right(pixel) | 滚动的像素 | 向左滚动若干像素，垂直位置不变 | -| left(pixel) | 滚动的像素 | 向右滚动若干像素，垂直位置不变 | +| 方法 | 参数说明 | 功能 | +|:-------------------:|:------:|:----------------:| +| `to_top()` | 无 | 滚动到顶端，水平位置不变 | +| `to_bottom()` | 无 | 滚动到底端，水平位置不变 | +| `to_half()` | 无 | 滚动到垂直中间位置，水平位置不变 | +| `to_rightmost()` | 无 | 滚动到最右边，垂直位置不变 | +| `to_leftmost()` | 无 | 滚动到最左边，垂直位置不变 | +| `to_location(x, y)` | 滚动条坐标值 | 滚动到指定位置 | +| `up(pixel)` | 滚动的像素 | 向上滚动若干像素，水平位置不变 | +| `down(pixel)` | 滚动的像素 | 向下滚动若干像素，水平位置不变 | +| `right(pixel)` | 滚动的像素 | 向左滚动若干像素，垂直位置不变 | +| `left(pixel)` | 滚动的像素 | 向右滚动若干像素，垂直位置不变 | ```python # 页面滚动到底部 @@ -475,15 +470,15 @@ page.scroll.down(200) page.scroll.to_location(100, 300) ``` -## scroll_to_see() +## 📍 `scroll_to_see()` 此方法用于滚动页面直到元素可见。 -参数： +**参数：** -- loc_or_ele：元素的定位信息，可以是元素、定位符 +- `loc_or_ele`：元素的定位信息，可以是元素、定位符 -返回：`None` +**返回：**`None` ```python # 滚动到某个已获取到的元素 @@ -497,68 +492,68 @@ page.scroll_to_see('tag: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 格式。 此方法能够自动处理文件重命名的情况，给新文件后面增加序号。 也可以返回图片的二进制文本。 -参数： +**参数：** -- path：图片保存路径 -- filename：图片文件名，可不写后缀，不传入时以页面 title 命名 -- as_bytes：是否已字节形式返回图片，为True时上面两个参数失效 +- `path`：图片保存路径 +- `filename`：图片文件名，可不写后缀，不传入时以页面 title 命名 +- `as_bytes`：是否已字节形式返回图片，为True时上面两个参数失效 -返回：图片完整路径或字节文本 +**返回：** 图片完整路径或字节文本 ```python path = page.screenshot(r'D:\tmp', 'img1') # 保存到路径，文件名为img1.png bytes = page.screenshot(as_bytes=True) # 返回截图二进制文本 ``` -## set_window_size() +## 📍 `set_window_size()` 此方法用于设置浏览器窗口大小。 默认最大化，任一参数为 0 最小化。 -参数： +**参数：** -- height：浏览器窗口高度 -- width：浏览器窗口宽度 +- `height`：浏览器窗口高度 +- `width`：浏览器窗口宽度 -返回：None +**返回：**`None` ```python # 窗口最大化 @@ -571,19 +566,19 @@ page.set_window_size(0) page.set_window_size(800, 600) ``` -## process_alert() +## 📍 `process_alert()` 此方法 用于处理提示框。 它能够设置等待时间，等待提示框出现才进行处理，若超时没等到提示框，返回`None`。 它可只获取提示框文本而不处理提示框。 -参数： +**参数：** -- ok：`True`表示确认，`False`表示取消，其它值不会按按钮但依然返回文本值 -- send：处理 prompt 提示框时可输入文本 -- timeout：等待提示框出现的超时时间 +- `ok`：`True`表示确认，`False`表示取消，其它值不会按按钮但依然返回文本值 +- `send`：处理 prompt 提示框时可输入文本 +- `timeout`：等待提示框出现的超时时间 -返回：提示框内容文本，未等到提示框则返回`None` +**返回：** 提示框内容文本，未等到提示框则返回`None` ```python # 确认提示框并获取提示框文本 @@ -599,7 +594,7 @@ paeg.process_alert(True, 'some text') txt = page.process_alert(None) ``` -## check_page() +## 📍 `check_page()` 此方法用于检查页面是否符合预期，它默认返回`None`，须由子类实现其功能。 用于 POM 模式时，可派生各种页面子类，从而实现检查页面的功能。 diff --git a/docs/README.md b/docs/README.md index 8f5571b..fbdb2c0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -96,4 +96,4 @@ DrissionPage，即 driver 和 session 组合而成的 page。 如果本项目对您有所帮助，不妨请作者我喝杯咖啡 ：） -![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/code.jpg) +![](imgs/code.jpg) diff --git a/docs/Tips大集合.md b/docs/Tips大集合.md deleted file mode 100644 index a70baef..0000000 --- a/docs/Tips大集合.md +++ /dev/null @@ -1,26 +0,0 @@ -## 全局 - -- 切换模式时会自动复制`cookies`到目标模式，并在目标模式下重新访问当前网址，可在参数中禁止自动访问。 -- 访问网址时如遇到异常，会自动重试 3 次，也可在对象属性或连接参数里设置重试次数和间隔时间。d 模式这个功能要重载了`check_page()`方法才有效。 -- 获取到的文本会自动替换` `为空格。 -- 可以在元素下直接使用`>`以 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 时程序会自动检测该端口，如为空，则自动在该端口启动一个浏览器进程并接入。程序完毕该浏览器不自动关闭，以便后续使用。 \ No newline at end of file diff --git a/docs/WebPage使用方法/3.10动作链.md b/docs/WebPage使用方法/3.10动作链.md index 8d801c2..c85c5bc 100644 --- a/docs/WebPage使用方法/3.10动作链.md +++ b/docs/WebPage使用方法/3.10动作链.md @@ -99,30 +99,118 @@ ac.up(50) # 鼠标向上移动 50 像素 **返回：**`ActionChains`对象自己 -# ✔ 点击鼠标 +# ✔ 鼠标按键 ## 📍 `click()` +此方法用于单击鼠标左键，单击前可先移动到元素上。 + +**参数：** + +- `on_ele`：`ChromiumElement`元素 + +**返回：**`ActionChains`对象自己 + ## 📍 `r_click()` +此方法用于单击鼠标右键，单击前可先移动到元素上。 + +**参数：** + +- `on_ele`：`ChromiumElement`元素 + +**返回：**`ActionChains`对象自己 + ## 📍 `hold()` +此方法用于按住鼠标左键不放，按住前可先移动到元素上。 + +**参数：** + +- `on_ele`：`ChromiumElement`元素 + +**返回：**`ActionChains`对象自己 + ## 📍 `release()` +此方法用于释放鼠标左键，释放前可先移动到元素上。 + +**参数：** + +- `on_ele`：`ChromiumElement`元素 + +**返回：**`ActionChains`对象自己 + # ✔ 滚动滚轮 ## 📍 `scroll()` +此方法用于滚动鼠标滚轮，滚动前可先移动到元素上。 + +**参数：** + +- `delta_x`：滚轮变化值 x +- `delta_y`：滚轮变化值 y +- `on_ele`：`ChromiumElement`元素 + +**返回：**`ActionChains`对象自己 + # ✔ 键盘按键 ## 📍 `key_down()` +此方法用于按下键盘按键。 + +**参数：** + +- `key`：按键键值，特殊字符见 Keys + +**返回：**`ActionChains`对象自己 + +```python +from DrissionPage.keys import Keys + +ac.key_down(Keys.CTRL) # 按下 ctrl 键 +``` + ## 📍 `key_up()` +此方法用于提起键盘按键。 + +**参数：** + +- `key`：按键键值，特殊字符见 Keys + +**返回：**`ActionChains`对象自己 + # ✔ 等待 ## 📍 `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') +``` + diff --git a/docs/WebPage使用方法/3.3查找元素.md b/docs/WebPage使用方法/3.3查找元素.md index 962ed61..2b1a44d 100644 --- a/docs/WebPage使用方法/3.3查找元素.md +++ b/docs/WebPage使用方法/3.3查找元素.md @@ -105,13 +105,13 @@ d 模式下返回`ChromiumElement`对象，s 模式下返回`SessionElement`对 在元素下查找子元素时，还可以用 xpath 获取元素属性，直接返回属性文本。 页面对象和元素对象的`ele()`方法参数名称稍有不同，但用法一样。 -参数： +**参数：** -- loc_or_str（元素对象）：元素的定位信息，可以是 loc 元组，或查询字符串 -- loc_or_ele（页面对象）：元素的定位信息，可以是元素对象，loc 元组，或查询字符串 -- timeout：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 +- `loc_or_str`（元素对象）：元素的定位信息，可以是 loc 元组，或查询字符串 +- `loc_or_ele`（页面对象）：元素的定位信息，可以是元素对象，loc 元组，或查询字符串 +- `timeout`：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 -返回：s 模式下返回`SessionElement`，d 模式下返回`ChromiumElement`；或用 xpath 获取到的属性值 +**返回：** s 模式下返回`SessionElement`，d 模式下返回`ChromiumElement`；或用 xpath 获取到的属性值 ```python from DrissionPage import WebPage @@ -134,12 +134,12 @@ ele_class = ele1.ele('xpath://div/@class') 此方法与`ele()`相似，但返回的是匹配到的所有元素组成的列表，用 xpath 获取元素属性时，返回属性文本组成的列表。 -参数： +**参数：** -- loc_or_str：元素的定位信息，可以是 loc 元组，或查询字符串 -- timeout：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 +- `loc_or_str`：元素的定位信息，可以是 loc 元组，或查询字符串 +- `timeout`：查找元素超时时间，默认与元素所在页面等待时间一致，s 模式下无效 -返回：s 模式下返回`SessionElement`组成的列表，d 模式下返回`ChromiumElement`组成的列表；或用 xpath 获取到的属性值组成的列表 +**返回：** s 模式下返回`SessionElement`组成的列表，d 模式下返回`ChromiumElement`组成的列表；或用 xpath 获取到的属性值组成的列表 ```python # 获取 ele 元素内的所有 p 元素 @@ -167,12 +167,12 @@ s 模式下，所有元素本身就是静态元素，d 模式下，用`s_ele()` s 模式下这个方法和`ele()`是一样的。 -参数： +**参数：** -- loc_or_str（元素对象）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前元素的`SessionElemnet`版本 -- loc_or_ele（页面对象）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前页面的 `SessionElemnet`版本 +- `loc_or_str`（元素对象）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前元素的`SessionElemnet`版本 +- `loc_or_ele`（页面对象）：元素的定位信息，可以是 loc 元组，或查询字符串。为`None`时直接返回当前页面的 `SessionElemnet`版本 -返回：`SessionElement`，或用 xpath 获取到的属性值 +**返回：**`SessionElement`，或用 xpath 获取到的属性值 !>**注意：**
页面对象和元素对象的`s_ele()`方法不能搜索到在 frame 里的元素，页面对象的静态版本也不能搜索 frame 里的元素。要使用 frame 里元素的静态版本，可先获取该元素，再转换。而使用`ChromiumFrame`对象，则可以直接用`s_ele()`查找元素，这在后面章节再讲述。 @@ -205,11 +205,11 @@ ele4 = s_ele.ele('search text') 此方法与`s_ele()`相似，但返回的是匹配到的所有元素组成的列表，或属性值组成的列表。 -参数： +**参数：** -- loc_or_str：元素的定位信息，可以是 loc 元组，或查询字符串（必填） +- `loc_or_str`：元素的定位信息，可以是 loc 元组，或查询字符串（必填） -返回：`SessionElement`组成的列表，或用 xpath 获取到的属性值组成的列表 +**返回：**`SessionElement`组成的列表，或用 xpath 获取到的属性值组成的列表 ```python from DrissionPage import WebPage @@ -248,17 +248,17 @@ ele1.click() **匹配模式** 指字符串是否完全匹配，有以下两种： -## 📍 精确匹配符`=` +## 📍 精确匹配符 `=` 表示精确匹配，匹配完全符合的文本或属性。 -## 📍 模糊匹配符`:` +## 📍 模糊匹配符 `:` 表示模糊匹配，匹配含有某个字符串的文本或属性。 **关键字** 是出现在定位语句最左边，用于指明该语句以哪种方式去查找元素，有以下这些： -## 📍 id 匹配符`#` +## 📍 id 匹配符 `#` 表示`id`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。 @@ -270,7 +270,7 @@ ele1 = page.ele('#ele_id') ele2 = ele1.ele('#:ele_id') ``` -## 📍 class 匹配符`.` +## 📍 class 匹配符 `.` 表示`class`属性，只在语句最前面且单独使用时生效，可配合`=`或`:`。 @@ -310,7 +310,7 @@ ele2 = ele1.ele('@email=abc@def.com') ele2 = ele1.ele('css:div[abc\@def="v"]') ``` -## 📍 多属性匹配符`@@` +## 📍 多属性匹配符 `@@` 表示某个属性，多属性匹配时使用，个数不限。还能匹配要忽略的元素，匹配文本时也和`@`不一样。 `@@`后跟 - 时，表示 not。如： @@ -338,7 +338,7 @@ ele2 = ele1.ele('@@-class') ele2 = ele1.ele('@@-name:ele_name') ``` -## 📍 文本匹配符`text` +## 📍 文本匹配符 `text` 要匹配的文本，查询字符串如开头没有任何关键字，也表示根据传入的文本作模糊查找。 如果元素内有多个直接的文本节点，精确查找时可匹配所有文本节点拼成的字符串，模糊查找时可匹配每个文本节点。 @@ -360,12 +360,9 @@ ele2 = ele1.ele('some text') ele2 = page.ele('text:text:') ``` -## 📍 文本匹配符`text()` +## 📍 文本匹配符 `text()` 作为查找属性时使用的文本关键字，必须与`@`或`@@`配合使用。 -与`@`配合和与`@@`配合使用时，`text()`的意义是有差别的。 - -`@text()`表示在元素的直接子文本节点中匹配，且多个节点不能合并匹配。 `@@text()`表示在元素内部所有文本中匹配，且会把元素内部所有文本拼成一个总字符串再进行匹配，因此可以模糊匹配元素里面任意文本。 ```python # 查找文本为 some text 的元素 @@ -388,7 +385,11 @@ ele = page.ele('text:some text') ele = page.ele('@@text():some text') ``` -## 📍 类型匹配符`tag` +须要注意的是，`'text=xxxx'`与`'@text()=xxxx'`使用上是有细微差别的。 + +`text=`表示在元素的直接子文本节点中匹配，`@text()=`会忽略一些文本标签，在整个元素的内容里匹配。 + +## 📍 类型匹配符 `tag` 表示元素的标签，只在语句最前面且单独使用时生效，可与`@`或`@@`配合使用。`tag:`与`tag=`效果一致。 @@ -412,10 +413,9 @@ ele2 = ele1.ele('tag:div@text():text') ele2 = ele1.ele('tag:div@@text():text') ``` -?> **Tips:**
-注意， `tag:div@text():text` 和 `tag:div@@text():text` 是有区别的，前者只在`div`的直接文本节点搜索，后者搜索`div`的整个内部。 +?> **Tips:**
注意， `tag:div@text():text` 和 `tag:div@@text():text` 是有区别的，前者只在`div`的直接文本节点搜索，后者搜索`div`的整个内部。 -## 📍 css selector 匹配符`css` +## 📍 css selector 匹配符 `css` 表示用 css selector 方式查找元素。`css:`与`css=`效果一致。 @@ -427,7 +427,7 @@ ele2 = ele1.ele('css:.div') ele2 = ele1.ele('css:>div') ``` -## 📍 xpath 匹配符`xpath` +## 📍 xpath 匹配符 `xpath` 表示用 xpath 方式查找元素。`xpath:`与`xpath=`效果一致。 该方法支持完整的 xpath 语法，能使用 xpath 直接获取元素属性，selenium 不支持这种用法。 @@ -498,13 +498,13 @@ ele2 = ele1.ele('some text', timeout=1) - `loc_or_ele`：要等待的元素，可以是元素或定位符 - `timeout`：等待超时时间，默认使用页面超时时间 -方法： +**方法：** -| 方法 | 参数 | 功能 | -| --------- | --- | ------------ | -| display() | 无 | 等待元素从 DOM 显示 | -| hidden() | 无 | 等待元素从 DOM 隐藏 | -| delete() | 无 | 等待元素从 DOM 删除 | +| 方法 | 参数 | 功能 | +| ----------- | --- | ------------ | +| `display()` | 无 | 等待元素从 DOM 显示 | +| `hidden()` | 无 | 等待元素从 DOM 隐藏 | +| `delete()` | 无 | 等待元素从 DOM 删除 | **返回：** 这些方法返回布尔值，代表是否等待成功。 @@ -529,11 +529,11 @@ ele1.wait_ele(ele2).hidden() `parent()`方法获取当前元素某一级父元素，可指定筛选条件或层数。 -参数： +**参数：** -- level_or_loc：第几级父元素，或定位符 +- `level_or_loc`：第几级父元素，或定位符 -返回： +**返回：** 某层父级元素 ```python # 获取 ele1 的第二层父元素 @@ -547,13 +547,13 @@ ele2 = ele1.parent('#id1') `next()`方法返回当前元素后面的某一个同级元素，可指定筛选条件和第几个。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- index：查询结果中的第几个 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `index`：查询结果中的第几个 +- `timeout`：查找元素的超时时间 -返回：本元素后面某个兄弟元素或节点文本 +**返回：** 本元素后面某个兄弟元素或节点文本 ```python # 获取 ele1 后面第一个兄弟元素 @@ -573,12 +573,12 @@ txt = ele1.next('xpath:text()', 1) `nexts()`方法返回当前元素后面全部符合条件的同级元素或节点组成的列表，可用查询语法筛选。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素前面符合条件的兄弟元素或节点文本组成的列表 +**返回：** 本元素前面符合条件的兄弟元素或节点文本组成的列表 ```python # 获取 ele1 后面所有兄弟元素 @@ -595,13 +595,13 @@ txts = ele1.nexts('xpath:text()') `prev()`方法返回当前元素前面的某一个同级元素，可指定筛选条件和第几个。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- index：查询结果中的第几个 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `index`：查询结果中的第几个 +- `timeout`：查找元素的超时时间 -返回：本元素前面某个兄弟元素或节点文本 +**返回：** 本元素前面某个兄弟元素或节点文本 ```python # 获取 ele1 前面第一个兄弟元素 @@ -621,12 +621,12 @@ txt = ele1.prev(1, 'xpath:text()') `prevs()`方法返回当前元素前面全部符合条件的同级元素或节点组成的列表，可用查询语法筛选。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素前面符合条件的兄弟元素或节点文本组成的列表 +**返回：** 本元素前面符合条件的兄弟元素或节点文本组成的列表 ```python # 获取 ele1 前面所有兄弟元素 @@ -640,13 +640,13 @@ divs = ele1.prevs('tag:div') `after()`方法返回当前元素后面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- index：查询结果中的第几个 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `index`：查询结果中的第几个 +- `timeout`：查找元素的超时时间 -返回：本元素后面某个元素或节点 +**返回：** 本元素后面某个元素或节点 ```python # 获取 ele1 后面第 3 个元素 @@ -663,12 +663,12 @@ txt = ele1.after('xpath:text()', 1) `afters()`方法返回当前元素后面符合条件的全部元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素后面符合条件的元素或节点组成的列表 +**返回：** 本元素后面符合条件的元素或节点组成的列表 ```python # 获取 ele1 后所有元素 @@ -682,13 +682,13 @@ divs = ele1.afters('tag:div') `before()`方法返回当前元素前面的某一个元素，可指定筛选条件和第几个。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- index：查询结果中的第几个 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `index`：查询结果中的第几个 +- `timeout`：查找元素的超时时间 -返回：本元素前面某个元素或节点 +**返回：** 本元素前面某个元素或节点 ```python # 获取 ele1 前面第 3 个元素 @@ -705,12 +705,12 @@ txt = ele1.before('xpath:text()', 1) `befores()`方法返回当前元素前面全部符合条件的元素或节点组成的列表，可用查询语法筛选。这个方法查找范围不局限在兄弟元素间，而是整个 DOM 文档。 -参数： +**参数：** -- filter_loc：用于筛选元素的查询语法 -- timeout：查找元素的超时时间 +- `filter_loc`：用于筛选元素的查询语法 +- `timeout`：查找元素的超时时间 -返回：本元素前面符合条件的元素或节点组成的列表 +**返回：** 本元素前面符合条件的元素或节点组成的列表 ```python # 获取 ele1 前面所有元素 @@ -814,14 +814,14 @@ ele2 = ele1('x://div[@class="ele_class"]') 简化写法对应列表 -| 原写法 | 简化写法 | -|:-----------:|:----:| -| text | tx | -| text() | tx() | -| tag | t | -| xpath | x | -| css | c | -| shadow_root | sr | +| 原写法 | 简化写法 | +|:-------------:|:------:| +| `text` | `tx` | +| `text()` | `tx()` | +| `tag` | `t` | +| `xpath` | `x` | +| `css` | `c` | +| `shadow_root` | `sr` | # ✔️ Tips diff --git a/docs/_navbar.md b/docs/_navbar.md index b15f502..24717e7 100644 --- a/docs/_navbar.md +++ b/docs/_navbar.md @@ -1,5 +1,2 @@ * [DataRecorder](https://gitee.com/g1879/DataRecorder) -* [ListPage](https://gitee.com/g1879/ListPage) -* [DownloadKit](https://gitee.com/g1879/DownloadKit) * [FlowViewer](http://g1879.gitee.io/flowviewer) -* [Demos](https://gitee.com/g1879/DrissionPage-demos) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index aafb44e..b0b9a10 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -10,6 +10,7 @@ * [🌿 模式切换](入门指南\特性演示\模式切换.md) * [🌿 获取并打印元素属性](入门指南\特性演示\获取并打印元素属性.md) * [🌿 下载文件](入门指南\特性演示\下载文件.md) + * [💖 2.4 贴心设计](入门指南\贴心设计.md) * [🛠 3 WebPage 使用方法](#) @@ -33,29 +34,35 @@ * [🔨 4.5 元素操作](MixPage使用方法\元素操作.md) * [🔨 4.6 获取网页信息](MixPage使用方法\获取网页信息.md) * [🔨 4.7 页面操作](MixPage使用方法\页面操作.md) - * [🔨 4.8 启动配置](#) - * [🔧 概述](MixPage使用方法\启动配置\概述.md) - * [🔧 Chrome 启动配置](MixPage使用方法\启动配置\Chrome启动配置.md) - * [🔧 Session 启动配置](MixPage使用方法\启动配置\Session启动配置.md) - * [🔧 使用配置文件](MixPage使用方法\启动配置\使用配置文件.md) - * [🔨 4.9 下载文件](MixPage使用方法\下载文件.md) - * [🔨 4.10 监听浏览器网络数据](MixPage使用方法\监听浏览器网络数据.md) - * [🔨 4.11 cookies 的使用](MixPage使用方法\cookies的使用.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) + * [🔨 4.8 下载文件](MixPage使用方法\下载文件.md) + * [🔨 4.9 监听浏览器网络数据](MixPage使用方法\监听浏览器网络数据.md) + * [🔨 4.10 cookies 的使用](MixPage使用方法\cookies的使用.md) + * [🔨 4.11 Drission 对象](MixPage使用方法\Drission对象.md) + * [🔨 4.12 对接 selenium 及 requests 代码](MixPage使用方法\对接selenium及requests代码.md) + * [🔨 4.13 使用其它系统或浏览器](MixPage使用方法\使用其它系统或浏览器.md) + * [🔨 4.14 DriverPage 和 SessionPage](MixPage使用方法\DriverPage和SessionPage.md) + * [🔨 4.15 打包程序](MixPage使用方法\打包程序.md) -* [💖 5 实用示例](#) +* [🛠 5 启动配置](#) - * [🧡 自动登录码云](实用示例\自动登录码云.md) - * [🧡 获取各国疫情排名](实用示例\获取各国疫情排名.md) - * [🧡 下载星巴克产品图片](实用示例\下载星巴克产品图片.md) - * [🧡 同时操作多个浏览器](实用示例\同时操作多个浏览器.md) + * [🔨 5.1 概述](启动配置\概述.md) + * [🔨 5.2 浏览器启动配置](启动配置\浏览器启动配置.md) + * [🔨 5.3 Session 启动配置](启动配置\Session启动配置.md) + * [🔨 5.4 使用配置文件](启动配置\使用配置文件.md) -* [⚡️ 6 Tips大集合](Tips大集合.md) +* [🧰 6 进阶使用](#) + + * [⚙️ 6.1 打包程序](进阶使用\打包程序.md) + * [⚙️ 6.2 监听浏览器网络](进阶使用\监听浏览器网络.md) + * [⚙️ 6.3 下载文件](进阶使用\下载文件.md) -* [🎯️ 7 版本历史](版本历史.md) +* [⚡️ 7 实用示例](#) + + * [🌠 自动登录码云](实用示例\自动登录码云.md) + * [🌠 获取各国疫情排名](实用示例\获取各国疫情排名.md) + * [🌠 下载星巴克产品图片](实用示例\下载星巴克产品图片.md) + * [🌠 同时操作多个浏览器](实用示例\同时操作多个浏览器.md) + +* [🔖 9 版本历史](版本历史.md) * [💐 鸣谢](鸣谢.md) diff --git a/docs/imgs/code.jpg b/docs/imgs/code.jpg new file mode 100644 index 0000000..f86aca7 Binary files /dev/null and b/docs/imgs/code.jpg differ diff --git a/docs/imgs/mixpage.jpg b/docs/imgs/mixpage.jpg new file mode 100644 index 0000000..3930da2 Binary files /dev/null and b/docs/imgs/mixpage.jpg differ diff --git a/docs/imgs/webpage.jpg b/docs/imgs/webpage.jpg new file mode 100644 index 0000000..3f571f0 Binary files /dev/null and b/docs/imgs/webpage.jpg differ diff --git a/docs/入门指南/基本概念.md b/docs/入门指南/基本概念.md index 6ceb440..e71fd5b 100644 --- a/docs/入门指南/基本概念.md +++ b/docs/入门指南/基本概念.md @@ -176,15 +176,17 @@ page = MixPage() ## 📍 `WebPage`结构图 -待更新。 +`WebPage`继承自`ChromiumPage`和`SessionPage`，前者负责控制浏览器，后者负责数据包收发。 + +![](../imgs/webpage.jpg) ## 📍 `MixPage`结构图 -如图所示，`Drission`对象负责链接的创建、共享登录状态等工作，类似 selenium 中 driver 的概念。 +`Drission`对象负责链接的创建、共享登录状态等工作，类似 selenium 中 driver 的概念。 `MixPage`对象负责对获取到的页面进行解析、操作。 `DriverElement`和`SessionElement`则是从页面对象中获取到的元素对象。负责对元素进行解析和操作。 -![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/20201118170751.jpg) +![](../imgs/mixpage.jpg) # ✔️ 配置管理 diff --git a/docs/入门指南/贴心设计.md b/docs/入门指南/贴心设计.md new file mode 100644 index 0000000..5f27d33 --- /dev/null +++ b/docs/入门指南/贴心设计.md @@ -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 同一时间只能操作一个标签页或`