DrissionPage/docs/5_ChromiumPage/4_page_operation.md

本节介绍浏览器页面交互功能，元素的交互在下一节。

页面对象包括ChromiumPage、d 模式的WebPage、ChromiumTab、ChromiumFrame几种，这里只介绍ChromiumPage，其它几种后面专门章节介绍。

✔️ 页面跳转

📍 get()

该方法用于跳转到一个网址。当连接失败时，程序会进行重试。

参数名称	类型	默认值	说明
url	str	必填	目标 url
show_errmsg	bool	False	连接出错时是否显示和抛出异常
retry	int	None	重试次数，为None时使用页面参数，默认 3
interval	int float	None	重试间隔（秒），为None时使用页面参数，默认 2
timeout	int float	None	加载超时时间（秒）

返回类型	说明
bool	是否连接成功

示例：

page.get('https://www.baidu.com')

---

📍 back()

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

参数名称	类型	默认值	说明
steps	int	1	后退步数

返回：None

示例：

page.back(2)  # 后退两个网页

---

📍 forward()

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

参数名称	类型	默认值	说明
steps	int	1	前进步数

返回：None

page.forward(2)  # 前进两步

---

📍 refresh()

此方法用于刷新当前页面。

参数名称	类型	默认值	说明
ignore_cache	bool	False	刷新时是否忽略缓存

返回：None

page.refresh()  # 刷新页面

---

📍 stop_loading()

此方法用于强制停止当前页面加载。

参数： 无

返回：None

---

📍 wait_loading()

此方法用于等待页面进入加载状态。

我们经常会通过点击页面元素进入下一个网页，并立刻获取新页面的元素。但若跳转前的页面拥有和跳转后页面相同定位符的元素，会导致过早获取元素，跳转后失效的问题。使用此方法，会阻塞程序，等待页面开始加载后再继续，从而避免上述问题。

参数名称	类型	默认值	说明
timeout	int float None True	None	超时时间，为None或Ture时使用页面timeout设置 为数字时等待相应时间

返回类型	说明
bool	等待结束时是否进入加载状态

示例：

ele.click()  # 点击某个元素
page.wait_loading()  # 等待页面进入加载状态
# 执行在新页面的操作
print(page.title)

---

✔️ 执行脚本或命令

📍 run_js()

此方法用于执行 js 脚本。

参数名称	类型	默认值	说明
script	str	必填	js 脚本文本
as_expr	bool	False	是否作为表达式运行，为True时args参数无效
*args	-	无	传入的参数，按顺序在js文本中对应argument[0]、argument[1]...

返回类型	说明
Any	脚本执行结果

示例：

# 用传入参数的方式执行 js 脚本显示弹出框显示 Hello world!
page.run_js('alert(arguments[0]+arguments[1]);', 'Hello', ' world!')

---

📍 run_async_script()

此方法用于以异步方式执行 js 代码。

参数：

参数名称	类型	默认值	说明
script	str	必填	js 脚本文本
as_expr	bool	False	是否作为表达式运行，为True时args参数无效
*args	-	无	传入的参数，按顺序在js文本中对应argument[0]、argument[1]...

返回：None

---

📍 run_cdp()

此方法用于执行 Chrome DevTools Protocol 语句。

cdp 用法详见 Chrome DevTools Protocol。

参数名称	类型	默认值	说明
cmd	str	必填	协议项目
**cmd_args	-	无	项目参数

返回类型	说明
dict	执行返回的结果

示例：

# 停止页面加载
page.run_cdp('Page.stopLoading')

---

✔️ cookies 及缓存

📍 set_cookies()

此方法用于设置 cookies。

可以接收CookieJar、list、tuple、str、dict格式的 cookies。

参数名称	类型	默认值	说明
cookies	RequestsCookieJar list tuple str dict	必填	cookies 信息

返回：None

cookies = {'name': 'abc'}
page.set_cookies(cookies, set_session=True, set_driver=True)

---

📍 set_session_storage()

此方法用于设置或删除某项 sessionStorage 信息。

参数名称	类型	默认值	说明
item	str	必填	要设置的项
value	str False	必填	为False时，删除该项

返回：None

示例：

page.set_session_storage(item='abc', value='123')

---

📍 set_local_storage()

此方法用于设置或删除某项 localStorage 信息。

参数名称	类型	默认值	说明
item	str	必填	要设置的项
value	str False	必填	为False时，删除该项

返回：None

---

📍 clear_cache()

此方法用于清除缓存，可选择要清除的项。

参数名称	类型	默认值	说明
session_storage	bool	True	是否清除 sessionstorage
local_storage	bool	True	是否清除 localStorage
cache	bool	True	是否清除 cache
cookies	bool	True	是否清除 cookies

返回：None

示例：

