blackteay/DrissionPage
1
0
Fork 0
mirror of https://gitee.com/g1879/DrissionPage.git synced 2024-12-10 04:00:23 +08:00
Code Issues Projects Releases Wiki Activity
DrissionPage/docs/WebPage使用方法/3.7页面操作.md

13 KiB
Raw Blame History

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

✔️ 页面跳转

📍 get()

此方法用于跳转到一个 url，两种模式都支持，详细用法见“使用方法 -> 访问网页”章节。

参数：

  • url：目标 url
  • show_errmsg：是否显示和抛出异常，默认不抛出，连接错误会返回 None
  • retry：重试次数，与页面对象的设置一致，默认 3 次
  • interval：重试间隔（秒），与页面对象的设置一致，默认 2 秒
  • timeout：连接超时时间（秒）
  • **kwargs：s 模式用到的连接参数，具体见 requests 用法

返回：bool类型，表示是否连接成功

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类型，表示是否连接成功

page.post('https://xxxxxx', data=data)

📍 back()

此方法用于在浏览历史中后退若干步，d 模式独有。

参数：

  • steps：后退步数

返回：None

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

📍 forward()

此方法用于在浏览历史中前进若干步，d 模式独有。

参数：

  • steps：前进步数

返回：None

page.forward(2)  # 前进两步

📍 refresh()

此方法用于刷新当前页面，d 模式独有。

参数：

  • ignore_cache：刷新时是否忽略缓存

返回：None

page.refresh()  # 刷新页面

📍 stop_loading()

此方法用于强制当前页面加载，d 模式独有。

参数：无

返回：None

📍 wait_loading()

此方法用于等待页面进入加载状态，d 模式独有。

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

参数：

  • timeout：超时时间

返回： 等待结束时是否进入加载状态

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

✔️切换页面模式

📍 change_mode()

此方法是WebPage用于切换模式的方法。

切换后默认在目标模式重新跳转到原模式所在 url。

参数：

  • mode：目标模式字符串，'s'或'd'，默认转换到另一种
  • go：转换后是否跳转到原模式所在 url
  • copy_cookies：是否复制cookies到目标模式

返回：None

以下例子演示用浏览器登录 gitee 网站，再切换到 s 模式。可见 s 模式依然处于登录状态。

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]...

返回： 脚本执行结果

# 用传入参数的方式执行 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。

参数：

  • cmd：协议项目

  • **cmd_args：项目参数

返回： 该语句返回的值

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

✔️ cookies 及缓存

📍 set_cookies()

此方法用于对浏览器或Session对象设置 cookies，两种模式都支持。
可以接收CookieJar、list、tuple、str、dict格式的 cookies。

参数：

  • cookies：cookies 信息
  • set_session：是否设置到Session对象
  • set_driver：是否设置到浏览器

返回：None

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

📍 cookies_to_session()

此方法用于从浏览器复制 cookies 到Session对象。不会触发模式切换。

参数：

  • copy_user_agent：是否同时复制 user agent 信息

返回：None

page.cookies_to_session()

📍 cookies_to_driver()

此方法用于从Session对象复制 cookies 到浏览器。不会触发模式切换。

参数： 无

返回：None

📍 set_session_storage()

此方法用于设置或删除某项 sessionStorage 信息，d 模式独有。

参数：

  • item：要设置的项

  • value：项的值，设置为False时，删除该项

返回：None

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

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

✔️ 各种设置

📍 set_timeouts()

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

参数：

  • implicit：查找元素超时时间
  • page_load：页面加载超时时间
  • lscript：脚本运行超时时间

返回：None

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

📍 set_page_load_strategy

此属性用于设置页面加载策略，d 模式独有。

页面加载策略有三种：

  • normal：等待页面完全加载完成，为默认状态

  • eager：等待文档加载完成就结束，不等待资源加载

  • none：页面连接完成就结束

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

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) 屏幕坐标 设置位置 
# 窗口最大化
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

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) 滚动的像素 向右滚动若干像素，垂直位置不变 
# 页面滚动到底部
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

# 滚动到某个已获取到的元素
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

# 确认提示框并获取提示框文本
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

page.close_driver()

📍 close_session()

此方法用于关闭WebPage控制的Session对象，并切换到 d 模式。

参数： 无

**返回：**None

page.close_session()

📍quit()

此方法用于退出浏览器并且关闭 Session 对象。彻底关闭WebPage对象。

参数： 无

**返回：**None

page.quit()