【Drissionpage】ChromiumPage实用介绍

# 导入
from DrissionPage import ChromiumPage

# 创建对象
page = ChromiumPage()
# 访问网页
page.get('https://www.baidu.com')
# 输入文本
page('#kw').input('DrissionPage')
# 点击按钮
page('#su').click()
# 等待页面跳转
page.wait.load_start()
# 获取所有结果
links = page.eles('tag:h3')
# 遍历并打印结果
for link in links:
    print(link.text)

二、创建页面对象

ChromiumPage对象和WebPage对象的 d 模式都能控制浏览器，本节只介绍ChromiumPage的创建，在WebPage的章节再对其进行介绍。

用ChromiumPage()创建页面对象。根据不同的配置，可以接管已打开的浏览器，也可以启动新的浏览器。

程序结束时，被打开的浏览器不会主动关闭，以便下次运行程序时使用（由VSCode启动的会被关闭）。新手在使用无头模式时需注意，程序关闭后其实浏览器进程还在，只是看不见。

ChromiumPage和WebPage对象为单例，每个浏览器只能有一个该对象。对同一个浏览器重复使用ChromiumPage获取的都是同一个对象。

`2.1 ChromiumPage`初始化参数

初始化参数	类型	默认值	说明
`addr_or_opts`	`str` `int` `ChromiumOptions`	`None`	浏览器启动配置或接管信息。传入 'ip: port' 字符串、端口数字或`ChromiumOptions`对象时按配置启动或接管浏览器；为`None`时使用配置文件配置启动浏览器
`tab_id`	`str`	`None`	要控制的标签页 id，为`None`则控制激活的标签页
`timeout`	`float`	`None`	整体超时时间，为`None`则从配置文件中读取，默认`10`

2.2 直接创建

这种方式代码最简洁，程序会使用默认配置，自动生成页面对象。

from DrissionPage import ChromiumPage

page = ChromiumPage()

创建ChromiumPage对象时会在指定端口启动浏览器，或接管该端口已有浏览器。

默认情况下，程序使用 9222 端口，浏览器可执行文件路径为'chrome'。

如路径中没找到浏览器可执行文件，Windows 系统下程序会在注册表中查找路径。

如果都没找到，则要用下文介绍的手动配置方法。

直接创建时，程序默认读取 ini 文件配置，如 ini 文件不存在，会使用内置配置。

默认 ini 和内置配置信息详见“进阶使用->配置文件的使用”章节。

TIPS

您可以修改配置文件中的配置，实现所有程序都按您的需要进行启动，详见”启动配置“章节。

2.3 通过配置信息创建

如果需要已指定方式启动浏览器，可使用ChromiumOptions。它是专门用于设置浏览器初始状态的类，内置了常用的配置。详细使用方法见“浏览器启动配置”一节。

2.3.1 使用方法

ChromiumOptions用于管理创建浏览器时的配置，内置了常用的配置，并能实现链式操作。详细使用方法见“启动配置”一节。

初始化参数	类型	默认值	说明
`read_file`	`bool`	`True`	是否从 ini 文件中读取配置信息，如果为`False`则用默认配置创建
`ini_path`	`str`	`None`	文件路径，为`None`则读取默认 ini 文件

注意

配置对象只有在启动浏览器时生效。
浏览器创建后再修改这个配置是没有效果的。
接管已打开的浏览器配置也不会生效。

# 导入 ChromiumOptions
from DrissionPage import ChromiumPage, ChromiumOptions

# 创建浏览器配置对象，指定浏览器路径
co = ChromiumOptions().set_browser_path(r'D:\chrome.exe')
# 用该配置创建页面对象
page = ChromiumPage(addr_or_opts=co)

2.3.2 直接指定地址创建

ChromiumPage可以直接接收浏览器地址来创建，格式为 'ip:port'。

使用这种方式时，如果浏览器已存在，程序会直接接管；如不存在，程序会读取默认配置文件配置，在指定端口启动浏览器。

page = ChromiumPage(addr_or_opts='127.0.0.1:9333')

2.3.3 使用指定 ini 文件创建

以上方法是使用默认 ini 文件中保存的配置信息创建对象，你可以保存一个 ini 文件到别的地方，并在创建对象时指定使用它。

from DrissionPage import ChromiumPage, ChromiumOptions

# 创建配置对象时指定要读取的ini文件路径
co = ChromiumOptions(ini_path=r'./config1.ini')
# 使用该配置对象创建页面
page = ChromiumPage(addr_or_opts=co)

2.4 接管已打开的浏览器

页面对象创建时，只要指定的地址（ip: port）已有浏览器在运行，就会直接接管。无论浏览器是下面哪种方式启动的。

2.4.1 用程序启动的浏览器

默认情况下，创建浏览器页面对象时会自动启动一个浏览器。只要这个浏览器不关闭，下次运行程序时会接管同一个浏览器继续操作（配置的 ip: port 信息不变）。

这种方式极大地方便了程序的调试，使程序不必每次重新开始，可以单独调试某个功能。

from DrissionPage import ChromiumPage

# 创建对象同时启动浏览器，如果浏览器已经存在，则接管它
page = ChromiumPage()

2.4.2 手动打开的浏览器

如果需要手动打开浏览器再接管，可以这样做：

右键点击浏览器图标，选择属性
在“目标”路径后面加上 --remote-debugging-port=端口号 --remote-allow-origins=*（注意最前面有个空格）
点击确定
在程序中的浏览器配置中指定接管该端口浏览器

文件快捷方式的目标路径设置：

D:\chrome.exe --remote-debugging-port=9222 --remote-allow-origins=*

程序代码：

from DrissionPage import ChromiumPage, ChromiumOptions

co = ChromiumOptions().set_local_port(9222)
page = ChromiumPage(addr_or_opts=co)

注意

接管浏览器时只有local_port、address参数是有效的。

2.4.3 bat 文件启动的浏览器

可以把上一种方式的目标路径设置写进 bat 文件（Windows系统），运行 bat 文件来启动浏览器，再用程序接管。

新建一个文本文件，在里面输入以下内容（路径改为自己电脑的）：

"D:\chrome.exe" --remote-debugging-port=9222 --remote-allow-origins=*

保存后把后缀改成 bat，然后双击运行就能在 9222 端口启动一个浏览器。程序代码则和上一个方法一致。

2.5 多浏览器共存

如果想要同时操作多个浏览器，或者自己在使用其中一个上网，同时控制另外几个跑自动化，就需要给这些被程序控制的浏览器设置单独的端口和用户文件夹，否则会造成冲突。

2.5.1 指定独立端口和数据文件夹

每个要启动的浏览器使用一个独立的ChromiumOptions对象进行设置：

from DrissionPage import ChromiumPage, ChromiumOptions

# 创建多个配置对象，每个指定不同的端口号和用户文件夹路径
do1 = ChromiumOptions().set_paths(local_port=9111, user_data_path=r'D:\data1')
do2 = ChromiumOptions().set_paths(local_port=9222, user_data_path=r'D:\data2')

# 创建多个页面对象
page1 = ChromiumPage(addr_or_opts=do1)
page2 = ChromiumPage(addr_or_opts=do2)

# 每个页面对象控制一个浏览器
page1.get('https://www.baidu.com')
page2.get('http://www.163.com')

注意

每个浏览器都要设置独立的端口号和用户文件夹，二者缺一不可。

`2.5.2 auto_port()`方法

ChromiumOptions对象的auto_port()方法，可以指定程序每次使用空闲的端口和临时用户文件夹创建浏览器。也是每个浏览器要使用独立的ChromiumOptions对象。

但这种方法创建的浏览器不能重复使用。

TIPS

auto_port()支持多线程，但不支持多进程。
多进程使用时，可用scope参数指定每个进程使用的端口范围，以免发生冲突。

from DrissionPage import ChromiumPage, ChromiumOptions

co1 = ChromiumOptions().auto_port()
co2 = ChromiumOptions().auto_port()

page1 = ChromiumPage(addr_or_opts=co1)
page2 = ChromiumPage(addr_or_opts=co2)

page1.get('https://www.baidu.com')
page2.get('http://www.163.com')

2.5.3 在 ini 文件设置自动分配

可以把自动分配的配置记录到 ini 文件，这样无需创建ChromiumOptions，每次启动的浏览器都是独立的，不会冲突。但和auto_port()一样，这些浏览器也不能复用。

from DrissionPage import ChromiumOptions

ChromiumOptions().auto_port(True).save()

这段代码把该配置记录到 ini 文件，只需运行一次，要关闭的话把参数换成False再执行一次即可。

from DrissionPage import ChromiumPage

page1 = ChromiumPage()
page2 = ChromiumPage()

page1.get('https://www.baidu.com')
page2.get('http://www.163.com')

2.6 使用系统浏览器用户目录

初始默认配置下，程序会为每个使用的端口创建空的用户目录，并且每次接管都使用，这样可以有效避免浏览器冲突。

有些时候我们希望使用系统安装的浏览器的默认用户文件夹。以便复用用户信息和插件等。

我们可以这样设置：

2.6.1 使用`ChromiumOptions`

用ChromiumOptions在每次启动时配置。

from DrissionPage import ChromiumPage, ChromiumOptions

co = ChromiumOptions().use_system_user_path()
page = ChromiumPage(co)

2.6.2 使用 ini 文件

把这个配置记录到 ini 文件，就不用每次使用都配置。

from DrissionPage import ChromiumOptions

ChromiumOptions().use_system_user_path().save()

2.6.3 冲突的处理

假如和已打开的浏览器发生冲突，会弹出异常并提醒用户关闭浏览器。

DrissionPage.errors.BrowserConnectError: 
127.0.0.1:9222浏览器无法链接。
请确认：
1、该端口为浏览器
2、已添加'--remote-debugging-port=9222'启动项
3、用户文件夹没有和已打开的浏览器冲突
4、如为无界面系统，请添加'--headless=new'参数
5、如果是Linux系统，可能还要添加'--no-sandbox'启动参数
可使用ChromiumOptions设置端口和用户文件夹路径。

2.7 创建全新的浏览器

默认情况下，程序会复用之前用过的浏览器用户数据，因此可能带有登录数据、历史记录等。

如果想打开全新的浏览器，可用以下方法：

2.7.1 使用`auto_port()`

上文提过的auto_port()方法，设置后每次打开的浏览器都是全新的。

示例见上文。

2.7.2 手动指定端口和路径

给浏览器用户文件夹路径指定空的路径，以及指定一个空闲的端口，即可打开全新浏览器。

from DrissionPage import ChromiumPage, ChromiumOptions

co = ChromiumOptions().set_local_port(9333).set_user_data_path(r'C:\tmp')
page = ChromiumPage(co)

三、访问网页

ChromiumPage对象和WebPage对象的 d 模式都能控制浏览器访问网页。这里只对ChromiumPage进行说明，后面章节再单独介绍WebPage。

`3.1 get()`

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

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

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

示例：

from DrissionPage import ChromiumPage

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

3.2 设置超时和重试

