mirror of
https://gitee.com/g1879/DrissionPage.git
synced 2024-12-10 04:00:23 +08:00
545 lines
13 KiB
Markdown
545 lines
13 KiB
Markdown
本节介绍`WebPage`对象可以使用的方法，有些方法是两种模式共有的，有些只有某种模式可以使用。当调用独有方法时，会自动切换到该模式。如调用`post()`方法时，会先切换到 s 模式，并同步登录信息。
|
||
|
||
# ✔️ 页面跳转
|
||
|
||
## 📍 `get()`
|
||
|
||
此方法用于跳转到一个 url，两种模式都支持，详细用法见“使用方法 -> 访问网页”章节。
|
||
|
||
**参数：**
|
||
|
||
- `url`：目标 url
|
||
- `show_errmsg`：是否显示和抛出异常，默认不抛出，连接错误会返回 `None`
|
||
- `retry`：重试次数，与页面对象的设置一致，默认 3 次
|
||
- `interval`：重试间隔（秒），与页面对象的设置一致，默认 2 秒
|
||
- `timeout`：连接超时时间（秒）
|
||
- `**kwargs`：s 模式用到的连接参数，具体见 requests 用法
|
||
|
||
**返回：**`bool`类型，表示是否连接成功
|
||
|
||
```python
|
||
page.get('https://www.baidu.com')
|
||
```
|
||
|
||
## 📍 `post()`
|
||
|
||
此方法用于以 post 方式访问 url，仅 s 模式支持。具体用法见“使用方法 -> 访问网页”章节。
|
||
|
||
参数：
|
||
|
||
- `url`：目标 url
|
||
- `data`：提交的数据，可以是`dict`或`str`类型
|
||
- `json`：提交的数据，可以是`dict`或`str`类型
|
||
- `show_errmsg`：是否显示和抛出异常，默认不抛出，连接错误会返回`None`
|
||
- `retry`：重试次数，与页面对象的设置一致，默认 3 次
|
||
- `interval`：重试间隔（秒），与页面对象的设置一致，默认 2 秒
|
||
- `**kwargs`：连接参数，具体见 requests 用法
|
||
|
||
返回：**`bool`类型，表示是否连接成功
|
||
|
||
```python
|
||
page.post('https://xxxxxx', data=data)
|
||
```
|
||
|
||
## 📍 `back()`
|
||
|
||
此方法用于在浏览历史中后退若干步，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `steps`：后退步数
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
page.back(2) # 后退两个网页
|
||
```
|
||
|
||
## 📍 `forward()`
|
||
|
||
此方法用于在浏览历史中前进若干步，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `steps`：前进步数
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
page.forward(2) # 前进两步
|
||
```
|
||
|
||
## 📍 `refresh()`
|
||
|
||
此方法用于刷新当前页面，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `ignore_cache`：刷新时是否忽略缓存
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
page.refresh() # 刷新页面
|
||
```
|
||
|
||
## 📍 `stop_loading()`
|
||
|
||
此方法用于强制当前页面加载，d 模式独有。
|
||
|
||
参数：无
|
||
|
||
返回：`None`
|
||
|
||
## 📍 `wait_loading()`
|
||
|
||
此方法用于等待页面进入加载状态，d 模式独有。
|
||
|
||
我们经常会通过点击页面元素进入下一个网页，并立刻获取新页面的元素。但若跳转前的页面拥有和跳转后页面相同定位符的元素，会导致过早获取元素，跳转后失效的问题。使用此方法，会阻塞程序，等待页面开始加载后再继续，从而避免上述问题。
|
||
|
||
**参数：**
|
||
|
||
- `timeout`：超时时间
|
||
|
||
**返回：** 等待结束时是否进入加载状态
|
||
|
||
```python
|
||
ele.click() # 点击某个元素
|
||
page.wait_loading() # 等待页面进入加载状态
|
||
# 执行在新页面的操作
|
||
```
|
||
|
||
# ✔️切换页面模式
|
||
|
||
## 📍 `change_mode()`
|
||
|
||
此方法是`WebPage`用于切换模式的方法。
|
||
|
||
切换后默认在目标模式重新跳转到原模式所在 url。
|
||
|
||
参数：
|
||
|
||
- `mode`：目标模式字符串，`'s'`或`'d'`，默认转换到另一种
|
||
- `go`：转换后是否跳转到原模式所在 url
|
||
- `copy_cookies`：是否复制cookies到目标模式
|
||
|
||
返回：`None`
|
||
|
||
以下例子演示用浏览器登录 gitee 网站，再切换到 s 模式。可见 s 模式依然处于登录状态。
|
||
|
||
```python
|
||
from DrissionPage import WebPage
|
||
|
||
# 创建页面对象，默认 d 模式
|
||
page = WebPage()
|
||
# 访问个人中心页面（未登录，重定向到登录页面）
|
||
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')
|
||
page.wait_loading()
|
||
|
||
# 切换到 session 模式
|
||
page.change_mode()
|
||
|
||
# 打印当前模式和登录后的 title（）
|
||
print('当前模式：', page.mode)
|
||
print('登录后title：', page.title)
|
||
```
|
||
|
||
输出：
|
||
|
||
```
|
||
当前模式：d
|
||
登录前title： 登录 - Gitee.com
|
||
|
||
当前模式：s
|
||
登录后title： 个人资料 - 码云 Gitee.com
|
||
```
|
||
|
||
# ✔️ 执行脚本或命令
|
||
|
||
## 📍 `run_js()`
|
||
|
||
此方法用于执行 js 脚本，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `script`：js 脚本文本
|
||
- `as_expr`：是否作为表达式运行，为`True`时`args`参数无效
|
||
- `*args`：传入的参数，按顺序在js文本中对应`argument[0]`、`argument[1]`...
|
||
|
||
**返回：** 脚本执行结果
|
||
|
||
```python
|
||
# 用传入参数的方式执行 js 脚本显示弹出框显示 Hello world!
|
||
page.run_js('alert(arguments[0]+arguments[1]);', 'Hello', ' world!')
|
||
```
|
||
|
||
## 📍 `run_async_script()`
|
||
|
||
此方法用于以异步方式执行 js 代码，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `script`：js 文本
|
||
- `as_expr`：是否作为表达式运行，为`True`时`args`参数无效
|
||
- `*args`：传入 js 的参数，按顺序在js文本中对应`argument[0]`、`argument[1]`...
|
||
|
||
**返回：**`None`
|
||
|
||
## 📍 `run_cdp()`
|
||
|
||
此方法用于执行 Chrome DevTools Protocol 语句，d 模式独有。cdp
|
||
用法详见[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)。
|
||
|
||
**参数：**
|
||
|
||
- `cmd`：协议项目
|
||
|
||
- `**cmd_args`：项目参数
|
||
|
||
**返回：** 该语句返回的值
|
||
|
||
```python
|
||
# 停止页面加载
|
||
page.run_cdp('Page.stopLoading')
|
||
```
|
||
|
||
# ✔️ cookies 及缓存
|
||
|
||
## 📍 `set_cookies()`
|
||
|
||
此方法用于对浏览器或`Session`对象设置 cookies，两种模式都支持。
|
||
可以接收`CookieJar`、`list`、`tuple`、`str`、`dict`格式的 cookies。
|
||
|
||
**参数：**
|
||
|
||
- `cookies`：cookies 信息
|
||
- `set_session`：是否设置到`Session`对象
|
||
- `set_driver`：是否设置到浏览器
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
cookies = {'name': 'abc'}
|
||
page.set_cookies(cookies, set_session=True, set_driver=True)
|
||
```
|
||
|
||
## 📍 `cookies_to_session()`
|
||
|
||
此方法用于从浏览器复制 cookies 到`Session`对象。不会触发模式切换。
|
||
|
||
**参数：**
|
||
|
||
- `copy_user_agent`：是否同时复制 user agent 信息
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
page.cookies_to_session()
|
||
```
|
||
|
||
## 📍 `cookies_to_driver()`
|
||
|
||
此方法用于从`Session`对象复制 cookies 到浏览器。不会触发模式切换。
|
||
|
||
**参数：** 无
|
||
|
||
**返回：**`None`
|
||
|
||
## 📍 `set_session_storage()`
|
||
|
||
此方法用于设置或删除某项 sessionStorage 信息，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `item`：要设置的项
|
||
|
||
- `value`：项的值，设置为`False`时，删除该项
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
page.set_session_storage(item='abc', value='123')
|
||
```
|
||
|
||
## 📍 `set_local_storage()`
|
||
|
||
此方法用于设置或删除某项 localStorage 信息，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `item`：要设置的项
|
||
|
||
- `value`：项的值，设置为`False`时，删除该项
|
||
|
||
**返回：**`None`
|
||
|
||
## 📍 `clear_cache()`
|
||
|
||
此方法用于清除缓存，可选要清除的项，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `session_storage`：是否清除 sessionstorage
|
||
|
||
- `local_storage`：是否清除 localStorage
|
||
|
||
- `cache`：是否清除 cache
|
||
|
||
- `cookies`：是否清除 cookies
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
page.clear_cache(cookies=False) # 除了 cookies，其它都清除
|
||
```
|
||
|
||
# ✔️ 各种设置
|
||
|
||
## 📍 `set_timeouts()`
|
||
|
||
此方法用于设置三种超时时间，单位为秒。可单独设置，为`None`表示不改变原来设置。
|
||
|
||
**参数：**
|
||
|
||
- `implicit`：查找元素超时时间
|
||
- `page_load`：页面加载超时时间
|
||
- `lscript`：脚本运行超时时间
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
page.set_timeouts(implicit=10, page_load=30)
|
||
```
|
||
|
||
## 📍 `set_page_load_strategy`
|
||
|
||
此属性用于设置页面加载策略，d 模式独有。
|
||
|
||
页面加载策略有三种：
|
||
|
||
- `normal`：等待页面完全加载完成，为默认状态
|
||
|
||
- `eager`：等待文档加载完成就结束，不等待资源加载
|
||
|
||
- `none`：页面连接完成就结束
|
||
|
||
```python
|
||
page.set_page_load_strategy.eager()
|
||
```
|
||
|
||
## 📍 `set_ua_to_tab()`
|
||
|
||
此方法用于为浏览器当前标签页设置 user agent，只在当前 tab 有效，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `ua`：user agent 字符串
|
||
|
||
**返回：**`None`
|
||
|
||
## 📍 `set_headers()`
|
||
|
||
此方法用于设置headers参数，两种模式都支持。s 模式下，新 headers 值会逐项覆盖原来的，不会删除原来未被设置的值。
|
||
|
||
**参数：**
|
||
|
||
- `headers`：`dict`形式的 headers
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
h = {'connection': 'keep-alive', 'accept-charset': 'GB2312,utf-8;q=0.7,*;q=0.7'}
|
||
page.set_headers(headers=h)
|
||
```
|
||
|
||
# ✔️ 窗口管理
|
||
|
||
## 📍 调整大小和位置
|
||
|
||
`set_window`属性返回一个`WindowSetter`对象，用于执行改变窗口的各种方法，d 模式独有。
|
||
|
||
| 方法 | 参数 | 说明 |
|
||
| --------------------- | ---- | ---- |
|
||
| `maximized()` | 无 | 最大化 |
|
||
| `minimized()` | 无 | 最小化 |
|
||
| `fullscreen()` | 无 | 全屏 |
|
||
| `normal()` | 无 | 常规 |
|
||
| `size(width, height)` | 宽，高 | 设置大小 |
|
||
| `location(x, y)` | 屏幕坐标 | 设置位置 |
|
||
|
||
```python
|
||
# 窗口最大化
|
||
page.set_window.maximized()
|
||
|
||
# 窗口全屏，即 F11
|
||
page.set_window.fullscreen()
|
||
|
||
# 恢复普通窗口
|
||
page.set_window.normal()
|
||
|
||
# 设置窗口大小
|
||
page.set_window.size(500, 500)
|
||
|
||
# 设置窗口位置
|
||
page.set_window.location(200, 200)
|
||
```
|
||
|
||
## 📍 隐藏和显示窗口
|
||
|
||
`hide_browser()`和`show_browser()`方法用于随时隐藏和显示浏览器窗口，d 模式独有。
|
||
|
||
与 headless 模式不一样，这两个方法是直接隐藏和显示浏览器进程。在任务栏上也会消失。
|
||
|
||
只支持 Windows 系统，并且必须已安装 pypiwin32 库才可使用。
|
||
|
||
`hide_browser()`
|
||
|
||
**参数：** 无
|
||
|
||
返回：`None`
|
||
|
||
`show_browser()`
|
||
|
||
**参数：** 无
|
||
|
||
返回：`None`
|
||
|
||
```python
|
||
page.hide_browser()
|
||
```
|
||
|
||
**注意：**
|
||
|
||
- 浏览器隐藏后并没有关闭，下次运行程序还会接管已隐藏的浏览器
|
||
|
||
- 浏览器隐藏后，如果有新建标签页，会自行显示出来
|
||
|
||
# ✔️ 滚动页面
|
||
|
||
## 📍 `scroll`
|
||
|
||
此属性用于以某种方式滚动页面，d 模式独有。
|
||
调用此属性返回一个`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()`
|
||
|
||
此方法用于滚动页面直到元素可见，d 模式独有。
|
||
|
||
**参数：**
|
||
|
||
- `loc_or_ele`：元素的定位信息，可以是元素、定位符
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
# 滚动到某个已获取到的元素
|
||
ele = page.ele('tag:div')
|
||
page.scroll_to_see(ele)
|
||
|
||
# 滚动到按定位符查找到的元素
|
||
page.scroll_to_see('tag:div')
|
||
```
|
||
|
||
# ✔️ 处理弹出消息
|
||
|
||
## 📍 `handle_alert()`
|
||
|
||
此方法 用于处理提示框，d 模式独有。
|
||
它能够设置等待时间，等待提示框出现才进行处理，若超时没等到提示框，返回`None`。
|
||
它可只获取提示框文本而不处理提示框。
|
||
|
||
**参数：**
|
||
|
||
- `accept`：`True`表示确认，`False`表示取消，其它值不会按按钮但依然返回文本值
|
||
- `send`：处理 prompt 提示框时可输入文本
|
||
- `timeout`：等待提示框出现的超时时间
|
||
|
||
**返回：** 提示框内容文本，未等到提示框则返回`None`
|
||
|
||
```python
|
||
# 确认提示框并获取提示框文本
|
||
txt = page.handle_alert()
|
||
|
||
# 点击取消
|
||
page.handle_alert(accept=False)
|
||
|
||
# 给 prompt 提示框输入文本并点击确定
|
||
paeg.handle_alert(accept=True, send='some text')
|
||
|
||
# 不处理提示框，只获取提示框文本
|
||
txt = page.handle_alert(accept=None)
|
||
```
|
||
|
||
# ✔️ 关闭
|
||
|
||
## 📍 `close_driver()`
|
||
|
||
此方法用于关闭`WebPage`控制的浏览器，并切换到 s 模式。
|
||
|
||
**参数：** 无
|
||
|
||
**返回：**`None`
|
||
|
||
```python
|
||
page.close_driver()
|
||
```
|
||
|
||
## 📍 `close_session()`
|
||
|
||
此方法用于关闭`WebPage`控制的`Session`对象，并切换到 d 模式。
|
||
|
||
**参数：** 无
|
||
|
||
**返回：`**None`
|
||
|
||
```python
|
||
page.close_session()
|
||
```
|
||
|
||
## 📍`quit()`
|
||
|
||
此方法用于退出浏览器并且关闭 Session 对象。彻底关闭`WebPage`对象。
|
||
|
||
**参数：** 无
|
||
|
||
**返回：`**None`
|
||
|
||
```python
|
||
page.quit()
|
||
```
|