page.clear_cache(cookies=False)  # 除了 cookies，其它都清除

---

✔️ 各种设置

📍 set_timeouts()

此方法用于设置三种超时时间，单位为秒。可单独设置，为None表示不改变原来设置。

参数名称	类型	默认值	说明
implicit	int float None	None	整体超时时间
page_load	int float None	None	页面加载超时时间
script	int float None	None	脚本运行超时时间

返回：None

示例：

page.set_timeouts(implicit=10, page_load=30)

---

📍 set_page_load_strategy

此属性用于设置页面加载策略，调用其方法选择某种策略。

方法名称	参数	说明
normal()	无	等待页面完全加载完成，为默认状态
eager()	无	等待文档加载完成就结束，不等待资源加载
none()	无	页面连接完成就结束

示例：

page.set_page_load_strategy.normal()
page.set_page_load_strategy.eager()
page.set_page_load_strategy.none()

---

📍 set_ua_to_tab()

此方法用于为浏览器当前标签页设置 user agent，只在当前 tab 有效。

参数名称	类型	默认值	说明
ua	str	必填	user agent 字符串

返回：None

---

📍 set_headers()

此方法用于设置额外添加到当前页面请求 headers 的参数。

参数名称	类型	默认值	说明
headers	dict	必填	dict形式的 headers

返回：None

示例：

h = {'connection': 'keep-alive', 'accept-charset': 'GB2312,utf-8;q=0.7,*;q=0.7'}
page.set_headers(headers=h)

---

✔️ 窗口管理

📍 调整大小和位置

set_window属性返回一个WindowSetter对象，调用其方法执行改变窗口状态。

方法	参数	说明
maximized()	无	最大化
minimized()	无	最小化
fullscreen()	无	全屏
normal()	无	常规
size(width, height)	宽，高	设置大小
location(x, y)	屏幕坐标，左上角为 (0, 0)	设置位置

# 窗口最大化
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()方法用于随时隐藏和显示浏览器窗口。

与 headless 模式不一样，这两个方法是直接隐藏和显示浏览器进程。在任务栏上也会消失。

只支持 Windows 系统，并且必须已安装 pypiwin32 库才可使用。

🔸 hide_browser()

此方法用于隐藏当前浏览器窗口。

参数： 无

返回：None

---

🔸 show_browser()

此方法用于显示当前浏览器窗口。

参数： 无

返回：None

示例：

page.hide_browser()

!>注意：
- 浏览器隐藏后并没有关闭，下次运行程序还会接管已隐藏的浏览器
- 浏览器隐藏后，如果有新建标签页，会自行显示出来

---

✔️ 滚动页面

📍 scroll

此属性用于以某种方式滚动页面。
调用时返回一个Scroll对象，调用其方法实现页面各种方式的滚动。

方法	参数	功能
to_top()	无	滚动到顶端，水平位置不变
to_bottom()	无	滚动到底端，水平位置不变
to_half()	无	滚动到垂直中间位置，水平位置不变
to_rightmost()	无	滚动到最右边，垂直位置不变
to_leftmost()	无	滚动到最左边，垂直位置不变
to_location(x, y)	滚动条坐标值，左上角为 (0 , 0)	滚动到指定位置
up(pixel)	滚动的像素	向上滚动若干像素，水平位置不变
down(pixel)	滚动的像素	向下滚动若干像素，水平位置不变
right(pixel)	滚动的像素	向左滚动若干像素，垂直位置不变
left(pixel)	滚动的像素	向右滚动若干像素，垂直位置不变

# 页面滚动到底部
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	str tuple ChromiumElement	必填	元素的定位信息，可以是元素、定位符

返回：None

示例：

# 滚动到某个已获取到的元素
ele = page.ele('tag:div')
page.scroll_to_see(ele)

# 滚动到按定位符查找到的元素
page.scroll_to_see('tag:div')

---

✔️ 处理弹出消息

📍 handle_alert()

此方法 用于处理提示框。
它能够设置等待时间，等待提示框出现才进行处理，若超时没等到提示框，返回None。
也可只获取提示框文本而不处理提示框。

参数名称	类型	默认值	说明
accept	bool None	True	True表示确认，False表示取消，None不会按按钮但依然返回文本值
send	str	None	处理 prompt 提示框时可输入文本
timeout	int float	None	等待提示框出现的超时时间，为None时使用页面整体超时时间

返回类型	说明
str	提示框内容文本
None	未等到提示框则返回None

示例：

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

# 点击取消
page.handle_alert(accept=False)

# 给 prompt 提示框输入文本并点击确定
paeg.handle_alert(accept=True, send='some text')

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

---

✔️ 关闭浏览器

📍 quit()

此方法用于关闭浏览器。

参数： 无

返回：**None

page.quit()