网络不稳定时，访问页面不一定成功，get()方法内置了超时和重试功能。通过retry、interval、timeout三个参数进行设置。
其中，如不指定timeout参数，该参数会使用ChromiumPage的timeouts属性的page_load参数中的值。

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.get('https://g1879.gitee.io/drissionpagedocs', retry=1, interval=1, timeout=1.5)

3.3 加载模式

3.3.1 概述

加载模式是指程序在页面加载阶段的行为模式，有以下三种：

normal()：常规模式，会等待页面加载完毕，超时自动重试或停止，默认使用此模式
eager()：加载完 DOM 或超时即停止加载，不加载页面资源
none()：超时也不会自动停止，除非加载完成

前两种模式下，页面加载过程会阻塞程序，直到加载完毕才执行后面的操作。

none()模式下，只在连接阶段阻塞程序，加载阶段可自行根据情况执行stop_loading()停止加载。

这样提供给用户非常大的自由度，可等到关键数据包或元素出现就主动停止页面加载，大幅提升执行效率。

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.set.load_mode.eager()
page.get('https://g1879.gitee.io/drissionpagedocs')

3.3.2 模式设置

可通过 ini 文件、ChromiumOptions对象和页面对象的set.load_mode.xxxx()方法进行设置。

运行时可随时动态设置。

配置对象中设置

from DrissionPage import ChromiumOptions, ChromiumPage

co = ChromiumOptions().set_load_mode('none')
page = ChromiumPage(co)

运行中设置

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.set.load_mode.none()

`3.3.3 none`模式技巧

示例 1，配合监听器

跟监听器配合，可在获取到需要的数据包时，主动停止加载。

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.set.load_mode.none()  # 设置加载模式为none

page.listen.start('api/getkeydata')  # 指定监听目标并启动监听
page.get('http://www.hao123.com/')  # 访问网站
packet = page.listen.wait()  # 等待数据包
page.stop_loading()  # 主动停止加载
print(packet.response.body)  # 打印数据包正文

示例 2，配合元素查找

跟元素查找配合，可在获取到某个指定元素时，主动停止加载。

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.set.load_mode.none()  # 设置加载模式为none

page.get('http://www.hao123.com/')  # 访问网站
ele = page.ele('中国日报')  # 查找text包含“中国日报”的元素
page.stop_loading()  # 主动停止加载
print(ele.text)  # 打印元素text

示例 2，配合页面特征

可等待到页面到达某种状态时，主动停止加载。比如多级跳转的登录，可等待 title 变化到最终目标网址时停止。

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.set.load_mode.none()  # 设置加载模式为none

page.get('http://www.hao123.com/')  # 访问网站
page.wait.title_change('hao123')  # 等待title变化出现目标文本
page.stop_loading()  # 主动停止加载

四、获取网页信息

成功访问网页后，可使用ChromiumPage自身属性和方法获取页面信息。

操控浏览器除了ChromiumPage，还有ChromiumTab和ChromiumFrame两种页面对象分别对应于标签页对象和<iframe>元素对象，后面会有单独章节介绍。

4.1 页面信息

`4.1.1 html`

此属性返回当前页面 html 文本。

返回类型：str

4.1.2 `json`

此属性把请求内容解析成 json。

假如用浏览器访问会返回 *.json 文件的 url，浏览器会把 json 数据显示出来，这个参数可以把这些数据转换为dict格式。

如果是API返回的json字符串，请使用 SessionPage 对象而不是 ChromiumPage。

返回类型：dict

4.1.3 `title`

此属性返回当前页面title文本。

返回类型：str

4.1.4 `user_agent`

此属性返回当前页面 user agent 信息。

返回类型：str

`4.1.5 save()`

把当前页面保存为文件，同时返回保存的内容。

如果path和name参数都为None，只返回内容，不保存文件。

Page 对象和 Tab 对象有这个方法。

参数名称	类型	默认值	说明
`path`	`str` `Path`	`None`	保存路径，为`None`且`name`不为`None`时保存到当前路径
`name`	`str`	`None`	保存的文件名，为`None`且`path`不为`None`时使用 title 值
`as_pdf`	`bool`	`False`	为`Ture`保存为 pdf，否则保存为 mhtml 且忽略`kwargs`参数
`**kwargs`	多种	无	pdf 生成参数

pdf 生成参数包括：landscape, displayHeaderFooter, printBackground, scale, paperWidth, paperHeight, marginTop, marginBottom, marginLeft, marginRight, pageRanges, headerTemplate, footerTemplate, preferCSSPageSize, generateTaggedPDF, generateDocumentOutline

返回类型	说明
`str`	`as_pdf`为`False`时返回 mhtml 文本
`bytes`	`as_pdf`为`True`时返回文件字节数据

4.2 运行状态信息

`4.2.1 url`

此属性返回当前访问的 url。

返回类型：str

4.2.2 `address`

此属性返回当前对象控制的页面地址和端口。

返回类型：str

print(page.address)

输出：

127.0.0.1:9222

4.2.3 `tab_id`

返回类型：str

此属性返回当前标签页的 id。

4.2.4 `process_id`

此属性返回浏览器进程 id。

返回类型：int、None

4.2.5 `states.is_loading`

此属性返回页面是否正在加载状态。

返回类型：bool

4.2.6 `states.is_alive`

此属性返回页面是否仍然可用，标签页已关闭则返回False。

返回类型：bool

4.2.7 `states.ready_state`

此属性返回页面当前加载状态，有 4 种：

'connecting'：网页连接中
'loading'：表示文档还在加载中
'interactive'：DOM 已加载，但资源未加载完成
'complete'：所有内容已完成加载

返回类型：str

4.2.8 `url_available`

此属性以布尔值返回当前链接是否可用。

返回类型：bool

4.2.9 `states.has_alert`

此属性以布尔值返回页面是否存在弹出框。

返回类型：bool

4.3 窗口信息

4.3.1 `size`和`rect.page_size`

这两个属性是一样的，以tuple返回页面大小，格式：(宽, 高)。

返回类型：Tuple[int, int]

4.3.2 `rect.window_size`

此属性以tuple返回窗口大小，格式：(宽, 高)。

返回类型：Tuple[int, int]

4.3.3 `rect.window_location`

此属性以tuple返回窗口在屏幕上的坐标，左上角为(0, 0)。

返回类型：Tuple[int, int]

4.3.4 `rect.window_state`

此属性以返回窗口当前状态，有'normal'、'fullscreen'、'maximized'、 'minimized'几种。

返回类型：str

4.3.5 `rect.viewport_size`

此属性以tuple返回视口大小，不含滚动条，格式：(宽, 高)。

返回类型：Tuple[int, int]

4.3.6 `rect.viewport_size_with_scrollbar`

此属性以tuple返回浏览器窗口大小，含滚动条，格式：(宽, 高)。

返回类型：Tuple[int, int]

4.3.6 `rect.page_location`

此属性以tuple返回页面左上角在屏幕中坐标，左上角为(0, 0)。

返回类型：Tuple[int, int]

4.3.7 `rect.viewport_location`

此属性以tuple返回视口在屏幕中坐标，左上角为(0, 0)。

返回类型：Tuple[int, int]

4.4 配置参数信息

4.4.1 `timeout`

此属性为整体默认超时时间，包括元素查找、点击、处理提示框、列表选择等需要用到超时设置的地方，都以这个数据为默认值。
默认为 10，可对其赋值。

返回类型：int、float

# 创建页面对象时指定
page = ChromiumPage(timeout=5)

# 修改 timeout
page.timeout = 20

4.4.2 `timeouts`

此属性以字典方式返回三种超时时间。

'base'：与timeout属性是同一个值
'page_load'：用于等待页面加载
'script'：用于等待脚本执行

返回类型：dict

print(page.timeouts)

输出：

{'base': 10, 'page_load': 30.0, 'script': 30.0}

4.4.3 `retry_times`

此属性为网络连接失败时的重试次数。默认为 3，可对其赋值。

返回类型：int

# 修改重试次数
page.retry_times = 5

4.4.5 `retry_interval`

此属性为网络连接失败时的重试等待间隔秒数。默认为 2，可对其赋值。

返回类型：int、float

# 修改重试等待间隔时间
page.retry_interval = 1.5

4.4.6 `load_mode`

此属性返回页面加载策略，有 3 种：

'normal'：等待页面所有资源完成加载
'eager'：DOM 加载完成即停止
'none'：页面完成连接即停止

返回类型：str

4.5 cookies 和缓存信息

4.5.1 `cookies()`

此方法返回 cookies 信息。

参数名称	类型	默认值	说明
`as_dict`	`bool`	`False`	是否以字典方式返回结果。为`True`时返回由`{name: value}`键值对组成的`dict`，且`all_info`参数无效；为`False`返回 cookie 组成的`list`
`all_domains`	`bool`	`False`	是否返回所有 cookies，为`False`只返回当前 url 的
`all_info`	`bool`	`False`	返回的 cookies 是否包含所有信息，`False`时只包含`name`、`value`、`domain`信息

返回类型	说明
`dict`	`as_dict`为`True`时，返回字典格式 cookies
`list`	`as_dict`为`False`时，返回 cookies 组成的列表

示例：

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.get('http://www.baidu.com')

for i in page.cookies(as_dict=False):
    print(i)

输出：

{'domain': '.baidu.com', 'domain_specified': True, ......}
......

4.5.2 `session_storage()`

此方法用于获取 sessionStorage 信息，可获取全部或单个项。

参数名称	类型	默认值	说明
`item`	`str`	`None`	要获取的项目，为`None`则返回全部项目组成的字典

返回类型	说明
`dict`	`item`参数为`None`时返回所有项目
`str`	指定`item`时返回该项目内容

4.5.3 `local_storage()`

此方法用于获取 localStorage 信息，可获取全部或单个项。

参数名称	类型	默认值	说明
`item`	`str`	`None`	要获取的项目，为`None`则返回全部项目组成的字典

返回类型	说明
`dict`	`item`参数为`None`时返回所有项目
`str`	指定`item`时返回该项目内容

4.6 内嵌对象

4.6.1 `driver`

此属性返回当前页面对象使用的Driver对象。

返回类型：Driver

`五、页面交互`

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

一个 Tab 对象（ChromiumTab和WebPageTab）控制一个浏览器的标签页，是页面控制的主要单位。

ChromiumPage和WebPage也控制一个标签页，只是它们增加了一些浏览器总体控制功能。

下面介绍的功能，除了关闭浏览器，Tab 对象都可使用。

5.1 页面跳转

5.1.1 `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')

5.1.2 `back()`

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

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

返回：None

示例：

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

5.1.3 `forward()`

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

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

返回：None

page.forward(2)  # 前进两步

5.1.4 `refresh()`

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

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

返回：None

示例：

page.refresh()  # 刷新页面

5.1.5 `stop_loading()`

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

参数： 无

返回：None

5.1.6 `set.blocked_urls()`

此方法用于设置忽略的连接。

参数名称	类型	默认值	说明
`urls`	`str` `list` `tuple` `None`	必填	要忽略的 url，可传入多个，可用`'*'`通配符，传入`None`时清空已设置的项

返回：None

示例：

page.set.blocked_urls('*.css*')  # 设置不加载css文件

5.2 元素管理

5.2.1 `add_ele()`

此方法用于插入一个元素。

参数名称	类型	默认值	说明
`outerHTML`	`str`	必填	新元素的 html 文本
`insert_to`	`str` `ChromiumElement` `Tuple[str, str]`	`None`	插入到哪个元素中，可接收元素对象和定位符，为`None`添加到` body
`before`	`str` `ChromiumElement` `Tuple[str, str]`	`None`	在哪个子节点前面插入，可接收对象和定位符，为`None`插入到父元素末尾

