跳到主要内容

🛰️ 元素交互


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

✅️️ 点击元素

📌 click()click.left()

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

参数名称类型默认值说明
by_jsboolFalse指定点击行为方式。
None时,如不被遮挡,用模拟点击,否则用 js 点击
True时直接用 js 点击;
False时强制模拟点击,被遮挡也会进行点击
timeoutfloat1.5模拟点击的超时时间(秒),等待元素可见、可用、进入视口
wait_stopboolTrue点击前是否等待元素停止运动
返回值说明
Falseby_jsFalse,且元素不可用、不可见时,返回False
True除以上情况,其余情况都返回True

示例:

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

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

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

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

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

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

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

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

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

from DrissionPage.common import Settings

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

📌 click.right()

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

参数:

返回:None

示例:

ele.click.right()

📌 click.middle()

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

参数名称类型默认值说明
get_tabboolTrue是否返回新出现的 Tab 对象
返回类型说明
ChromiumTabget_tab参数为True,元素在ChromiumTab返回对象
MixTabget_tab参数为True,元素在MixTab里时返回的对象
Noneget_tab参数为False

示例:

tab = ele.click.middle()
print(tab.title)

📌 click.multi()

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

参数名称类型默认值说明
timesint2点击次数

返回:None


📌 click.at()

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

参数名称类型默认值说明
offset_xfloatNone相对元素左上角坐标的 x 轴偏移量,向下向右为正
offset_yfloatNone相对元素左上角坐标的 y 轴偏移量,向下向右为正
buttonstr'left'要点击的键,传入'left''right''middle''back''forward'
countint1点击次数

返回:None

示例:

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

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

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

📌 click.to_upload()

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

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

返回:None


📌 click.to_download()

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

参数名称类型默认值说明
save_pathstr
Path
必填保存路径,为None保存在原来设置的,如未设置保存到当前路径
renamestrNone重命名文件名,为None则不修改
suffixstr'left'指定文件后缀,为None则不修改
new_tabbool1该下载是否在新 tab 中触发
by_jsboolFalse是否用 js 方式点击,逻辑与click()一致
timeoutfloatNone超时时间(秒),为None时使用页面对象默认超时时间
返回类型说明
DownloadMission下载任务对象

📌 click.for_new_tab()

在预期点击后会出现新 tab 的时候,可用此方法点击,会等待并返回新 tab 对象。

参数名称类型默认值说明
by_jsboolFalse是否用 js 方式点击,逻辑与click()一致
返回类型说明
ChromiumTab元素在ChromiumTab里时返回
MixTab元素在MixTab里时返回

✅️️ 输入内容

📌 clear()

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

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

参数名称类型默认值说明
by_jsboolFalse是否用 js 方式清空

返回:None

示例:

ele.clear() 

📌 input()

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

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

返回:None

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

示例:

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

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

📌 输入组合键

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

from DrissionPage.common import Keys

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

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

Keys内置了 5 个常用组合键,分别为CTRL_ACTRL_CCTRL_XCTRL_VCTRL_ZCTRL_Y

ele.input(Keys.CTRL_A)  # 全选

📌 focus()

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

参数:

返回: None


✅️️ 拖拽和悬停

Tips

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

📌 drag()

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

参数名称类型默认值说明
offset_xint0x 轴偏移量,向下向右为正
offset_yint0y 轴偏移量,向下向右为正
durationfloat0.5用时,单位秒,传入0即瞬间到达

返回:None

示例:

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

📌 drag_to()

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

参数名称类型默认值说明
ele_or_locChromiumElement
Tuple[int, int]
必填另一个元素对象或坐标元组
durationfloat0.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))

📌 hover()

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

参数名称类型默认值说明
offset_xintNone相对元素左上角坐标的 x 轴偏移量,向下向右为正
offset_yintNone相对元素左上角坐标的 y 轴偏移量,向下向右为正

返回:None

示例:

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

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

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

✅️️ 修改元素

📌 set.innerHTML()

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

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

返回:None


📌 set.property()

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

参数名称类型默认值说明
namestr必填属性名
valuestr必填属性值

返回:None

示例:

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

📌 set.style()

此方法用于设置元素样式。

参数名称类型默认值说明
namestr必填属性名
valuestr必填属性值

返回:None


📌 set.attr()

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

参数名称类型默认值说明
namestr必填属性名
valuestr必填属性值

返回:None

示例:

ele.set.attr('href', 'https://DrissionPage.cn')

📌 remove_attr()

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

参数名称类型默认值说明
namestr必填属性名

返回:None

示例:

ele.remove_attr('href')

📌 set.value()

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

参数名称类型默认值说明
valuestr必填属性值

返回:None


📌 check()

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

参数名称类型默认值说明
uncheckboolFalse是否取消选中
by_jsboolFalse是否用 js 方式选择

返回:None


✅️️ 执行 js 脚本

📌 run_js()

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

参数名称类型默认值说明
scriptstr必填js 脚本文本或脚本文件路径
*args-传入的参数,按顺序在js文本中对应arguments[0]arguments[1]...
as_exprboolFalse是否作为表达式运行,为Trueargs参数无效
timetoutfloatNonejs 超时时间(秒),为None则使用页面timeouts.script设置
返回类型说明
Any脚本执行结果
注意

要获取 js 结果记得写上return

示例:

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

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

📌 run_async_js()

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

