🚤 页面交互

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

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

✅️️ 页面跳转

📌 `get()`

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

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

✅️️ 各种等待

网络环境不稳定，因此程序能够智能等待是非常重要的，ChromiumPage内置了一些等待方法，可以提高程序稳定性和效率。

它们藏在wait属性里。

📌 `wait.load_start()`

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

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

我们通常只需等待页面加载开始，程序会自动等待加载结束。

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

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

示例：

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

📌 `wait.load_complete()`

此方法用于等待页面加载完成。

一般来说都无须开发者使用，程序大部分动作都会自动等待加载完成再执行。

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

返回类型	说明
`bool`	等待结束时是否完成加载完成

📌 `wait.ele_display()`

此方法用于等待一个元素变成显示状态。

参数名称	类型	默认值	说明
`loc_or_ele`	`str` `Tuple[str, str]` `ChromiumElement`	必填	要等待的元素，可以是元素或定位符
`timeout`	`float`	`None`	超时时间，为`None`时使用页面`timeout`设置

返回类型	说明
`bool`	是否等待成功

示例：

# 等待 id 为 div1 的元素显示，超时使用页面设置
page.wait.ele_display('#div1')

# 等待 id 为 div1 的元素显示，设置超时3秒
page.wait.ele_display('#div1', timeout=3)

# 等待已获取到的元素被显示
ele = page.ele('#div1')
page.wait.ele_display(ele)

📌 `wait.ele_hidden()`

此方法用于等待一个元素变成隐藏状态。

参数名称	类型	默认值	说明
`loc_or_ele`	`str` `Tuple[str, str]` `ChromiumElement`	必填	要等待的元素，可以是元素或定位符
`timeout`	`float`	`None`	超时时间，为`None`时使用页面`timeout`设置

返回类型	说明
`bool`	是否等待成功

📌 `wait.ele_delete()`

此方法用于等待一个元素从 DOM 中删除。

参数名称	类型	默认值	说明
`loc_or_ele`	`str` `Tuple[str, str]` `ChromiumElement`	必填	要等待的元素，可以是元素或定位符
`timeout`	`float`	`None`	超时时间，为`None`时使用页面`timeout`设置

返回类型	说明
`bool`	是否等待成功

📌 `wait.download_begin()`

此方法用于等待下载开始，详见下载功能章节。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	超时时间，为`None`时使用页面`timeout`设置

返回类型	说明
`bool`	是否等待成功

示例：

page('#download_btn').click()  # 点击按钮触发下载
page.wait.download_begin()  # 等待下载开始

📌 `wait.upload_paths_inputted()`

此方法用于等待自动填写上传文件路径。详见文件上传章节。

参数： 无

返回：None

示例：

# 设置要上传的文件路径
page.set.upload_files('demo.txt')
# 点击触发文件选择框按钮
btn_ele.click()
# 等待路径填入
page.wait.upload_paths_inputted()

📌 `wait.new_tab()`

此方法用于等待新标签页出现。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	超时时间，为`None`时使用页面`timeout`设置

返回类型	说明
`bool`	是否等待成功

✅️️ 等待和抓取数据包

这是一个非常实用的功能，可以指定需要的数据包，等待它出现并抓取。

可以配合翻页、动态加载等，能够大幅提高程序可靠性和效率。

📌 `wait.set_targets()`

此方法用于设置要等待的目标数据包。格式是正则表达式。可以用list等指定多个目标。

执行此方法后，程序开始监听数据包。

参数名称	类型	默认值	说明
`targets`	`str` `list` `tuple` `set`	必填	要匹配的数据包 url 特征指定单个目标时传入`str`，多个目标可传入其余几种类型
`is_regex`	`bool`	`False`	设置的 target 是否正则表达式，这个设置会对所有监听目标生效

返回： None

📌 `wait.data_packets()`

此方法用于等待指定数据包出现并加载完成。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	超时时间，为`None`则使用页面对象`timeout`属性
`any_one`	`bool`	`False`	多个目标时，是否全部监听到才结束，为`True`时监听到一个目标就结束

返回类型	说明
`ResponseData`	指定单个目标时
`List[ResponseData]`	指定多个目标时，返回结果列表
`False`	没有等待到目标数据包

📌 `wait.stop_listening()`