返回类型	说明
`ChromiumElement`	新建的元素对象

5.2.2 `remove_ele()`

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

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

返回：None

示例：

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

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

5.3 执行脚本或命令

5.3.1 `run_js()`

此方法用于执行 js 脚本。

参数名称	类型	默认值	说明
`script`	`str`	必填	js 脚本文本或脚本文件路径
`*args`	-	无	传入的参数，按顺序在js文本中对应`arguments[0]`、`arguments[1]`...
`as_expr`	`bool`	`False`	是否作为表达式运行，为`True`时`args`参数无效
`timetout`	`float`	`None`	js 超时时间，为`None`则使用页面`timeouts.script`设置

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

示例：

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

注意

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

5.3.2 `run_js_loaded()`

此方法用于运行 js 脚本，执行前等待页面加载完毕。

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

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

5.3.3 `run_async_js()`

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

参数：

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

返回：None

5.3.4 `run_cdp()`

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

cdp 用法详见 Chrome DevTools Protocol。

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

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

示例：

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

5.3.5 `run_cdp_loaded()`

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

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

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

5.4 cookies 及缓存

5.4.1 `set.cookies()`

此方法用于设置 cookie。

可以接收CookieJar、list、tuple、str、dict格式的 cookies。注意本方法没有后面两种方法的 item、value 参数。

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

返回：None

示例：

# 可以接受多种类型的参数
cookies1 = ['name1=value1', 'name2=value2'],
cookies2 = ('name1=value1', 'name2=value2', 'secure')
cookies3 = 'name1=value1; name2=value2; path=/; domain=.example.com; secure'
cookies4 = {'name1': 'value1', 'name2': 'value2'}
page.set.cookies(cookies1)

5.4.2 `set.cookies.clear()`

此方法用于清除所有 cookie。

参数： 无

返回：None

5.4.3 `set.cookies.remove()`

此方法用于删除一个 cookie。

参数名称	类型	默认值	说明
`name`	`str`	必填	cookie 的 name 字段
`url`	`str`	`None`	cookie 的 url 字段
`domain`	`str`	`None`	cookie 的 domain 字段
`path`	`str`	`None`	cookie 的 path 字段

返回：None

5.4.4 `set.session_storage()`

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

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

返回：None

示例：

page.set.session_storage(item='abc', value='123')

5.4.5 `set.local_storage()`

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

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

返回：None

5.4.6 `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，其它都清除

5.5 运行参数设置

各种设置功能藏在set属性中。

5.5.1 `set.retry_times()`

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

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

返回：None

5.5.2 `set.retry_interval()`

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

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

返回：None

5.5.3 `set.timeouts()`

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

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

返回：None

示例：

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

5.5.4 `set.load_strategy`

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

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

示例：

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

5.5.5 `set.user_agent()`

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

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

返回：None

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

5.6 窗口管理

窗口管理功能藏在set.window属性中。

5.6.1 `set.window.max()`

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

参数： 无

返回：None

示例：

page.set.window.max()

5.6.2 `set.window.mini()`

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

参数： 无

返回：None

5.6.3 `set.window.full()`

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

参数： 无

返回：None

5.6.4 `set.window.normal()`

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

参数： 无

返回：None

5.6.5 `set.window.size()`

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

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

返回：None

示例：

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

5.6.6 `set.window.location()`

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

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

返回：None

示例：

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

5.6.7 `set.window.hide()`

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

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

不过，窗口隐藏后，如果有新窗口出现，整个浏览器又会显现出来。

参数： 无

返回：None

示例：

page.set.window.hide()

注意

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

5.6.7 `set.window.show()`

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

参数： 无

返回：None

5.7 页面滚动

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

5.7.1 `scroll.to_top()`

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

参数： 无

返回：None

示例：

page.scroll.to_top()

5.7.2 `scroll.to_bottom()`

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

参数： 无

返回：None

5.7.3 `scroll.to_half()`

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

参数： 无

返回：None

5.7.4 `scroll.to_rightmost()`

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

参数： 无

返回：None

5.7.5 `scroll.to_leftmost()`

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

参数： 无

返回：None

5.7.6 `scroll.to_location()`

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

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

返回：None

示例：

page.scroll.to_location(300, 50)

5.7.7 `scroll.up()`

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

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

返回：None

示例：

page.scroll.up(30)

5.7.8 `scroll.down()`

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

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

返回：None

5.7.9 `scroll.right()`

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

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

返回：None

5.7.10 `scroll.left()`

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

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

返回：None

5.7.11 `scroll.to_see()`

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

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

返回：None

示例：

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

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

5.8 滚动设置

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

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

5.8.1 `set.scroll.smooth()`

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

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

返回：None

示例：

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

5.8.2 `set.scroll.wait_complete()`

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

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

返回：None

示例：

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

5.9 弹出消息处理

5.9.1 `handle_alert()`

此方法用于处理提示框。
它能够设置等待时间，等待提示框出现才进行处理，若超时没等到提示框，返回False。
也可只获取提示框文本而不处理提示框。还可以处理下一个出现的提示框，这在处理离开页面时触发的弹窗非常有用。

注意

程序无法接管一个已经弹出了提示框的浏览器或标签页。

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

返回类型	说明
`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)

5.9.2 自动处理

可使用set.auto_handle_alert()方法设置自动处理提示框，使提示框不会弹窗而直接被处理掉。

参数名称	类型	默认值	说明
`on_off`	`bool`	`True`	`bool`表示开或关
`accept`	`bool`	`True`	`bool`表示确定还是取消

返回：None

示例：

from DrissionPage import ChromiumPage

p = ChromiumPage()
p.set.auto_handle_alert()  # 这之后出现的弹窗都会自动确认

5.10 关闭及重连

5.10.1 `disconnect()`

此方法用于页面对象断开与页面的连接，但不关闭标签页。断开后，对象不能对标签页进行操作。

Page、Tab 和ChromiumFrame对象都有此方法。

值得注意的是，Page 对象断开和浏览器的连接后，仍能进行标签页的管理。

参数： 无

返回：None

5.10.2 `reconnect()`

此方法用于关闭与页面连接，然后重建一个新连接。

这主要用于应付长期运行导致内存占用过高，断开连接可释放内存，然后重连继续控制浏览器。

Page、Tab 和ChromiumFrame对象都有此方法。

参数名称	类型	默认值	说明
`wait`	`float`	`0`	关闭后等待多少秒再连接

返回：None

5.10.3 `quit()`

此方法用于关闭浏览器。

参数名称	类型	默认值	说明
`timeout`	`float`	`5`	等待浏览器关闭超时时间（秒）
`force`	`bool`	`True`	关闭超时是否强制终止进程

返回：None

`六、获取元素信息`

浏览器元素对应的对象是ChromiumElement和ShadowRoot，本节介绍获取到元素对象后，如何获取其信息。

ChromiumElement拥有SessionElement所有属性，并有更多浏览器专属的信息。本节重点介绍如何获取浏览器专有的元素信息。

6.1 与`SessionElement`共有信息

此处仅列出列表，具体用法请查看收发数据包部分的“获取元素信息”。

属性或方法	说明
`html`	此属性返回元素的 outerHTML 文本
`inner_html`	此属性返回元素的 innerHTML 文本
`tag`	此属性返回元素的标签名
`text`	此属性返回元素内所有文本组合成的字符串
`raw_text`	此属性返回元素内原始文本
`texts()`	此方法返回元素内所有直接子节点的文本，包括元素和文本节点
`comments`	此属性以列表形式返回元素内的注释
`attrs`	此属性以字典形式返回元素所有属性及值
`attre()`	此方法返回元素某个 attribute 属性值
`link`	此方法返回元素的 href 属性或 src 属性
`page`	此属性返回元素所在的页面对象
`xpath`	此属性返回当前元素在页面中 xpath 的绝对路径
`css_path`	此属性返回当前元素在页面中 css selector 的绝对路径

6.2 大小和位置

6.2.1 `rect.size`

此属性以元组形式返回元素的大小。

类型：Tuple[float, float]

size = ele.rect.size
# 返回：(50, 50)

6.2.2 `rect.location`

此属性以元组形式返回元素左上角在整个页面中的坐标。

类型：Tuple[float, float]

loc = ele.rect.location
# 返回：(50, 50)

6.2.3 `rect.midpoint`

此属性以元组形式返回元素中点在整个页面中的坐标。

类型：Tuple[float, float]

loc = ele.rect.midpoint
# 返回：(55, 55)

6.2.4 `rect.click_point`

此属性以元组形式返回元素点击点在整个页面中的坐标。

点击点是指click()方法点击时的位置，位于元素中上部。

类型：Tuple[float, float]

6.2.5 `rect.viewport_location`

此属性以元组形式返回元素左上角在当前视口中的坐标。

类型：Tuple[float, float]

6.2.6 `rect.viewport_midpoint`

此属性以元组形式返回元素中点在当前视口中的坐标。

类型：Tuple[floatt, float]

6.2.7 `rect.viewport_click_point`

此属性以元组形式返回元素点击点在当前视口中的坐标。

类型：Tuple[float, float]

6.2.8 `rect.screen_location`

此属性以元组形式返回元素左上角在屏幕中的坐标。

类型：Tuple[float, float]

6.2.9 `rect.screen_midpoint`

此属性以元组形式返回元素中点在屏幕中的坐标。

类型：Tuple[float, float]

6.2.10 `rect.screen_click_point`

此属性以元组形式返回元素点击点在屏幕中的坐标。

类型：Tuple[float, float]

6.2.11 `rect.corners`

此属性以列表形式返回元素四个角在页面中的坐标，顺序：左上、右上、右下、左下。

类型：((float, float), (float, float), (float, float), (float, float),)

6.2.12 `rect.viewport_corners`

此属性以列表形式返回元素四个角在视口中的坐标，顺序：左上、右上、右下、左下。

类型：list[(float, float), (float, float), (float, float), (float, float)]

6.2.13 `rect.viewport_rect`

此属性以列表形式返回元素四个角在视口中的坐标，顺序：左上、右上、右下、左下。

类型：List[(float, float), (float, float), (float, float), (float, float)]

6.3 属性和内容

6.3.1 `pseudo.before`

此属性以文本形式返回当前元素的::before伪元素内容。

类型：str

before_txt = ele.pseudo.before

6.3.2 `pseudo.after`

此属性以文本形式返回当前元素的::after伪元素内容。

类型：str

after_txt = ele.pseudo.after

6.3.3 `style()`