参数名称类型默认值说明
scriptstr必填js 脚本文本
*args-传入的参数,按顺序在js文本中对应arguments[0]arguments[1]...
as_exprboolFalse是否作为表达式运行,为Trueargs参数无效

返回:None


📌 add_init_js()

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

参数名称类型默认值说明
scriptstr必填js 脚本文本
返回类型说明
str添加的脚本的 id

📌 remove_init_js()

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

参数名称类型默认值说明
script_idstrNone脚本的id,传入None时删除所有

返回:None


✅️️ 元素滚动

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

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

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

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

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

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

📌 scroll()scroll.down()

这两个方法效果是一样的,用于使元素向下滚动若干像素,水平位置不变。

参数名称类型默认值说明
pixelint必填滚动的像素
返回类型说明
ChromiumElement执行滚动的元素自身
# 向下滚动30像素
ele.scroll(30)
ele.scroll.down(30)

📌 scroll.up()

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

参数名称类型默认值说明
pixelint必填滚动的像素
返回类型说明
ChromiumElement执行滚动的元素自身

示例:

page.scroll.up(30)

📌 scroll.right()

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

参数名称类型默认值说明
pixelint必填滚动的像素
返回类型说明
ChromiumElement执行滚动的元素自身

📌 scroll.left()

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

参数名称类型默认值说明
pixelint必填滚动的像素
返回类型说明
ChromiumElement执行滚动的元素自身

📌 scroll.to_top()

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

参数:

返回类型说明
ChromiumElement执行滚动的元素自身

示例:

page.scroll.to_top()

📌 scroll.to_bottom()

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

参数:

返回类型说明
ChromiumElement执行滚动的元素自身

📌 scroll.to_half()

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

参数:

返回类型说明
ChromiumElement执行滚动的元素自身

📌 scroll.to_rightmost()

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

参数:

返回类型说明
ChromiumElement执行滚动的元素自身

📌 scroll.to_leftmost()

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

参数:

返回类型说明
ChromiumElement执行滚动的元素自身

📌 scroll.to_location()

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

参数名称类型默认值说明
xint必填水平位置
yint必填垂直位置
返回类型说明
ChromiumElement执行滚动的元素自身

示例:

page.scroll.to_location(300, 50)

📌 scroll.to_see()

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

参数名称类型默认值说明
centerbool
None
None是否尽量滚动到页面正中,为None时如果被遮挡,则滚动到页面正中
返回类型说明
ChromiumElement执行滚动的元素自身

📌 scroll.to_center()

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

参数:

返回类型说明
ChromiumElement执行滚动的元素自身

✅️️ 列表选择

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

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

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

示例:

from DrissionPage import Chromium

tab = Chromium().latest_tab
ele = tab('t:select')('t:option')
ele.click()

📌 select()select.by_text()

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

参数名称类型默认值说明
textstr
list
tuple
必填作为选择条件的文本,传入listtuple可选择多项
timeoutfloatNone超时时间(秒),为None默认使用页面超时时间
返回类型说明
bool是否选择成功

📌 select.by_value()

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

参数名称类型默认值说明
valuestr
list
tuple
必填作为选择条件的value值,传入listtuple可选择多项
timeoutfloatNone超时时间(秒),为None默认使用页面超时时间
返回类型说明
bool是否选择成功

📌 select.by_index()

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

参数名称类型默认值说明
indexint
list
tuple
必填选择第几项,传入listtuple可选择多项
timeoutfloatNone超时时间(秒),为None默认使用页面超时时间
返回类型说明
bool是否选择成功

📌 select.by_locator()

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

参数名称类型默认值说明
locatorstr
list
tuple
必填定位符,传入listtuple可选择多项
timeoutfloatNone超时时间(秒),为None默认使用页面超时时间
返回类型说明
bool是否选择成功

📌 select.by_option()

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

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

返回:None

示例:

from DrissionPage import Chromium

tab = Chromium().latest_tab
select = tab('t:select')
option = select('t:option')
select.select.by_option(option)

📌 select.cancel_by_text()

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

参数名称类型默认值说明
textstr
list
tuple
必填作为选择条件的文本,传入listtuple可选择多项
timeoutfloatNone超时时间(秒),为None默认使用页面超时时间
返回类型说明
bool是否选择成功

📌 select.cancel_by_value()

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

参数名称类型默认值说明
valuestr
list
tuple
必填作为选择条件的value值,传入listtuple可选择多项
timeoutfloatNone超时时间(秒),为None默认使用页面超时时间
返回类型说明
bool是否选择成功

📌 select.cancel_by_index()

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

参数名称类型默认值说明
indexint
list
tuple
必填选择第几项,传入listtuple可选择多项
timeoutfloatNone超时时间(秒),为None默认使用页面超时时间
返回类型说明
bool是否选择成功

📌 select.cancel_by_locator()

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

参数名称类型默认值说明
locatorstr
list
tuple
必填定位符,传入listtuple可选择多项
timeoutfloatNone超时时间,为None默认使用页面超时时间
返回类型说明
bool是否选择成功

📌 select.cancel_by_option()

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

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

返回:None


📌 select.all()

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

参数:

返回:None


📌 select.clear()

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

参数:

返回:None


📌 select.invert()

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

参数:

返回:None


📌 select.is_multi

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

返回类型:bool


📌 select.options

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

返回类型:ChromiumElement


📌 select.selected_option

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

返回类型:ChromiumElement


📌 select.selected_options

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

返回类型:List[ChromiumElement]