此方法用于停止监听数据包。

参数： 无

返回： None

📌 `ResponseData`对象

ResponseData对象是获取到的数据包结果对象，包含了数据包各种信息。

属性：

requestId：浏览器保存的请求唯一 id
response：response 数据，是一个大小写不敏感的字典
body：reponse body 数据，如果请求是 json 格式，返回转换后的字典，如果是图片，进行 base64 转码后返回字节，否则返回其文本
rawBody：转换字典前的 body 原始文本
postData：如果是 post 方式请求，返回其 post data 文本，否则为None（即使是 post 方式，服务器也不一定会返回这个数据）
headers：以大小写不敏感字典方式返回 response 的 headers
requestHeaders：以大小写不敏感字典方式返回 request 的 headers
tab：产生这个请求的标签页的 id
target：产生这个请求的监听目标

除以上属性，ResponseData可通过 key 或指定属性来访问具体的 response 字段：

# 假设rd是一个ResponseData对象
print(rd.url)  # 打印response中的url数据
print(rd['url'])  # 和上面一行一致

其它可以使用的属性有：

url、status、statusText、headersText、mimeType、requestHeadersText、connectionReused、connectionId、remoteIPAddress、remotePort、fromDiskCache、fromServiceWorker、 fromPrefetchCache、encodedDataLength、timing、serviceWorkerResponseSource、responseTime、 cacheStorageCacheName、protocol、securityState、securityDetails

📌 示例

以下示例演示工作方式。

点击下一页，等待数据包，再点击下一页，循环。

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.get('https://gitee.com/explore/all')
page.wait.set_targets('gitee.com/explore', is_regex=False)

for _ in range(5):
    page('@rel=next').click()
    res = page.wait.data_packets()
    print(res.url)

输出：

https://gitee.com/explore/all?page=2
https://gitee.com/explore/all?page=3
https://gitee.com/explore/all?page=4
https://gitee.com/explore/all?page=5
https://gitee.com/explore/all?page=6

✅️️ 元素管理

📌 `remove_ele()`

此方法用于从页面上删除一个元素。

参数名称	类型	默认值	说明
`loc_or_ele`	`str` `Tuple[str, str]` `ChromiumElement`	必填	要删除的元素，可以是元素或定位符

返回：None

示例：

# 删除一个已获得的元素
ele = page('tag:a')
page.remove_ele(ele)

# 删除用定位符找到的元素
page.remove_ele('tag:a')

✅️️ 执行脚本或命令

📌 `run_js()`

此方法用于执行 js 脚本。

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

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

示例：

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

注意