该方法返回元素 css 样式属性值，可获取伪元素的属性。它有两个参数，style参数输入样式属性名称，pseudo_ele 参数输入伪元素名称，省略则获取普通元素的 css 样式属性。

参数名称	类型	默认值	说明
`style`	`str`	必填	样式名称
`pseudo_ele`	`str`	`''`	伪元素名称（如有）

返回类型	说明
`str`	样式属性值

示例：

# 获取 css 属性的 color 值
prop = ele.style('color')

# 获取 after 伪元素的内容
prop = ele.style('content', 'after')

6.3.4 `property()`

此方法返回property属性值。它接收一个字符串参数，返回该参数的属性值。

参数名称	类型	默认值	说明
`name`	`str`	必填	属性名称

返回类型	说明
`str`	属性值

6.3.5 `shadow_root`

此属性返回元素内的 shadow-root 对象，没有的返回None。

类型：ShadowRoot

6.4 状态信息

状态信息藏在states属性中。

6.4.1 `states.is_in_viewport`

此属性以布尔值方式返回元素是否在视口中，以元素可以接受点击的点为判断。

类型：bool

6.4.2 `states.is_whole_in_viewport`

此属性以布尔值方式返回元素是否整个在视口中。

类型：bool

6.4.3 `states.is_alive`

此属性以布尔值形式返回当前元素是否仍可用。用于判断 d 模式下是否因页面刷新而导致元素失效。

类型：bool

6.4.4 `states.is_checked`

此属性以布尔值返回表单单选或多选元素是否选中。

类型：bool

6.4.5 `states.is_selected`

此属性以布尔值返回<select>元素中的项是否选中。

类型：bool

6.4.6 `states.is_enabled`

此属性以布尔值返回元素是否可用。

类型：bool

6.4.7 `states.is_displayed`

此属性以布尔值返回元素是否可见。

类型：bool

6.4.8 `states.is_covered`

此属性返回元素是否被其它元素覆盖。如被覆盖，返回覆盖元素的 id，否则返回False

返回类型	说明
`False`	未被覆盖，返回`False`
`int`	被覆盖时返回覆盖元素的 id

6.4.9 `states.has_rect`

此属性返回元素是否拥有大小和位置信息，有则返回四个角在页面上的坐标组成的列表，没有则返回False。

返回类型	说明
`list`	存在大小和位置信息时，以[(int, int), ...] 格式返回元素四个角的坐标，顺序：左上、右上、右下、左下
`False`	不存在时返回`False`

6.5 保存和截图

保存功能是本库一个特色功能，可以直接读取浏览器缓存，无需依赖另外的 ui 库或重新下载就可以保存页面资源。

作为对比，selenium 无法自身实现图片另存，往往需要通过使用 ui 工具进行辅助，不仅效率和可靠性低，还占用键鼠资源。

6.5.1 `src()`

此方法用于返回元素src属性所使用的资源。base64 的可转为bytes返回，其它的以str返回。无资源的返回None。

例如，可获取页面上图片字节数据，用于识别内容，或保存到文件。<script>标签也可获取 js 文本。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	等待资源加载超时时间，为`None`时使用元素所在页面`timeout`属性
`base64_to_bytes`	`bool`	`True`	为`True`时，如果是 base64 数据，转换为`bytes`格式

返回类型	说明
`str`	资源字符串
`None`	无资源的返回`None`

示例：

img = page('tag:img')
src = img.src()

6.5.2 `save()`

此方法用于保存src()方法获取到的资源到文件。

参数名称	类型	默认值	说明
`path`	`str` `Path`	`None`	文件保存路径，为`None`时保存到当前文件夹
`name`	`str`	`None`	文件名称，需包含后缀，为`None`时从资源 url 获取
`timeout`	`float`	`None`	等待资源加载超时时间，为`None`时使用元素所在页面`timeout`属性

返回类型	说明
`str`	保存路径

示例：

img = page('tag:img')
img.save('D:\\img.png')

6.6 `ShadowRoot`属性

本库把 shadow dom 的root看作一个元素处理，可以获取属性，也可以执行其下级的查找，使用逻辑与ChromiumElement 一致，但属性较之少，有如下这些：

6.6.1 `tag`

此属性返回元素标签名，即'shadow-root'。

类型：str

6.6.2 `html`

此属性返回shadow_root的 html 文本，由<shadow_root></shadow_root> 标签包裹。

类型：str

6.6.3 `inner_html`

此属性返回shadow_root内部的 html 文本。

类型：str

6.6.4 `page`

此属性返回元素所在页面对象。

类型：ChromiumPage、ChromiumTab、ChromiumFrame、WebPage

6.6.5 `parent_ele`

此属性返回所依附的普通元素对象。

类型：ChromiumElement

6.6.6 `states.is_enabled`

与ChromiumElement一致。

类型：bool

6.6.7 `states.is_alive`

与ChromiumElement一致。

类型：bool

6.7 比较元素

两个元素对象可以用==来比较，以判断它们是否指向同一个元素。

示例：

ele1 = page('t:div')
ele2 = page('t:div')
print(ele1==ele2)  # 输出True

七、元素交互

本节介绍与浏览器元素的交互。浏览器元素对象为ChromiumElement。

7.1 点击元素

7.1.1 `click()`和`click.left()`

这两个方法作用是一样的，用于左键点击元素。可选择模拟点击或 js 点击。

参数名称	类型	默认值	说明
`by_js`	`bool`	`False`	指定点击行为方式。为`None`时，如不被遮挡，用模拟点击，否则用 js 点击为`True`时直接用 js 点击；为`False`时强制模拟点击，被遮挡也会进行点击
`timeout`	`float`	`1.5`	模拟点击的超时时间，等待元素可见、可用、进入视口
`wait_stop`	`bool`	`True`	点击前是否等待元素停止运动

返回值	说明
`False`	`by_js`为`False`，且元素不可用、不可见时，返回`False`
`True`	除以上情况，其余情况都返回`True`

示例：

# 对ele元素进行模拟点击，如判断被遮挡也会点击
ele.click()

# 用js方式点击ele元素，无视遮罩层
ele.click(by_js=True)

# 如元素不被遮挡，用模拟点击，否则用js点击
ele.click(by_js=None)

默认情况下，by_js为None，优先用模拟方式点击，如遇遮挡、元素不可用、不可见、无法自动进入视口，等待直到超时后自动改用 js 方式点击。

by_js为False，程序会强制使用模拟点击，即使被遮挡也会点击元素位置。如果元素不可见、不可用，会返回False。如元素无法自动滚动到视口，会改用 js 点击。

by_js为True时，则可无视任何遮挡，只要元素在 DOM 内，就能点击得到，但元素是否响应点击视网页所用架构而定。

可以根据需要灵活地对元素进行操作。

在模拟点击前，程序会先尝试把元素滚动到视口中。

默认情况下，如无法进行模拟点击（元素无法进入视口、不可用、隐藏）时，左键单击会返回False。但也可以通过全局设置使其抛出异常：

from DrissionPage.common import Settings

Settings.raise_click_failed = True
ele.click()  # 如无法点击则抛出异常

7.1.2 `click.right()`

此方法实现右键单击元素。

参数： 无

返回：None

示例：

ele.click.right()

7.1.3 `click.middle()`

此方法实现中键单击元素。

参数： 无

返回：None

示例：

ele.click.middle()

7.1.4 `click.multi()`

此方法实现左键多次点击元素。

参数名称	类型	默认值	说明
`times`	`int`	`2`	点击次数

返回：None

7.1.5 `click.at()`

此方法用于带偏移量点击元素，偏移量相对于元素左上角坐标。不传入offset_x和offset_y时点击元素中间点。
点击的目标不一定在元素上，可以传入负值，或大于元素大小的值，点击元素附近的区域。向右和向下为正值，向左和向上为负值。

参数名称	类型	默认值	说明
`offset_x`	`float`	`None`	相对元素左上角坐标的 x 轴偏移量，向下向右为正
`offset_y`	`float`	`None`	相对元素左上角坐标的 y 轴偏移量，向下向右为正
`button`	`str`	`'left'`	要点击的键，传入`'left'`、`'right'`、`'middle'`、`'back'`、`'forward'`
`count`	`int`	`1`	点击次数

返回：None

示例：

# 点击元素右上方 50*50 的位置
ele.click.at(50, -50)

# 点击元素上中部，x相对左上角向右偏移50，y保持在元素中点
ele.click.at(offset_x=50)

# 和click()一致，但没有重试功能
ele.click.at()

7.1.6 `click.to_upload()`

此方法用于点击元素，触发文件选择框并把指定的文件路径添加到网页，详见“文件上传”章节。

参数名称	类型	默认值	说明
`file_paths`	`str` `list` `tuple`	必填	文件路径，如果上传框支持多文件，可传入列表或字符串，字符串时多个文件用`\n`分隔
`by_js`	`bool`	`False`	是否用 js 方式点击，逻辑与`click()`一致

返回：None

7.1.7 `click.to_download()`

此方法用于点击元素触发下载，并返回下载任务对象。用法详见“文件下载”章节。

参数名称	类型	默认值	说明
`save_path`	`str` `Path`	必填	保存路径，为`None`保存在原来设置的，如未设置保存到当前路径
`rename`	`str`	`None`	重命名文件名，为`None`则不修改
`suffix`	`str`	`'left'`	指定文件后缀，为`None`则不修改
`new_tab`	`bool`	`1`	该下载是否在新 tab 中触发
`by_js`	`bool`	`False`	是否用 js 方式点击，逻辑与`click()`一致

返回类型	说明
`DownloadMission`	下载任务对象

7.2 输入内容

7.2.1 `clear()`

此方法用于清空元素文本，可选择模拟按键或 js 方式。

模拟按键方式会自动输入ctrl-a-del组合键来清除文本框，js 方式则直接把元素value属性设置为''。

参数名称	类型	默认值	说明
`by_js`	`bool`	`False`	是否用 js 方式清空

返回：None

示例：

ele.clear()

7.2.2 `input()`

此方法用于向元素输入文本或组合键，也可用于输入文件路径到上传控件。可选择输入前是否清空元素。

参数名称	类型	默认值	说明
`vals`	`Any`	`False`	文本值或按键组合对文件上传控件时输入路径字符串或其组成的列表
`clear`	`bool`	`True`	输入前是否清空文本框
`by_js`	`bool`	`False`	是否用 js 方式输入，为`True`时不能输入组合键

返回：None

TIPS

有些文本框可以接收回车代替点击按钮，可以直接在文本末尾加上'\n'。
会自动把非str数据转换为str。

示例：

# 输入文本
ele.input('Hello world!')

# 输入文本并回车
ele.input('Hello world!\n')

7.2.3 输入组合键

使用组合键或要传入特殊按键前，先要导入按键类Keys。

from DrissionPage.common import Keys

然后将组合键放在一个tuple中传入input()即可。

ele.input((Keys.CTRL, 'a', Keys.DEL))  # ctrl+a+del

7.2.4 `focus()`

此方法用于使元素获取焦点。

参数： 无

返回： None

7.3 拖拽和悬停

TIPS

除了以下方法，本库还提供更灵活的动作链功能，详见后面章节。

