本节介绍`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_script()`

此方法用于执行 js 脚本，d 模式独有。

**参数：**

- `script`：js 脚本文本
- `as_expr`：是否作为表达式运行，为`True`时`args`参数无效
- `*args`：传入的参数，按顺序在js文本中对应`argument[0]`、`argument[1]`...

**返回：** 脚本执行结果

```python
# 用传入参数的方式执行 js 脚本显示弹出框显示 Hello world!
page.run_script('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_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()
```