diff --git a/docs/APIs/DriverElement 类.md b/docs/APIs/DriverElement 类.md index 0905420..e1cf7d6 100644 --- a/docs/APIs/DriverElement 类.md +++ b/docs/APIs/DriverElement 类.md @@ -254,7 +254,7 @@ driver 模式的元素对象,包装了一个 WebElement 对象,并封装了 返回: List[SessionElement or str] -## get_style_property() +## style() 返回元素样式属性值。 @@ -306,15 +306,16 @@ driver 模式的元素对象,包装了一个 WebElement 对象,并封装了 ## input() -输入文本或组合键。 +输入文本或组合键,返回是否成功输入。insure_input 为 False 时始终返回 True。 参数说明: - vals: Union[str, tuple] - 文本值或按键组合 - clear: bool - 输入前是否清除文本框 - insure_input: bool - 是否自动检测并确保输入正确 +- timeout: folat - 尝试输入的超时时间,不指定则使用父页面的超时时间,只在insure_input为True时生效 -返回: None +返回: bool,是否成功输入。insure_input 为 False 时始终返回 True。 ## run_script() @@ -337,7 +338,11 @@ driver 模式的元素对象,包装了一个 WebElement 对象,并封装了 清空文本框。 -返回: None +参数说明: + +- insure_clear: bool - 是否确保清空 + +返回: bool - 是否清空成功,不能清空的元素返回None ## is_selected() diff --git a/docs/使用方法/元素操作.md b/docs/使用方法/元素操作.md deleted file mode 100644 index 81d1c00..0000000 --- a/docs/使用方法/元素操作.md +++ /dev/null @@ -1,40 +0,0 @@ -元素操作为 d 模式独有,调用以下方法会自动切换到 d 模式。 - -```python -element.click(by_js) # 点击元素,可选择是否用 js 方式点击 -element.click_at(by_js) # 带偏移量点击本元素,相对于左上角坐标。不传入x或y值时点击元素中点 -element.r_click(x, y, by_js) # 右键单击 -element.r_click_at(by_js) # 带偏移量右键单击本元素,相对于左上角坐标。不传入x或y值时点击元素中点 -element.input(vals, clear) # 输入文本或组合键,可选择输入前是否清空文本框 -element.input_txt(txt, clear) # 专门用于输入文本框,可选择输入前是否清空文本框 -element.run_script(js) # 对元素运行 JavaScript 脚本 -element.submit() # 提交 -element.clear() # 清空元素 -element.screenshot(path, filename) # 对元素截图 -element.set_prop(prop, value) # 设置元素property属性值 -element.set_attr(attr, value) # 设置元素attribute参数值 -element.remove_attr(attr) # 删除属性 -element.drag(x, y, speed, shake) # 拖动元素相对距离,可设置速度和是否随机抖动 -element.drag_to(ele_or_loc, speed, shake) # 拖动元素到另一个元素或某个坐标,可设置速度和是否随机抖动 -element.hover() # 在元素上悬停鼠标 -page.wait_ele(loc_or_ele, mode, timeout) # 等待要查找的子元素从 dom 删除、显示、隐藏 - -# select 功能: -element.select.is_multi # 是否多选列表 -element.select.options # 返回所有列表项对象 -element.select.selected_option # 返回第一个被选中的 option 元素 -element.select.selected_options # 返回所有被选中的 option 元素列表 - -element.select(text) # 根据文本选择下拉列表项 -element.select(value, 'value') # 根据 value 选择下拉列表项 -element.select(index, 'index') # 根据序号选择下拉列表项 - -# 多选列表功能: -element.select.deselect(text) # 根据文本取消选择下拉列表项(多选列表时有效) -element.select.deselect(value, 'value') # 根据 value 取消选择下拉列表项(多选列表时有效) -element.select.deselect(index, 'index') # 根据序号取消选择下拉列表项(多选列表时有效) -# 注:当列表为多选列表时,以上的第一个参数可以接收 list 或 tuple,同时选择或取消选择多个项 - -element.select.clear() # 清空多选列表选项 -element.select.invert() # 反选多选列表选项 -``` \ No newline at end of file diff --git a/docs/使用方法/操作页面元素.md b/docs/使用方法/操作页面元素.md new file mode 100644 index 0000000..151cbfa --- /dev/null +++ b/docs/使用方法/操作页面元素.md @@ -0,0 +1,417 @@ +# 操作页面元素 + +d 模式下的 DriverElement 对象可以对浏览器相应元素进行控制。 + +## click() + +此方法用于点击元素。可以选择是否用 js 方式点击,可以在点击失败时自动重试。默认情况下,使用 selenium 原生的点击方法,如果重试超过限定时间,自动改用 js 方式点击。可通过 by_js 参数设置点击方式。 +此设计除了可保证点击成功,还可以用于检测页面上的遮罩层是否消失。遮罩层经常出现在 js 方式翻页的时候,它出现的时候会阻碍 selenium +的原生点击,所以可以通过对其下面的元素不断重试点击,来判断遮罩层是否存在。当然,这个方法是否可行要看具体网页设计。 +而如果直接使用 js 进行点击,则可无视任何遮挡,只要元素在 DOM 内,就能点击得到,这样可以根据须要灵活地对元素进行操作。 + +注意:使用 js 方式点击时,是不会进行重试的。 + +参数: + +- by_js:是否用 js 方式点击,为 None 时先用 selenium 原生方法点击,重试失败超时后改为 用 js 点击;为 True 时直接用 js 点击;为 False 时即使重试超时也不会改用 js。 +- timeout:点击失败重试超时时间,为 None 时使用父页面 timeout 设置。 + +返回:bool,表示是否点击成功。 + +```python +# 点击一个元素,重试超时根据所在页面元素而定,都失败就改用 js 点击 +ele.click() + +# 点击一个元素,重试 5 秒,都失败也不改用 js 点击 +ele.click(by_js=False, timeout=5) + +# 假设遮罩层出现,ele 是遮罩层下方的元素 +ele.click(timeout = 10) # 不断重试点击,直到遮罩层消失,或到达 10 秒 +ele.click(by_js=True) # 无视遮罩层,直接用 js 点击下方元素 +``` + +## click_at() + +此方法用于带偏移量点击元素,偏移量相对于元素左上角坐标。不传入x或y值时点击元素中点。可选择是否用 js 方式点击,但不会进行重试。 +可用于点击一些奇怪的东西,比如用 before 表示的控件。 +点击的目标不一定在元素上,可以传入负值,或大于元素大小的值,点击元素附近的区域。向右和向下为正值,向左和向上为负值。 + +参数: + +- x:相对元素左上角坐标的x轴偏移量 +- y:相对元素左上角坐标的y轴偏移量 +- by_js:是否用js点击 + +返回:None + +```python +# 点击元素右上方 50*50 的位置 +ele.click_at(50, -50) + +# 点击元素上中部,x 相对左上角向右偏移50,y 保持在元素中点 +ele.click_at(x=50) + +# 点击元素中点,和 click() 相似,但没有重试功能 +ele.click_at() +``` + +## r_click() + +此方法实现右键单击元素。 + +无参数。 + +返回:None + +```python +ele.r_click() +``` + +## r_click_at() + +此方法用于带偏移量右键点击元素,用法和 click_at() 相似,但没有 by_js 参数。 + +参数: + +- x:相对元素左上角坐标的x轴偏移量 +- y:相对元素左上角坐标的y轴偏移量 + +返回:None + +```python +# 点击距离元素左上角 50*50 的位置(位于元素内部) +ele.r_click_at(50, 50) +``` + +## input() + +此方法用于向元素输入文本或组合键,也可用于输入文件路径到input元素(文件间用\n间隔)。可选择输入前是否清空元素。 +insure_input 参数为 True 时可自动确保输入正确。该功能是为了应对 selenium 原生输入在某些i情况下会失效的问题。 +接收组合键的时候可接收 selenium 的 Keys 对象的值。组合键要放在一个 tuple 中传入。 +注意:insure_input 为 True 时不能用于接收组合键。 +**Tips:** 有些文本框可以接收回车代替点击按钮,可以直接在文本末尾加上 '\n'。 + +参数: + +- vals:文本值或按键组合 +- clear:输入前是否清空文本框 +- insure_input:是否确保输入正确,不能用于输入组合键 +- timeout:尝试输入的超时时间,不指定则使用父页面的超时时间,只在 insure_input 参数为 True 时生效 + +返回:bool,表示是否成功输入。insure_input 为 False 时始终返回 True。 + +```python +# 输入文本 +ele.input('Hello world!') + +# 输入文本并回车 +ele.input('Hello world!\n') + +# 输入组合键 +from selenium.webdriver import Keys +ele.input((Keys.CONTROL, 'a'), insure_input=False) + +# 向上传文本控件输入文本路径(传入多个路径) +ele.input('D:\\test1.txt\nD:\\test2.txt') +``` + +## run_script() + +此方法用于对元素执行 js 代码。 + +参数: + +- script:js 文本 +- *args:传入 js 的参数 + +返回:js 执行的结果 + +```python +# 用执行 js 的方式点击元素 +ele.run_script('arguments[0].click()') +``` + +## clear() + +此方法用于清空元素文本,可使用确保清空的方式,若元素是不可编辑的,返回 None。 + +参数: + +- insure_clear:是否确保清空。为 True 则用 input() 确保值变成 '',为 False 则用 selenium 元素 clear() 方法 + +返回:bool,是否清空成功,不能清空的元素返回 None + +```python +ele.clear() +``` + +## screenshot() + +此方法用于对元素进行截图。 +如果是图片元素,会自动等待加载结束才截图。 +此方法能自动获取能够使用的文件名,避免重名覆盖原有文件。并返回保存路径。 +保存格式为 png。 + +参数: + +- path:图片保持路径 +- filename:图片文件名,不传入时以元素 tag 标签命名 + +返回:图片的完整路径 + +```python +path = ele.screenshot(r'D:\tmp', 'img_name') +``` + +## set_prop() + +此方法用于设置元素 property 属性。 + +参数: + +- prop: 属性名 +- value: 属性值 + +返回:bool,是否设置成功 + +```python +ele.set_prop('value', 'Hello world!') +``` + +## set_attr() + +此方法用于设置元素 attribute 属性。 + +参数: + +- attr:属性名 +- value:属性值 + +返回:bool,是否设置成功 + +```python +ele.set_attr('href', 'http://www.gitee.com') +``` + +## remove_attr() + +此方法用于删除元素 attribute 属性。 + +参数: + +- attr:属性名 + +返回:bool,是否删除成功 + +```python +ele.remove_attr('href') +``` + +## submit() + +此方法用于提交表单,若元素不在表单内,返回 None,否则返回 True。 + +无参数。 + +返回:True 或 None + +```python +ele.submit() +``` + +## drag() + +此方法用于拖拽元素到相对于当前的一个新位置,可以设置速度,可以选择是否随机抖动。 + +参数: + +- x:x 变化值 +- y:y 变化值 +- speed:拖动的速度,传入 0 即瞬间到达 +- shake:是否随机抖动 + +返回:bool,表示是否拖动成功 + +```python +# 拖动当前元素到距离 50*50 的位置,速度为 100,不随机抖动 +ele.drag(50, 50, 100, False) +``` + +## drag_to() + +此方法用于拖拽元素到另一个元素上或一个坐标上。 + +参数: + +- ele_or_loc: 另一个元素或坐标元组,接收元素时坐标是元素中点的坐标。可接收 selenium 的 WebElement 或本库的 DriverElement +- speed: 拖动的速度,传入 0 即瞬间到达 +- shake: 是否随机抖动 + +返回:bool,表示是否拖动成功 + +```python +# 把 ele1 拖拽到 ele2 上 +ele1 = page.ele('#div1') +ele2 = page.ele('#div2') +ele1.drag_to(ele2) + +# 把 ele1 拖拽到网页 50, 50 的位置 +ele1.drag_to((50, 50)) +``` + +## hover() + +此方法用于模拟鼠标悬停在元素上,可接受偏移量,偏移量相对于元素左上角坐标。不传入 x 或 y 值时悬停在元素中点。x 和 y 值可接受负值。 + +参数: + +- x:相对元素左上角坐标的x轴偏移量 +- y:相对元素左上角坐标的y轴偏移量 + +返回:None + +```python +# 悬停在元素右上方 50*50 的位置 +ele.hover(50, -50) + +# 悬停在元素上中部,x 相对左上角向右偏移50,y 保持在元素中点 +ele.hover(x=50) + +# 悬停在元素中点 +ele.hover() +``` + +# Select 类 + +select 元素的操作较为复杂,因此专门做了一个类用于处理它。每个 DriverElement 都有 select 属性,如果是 select 元素,该属性是一个 Select 类,否则该属性为 False。 +select 元素要操作列表时,实际上是对这个 Select 对象进行操作。 + +```python +ele.select # 元素对象的 select 属性 +``` + +## 属性 + +### is_multi + +该属性表示当前 select 元素是否多选列表。 + +```python +ele.select.is_multi +``` + +### options + +该属性以列表形式返回当前 select 元素下所有列表项元素对象,这些对象是 DriverElement。 + +```python +options = ele.select.options +``` + +### selected_option + +该属性返回第一个被选中的元素对象。 + +```python +option_ele = ele.select.selected_option +``` + +### selected_options + +该属性以列表形式返回第所有被选中的元素对象。如果是单选列表,返回一个列表 + +```python +options = ele.select.select.selected_options +``` + +## 方法 + +### select() + +该方法用于选定或取消选定下拉列表中子元素。Select 类的 \_\_call\_\_() 方法直接调用这个方法,因此可以直接`ele.select()`来替代这个方法。写法更直观。 +当元素是多选列表时,可以接受 list 或 tuple,同时选择多个项。 + +参数: + +- text_value_index:根据文本、值选或序号择选项,若允许多选,传入list或tuple可多选 +- para_type:参数类型,可选 'text'、'value'、'index',默认根据文本选择 +- deselect:是否取消选择 + +返回:是否选择成功 + +```python +# 根据文本选择下拉列表项 +ele.select('text') + +# 根据 value 选择下拉列表项 +ele.select(value, 'value') + +# 根据序号选择下拉列表项 +ele.select(index, 'index') + +# 选择多个文本项 +ele.select(('text1', 'text2')) + +# 选择多个 value 项 +ele.select(('value1', 'value2'), 'value') + +# 选择多个序号 +ele.select(('index1', 'index2'), 'index') +``` + +### deselect() + +此方法用于取消选定下拉列表中子元素。当元素是多选列表时,可以接受 list 或 tuple,同时取消选择多个项。 + +参数: + +- text_value_index:根据文本、值选或序号择选项,若允许多选,传入list或tuple可多选 +- para_type:参数类型,可选 'text'、'value'、'index' + +返回:是否选择成功 + +```python +# 根据文本取消选择下拉列表项 +ele.select.deselect('text') + +# 根据 value 取消选择下拉列表项 +ele.select.deselect(value, 'value') + +# 根据序号取消选择下拉列表项 +ele.select.deselect(index, 'index') + +# 取消选择多个文本项 +ele.select.deselect(('text1', 'text2')) + +# 取消选择多个 value 项 +ele.select.deselect(('value1', 'value2'), 'value') + +# 取消选择多个序号 +ele.select.deselect(('index1', 'index2'), 'index') +``` + +## 多项列表独有功能 + +### clear() + +此方法用于清空多选列表选项。 + +无参数。 + +返回:None + +```python +ele.select.clear() +``` + +### invert + +此方法用于反选多选列表选项。 + +无参数。 + +返回:None + +```python +ele.select.invert() +``` \ No newline at end of file diff --git a/docs/使用方法/获取元素信息.md b/docs/使用方法/获取元素信息.md index 122f36e..d278fea 100644 --- a/docs/使用方法/获取元素信息.md +++ b/docs/使用方法/获取元素信息.md @@ -241,12 +241,12 @@ before_txt = ele.before after_txt = ele.after ``` -## get_style_property() +## style() 该方法返回元素 css 样式属性值,可获取伪元素的属性。它有两个参数,style 参数输入样式属性名称,pseudo_ele 参数输入伪元素名称,省略则获取普通元素的 css 样式属性。 ```python -prop = ele.get_style_property('color', 'first-letter') +prop = ele.style('color', 'first-letter') ``` ## prop()