7.3.1 `drag()`

此方法用于拖拽元素到相对于当前的一个新位置，可以设置速度。

参数名称	类型	默认值	说明
`offset_x`	`int`	`0`	x 轴偏移量，向下向右为正
`offset_y`	`int`	`0`	y 轴偏移量，向下向右为正
`duration`	`float`	`0.5`	用时，单位秒，传入`0`即瞬间到达

返回：None

示例：

# 拖动当前元素到距离50*50的位置，用时1秒
ele.drag(50, 50, 1)

7.3.2 `drag_to()`

此方法用于拖拽元素到另一个元素上或一个坐标上。

参数名称	类型	默认值	说明
`ele_or_loc`	`ChromiumElement` `Tuple[int, int]`	必填	另一个元素对象或坐标元组
`duration`	`float`	`0.5`	用时，单位秒，传入`0`即瞬间到达

返回：None

示例：

# 把 ele1 拖拽到 ele2 上
ele1 = page.ele('#div1')
ele2 = page.ele('#div2')
ele1.drag_to(ele2)

# 把 ele1 拖拽到网页 50, 50 的位置
ele1.drag_to((50, 50))

7.3.3 `hover()`

此方法用于模拟鼠标悬停在元素上，可接受偏移量，偏移量相对于元素左上角坐标。不传入offset_x和offset_y值时悬停在元素中点。

参数名称	类型	默认值	说明
`offset_x`	`int`	`None`	相对元素左上角坐标的 x 轴偏移量，向下向右为正
`offset_y`	`int`	`None`	相对元素左上角坐标的 y 轴偏移量，向下向右为正

返回：None

示例：

# 悬停在元素右上方 50*50 的位置
ele.hover(50, -50)

# 悬停在元素上中部，x 相对左上角向右偏移50，y 保持在元素中点
ele.hover(offset_x=50)

# 悬停在元素中点
ele.hover()

7.4 修改元素

7.4.1 `set.innerHTML()`

此方法用于设置元素的 innerHTML 内容。

参数名称	类型	默认值	说明
`html`	`str`	必填	html文本

返回：None

7.4.2 `set.property()`

此方法用于设置元素property属性。

参数名称	类型	默认值	说明
`name`	`str`	必填	属性名
`value`	`str`	必填	属性值

返回：None

示例：

ele.set.propibute('value', 'Hello world!')

7.4.3 `set.attribut()`

此方法用于设置元素 attribute 属性。

参数名称	类型	默认值	说明
`name`	`str`	必填	属性名
`value`	`str`	必填	属性值

返回：None

示例：

ele.set.attr('href', 'http://www.gitee.com')

7.4.4 `remove_attr()`

此方法用于删除元素 attribute 属性。

参数名称	类型	默认值	说明
`name`	`str`	必填	属性名

返回：None

示例：

ele.remove_attr('href')

7.4.5 `set.value()`

此方法用于设置元素value值。

参数名称	类型	默认值	说明
`value`	`str`	必填	属性值

返回：None

7.4.6 `check()`

此方法用于选中或取消选中元素。

参数名称	类型	默认值	说明
`uncheck`	`bool`	`False`	是否取消选中
`by_js`	`bool`	`False`	是否用 js 方式选择

返回：None

7.5 执行 js 脚本

7.5.1 `run_js()`

此方法用于对元素执行 js 代码，代码中用this表示元素自己。

参数名称	类型	默认值	说明
`script`	`str`	必填	js 脚本文本或脚本文件路径
`*args`	-	无	传入的参数，按顺序在js文本中对应`arguments[0]`、`arguments[1]`...
`as_expr`	`bool`	`False`	是否作为表达式运行，为`True`时`args`参数无效
`timetout`	`float`	`None`	js 超时时间，为`None`则使用页面`timeouts.script`设置

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

注意

要获取 js 结果记得写上return。

示例：

# 用执行 js 的方式点击元素
ele.run_js('this.click();')

# 用 js 获取元素高度
height = ele.run_js('return this.offsetHeight;')

7.5.2 `run_async_js()`

此方法用于以异步方式执行 js 代码，代码中用this表示元素自己。

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

返回：None

7.5.3 `add_init_js()`

此方法用于添加初始化脚本，在页面加载任何脚本前执行。

参数名称	类型	默认值	说明
`script`	`str`	必填	js 脚本文本

返回类型	说明
`str`	添加的脚本的 id

7.5.4 `remove_init_js()`

此方法用于删除初始化脚本，script_id传入None时删除所有。

参数名称	类型	默认值	说明
`script_id`	`str`	`None`	脚本的id，传入`None`时删除所有

返回：None

7.6 元素滚动

元素滚动功能藏在scroll属性中。用于使可滚动的容器元素内部进行滚动，或使元素本身滚动到可见。

# 滚动到底部
ele.scroll.to_bottom()

# 滚动到最右边
ele.scroll.to_rightmost()

# 向下滚动 200 像素
ele.scroll.down(200)

# 滚动到指定位置
ele.scroll.to_location(100, 300)

# 滚动页面使自己可见
ele.scroll.to_see()

7.6.1 `scroll.to_top()`

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

参数： 无

返回：None

示例：

page.scroll.to_top()

7.6.2 `scroll.to_bottom()`

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

参数： 无

返回：None

7.6.3 `scroll.to_half()`

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

参数： 无

返回：None

7.6.4 `scroll.to_rightmost()`

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

参数： 无

返回：None

7.6.5 `scroll.to_leftmost()`

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

参数： 无

返回：None

7.6.6 `scroll.to_location()`

此方法用于滚动到元素滚动到指定位置。

参数名称	类型	默认值	说明
`x`	`int`	必填	水平位置
`y`	`int`	必填	垂直位置

返回：None

示例：

page.scroll.to_location(300, 50)

7.6.7 `scroll.up()`

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

参数名称	类型	默认值	说明
`pixel`	`int`	必填	滚动的像素

返回：None

示例：

page.scroll.up(30)

7.6.8 `scroll.down()`

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

参数名称	类型	默认值	说明
`pixel`	`int`	必填	滚动的像素

返回：None

7.6.9 `scroll.right()`

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

参数名称	类型	默认值	说明
`pixel`	`int`	必填	滚动的像素

返回：None

7.6.10 `scroll.left()`

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

参数名称	类型	默认值	说明
`pixel`	`int`	必填	滚动的像素

返回：None

7.6.11 `scroll.to_see()`

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

参数名称	类型	默认值	说明
`center`	`bool` `None`	`None`	是否尽量滚动到页面正中，为`None`时如果被遮挡，则滚动到页面正中

返回：None

7.6.12 `scroll.to_center()`

此方法用于尽量把元素滚动到视口正中。

参数： 无

返回：None

7.7 列表选择

<select>下拉列表元素功能在select属性中。可自动等待列表项出现再实施选择。

此属性用于对<select>元素的操作。非<select>元素此属性为None。

假设有以下<select>元素，下面示例以此为基础：

<select id='s' multiple>
    <option value='value1'>text1</option>
    <option value='value2'>text2</option>
    <option value='value3'>text3</option>
</select>

7.7.1 点击列表项元素进行选取

可以获取<option>元素，进行选取或取消选择。

示例：

from DrissionPage import ChromiumPage

page = ChromiumPage()
ele = page('t:select')('t:option')
ele.click()

7.7.2 `select()`和`select.by_text()`

这两个方法功能一样，用于按文本选择列表项。如为多选列表，可多选。

参数名称	类型	默认值	说明
`text`	`str` `list` `tuple`	必填	作为选择条件的文本，传入`list`或`tuple`可选择多项
`timeout`	`float`	`None`	超时时间，为`None`默认使用页面超时时间

返回类型	说明
`bool`	是否选择成功

7.7.3 `select.by_value()`

此方法用于按value属性选择列表项。如为多选列表，可多选。

参数名称	类型	默认值	说明
`value`	`str` `list` `tuple`	必填	作为选择条件的`value`值，传入`list`或`tuple`可选择多项
`timeout`	`float`	`None`	超时时间，为`None`默认使用页面超时时间

返回类型	说明
`bool`	是否选择成功

7.7.4 `select.by_index()`

此方法用于按序号选择列表项，从1开始。如为多选列表，可多选。

参数名称	类型	默认值	说明
`index`	`int` `list` `tuple`	必填	选择第几项，传入`list`或`tuple`可选择多项
`timeout`	`float`	`None`	超时时间，为`None`默认使用页面超时时间

返回类型	说明
`bool`	是否选择成功

7.7.5 `select.by_locator()`

此方法可用定位符筛选选项元素。如为多选列表，可多选。

参数名称	类型	默认值	说明
`locator`	`str` `list` `tuple`	必填	定位符，传入`list`或`tuple`可选择多项
`timeout`	`float`	`None`	超时时间，为`None`默认使用页面超时时间

返回类型	说明
`bool`	是否选择成功

7.7.6 `select.by_option()`

此方法用于选中单个或多个列表项元素。如为多选列表，可多选。

参数名称	类型	默认值	说明
`option`	`ChromiumElement` `List[ChromiumElement]`	必填	`<option>`元素或它们组成的列表

返回：None

示例：

from DrissionPage import ChromiumPage

page = ChromiumPage()
select = page('t:select')
option = select('t:option')
select.select.by_option(option)

7.7.7 `select.cancel_by_text()`

此方法用于按文本取消选择列表项。如为多选列表，可取消多项。

参数名称	类型	默认值	说明
`text`	`str` `list` `tuple`	必填	作为选择条件的文本，传入`list`或`tuple`可选择多项
`timeout`	`float`	`None`	超时时间，为`None`默认使用页面超时时间

返回类型	说明
`bool`	是否选择成功

7.7.8 `select.cancel_by_value()`

此方法用于按value属性取消选择列表项。如为多选列表，可取消多项。

参数名称	类型	默认值	说明
`value`	`str` `list` `tuple`	必填	作为选择条件的`value`值，传入`list`或`tuple`可选择多项
`timeout`	`float`	`None`	超时时间，为`None`默认使用页面超时时间

返回类型	说明
`bool`	是否选择成功

7.7.9 `select.cancel_by_index()`

此方法用于按序号取消选择列表项，从1开始。如为多选列表，可取消多项。

参数名称	类型	默认值	说明
`index`	`int` `list` `tuple`	必填	选择第几项，传入`list`或`tuple`可选择多项
`timeout`	`float`	`None`	超时时间，为`None`默认使用页面超时时间

返回类型	说明
`bool`	是否选择成功

7.7.10 `select.cancel_by_locator()`

此方法可用定位符筛选选项元素。如为多选列表，可取消多项。

参数名称	类型	默认值	说明
`locator`	`str` `list` `tuple`	必填	定位符，传入`list`或`tuple`可选择多项
`timeout`	`float`	`None`	超时时间，为`None`默认使用页面超时时间

返回类型	说明
`bool`	是否选择成功

7.7.11 `select.cancel_by_option()`

此方法用于取消选中单个或多个列表项元素。如为多选列表，可多选。

参数名称	类型	默认值	说明
`option`	`ChromiumElement` `List[ChromiumElement]`	必填	`<option>`元素或它们组成的列表