如果as_expr为True，脚本应是返回一个结果的形式，并且不能有return
如果as_expr不为`True'，脚本应尽量写成一个方法。

📌 `run_async_js()`

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

参数：

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

返回：None

📌 `run_cdp()`

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

cdp 用法详见 Chrome DevTools Protocol。

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

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

示例：

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

📌 run_js_loaded()

此方法用于执行 js 脚本，执行前先确保页面加载完毕。

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

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

📌 `run_cdp_loaded()`

此方法用于执行 Chrome DevTools Protocol 语句，执行前先确保页面加载完毕。

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

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

✅️️ 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属性中。

📌 `set.retry_times()`

此方法用于设置连接失败时重连次数。

参数名称	类型	默认值	说明
`times`	`int`	必填	秒数

返回：None

📌 `set.retry_interval()`

此方法用于设置连接失败时重连间隔。

参数名称	类型	默认值	说明
`interval`	`float`	必填	秒数

返回：None

📌 `set.timeouts()`

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

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

返回：None

示例：

page.set.timeouts(implicit=10, page_load=30)

📌 `set.load_strategy`

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

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

示例：

page.set.load_strategy.normal()
page.set.load_strategy.eager()
page.set.load_strategy.none()

📌 `set.user_agent()`

此方法用于为浏览器当前标签页设置 user agent。

参数名称	类型	默认值	说明
`ua`	`str`	必填	user agent 字符串
`platform`	`str`	`None`	平台类型，如`'android'`

返回：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属性中。

📌 `set.window.maximized()`

此方法用于使窗口最大化。

参数： 无

返回：None

示例：

page.set.window.maximized()

📌 `set.window.minimized()`

此方法用于使窗口最小化。

参数： 无

返回：None

📌 `set.window.fullscreen()`

此方法用于使窗口切换到全屏模式。

参数： 无

返回：None

📌 `set.window.normal()`

此方法用于使窗口切换到普通模式。

参数： 无

返回：None

📌 `set.window.size()`

此方法用于设置窗口大小。只传入一个参数时另一个参数不会变化。

参数名称	类型	默认值	说明
`width`	`int`	`None`	窗口宽度
`height`	`int`	`None`	窗口高度

返回：None

示例：

page.set.window.size(500, 500)

📌 `set.window.location()`

此方法用于设置窗口位置。只传入一个参数时另一个参数不会变化。

参数名称	类型	默认值	说明
`x`	`int`	`None`	距离顶部距离
`y`	`int`	`None`	距离左边距离

返回：None

示例：

page.set.window.location(500, 500)

📌 `set.window.hide()`

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

与 headless 模式不一样，这个方法是直接隐藏浏览器进程。在任务栏上也会消失。只支持 Windows 系统，并且必须已安装 pypiwin32 库才可使用。

参数： 无

返回：None

示例：

page.set.window.hide()

注意

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

📌 `set.window.show()`

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

参数： 无

返回：None

✅️️ 滚动页面

页面滚动的功能藏在scroll属性中。

📌 `scroll.to_top()`

此方法用于滚动页面到顶部，水平位置不变。

参数： 无

返回：None

示例：

page.scroll.to_top()

📌 `scroll.to_bottom()`

此方法用于滚动页面到底部，水平位置不变。

参数： 无

返回：None

📌 `scroll.to_half()`

此方法用于滚动页面到垂直中间位置，水平位置不变。

参数： 无

返回：None

📌 `scroll.to_rightmost()`

此方法用于滚动页面到最右边，垂直位置不变。

参数： 无

返回：None

📌 `scroll.to_leftmost()`

此方法用于滚动页面到最左边，垂直位置不变。

参数： 无

返回：None

📌 `scroll.to_location()`

此方法用于滚动页面到滚动到指定位置。

方法	参数	说明
`x`	必填	水平位置
`y`	必填	垂直位置

返回：None

示例：

page.scroll.to_location(300, 50)

📌 `scroll.up()`

此方法用于使页面向上滚动若干像素，水平位置不变。

方法	参数	说明
`pixel`	必填	滚动的像素

返回：None

示例：

page.scroll.up(30)

📌 `scroll.down()`

此方法用于使页面向下滚动若干像素，水平位置不变。

方法	参数	说明
`pixel`	必填	滚动的像素

返回：None

📌 `scroll.right()`

此方法用于使页面向右滚动若干像素，垂直位置不变。

方法	参数	说明
`pixel`	必填	滚动的像素

返回：None

📌 `scroll.left()`

此方法用于使页面向左滚动若干像素，垂直位置不变。

方法	参数	说明
`pixel`	必填	滚动的像素

返回：None

📌 `scroll.to_see()`

此方法用于滚动页面直到元素可见。

参数名称	类型	默认值	说明
`loc_or_ele`	`str` `tuple` `ChromiumElement`	必填	元素的定位信息，可以是元素、定位符
`center`	`bool`	`None`	是否尽量滚动到页面正中

返回：None

示例：

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

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

✅️️ 滚动设置

页面滚动有两种方式，一种是滚动时直接跳到目标位置，第二种是平滑滚动，须要一定时间。后者滚动时间难以确定，容易导致程序不稳定，点击不准确的问题。

一些网站会在 css 设置中指定网站使用平滑滚动，这是我们不希望的，但本着让开发者拥有充分选择权利的原则，本库没有强制修改，而是提供两项设置供开发者选择。

📌 `set.scroll.smooth()`

此方法设置网站是否开启平滑滚动。建议用此方法为网页关闭平滑滚动。

参数名称	类型	默认值	说明
`on_off`	`bool`	`True`	`bool`表示开或关

返回：None

示例：

page.set.scroll.smooth(on_off=False)

📌 `set.scroll.wait_complete()`

此方法用于设置滚动后是否等待滚动结束。在不想关闭网页平滑滚动功能时，可开启此设置以保障滚动结束后才执行后面的步骤

参数名称	类型	默认值	说明
`on_off`	`bool`	`True`	`bool`表示开或关

返回：None

示例：

page.set.scroll.smooth(on_off=True)

✅️️ 处理弹出消息

📌 `handle_alert()`

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

注意

程序不能接管一个已经弹出了提示框的浏览器。只有程序先运行，弹出框后出现，才能处理。

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

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

示例：

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

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

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

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

✅️️ 关闭浏览器

📌 `quit()`

此方法用于关闭浏览器。

参数： 无

返回：**None

page.quit()

🚤 页面交互

✅️️ 页面跳转

📌 get()

📌 back()

📌 forward()

📌 refresh()

📌 stop_loading()

✅️️ 各种等待

📌 wait.load_start()

📌 wait.load_complete()

📌 wait.ele_display()

📌 wait.ele_hidden()

📌 wait.ele_delete()

📌 wait.download_begin()

📌 wait.upload_paths_inputted()

📌 wait.new_tab()

✅️️ 等待和抓取数据包

📌 wait.set_targets()

📌 wait.data_packets()

📌 wait.stop_listening()

📌 ResponseData对象

📌 示例

✅️️ 元素管理

📌 remove_ele()

✅️️ 执行脚本或命令

📌 run_js()

📌 run_async_js()

📌 run_cdp()

📌 run_cdp_loaded()

✅️️ cookies 及缓存

📌 set.cookies()

📌 set.session_storage()

📌 set.local_storage()

📌 clear_cache()

✅️️ 运行参数设置

📌 set.retry_times()

📌 set.retry_interval()

📌 set.timeouts()

📌 set.load_strategy

📌 set.user_agent()

📌 set.headers()

✅️️ 窗口管理

📌 set.window.maximized()

📌 set.window.minimized()

📌 set.window.fullscreen()

📌 set.window.normal()

📌 set.window.size()

📌 set.window.location()

📌 set.window.hide()

📌 set.window.show()

✅️️ 滚动页面

📌 scroll.to_top()

📌 scroll.to_bottom()

📌 scroll.to_half()

📌 scroll.to_rightmost()

📌 scroll.to_leftmost()

📌 scroll.to_location()

📌 scroll.up()

📌 scroll.down()

📌 scroll.right()

📌 scroll.left()

📌 scroll.to_see()

✅️️ 滚动设置

📌 set.scroll.smooth()

📌 set.scroll.wait_complete()

✅️️ 处理弹出消息

📌 handle_alert()

✅️️ 关闭浏览器

📌 quit()

📌 `get()`

📌 `back()`

📌 `forward()`

📌 `refresh()`

📌 `stop_loading()`

📌 `wait.load_start()`

📌 `wait.load_complete()`

📌 `wait.ele_display()`

📌 `wait.ele_hidden()`

📌 `wait.ele_delete()`

📌 `wait.download_begin()`

📌 `wait.upload_paths_inputted()`

📌 `wait.new_tab()`

📌 `wait.set_targets()`

📌 `wait.data_packets()`

📌 `wait.stop_listening()`

📌 `ResponseData`对象

📌 `remove_ele()`

📌 `run_js()`

📌 `run_async_js()`

📌 `run_cdp()`

📌 `run_cdp_loaded()`

📌 `set.cookies()`

📌 `set.session_storage()`

📌 `set.local_storage()`

📌 `clear_cache()`

📌 `set.retry_times()`

📌 `set.retry_interval()`

📌 `set.timeouts()`

📌 `set.load_strategy`

📌 `set.user_agent()`

📌 `set.headers()`

📌 `set.window.maximized()`

📌 `set.window.minimized()`

📌 `set.window.fullscreen()`

📌 `set.window.normal()`

📌 `set.window.size()`

📌 `set.window.location()`

📌 `set.window.hide()`

📌 `set.window.show()`

📌 `scroll.to_top()`

📌 `scroll.to_bottom()`

📌 `scroll.to_half()`

📌 `scroll.to_rightmost()`

📌 `scroll.to_leftmost()`

📌 `scroll.to_location()`

📌 `scroll.up()`

📌 `scroll.down()`

📌 `scroll.right()`

📌 `scroll.left()`

📌 `scroll.to_see()`

📌 `set.scroll.smooth()`

📌 `set.scroll.wait_complete()`

📌 `handle_alert()`

📌 `quit()`