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