返回：None

7.7.12 `select.all()`

此方法用于全选所有项。多选列表才有效。

参数： 无

返回：None

7.7.13 `select.clear()`

此方法用于取消所有项选中状态。多选列表才有效。

参数： 无

返回：None

7.7.14 `select.invert()`

此方法用于反选。多选列表才有效。

参数： 无

返回：None

7.7.15 `select.is_multi`

此属性返回当前元素是否多选列表。

返回类型：bool

7.7.16 `select.options`

此属性返回当前列表元素所有选项元素对象。

返回类型：ChromiumElement

7.7.17 `select.selected_option`

此属性返回当前元素选中的选项（单选列表）。

返回类型：bool

7.7.18 `select.selected_options`

此属性返回当前元素所有选中的选项（多选列表）。

返回类型：List[ChromiumElement]

`八、自动等待`

网络环境不稳定，页面 js 运行时间也难以确定，自动化过程中经常遇到需要等待的情况。

如果总是用sleep()，显得不太优雅，等待多了浪费时间，等待不够会导致报错。

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

它们藏在页面对象和元素对象的wait属性里。

等待方法均有timeout参数，可自行设得超时时间，也可以设置超时后返回False还是抛出异常。

8.1 页面对象的等待方法

示例：

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.get('http://g1879.gitee.io/drissionpagedocs/')
page.wait.ele_displayed('tag:div')

8.1.1 `wait.load_start()`

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

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

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

参数名称	类型	默认值	说明
`timeout`	`float` `None` `True`	`None`	超时时间，为`None`或`Ture`时使用页面`timeout`设置为数字时等待相应时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

示例：

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

8.1.2 `wait.doc_loaded()`

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

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

注意

此功能仅用于等待页面主 document 加载，不能用于等待 js 加载的变化。
get()方法已内置此功能，后面无须添加等待。

参数名称	类型	默认值	说明
`timeout`	`float` `None` `True`	`None`	超时时间，为`None`或`Ture`时使用页面`timeout`设置为数字时等待相应时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

8.1.3 `wait.ele_loaded()`

此方法用于等待一个元素被加载到 DOM。

有时一个元素的正常出现是下一步操作的前提，用此方法可以防止一些元素加载速度慢于程序动作速度导致的误操作。

参数名称	类型	默认值	说明
`locator`	`str` `Tuple[str, str]`	必填	要等待的元素，定位符
`timeout`	`float`	`None`	超时时间，为`None`时使用页面`timeout`设置
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

返回类型	说明
`ChromiumElement`	等待成功返回元素对象
`False`	等待失败

示例：

ele1.click()  # 点击某个元素
page.wait.ele_loaded('#div1')  # 等待 id 为 div1 的元素加载
ele2.click()  # div1 加载完成后再执行下一步操作

8.1.4 `wait.ele_displayed()`

此方法用于等待一个元素变成显示状态。如果当前 DOM 中查找不到指定元素，则会自动等待元素加载，再等待它显示。

元素隐藏是指元素在 DOM 内，但处于隐藏状态（即使在视口内且不被遮挡）。父元素隐藏时子元素也是隐藏的。

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

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

示例：

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

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

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

8.1.5 `wait.ele_hidden()`

此方法用于等待一个元素变成隐藏状态。如果当前 DOM 中查找不到指定元素，则会自动等待元素加载，再等待它隐藏。

元素隐藏是指元素在 DOM 内，但处于隐藏状态（即使在视口内且不被遮挡）。父元素隐藏时子元素也是隐藏的。

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

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

8.1.6 `wait.ele_deleted()`

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

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

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

8.1.7 `wait.download_begin()`

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

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	超时时间，为`None`时使用页面`timeout`设置
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

示例：

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

8.1.8 `wait.upload_paths_inputted()`

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

参数： 无

返回：None

示例：

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

8.1.9 `wait.new_tab()`

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

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	超时时间，为`None`时使用页面`timeout`设置
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

返回类型	说明
`str`	等待成返回新标签页 id
`False`	等待失败返回`False`

8.1.10 `wait.title_change()`

此方法用于等待 title 变成包含或不包含指定文本。

参数名称	类型	默认值	说明
`text`	`str`	必填	用于识别的文本
`exclude`	`bool`	`False`	是否排除，为`True`时当 title 不包含`text`指定文本时返回`True`
`timeout`	`bool`	`float`	超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

8.1.11 `wait.url_change()`

此方法用于等待 url 变成包含或不包含指定文本。

比如有些网站登录时会进行多重跳转，url 发生多次变化，可用此功能等待到达最终需要的页面。

参数名称	类型	默认值	说明
`text`	`str`	必填	用于识别的文本
`exclude`	`bool`	`False`	是否排除，为`True`时当 url 不包含`text`指定文本时返回`True`
`timeout`	`bool`	`float`	超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

示例：

# 访问网站
page.get('https://www.*****.cn/login/')  # 访问登录页面
page.ele('#username').input('***')  # 执行登录逻辑
page.ele('#password').input('***\n')

page.wait.url_change('https://www.*****.cn/center/')  # 等待url变成后台url

8.1.12 `wait()`

此方法用于等待若干秒，与sleep()没有区别，只是作者懒得再写一句导入。

参数名称	类型	默认值	说明
`second`	`float`	必填	等待若干秒

返回：None

示例：

page.wait(1)  # 强制等待1秒

import time
time.sleep(1)  # 效果与这句没分别

8.2 元素对象的等待方法

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.get('http://g1879.gitee.io/drissionpagedocs/')
ele = page('tag:div')
ele.wait.covered()

8.2.1 `wait.displayed()`

此方法用于等待元素从隐藏状态变成显示状态。

元素隐藏是指元素在 DOM 内，但处于隐藏状态（即使在视口内且不被遮挡）。父元素隐藏时子元素也是隐藏的。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	等待超时时间，为`None`则使用元素所在页面超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

示例：

# 等待元素显示，超时使用ele所在页面设置
ele.wait.displayed()

8.2.2 `wait.hidden()`

此方法用于等待元素从显示状态变成隐藏状态。

元素隐藏是指元素在 DOM 内，但处于隐藏状态（即使在视口内且不被遮挡）。父元素隐藏时子元素也是隐藏的。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	等待超时时间，为`None`则使用元素所在页面超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

示例：

# 等待元素不显示，超时为3秒
ele.wait.hidden(timeout=3)

8.2.3 `wait.deleted()`

此方法用于等待元素被从 DOM 删除。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	等待超时时间，为`None`则使用元素所在页面超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

示例：

# 等待元素显示，超时使用ele所在页面设置
ele.wait.deleted()

8.2.4 `wait.covered()`

此方法用于等待元素被其它元素覆盖。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	等待超时时间，为`None`则使用元素所在页面超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

8.2.5 `wait.not_covered()`

此方法用于等待元素不被其它元素覆盖。

可用于等待遮挡被操作元素的“加载中”遮罩消失。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	等待超时时间，为`None`则使用元素所在页面超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

8.2.6 `wait.enabled()`

此方法用于等待元素变为可用状态。

不可用状态的元素仍然在 DOM 内，disabled属性为False。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	等待超时时间，为`None`则使用元素所在页面超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

8.2.7 `wait.disabled()`

此方法用于等待元素变为不可用状态。

不可用状态的元素仍然在 DOM 内，disabled属性为True。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	等待超时时间，为`None`则使用元素所在页面超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

8.2.8 `wait.stop_moving()`

此方法用于等待元素运动结束。如果元素没有大小和位置信息，会在超时时抛出NoRectError异常。

参数名称	类型	默认值	说明
`gap`	`float`	`0.1`	检测运动的间隔时间
`timeout`	`float`	`None`	等待超时时间，为`None`则使用元素所在页面超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

# 等待元素稳定
page.ele('#button1').wait.stop_moving()
# 点击元素
page.ele('#button1').click()

8.2.9 `wait.disable_or_deleted()`

此方法用于等待元素变为不可用或被删除。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	等待超时时间，为`None`则使用元素所在页面超时时间
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

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

8.2.10 `wait()`

此方法用于等待若干秒，与sleep()没有区别。

参数名称	类型	默认值	说明
`second`	`float`	必填	等待若干秒

返回：None

`九、文件上传`

上传文件有两种方式：

拦截文件输入框，自动填入路径
找到<input>元素，填入文件路径

9.1 自然的交互

传统自动化工具的文件上传，需要开发者在 DOM 里找到文件上传控件，然后用元素对象的input()方法填入路径。

有些上传控件是临时加载的，有些藏得很深，找起来费时费力。

本库提供一种自然的文件上传方式，无需在 DOM 里找控件，只要自然地点击触发文件选择框，程序就能主动截获，并填写设定好的路径，开发更省事。

9.1.1 `click.to_upload()`

浏览器元素对象拥有此方法，用于上传文件到网页。

参数名称	类型	默认值	说明
`file_paths`	`str` `list` `tuple`	必填	文件路径，如果上传框支持多文件，可传入列表或字符串，字符串时多个文件用`\n`分隔
`by_js`	`bool`	`False`	是否用 js 方式点击，逻辑与`click()`一致

返回：None

示例

from DrissionPage import ChromiumPage

page = ChromiumPage()
ele = page('#uploadButton')
ele.to_upload(r'C:\text.txt')

9.1.2 手动方式

上面的方法使用默认点击方式触发上传，假如页面要求其它触发方式，可自行手动写上传逻辑。

步骤：

设置要上传的文件路径，多路径传入list、tuple或以\n分隔的字符串
点击会触发文件选择框的按钮
调用等待录入语句，确保输入完整

示例：

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

点击按钮后，文本选择框被拦截不会弹出，但可以看到文件路径已经传入其中。

由于此动作是异步输入，需显式等待输入完成才进行下一步操作。

9.1.3 注意事项

如果您要操作的上传控件在一个异域的<iframe>，那必需用这个<iframe>对象来设置上传路径，而不能用页面对象设置。

❌ 错误做法：

page.set.upload_paths('demo.txt')
page.get_frame(1).ele('@type=file').click()
page.wait.upload_paths_inputted()

⭕ 正确做法：

iframe = page.get_frame(1)
iframe.set.upload_paths('demo.txt')
iframe.ele('@type=file').click()
iframe.wait.upload_paths_inputted()

如果<iframe>和主页面是同域的，则用域名对象和<iframe>对象设置均可。

9.2 传统方式

传统方式，需要开发者在 DOM 里找到文件上传控件，然后用元素对象的input()方法填入路径。

文件上传控件是type属性为'file'的<input>元素进行输入，把文件路径输入到元素即可，用法与输入文本一致。

稍有不同的是，无论clear参数是什么，都会清空原控件内容。

如果控件支持多文件上传，多个路径用list、tuple或以\n分隔的字符串传入。

upload = page('tag:input@type=file')

# 传入一个路径
upload.input('D:\\test1.txt')

# 传入多个路径，方式 1
paths = 'D:\\test1.txt\nD:\\test2.txt'
upload.input(paths)

