本节介绍页面对象可以使用的方法，有些方法是两种模式共有的，有些只有某种模式可以使用。当调用独有方法时，会自动切换到该模式。如调用`post()`方法时，会先切换到 s 模式，并同步登录信息。

# 两种模式共有的方法

## get()

此方法用于跳转到一个 url，详细用法见“[使用方法 -> 访问网页](访问网页.md)”章节。



## ele()、eles()、s_ele()、s_eles()

这些方法用于在页面中查找元素，详细用法见“[使用方法 -> 查找页面元素](查找页面元素)”章节。

## 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()

此方法用于下载文件，详细用法见“[使用方法 -> 下载文件](下载文件.md)”章节。



## close_driver()

此方法用于关闭`WebDriver`对象和浏览器。

参数：无

返回：`None`

## close_session()

此方法用于关闭`Session`对象。

参数：无

返回：`None`

# s 模式独有方法

## post()

此方法用于以 post 方式访问 url，具体用法见“[使用方法 -> 访问网页](访问网页.md)”章节。

# 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：传入的参数

返回：脚本执行结果

## set_timeouts()

此方法用于设置三种超时时间，selenium 4 以上版本生效。

参数：

- implicit：查找元素超时时间
- pageLoad：页面加载超时时间
- script：脚本运行超时时间

返回：`None`

## set_ua_to_tab()

此方法用于为当前 tab 设置 user agent，只在当前 tab 有效。

参数：

- ua：user agent字符串

返回：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>自动化过程中若手动点击标签页，会使被点击标签页的 handle 排到首位，从而导致排序与视觉效果不一致。

```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>当程序使用的是截关的浏览器，获取到的 handle 顺序和视觉效果不一致，不能按序号关闭。

参数：

- num_or_handles：要保留的标签页序号或 handle，可传入 list 或 tuple，为None时关闭当前页

返回：`None`

```python
# 关闭当前标签页
page.close_tabs()

# 关闭第1、3个标签页
page.close_tabs((0, 2))
```

## close_other_tabs()

此方法用于关闭指定标签页以外的标签页，标签页可以是序号或 handle 值，可保留多个。默认保留当前的。

!> **注意：** <br>当程序使用的是截关的浏览器，获取到的 handle 顺序和视觉效果不一致，不能按序号关闭。

参数：

- 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`

## back()

此方法用于在浏览历史中后退一步。

参数：无

返回：`None`

## forward()

此方法用于在浏览历史中前进一步。

参数：无

返回：`None`

## screenshot()

此方法用于生成页面可见范围截图。图片为 png 格式。  
此方法能够自动处理文件重命名的情况，给新文件后面增加序号。

参数：

- path：图片保存路径
- filename：图片文件名，可不写后缀，不传入时以页面 title 命名

返回：图片完整路径

```python
# 浏览器窗口截图，保存到 D 盘 img 文件夹，文件名为 img1.png
page.screenshot(r'D:\img', 'img1')
```

## 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`。  
它可只获取提示框文本而不处理提示框。

参数：

- mode：`'ok'`或`'cancel'`，若输入其它值，不会按按钮但依然返回文本值
- text：处理 prompt 提示框时可输入文本
- timeout：等待提示框出现的超时时间

返回：提示框内容文本，未等到提示框则返回`None`

```python
# 确认提示框并获取提示框文本
txt = page.process_alert()

# 点击取消
page.process_alert('cancel')

# 给 prompt 提示框输入文本并点击确定
paeg.process_alert('ok', 'some text')

# 不处理提示框，只获取提示框文本
txt = page.process_alert(None)
```

## check_page()

此方法用于检查页面是否符合预期，它默认返回`None`，须由子类实现其功能。  
用于 POM 模式时，可派生各种页面子类，从而实现检查页面的功能。