# 传入多个路径，方式 2
paths = ['D:\\test1.txt', 'D:\\test2.txt']
upload.input(paths)

如果<input>元素很好找，这种方式是很简便的。

有些<input>是临时加载的，或者经过修饰隐藏很深，找起来很费劲。

万一有些上传是用 js 控制的，这种方式未必能奏效。

十、标签页操作

本节介绍对浏览器标签页的管理及使用技巧。

一个 Tab 对象（ChromiumTab和WebPageTab）控制一个浏览器的标签页，是页面控制的主要单位。

一个标签页也可以被多个 Tab 对象同时控制（需禁用单例）。

ChromiumPage和WebPage是标签页的总管，也控制一个标签页，只是它们增加了一些浏览器总体控制功能。

说明

ChromiumPage和WebPage拥有所有 tab 控制的功能。 ChromiumTab和WebPageTab则只有关闭和激活自己的功能。

10.1 多标签页用法

selenium 没有 tab 对象，driver 每次只能操作一个 tab。多 tab 使用时需在不同的 tab 间来回切换，且切换的时候会丢失之前获取过的元素，效率低，使用不便。

DrissionPage 支持多 tab 对象共存，对象之间互不影响，而且标签页无需激活即可操作。而且，焦点切换会增加维护的复杂性和运行的不稳定性。

因此 DrissionPage 不提供标签页切入切出功能。而使用get_tab()或new_tab()方法获取指定标签页对象进行操作。

操作逻辑与 Page 对象一致。

示例1：新建标签页

from DrissionPage import ChromiumPage

page = ChromiumPage()
tab = page.new_tab()  # 新建标签页，获取标签页对象
tab.get('https://www.baidu.com')  # 用标签页对象对标签页进行操作

示例2：获取指定标签页

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.ele('某个链接').click()  # 点击某个链接新建标签页
page.wait.new_tab()  # 等待新标签页出现
tab = page.get_tab(page.latest_tab)  # 获取指定标签页对象
tab.get('https://www.baidu.com')  # 用标签页对象对标签页进行操作

10.2 标签页总览

10.2.1 `tabs_count`

此属性返回标签页数量。

类型：int

print(page.tabs_count)

输出：

10.2.2 `tabs`

此属性以list方式返回所有标签页 id。

类型：List[str]

print(page.tabs)

输出：

['0B300BEA6F1F1F4D5DE406872B79B1AD', 'B838E91F38121B32940B47E8AC59D015']

10.3 新建标签页

10.3.1 `new_tab()`

该方法用于新建一个标签页，该标签页在最后面。

只有 Page 对象拥有此方法。

参数名称	类型	默认值	说明
`url`	`str` `None`	`None`	新标签页访问的网址，不传入则新建空标签页
`new_window`	`bool`	`False`	是否在新窗口打开标签页
`background`	`bool`	`False`	是否不激活新标签页，如`new_window`为`True`则无效
`new_context`	`bool`	`False`	是否创建新的上下文，为`True`则打开一个无痕模式的新窗口，新窗口与其它窗口不共用 cookies

返回类型	说明
`ChromiumTab`	`ChromiumPage`对象的`new_tab()`返回`ChromiumTab`对象
`WebPageTab`	`WebPage`对象的`new_tab()`返回`WebPageTab`对象

示例：

page.new_tab(url='https://www.baidu.com')

10.3.2 `wait.new_tab()`

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

只有 Page 对象拥有此方法。

参数名称	类型	默认值	说明
`timeout`	`float`	`None`	超时时间，为`None`时使用页面`timeout`设置
`raise_err`	`bool`	`None`	等待失败时是否报错，为`None`时根据`Settings`设置

返回类型	说明
`str`	等待成返回新标签页 id
`False`	等待失败返回`False`

10.4 获取标签页对象

10.4.1 `get_tab()`

此方法用于获取一个标签页对象。可指定序号或标签页 id。

只有 Page 对象拥有此方法。

参数名称	类型	默认值	说明
`id_or_num`	`str` `int` `None`	`None`	要获取的标签页 id 或序号（从`1`开始，负数表示倒数），默认为`None`获取当前标签页

返回类型	说明
`ChromiumTab`	标签页对象

注意

如传入序号，序号与标签页视觉排序不一定一致，而是按照激活顺序排列。

示例：

tab = page.get_tab()  # 获取当前标签页对象
tab = page.get_tab(1)  # 获取列表中第二个标签页的对象
tab = page.get_tab('5399F4ADFE3A27503FFAA56390344EE5')  # 获取列表中指定id标签页的对象

10.4.2 `find_tabs()`

此方法用于查找符合条件的 tab。只有 Page 对象拥有此方法。

title、url和tab_type三个参数是三个检索条件，它们是与的关系。

参数名称	类型	默认值	说明
`title`	`str`	`None`	匹配 title 包含此文本的 tab，为`None`时匹配所有
`url`	`str`	`None`	匹配 url 包含此文本的 tab，为`None`时匹配所有
`tab_type`	`str` `list` `tuple` `set`	`None`	匹配该类型的 tab，可输入多个，为`None`时匹配所有
`single`	`bool`	`True`	为`True`返回首个结果的 id，为`False`返回所有信息

返回类型	说明
`str`	`single`为`True`时返回 tab id
`List[dict]`	`single`为`False`时返回所有 tab 信息

示例：

查找 url 包含'baidu.com'的 tab 并创建对象：

from DrissionPage import ChromiumPage

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

tab_id = page.find_tabs(url='baidu.com')
print(tab_id)

输出：

'8460E5D55BCA5798AF83BC4D243652A9'

获取所有 tab 信息：

tabs = page.find_tabs(single=False)
print(tab)

输出：

[{'description': '',
  'devtoolsFrontendUrl': '/devtools/inspector.html?ws=127.0.0.1:9222/devtools/page/8460E5D55BCA5798AF83BC4D243652A9',
  'faviconUrl': 'https://www.baidu.com/img/baidu_85beaf5496f291521eb75ba38eacbd87.svg',
  'id': '8460E5D55BCA5798AF83BC4D243652A9',
  'title': '百度一下，你就知道',
  'type': 'page',
  'url': 'https://www.baidu.com/',
  'webSocketDebuggerUrl': 'ws://127.0.0.1:9222/devtools/page/8460E5D55BCA5798AF83BC4D243652A9'}]

10.4.3 `latest_tab`

此属性返回最后激活的标签页 id。指最新出现或最新被激活的标签页。

只有 Page 对象拥有此属性。

类型：str

示例：

# 打开了一个标签页
ele.click()
# 获取最新标签页对象
tab = page.get_tab(page.latest_tab)  # 与page.get_tab(0)效果一致

10.5 使用多例

默认情况下，Tab 对象是单例的，即一个标签页只有一个对象，即使重复使用get_tab()，获取的都是同一个对象。

这主要是防止新手不理解机制，反复创建多个连接导致资源耗费。

实际上允许多个 Tab 对象同时操作一个标签页，每个负责不同的工作。比如一个执行主逻辑流程，另外的监视页面，处理各种弹窗。

要允许多例，可用Settings设置：

from DrissionPage.common import Settings

Settings.singleton_tab_obj = False

示例

from DrissionPage import ChromiumPage
from DrissionPage.common import Settings

page = ChromiumPage()
page.new_tab()
page.new_tab()

# 未启用多例：
tab1 = page.get_tab(1)
tab2 = page.get_tab(1)
print(id(tab1), id(tab2))

# 启用多例：
Settings.singleton_tab_obj = False
tab1 = page.get_tab(1)
tab2 = page.get_tab(1)
print(id(tab1), id(tab2))

输出：

可见第一次输出两个 Tab 对象是同一个，第二次输出是独立的。

2347582903056 2347582903056
2347588741840 2347588877712

10.6 关闭和重连

10.6.1 `close()`

此方法用于标签页关闭自己。

Page 对象和 Tab 对象都有此方法。

值得注意的是，Page 对象关闭标签页后，仍能进行其它标签页的管理。

参数： 无

返回：None

10.6.2 `disconnect()`

此方法用于页面对象断开和浏览器的连接，但不关闭标签页。断开后，对象不能对标签页进行操作。

Page 对象和 Tab 对象都有此方法。

值得注意的是，Page 对象断开和浏览器的连接后，仍能进行标签页的管理。

参数： 无

返回：None

10.6.3 `reconnect()`

此方法用于关闭与页面连接，然后重建一个新连接。

这主要用于应付长期运行导致内存占用过高，断开连接可释放内存，然后重连继续控制浏览器。

Page、Tab 和ChromiumFrame对象都有此方法。

参数名称	类型	默认值	说明
`wait`	`float`	`0`	关闭后等待多少秒再连接

返回：None

10.6.4 `close_tabs()`

此方法用于关闭指定的标签页，可关闭多个。默认关闭当前的。

如果被关闭的标签页包含当前页，会切换到剩下的第一个页面，但未必是视觉上第一个。

此方法只有 Page 对象拥有。

参数名称	类型	默认值	说明
`tabs_or_ids`	`str` `None` `ChromiumTab` `List[str, ChromiumTab]` `Tuple[str, ChromiumTab]`	`None`	要处理的标签页对象或 id，可传入列表或元组，为`None`时处理当前页
`others`	`bool`	`True`	是否关闭指定标签页之外的

返回：None

示例：

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

# 关闭第1、3个标签页
tabs = page.tabs
page.close_tabs(tabs_or_ids=(tabs[0], tabs[2]))

10.6.5 `close_other_tabs()`

此方法用于关闭传入的标签页以外标签页，默认保留当前页。可传入多个。

如果被关闭的标签页包含当前页，会切换到剩下的第一个页面，但未必是视觉上第一个。

此方法只有 Page 对象拥有。

参数名称	类型	默认值	说明
`tabs_or_ids`	`str` `None` `ChromiumTab` `List[str, ChromiumTab]` `Tuple[str, ChromiumTab]`	`None`	要处理的标签页对象或 id，可传入列表或元组，为`None`时处理当前页

返回：None

示例：

# 关闭除当前标签页外的所有标签页
page.close_other_tabs()

# 关闭除第一个以外的标签页
page.close_other_tabs(page.tab[0])

# 关闭除指定id以外的标签页
reserve_list = ('0B300BEA6F...', 'B838E91...')
page.close_other_tabs(reserve_list)

10.7 激活标签页

10.7.1 `set.tab_to_front()`

此方法用于激活标签页使其处于最前面。但不会把当前对象焦点跳转到该标签页。

此方法只有 Page 对象拥有。

参数名称	类型	默认值	说明
`tab_or_id`	`str` `ChromiumTab` `None`	`None`	标签页对象或 id，默认为`None`表示当前标签页

返回：None

10.7.2 `set.activate()`

此方法用于 Tab 对象或 Page 对象激活自己。

参数： 无

返回：None

10.8 多标签页协同

做自动化的时候，我们经常会遇到这样一种场景：我们有一个列表页，需要逐个点开里面的链接，获取新页面的内容，每个链接会打开一个新页面。

如果用 selenium 来做，点击一个链接后必需把焦点切换到新标签页，采集信息后再回到原来的页面，点击下一个链接，但由于焦点的切换，原来的元素信息已丢失，我们只能重新获取所有链接，以计数方式点击下一个，非常不优雅。

而用ChromiumPage，点开标签页后焦点无需移动，可直接生成一个新标签页的页面对象，对新页面进行采集，而原来列表页的对象可以继续操作下一个链接。甚至可以用多线程控制多个标签页，实现各种黑科技。

我们用 gitee 的推荐项目页面做个演示：最新推荐项目 - Gitee.com

from DrissionPage import ChromiumPage

page = ChromiumPage()
page.get('https://gitee.com/explore/all')

links = page.eles('t:h3')
for link in links[:-1]:
    # 点击链接
    link.click()
    # 等待新标签页出现
    page.wait.new_tab()
    # 获取新标签页对象
    new_tab = page.get_tab(0)
    # 等待新标签页加载
    new_tab.wait.load_start()
    # 打印标签页标题
    print(new_tab.title)
    # 关闭除列表页外所有标签页
    page.close_other_tabs()

输出：

wx-calendar: 原生小程序日历组件(可滑动，可标记，可禁用)
thingspanel-go: 开源插件化物联网平台，Go语言开发。支持MQTT、Modbus多协议、多类型设备接入与可视化、自动化、告警、规则引擎等功能。 QQ群：371794256。
APITable: vika.cn维格表社区版，地表至强的开源低代码、多维表格工具，Airtable的开源免费替代。
ideaseg: 基于 NLP 技术实现的中文分词插件，准确度比常用的分词器高太多，同时提供 ElasticSearch 和 OpenSearch 插件。
vue-plugin-hiprint: hiprint for Vue2/Vue3 ⚡打印、打印设计、可视化设计器、报表设计、元素编辑、可视化打印编辑
ExDUIR.NET: Windows平台轻量DirectUI框架

后面省略。。。

十一、iframe 操作

<iframe>元素是一种特殊的元素，它既是元素，也是页面，因此独立一个章节对其进行介绍。

与 selenium 不同，DrissionPage 无需切入切出即可处理<iframe> 元素。因此可实现跨级元素查找、元素内部单独跳转、同时操作<iframe>内外元素、多线程控制多个<iframe>等操作，功能更灵活，逻辑更清晰。

我们使用菜鸟教程在线编辑器来演示：

菜鸟教程在线编辑器 (runoob.com)

源代码框内容要作一点调整，然后按“点击运行”：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>菜鸟教程(runoob.com)</title>
</head>

<body>
<iframe id="sss" src="https://www.runoob.com">
    <p>您的浏览器不支持 iframe 标签。</p>
</iframe>
</body>
</html>

按F12，可以看到网页右侧是一个两层<iframe>，一个 id 是'iframeResult'的<iframe>里面有一个 id 是'sss'的<iframe> 。最里层的<iframe> 页面指向 https://www.runoob.com。

11.1 获取`iframe`对象

获取<iframe>对象的方法有两种，可用获取普通元素的方式获取，或者用get_frame()方法获取。推荐优先使用get_frame() 方法，因为当作普通元素获取时，IDE 无法正确识别获取到的是<iframe>元素。

11.1.1 `get_frame()`

此方法用于获取页面中一个<frame>或<iframe>对象。

参数名称	类型	默认值	说明
`loc_ind_ele`	`str` `int` `ChromiumFrame`	必填	定位符 `<iframe>`元素序号（从`1`开始，负数表示倒数） `ChromiumFrame对象` `id`属性内容 `name`属性内容
`timeout`	`float`	`None`	超时时间，为`None`时使用页面超时时间

返回类型	说明
`ChromiumFrame`	`<frame>`或`<iframe>`元素对象
`NoneElement`	找不到时返回`NoneElement`

注意

需要特别注意的是，如果页面中有嵌套的<iframe>，用序号获取的方式会存在不准确。比如上面说的网站，用get_frames()可获取到 6 个元素，但用get_frame(6)却获取不到最后一个。这是因为有两个<iframe>是嵌套关系，导致获取不准确。

示例：

# 使用定位符获取
iframe = page.get_frame('#sss')

# 获取第2个iframe
iframe = page.get_frame(1)

11.1.2 `get_frames()`

此方法用于获取页面中多个符合条件的<frame>或<iframe>对象。

参数名称	类型	默认值	说明
`locator`	`str` `Tuple[str, str]`	`None`	定位符，为`None`时返回所有
`timeout`	`float`	`None`	超时时间，为`None`时使用页面超时时间

返回类型	说明
`List[ChromiumFrame]`	`<frame>`或`<iframe>`元素对象组成的列表

提醒

获取所有<iframe>会很慢，而且浪费资源，一般使用获取需要用到的就好。

11.1.3 普通元素方式

可以用获取普通元素的方式获取<iframe>对象：

iframe = page('#sss')
print(iframe.html)

输出：

<iframe id="sss" src="https://www.runoob.com"><html><head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>菜鸟教程 - 学的不仅是技术，更是梦想！</title>

  <meta name="robots" content="max-image-preview:large">

下面省略。。。

这个ChromiumFrame对象既是页面也是元素。由于 IDE 不会提示<iframe> 元素对象相关的属性和方法，因此用这种方式获取时建议再用get_frame()包装一下：

iframe = page('#sss')
iframe = page.get_frame(iframe)

11.2 查找`iframe`内元素

从刚才获取元素对象看出，我们并不需要先切入 id 为'iframeResult'的<iframe> ，就可以获取到里面的元素。所以我们获取元素也并不一定要先获取到ChromiumFrame对象。

11.2.1 在 `iframe` 内查找

使用我们刚才获取到的元素，可以在里面查找元素：

ele = iframe('首页')
print(ele)

输出：

<ChromiumElement a href='https://www.runoob.com/' data-id='index' title='菜鸟教程' class='current'>

11.2.2 页面跨 `iframe` 查找

如果<iframe>元素的网址和主页面是同域的，我们可以直接用页面对象查找<iframe>内部元素，而无需先获取ChromiumFrame对象：

ele = page('首页')
print(ele)

输出：

<ChromiumElement a href='https://www.runoob.com/' data-id='index' title='菜鸟教程' class='current'>

只要是同域名的，无论跨多少层<iframe>都能用页面对象直接获取。

11.2.3 与 selenium 对比

WebPage：

from DrissionPage import WebPage

page = WebPage()
ele = page('首页')

MixPage（基于 selenium）：

from DrissionPage import MixPage

page = MixPage()
page.to_frame('#iframeResult')
page.to_frame('#sss')
ele = page('首页')
page.to_frame.main()

可见，原来的逻辑要切入切出，比较繁琐。

11.2.4 重要事项

如果<iframe>跟当前标签页是不同域名的，不能使用页面对象直接查找其中元素，只能先获取其ChromiumFrame元素对象，再在这个对象中查找。

11.3 `ChromiumFrame`的元素特征

正如上面所说，ChromiumFrame既是元素也是页面，这里说一下其元素方面的用法。

11.3.1 `tag`

此属性返回元素名称。

类型：str

11.3.2 `html`

此属性返回整个<iframe>元素的 outerHTML 文本。

类型：str

11.3.3 `inner_html`

此属性返回 innerHTML 文本。

类型：str

11.3.4 `attrs`

此属性以dict形式返回元素所有 attribute 属性。

类型：dict

11.3.5 `xpath`

此属性返回元素在其页面上的 xpath 路径。

类型：str

11.3.6 `css_path`

此属性返回元素在其页面上的 css selector 路径。

类型：str

11.3.7 `attr()`

此方法用于一个获取元素 attribute 属性。

参数名称	类型	默认值	说明
`name`	`str`	必填	属性名

返回类型	说明
`str`	属性值文本
`None`	没有该属性返回`None`

11.3.8 `set.attr()`

此方法用于设置元素的 attribute 属性。

参数名称	类型	默认值	说明
`name`	`str`	必填	属性名
`value`	`str`	必填	属性值

返回：None

11.3.9 `remove_attribute()`

此方法用于删除元素的 attribute 属性。

参数名称	类型	默认值	说明
`name`	`str`	必填	属性名

返回：None

11.3.10 相对定位

相对定位方法与普通元素一致，详见获取元素章节。

parent()：返回上面某一级父元素。
prev()：返回前面的一个兄弟元素。
next()：返回后面的一个兄弟元素。
before()：返回当前元素前面的一个元素。
after()：返回当前元素后面的一个元素。
prevs()：返回前面全部兄弟元素或节点组成的列表。
nexts()：返回后面全部兄弟元素或节点组成的列表。
befores()：返回当前元素后面符合条件的全部兄弟元素或节点组成的列表。

11.4 `ChromiumFrame`的页面特征

11.4.1 `url`

此属性返回页面当前 url。

类型：str

11.4.2 `title`

此属性返回页面当前 title 文本。

类型：str

11.4.3 `get()`

此方法用于实现<iframe>页面跳转，使用方法与ChromiumPage一致。

iframe.get('https://www.runoob.com/css3/css3-tutorial.html')

11.4.4 `refresh()`

此方法用于刷新页面。

参数：无

返回：None

iframe.refresh()

11.4.5 `active_ele`

此属性返回页面中焦点所在元素。

类型：ChromiumElement

11.4.6 `run_js()`

此方法用于在<iframe>内执行 js 脚本。

参数名称	类型	默认值	说明
`script`	`str`	必填	js 脚本文本或脚本文件路径
`*args`	-	无	传入的参数，按顺序在js文本中对应`arguments[0]`、`arguments[1]`...
`as_expr`	`bool`	`False`	是否作为表达式运行，为`True`时`args`参数无效
`timetout`	`float`	`None`	js 超时时间，为`None`则使用页面`timeouts.script`设置

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

11.4.7 `scroll`

ChromiumFrame的滚动方法与页面或元素是一致的。

示例： 使<iframe>元素向下滚动 300 像素

iframe.scroll.down(300)

11.4.8 `get_screenshot()`

此方法用于对<iframe>进行截图。由于技术限制，只能对视口截图。

下面三个参数三选一，优先级：as_bytes>as_base64>path。

参数名称	类型	默认值	说明
`path`	`str` `Path`	`None`	保存图片的路径，为`None`时保存在当前文件夹
`name`	`str`	`None`	完整文件名，后缀可选`'jpg'`、`'jpeg'`、`'png'`、`'webp'`，为`None`时以用 jpg 格式
`as_bytes`	`str` `True`	`None`	是否以字节形式返回图片，可选`'jpg'`、`'jpeg'`、`'png'`、`'webp'`、`None`、`True` 不为`None`时`path`和`as_base64`参数无效为`True`时选用 jpg 格式
`as_base64`	`str` `True`	`None`	是否以 base64 形式返回图片，可选`'jpg'`、`'jpeg'`、`'png'`、`'webp'`、`None`、`True` 不为`None`时`path`参数无效为`True`时选用 jpg 格式

返回类型	说明
`bytes`	`as_bytes`生效时返回图片字节
`str`	`as_bytes`和`as_base64`为`None`时返回图片完整路径
`str`	`as_base64`生效时返回 base64 格式的字符串