xbot.web.Element

概述

element接口主要是对网页元素的处理，如获取相似网页元素、查找目标元素父/子元素、点击元素等

详情

find

在当前元素中获取与选择器匹配的网页元素对象

find(self, selector, *, timeout=10)
参数：

• selector：要查找的选择器，支持以下格式：
  • 选择器名称：str类型
  • 选择器对象：Selector类型
• timeout：查找并返回与当前选择器匹配网页元素的元素对象，默认超时时间20s

返回值：

• WebElement：返回与目标元素相似的元素，如果找到多个相似元素则抛出 UIAError异常

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 百度一下 匹配的网页元素

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_element = browser.find('百度一下')

find_by_css

在当前元素中获取符合CSS选择器的网页元素

find_by_css(self, css_selector, *, timeout=10)
参数：

• css_selector：CSS选择器 (str)
• timeout：查找并返回当前网页满足CSS选择器的网页元素对象，默认超时时间20s

返回值：

• WebElement：返回与CSS选择器匹配的元素，如果找到多个相似元素则抛出 UIAError异常

示例1：
通过Chrome浏览器打开 百度 网页并返回和CSS选择器 百度一下 匹配的网页元素

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_element = browser.find_by_css('input#su.bg.s_btn', timeout=10)

find_by_xpath

在当前元素中获取符合Xpath选择器的网页元素

find_by_xpath(self, xpath_selector, *, timeout=10)
参数：

• xpath_selector：Xpath选择器 (str)
• timeout：查找并返回当前网页满足CSS选择器的网页元素对象，默认超时时间20s

返回值：

• WebElement：返回与CSS选择器匹配的元素，如果找到多个相似元素则抛出 UIAError异常

示例1：
通过Chrome浏览器打开 百度 网页并返回和Xpath选择器 百度一下 匹配的网页元素

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_element = browser.find_by_xpath("//input[@id='su']", timeout=20)

find_all

在当前元素中获取与选择器匹配的相似网页元素列表

find_all(self, selector, *, timeout=10)
参数：

• selector：要查找的选择器，支持以下格式：
  • 选择器名称：str类型
  • 选择器对象：Selector类型
• timeout：查找并返回与当前选择器匹配的全部网页元素列表的超时时间

返回值：

• list<WebElement>：返回与目标网页元素相似的全部网页元素列表

示例1：
通过Chrome浏览器打开 百度 网页并返回与元素选择器 百度一下 匹配的全部网页元素

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_elements = browser.find_all('百度一下')

find_all_by_css

在当前元素中获取符合CSS选择器的网页元素列表

find_all_by_css(self, css_selector, *, timeout=10)
参数：

• css_selector：CSS选择器 (str)
• timeout：查找并返回当前网页满足CSS选择器的网页元素对象，默认超时时间20s

返回值：

• list<WebElement>：返回满足CSS选择器条件的第一个网页元素对象列表

示例1：
通过Chrome浏览器打开 百度 网页并返回和CSS选择器 百度一下 匹配的网页元素列表

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_elements = browser.find_all_by_css('input#su.bg.s_bt', timeout=10)

find_all_by_xpath

在当前元素中获取符合Xpath选择器的网页元素列表

find_all_by_xpath(self, xpath_selector, *, timeout=10)
参数：

• xpath_selector：Xpath选择器 (str)
• timeout：查找并返回当前网页满足CSS选择器的网页元素对象，默认超时时间20s

返回值：

• list<WebElement>：返回满足CSS选择器条件的第一个网页元素对象列表

示例1：
通过Chrome浏览器打开 百度 网页并返回和Xpath选择器 百度一下 匹配的网页元素列表

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_element = browser.find_all_by_xpath('//input[@id='su']', timeout=20)

parent

获取当前元素的父元素

parent(self)
参数：

• 无

返回值：

• WebElement：返回当前元素的父元素

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 百度一下 匹配的元素对象，然后获取该对象的父对象

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_element = browser.find('百度一下')
    parent_element = web_element.parent()

children

获取当前元素的所有子元素

children(self)
参数：

• 无

返回值：

• List<WebElement>：返回当前元素的所有子元素

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 百度一下 匹配的元素对象，然后获取该对象的子对象

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_element = browser.find('百度一下')
    children_elements = web_element.children()

child_at

获取指定位置的子元素

child_at(self)
参数：

• index：子元素的位置索引，从0开始计数

返回值：

• WebElement：返回指定位置的子元素

_
示例1：

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_element = browser.find('左上角的菜单栏')
    child_element = web_element.child_at(0)

next_sibling

获取下一个并列的兄弟元素

next_sibling(self)
参数：

• 无

返回值：

• WebElement：返回下一个并列的兄弟元素

_
示例1：

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    web_element = browser.find('左上角的菜单栏')
    child_element = web_element.next_sibling()

_

click

单击当前网页元素

click(self, *, button=’left’, simulative=True, keys=’none’, delay_after=1, anchor=None)
参数：

• button：点击时的具体鼠标按键，如鼠标左、右键等，默认是左键
  • ‘left’：鼠标左键
  • ‘right’：鼠标右键
• simulative：是否模拟人工点击，模拟人工时鼠标回有明显的移动轨迹移动到目标元素上再进行点击，不模拟时会瞬间移动到目标元素上并进行点击，默认值为True
• keys：单击网页元素时的键盘辅助按钮, 如Alt键、Ctrl键等，可以为空默认值为空
  • ‘none’：不需要键盘辅助按钮
  • ‘ctrl’：使用ctrl键作为辅助按钮
  • ‘shift’：使用shift键作为辅助按钮
  • ‘win’：使用win(窗口)键作为辅助按钮
• delay_after：执行成功后延迟执行时间, 默认时间为1s
• anchor：锚点，鼠标点击元素的位置以及偏移量元组，可为 None，默认值为 None，为 None 时默认点击目标中心且无偏移量，参数结构如下:
  • sudoku_part：鼠标悬停的位置, 默认悬停在中心
    • ‘topLeft’：悬停左上角
    • ‘topCenter’：悬停在上中部
    • ‘topRight’：悬停在右上角
    • ‘middleLeft’：悬停在左中部
    • ‘middleCenter’：悬停在中心
    • ‘middleRight’：悬停在右中部
    • ‘bottomLeft’：悬停左下角
    • ‘bottomCenter’：悬停在下中部
    • ‘bottomRight’：悬停在右下角
  • offset_x：鼠标位置的水平偏移量
  • offset_y’：鼠标位置的垂直偏移量

返回值：
无

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 百度一下 匹配的元素对象，并用鼠标左键单击该元素

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('百度一下').click(button='left')

示例2：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 百度一下 匹配的元素对象，并用鼠标左键在元素的 左上角水平偏移 10 垂直偏移 10 的位置单击

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('百度一下').click(button='left', anchor=('topLeft', 100, 100))

dbclick

单击当前网页元素

dbclick(self, *, simulative=True, delay_after=1, anchor=None)
参数：

• simulative：是否模拟人工点击，模拟人工时鼠标回有明显的移动轨迹移动到目标元素上再进行点击，不模拟时会瞬间移动到目标元素上并进行点击，默认值为True
• delay_after：执行成功后延迟执行时间, 默认时间为1s
• anchor：锚点，鼠标点击元素的位置以及偏移量元组，可为 None，默认值为 None，为 None 时默认点击目标中心且无偏移量，参数结构如下:
  • sudoku_part：鼠标悬停的位置, 默认悬停在中心
    • ‘topLeft’：悬停左上角
    • ‘topCenter’：悬停在上中部
    • ‘topRight’：悬停在右上角
    • ‘middleLeft’：悬停在左中部
    • ‘middleCenter’：悬停在中心
    • ‘middleRight’：悬停在右中部
    • ‘bottomLeft’：悬停左下角
    • ‘bottomCenter’：悬停在下中部
    • ‘bottomRight’：悬停在右下角
  • offset_x：鼠标位置的水平偏移量
  • offset_y’：鼠标位置的垂直偏移量

返回值：
无

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 百度一下 匹配的元素对象，并用鼠标在元素的 左上角水平偏移 10 垂直偏移 10 的位置双击

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('百度一下').dblclick(anchor=('topLeft', 100, 100))

示例2：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 百度一下 匹配的元素对象，并用鼠标左键双击该元素

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('百度一下').dblclick()

input

填写网页输入框

input(self, text: str, *, simulative=True, append=False, contains_hotkey=False, force_img_ENG=False, send_key_delay=50, focus_timeout=1000, delay_after=1, anchor=None)
参数：

• text：需要填写到网页输入框元素中的文本内容，可包含快捷键
• simulative：是否模拟人工填写，模拟人工时会有明显键盘输入效果，非模拟时则无明显的输入效果，且非模拟人工时输入内容不支持包含快捷键，默认值为True
• append：是否是追加输入，追加输入时不会覆盖输入框中原有的内容，会在原有内容的末尾追加新的内容，非追加输入时输入内容会覆盖掉输入框中原有内容，默认值为False
• contains_hotkey：输入内容是否包含快捷键，该参数只在模拟人工输入时生效，默认值为False
• send_key_delay：两次按键之间的时间间隔(对影刀浏览器该参数无效)，默认为50ms
• focus_timeout：焦点超时时间(获取焦点和输入操作的间隔)，默认1000毫秒
• delay_after：执行成功后延迟执行时间, 默认时间为1s
• anchor：锚点，鼠标点击元素的位置以及偏移量元组，可为 None，默认值为 None，为 None 时默认点击目标中心且无偏移量，参数结构如下:
  • sudoku_part：鼠标悬停的位置, 默认悬停在中心
    • ‘topLeft’：悬停左上角
    • ‘topCenter’：悬停在上中部
    • ‘topRight’：悬停在右上角
    • ‘middleLeft’：悬停在左中部
    • ‘middleCenter’：悬停在中心
    • ‘middleRight’：悬停在右中部
    • ‘bottomLeft’：悬停左下角
    • ‘bottomCenter’：悬停在下中部
    • ‘bottomRight’：悬停在右下角
  • offset_x：鼠标位置的水平偏移量
  • offset_y’：鼠标位置的垂直偏移量

返回值：

• 无

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 输入框 匹配的元素对象，并将 hello world 填写到元素中

from xbot import web
from . import package
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('输入框').input('hello world')

示例2：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 输入框 匹配的元素对象，并用鼠标在元素的 左上角水平偏移 10 垂直偏移 10 的位置单击，然后将 hello world 填写到元素中

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('输入框').input('hello world', anchor=('topLeft', 100, 100))

clipboard_input

通过剪切板填写网页输入框(可有效避免输入法问题)

clipboard_input(self, text: str, *, append=False, focus_timeout=1000, delay_after=1, anchor=None)
参数：

• text：需要填写到网页输入框元素中的文本内容
• append：是否是追加输入，追加输入时不会覆盖输入框中原有的内容，会在原有内容的末尾追加新的内容，非追加输入时输入内容会覆盖掉输入框中原有内容，默认值为False
• focus_timeout, 焦点超时时间(获取焦点和输入操作的间隔)，默认1000毫秒
• delay_after：执行成功后延迟执行时间，默认时间为1s
• anchor：锚点，鼠标点击元素的位置以及偏移量元组，可为 None，默认值为 None，为 None 时默认点击目标中心且无偏移量，参数结构如下:
  • sudoku_part：鼠标悬停的位置, 默认悬停在中心
    • ‘topLeft’：悬停左上角
    • ‘topCenter’：悬停在上中部
    • ‘topRight’：悬停在右上角
    • ‘middleLeft’：悬停在左中部
    • ‘middleCenter’：悬停在中心
    • ‘middleRight’：悬停在右中部
    • ‘bottomLeft’：悬停左下角
    • ‘bottomCenter’：悬停在下中部
    • ‘bottomRight’：悬停在右下角
  • offset_x：鼠标位置的水平偏移量
  • offset_y’：鼠标位置的垂直偏移量

返回值：

• 无

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 输入框 匹配的元素对象，并将 hello world 追加到元素中

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('输入框').clipboard_input('hello world', append=True)

示例2：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 输入框 匹配的元素对象，并用鼠标在元素的 左上角水平偏移 10 垂直偏移 10 的位置单击，然后将 hello world 追加到元素中

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('输入框').clipboard_input('hello wor;d', append=True, 
                                           anchor=('topLeft', 100, 100))

focus

选中(激活)当前元素

focus(self)
参数：

• 无

返回值：

• 无

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 输入框 匹配的元素对象，并选中该元素

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('输入框').focus()

hover

选中(激活)当前元素

hover(self, simulative=True, delay_after=1, anchor=None)
参数：

• simulative：是否模拟人工悬停，模拟人工悬停时会有明显的鼠标移动轨迹,非模拟时鼠标会瞬间移动目标元素上
• delay_after：执行成功后延迟执行时间, 默认时间为1s
• anchor：锚点，鼠标点击元素的位置以及偏移量元组，可为 None，默认值为 None，为 None 时默认点击目标中心且无偏移量，参数结构如下:
  • sudoku_part：鼠标悬停的位置, 默认悬停在中心
    • ‘topLeft’：悬停左上角
    • ‘topCenter’：悬停在上中部
    • ‘topRight’：悬停在右上角
    • ‘middleLeft’：悬停在左中部
    • ‘middleCenter’：悬停在中心
    • ‘middleRight’：悬停在右中部
    • ‘bottomLeft’：悬停左下角
    • ‘bottomCenter’：悬停在下中部
    • ‘bottomRight’：悬停在右下角
  • offset_x：鼠标位置的水平偏移量
  • offset_y’：鼠标位置的垂直偏移量

返回值：

• 无

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 百度一下 匹配的元素对象，并模拟人工将鼠标悬停在该元素上

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('输入框').hover()

get_text

获取当前网页元素的文本内容

get_text(self)
参数：

• 无

返回值：

• str：返回当前网页元素的文本内容

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 百度一下 匹配的元素对象，并获取该元素的文本信息

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    value = browser.find('输入框').get_text()

get_html

获取当前网页元素的html内容

get_html(self)
参数：

• 无

返回值：

• str：返回当前网页元素的html内容

示例1：
通过Chrome浏览器打开 百度 网页并获取该网页的html信息

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    html = browser.get_html()

get_value

获取当前网页元素的值

get_value(self)
参数：

• 无

返回值：

• str：返回当前网页元素的值

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 输入框 匹配的元素对象，并获取该元素的值

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    value = browser.find('输入框').get_value()

set_value

设置当前网页元素的值

set_value(self, value: str)
参数：

• value：需要设置到网页元素上的文本值

返回值：

• 无

示例1：
通过Chrome浏览器打开 百度 网页并返回和元素选择器 输入框 匹配的元素对象，并设置该元素的值为 hello world

from xbot import web
from . import package
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('输入框').set_value('hello world')

check

设置网页复选框

check(self, mode=’check’, delay_after=1)
参数：

• mode, 设置网页复选框的结果, 默认为选中
  • ‘check’：选中复选框
  • ‘uncheck’：取消选中
  • ‘toggle’：取反，如当前是 check则改为 unchenck， 反正则从 uncheck变为 check

返回值：

• 无

示例1：
通过Chrome浏览器打开 百度登录 网页，并找到与元素选择器 下次自动登录 匹配的复选框元素，然后设置该复选框元素为选中状态

from xbot import web
def main(args):
    browser = web.create('https://passport.baidu.com/v2/?login', 'chrome')
    browser.find('用户名登录').click()
    browser.find('下次自动登录').check('check')

select

按选项内容设置单选网页下拉框元素

select(self, item: str, *, mode=’fuzzy’, delay_after=1)
参数：

• item：要设置的网页下拉框元素的某一项的文本内容
• mode：查找项的匹配模式, 默认是模糊匹配
  • ‘fuzzy’：模糊匹配
  • ‘exact’：精准匹配
  • ‘regex’：正则匹配
• delay_after：执行成功后延迟执行时间, 默认时间为1s

返回值：

• 无

示例1：
使用Chrome打开 淘宝登录 页面，并查找与元素选择器 用户名 匹配的下拉框元素，然后使用精准匹配找到内容为 张三 并设置其为当前选中项

from xbot import web
def main(args):
    browser = web.create('www.taobao.com', 'chrome')
    browser.find('用户名').select('张三')

select_multiple

按选项内容设置单选网页下拉框元素

select_multiple(self, items: typing.List[str], *, mode=’fuzzy’, append=False, delay_after=1)
参数：

• item：要设置的多选网页下拉框元素的某一项或多项的文本内容
• mode：查找项的匹配模式, 默认是模糊匹配
  • ‘fuzzy’：模糊匹配
  • ‘exact’：精准匹配
  • ‘regex’：正则匹配
• append：是否追加设置, 默认值为False
• delay_after：执行成功后延迟执行时间, 默认时间为1s

返回值：

• 无

示例1：
使用Chrome打开 xxxx 网页，并查找与元素选择器 多选下拉框 匹配的下拉框元素，然后使用精准匹配找到内容为 张三，李四，王五 并全部勾选

from xbot import web
def main(args):
    browser = web.create('www.xxx.com', 'chrome')
    browser.find('多选下拉框').select_multiple(['张三','李四', '王五'])

select_by_index

按下标设置单选网页下拉框元素

select_by_index(self, index: int, delay_after=1)
参数：

• index：要设置的单选网页下拉框元素的某一项下标值, 下标值从0开始
• delay_after：执行成功后延迟执行时间, 默认时间为1s

返回值：

• 无

示例1：
使用Chrome打开 淘宝登录 页面，并查找与元素选择器 用户名 匹配的下拉框元素，然后设置下拉框中下标为 1 的项作为当前选中项

from xbot import web
def main(args):
    browser = web.create('www.taobao.com', 'chrome')
    browser.find('用户名').select_by_index(1)

select_multiple_by_index

按下标设置多选网页下拉框元素

select_multiple_by_index(self, indexes: typing.List[int], *, append=False, delay_after=1)
参数：

• index：要设置的多项网页下拉框元素的某一项或多项的下标值列表, 下标值从0开始
• append：是否追加设置, 默认值为False
• delay_after：执行成功后延迟执行时间, 默认时间为1s

返回值：

• 无

示例1：
使用Chrome打开 xxxx 网页，并查找与元素选择器 多选下拉框 匹配的下拉框元素，然后设置下拉框选项下标为 1、3、5 的项为选中状态

from xbot import web
def main(args):
    browser = web.create('www.xxx.com', 'chrome')
    browser.find('多选下拉框').select_multiple_by_index([1,3,5])

get_select_options

获取网页下拉框的值

get_select_options(self)
参数：

• 无

返回值：

• typing.List[typing.Tuple]：返回下拉框值（选项，选项值，被选中状态）的列表
  

示例：
使用Chrome打开 xxxx 网页，并查找与元素选择器 下拉框 匹配的下拉框元素，然后获取下拉框的值

from xbot import web
def main(args):
    browser = web.create('www.xxx.com', 'chrome')
    list_value = browser.find('下拉框').get_select_options()

set_attribute

设置网页元素属性值

set_attribute(self, name: str, value: str)
参数：

• name：元素属性名称
• value：要设置的元素属性值

返回值：

• 无

示例1：
使用Chrome打开 百度网页，并查找与元素选择器 百度一下 匹配的元素，并设置该元素的 height 为 100

from xbot import web
def main(args):
    browser = web.create('www.xxx.com', 'chrome')
    browser.find('百度一下').set_attribute('height', '100')

get_attribute

获取网页元素属性值

get_attribute(self, name: str)
参数：

• name：元素属性名称

返回值：

• str返回网页元素目标属性的属性值

示例1：
使用Chrome打开 百度网页，并查找与元素选择器 百度一下 匹配的元素，并获取该元素的 height 属性值

from xbot import web
from . import package
def main(args):
    browser = web.create('www.xxx.com', 'chrome')
    height = browser.find('百度一下').get_attribute('height')

get_all_attributes

获取网页元素全部属性值

get_all_attributes(self)
参数：

• 无

返回值：

• typing.List[typing.Tuple]：返回目标网页元素的全部属性名与属性值的组合列表

示例1：
使用Chrome打开 百度网页，并查找与元素选择器 百度一下 匹配的元素，并获取该元素的全部属性值

from xbot import web
def main(args):
    browser = web.create('www.xxx.com', 'chrome')
    list_tuple = browser.find('百度一下').get_all_attributes()

get_bounding

获取网页元素的边框属性组合

get_bounding(self, to96dpi=True)
参数：

• to96dpi：是否需要将边框属性转换成dpi为96的对应属性值

返回值：

• typing.Tuple：返回网页元素的边框属性组合，如(‘x’, ‘y’, ‘width’, ‘height’)

示例1：
使用Chrome打开 百度 网页，并查找与元素选择器 百度一下 匹配的元素，并获取该元素的边框属性信息

from xbot import web
def main(args):
    browser = web.create('www.xxx.com', 'chrome')
    list_tuple = browser.find('百度一下').get_bounding()

extract_table

获取当前元素所属表格的内容列表

extract_table(self)
参数：

• 无

返回值：

• typing.List[typing.Tuple]: 返回数据表格内容

示例1：
使用Chrome打开 xxx 网页，并查找与元素选择器 数据表格 匹配的元素，并获返回表格中内容

from xbot import web
def main(args):
    browser = web.create('www.xxx.com', 'chrome')
    list_tuple = browser.find('selector').extract_table()

screenshot

对目标元素进行截图, 并将图片进行保存

screenshot(self, folder_path, *, filename=None)
参数：

• folder_path：元素截图后图片需要保存的路径
• filename：截图后图片保存后的名称，可为空，为空时会根据当前时间自动生成文件名称

返回值：

• 无

示例1：
使用Chrome打开 百度 网页，并查找与元素选择器 百度一下 匹配的元素，然后对该元素截图并将结果命名为 123.png 保存在 D: 下

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('百度一下').screenshot('D:\\', filename='123.png')

screenshot_to_clipboard

对目标元素进行截图, 并将图片保存至剪切板

screenshot_to_clipboard(self)
参数：

• 无

返回值：

• 无

示例1：
使用Chrome打开 百度 网页，并查找与元素选择器 百度一下 匹配的元素，然后对该元素截图并将结果添加到剪切板中

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('百度一下').screenshot_to_clipboard()

is_checked

判断网页复选框元素是否被选中

is_checked(self)
参数：

• 无

返回值：

• bool：返回元素的选中状态, 选中返回True， 否则返回False

示例1：
使用Chrome打开 xxx 网页，并查找与元素选择器 复选框 匹配的元素，判断该元素是否被选中

from xbot import web
def main(args):
    browser = web.create('www.xxx.com', 'chrome')
    is_checked = browser.find('复选框').is_checked()

is_enabled

判断网页元素是否可用

is_enabled(self)
参数：

• 无

返回值：

• bool：返回元素的可用状态, 可用返回True， 否则返回False

示例1：
使用Chrome打开 百度 网页，并查找与元素选择器 百度一下 匹配的元素，判断该元素是否可用

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    is_enabled = browser.find('百度一下').is_enabled()

is_displayed

判断网页元素是否可见

is_displayed(self)
参数：

• 无

返回值：

• bool：返回元素的可见状态, 可见返回True， 否则返回False

示例1：
使用Chrome打开 百度 网页，并查找与元素选择器 百度一下 匹配的元素，判断该元素是否可见

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    is_displayed = browser.find('百度一下').is_displayed()

execute_javascript

在当前网页元素上执行JS脚本

execute_javascript(self, code, argument=None)
参数：

• code：要执行的JS脚本，必须为javascript函数形式
• argument：要传入到JS函数中的参数，必须为字符串，如果需要传入其他类型可以先将其转为JSON字符串形式

返回值：

• typing.Any：返回JS脚本执行结果

示例1：
打开百度 网页，通过Javascript的方式将文字输入到百度搜索框中

import xbot
from .import package
def main(args):
    page = xbot.web.create('www.baidu.com')
    code = """
    function (element, keywords) {
        // element 表示输入框的Html元素
        // keywords 表示传入的关键字
        element.value = keywords
    }
    """
    page.find('输入框wd').execute_javascript(code, 'james')

scroll_to

在当前网页指定的元素上滚动鼠标滚轮

scroll_to(self, *, location=’bottom’, behavior=’instant’, top=0, left=0)
参数：

• location：滚动位置, 默认滚动到底部
  • ‘bottom’：滚动到底部
  • ‘top’：滚动到顶部
  • ‘point’：滚动到指定位置
• behavior：滚动效果，默认平滑滚动
  • ‘smooth’：平滑滚动
  • ‘instant’：瞬间滚动
• top：滚动到指定位置的纵坐标
• left：滚动到指定位置的横坐标

返回值：

• 无

示例1：
使用Chrome浏览器打开 百度 网页，然后往下平滑滚动鼠标直到滚动到网页底部为止

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.scroll_to(location='bottom', behavior='instant')

示例2：
使用Chrome浏览器打开 百度 网页，然后往下平滑滚动鼠标滚到 top:100，left:100 的位置

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.scroll_to(location='point', behavior='smooth', top=100, left=100)

drag_to

拖拽网页元素到指定位置

drag_to(self, *, simulative=True, behavior=’smooth’, top=0, left=0, delay_after=1, anchor=None)
参数：

• simulative：是否模拟人工拖拽，默认值为True模拟人工
• behavior：滚动效果，默认平滑滚动
  • ‘smooth’：平滑拖拽
  • ‘instant’：瞬间拖拽
• top：相对于当前元素中心的纵向位移
• left：相对于当前元素中心的横向位移
• delay_after：指令执行成功后延迟执行时间，默认值为1s
• anchor：锚点，鼠标点击元素的位置以及偏移量元组，可为 None，默认值为 None，为 None 时默认点击目标中心且无偏移量，参数结构如下:
  • sudoku_part：鼠标悬停的位置, 默认悬停在中心
    • ‘topLeft’：悬停左上角
    • ‘topCenter’：悬停在上中部
    • ‘topRight’：悬停在右上角
    • ‘middleLeft’：悬停在左中部
    • ‘middleCenter’：悬停在中心
    • ‘middleRight’：悬停在右中部
    • ‘bottomLeft’：悬停左下角
    • ‘bottomCenter’：悬停在下中部
    • ‘bottomRight’：悬停在右下角
  • offset_x：鼠标位置的水平偏移量
  • offset_y’：鼠标位置的垂直偏移量

返回值：

• 无

示例1：
使用Chrome浏览器打开 xxx 网页，并查找与元素选择器 可移动元素 匹配的元素，并模拟人工拖拽元素到 top:100，left:100 位置

from xbot import web
def main(args):
    browser = web.create('www.baidu.com', 'chrome')
    browser.find('可移动元素').drag_to(simulative=True, behavior='smooth', 
                                      top=100, left=100)

get_all_select_items

获取网页下拉框元素的全部下拉选项

get_all_select_items(self)
参数：
无
返回值：

• typinging.list[str]：返回网页下拉框全部下拉选项列表

示例1：
获取当前网页中 下拉框 元素的全部下拉选项

from xbot import web
def main(args):
    browser = web.get_active()
    element = browser.find('下拉框')
    values = element.get_all_select_items()

get_selected_item

获取网页下拉框当前选中的项

get_selected_item(self)
参数：
无
返回值：

• typinging.list[str]：返回网页下拉框当前全部选中项列表

示例1
获取当前网页中 下拉框 元素当前所有选中项

from xbot import web
def main(args):
    browser = web.get_active()
    element = browser.find('下拉框')
    values = element.get_selected_item()

upload

自动完成点击上传按钮、在文件选择对话框中输入待上传文件等系列操作

upload(self, file_names, *, simulative=False, clipboard_input=True, dialog_timeout=20, send_key_delay=50, focus_timeout=1000)
参数：

• file_names：上传文件列表，比如[r\”C:\test.txt\”,r\”C:\text1.txt\”]
• simulative：模拟输入； 通过模拟人工的方式触发输入事件; 非模拟输入(自动化接口输入): 调用元素自身实现的自动化接口输入; 默认值为False
• clipboard_input：文件选择对话框中输入file_names时，是否用剪贴板输入
• dialog_timeout：点击上传按钮后，等待文件选择框的最大时间,单位（秒）
• send_key_delay：两次按键之间的时间间隔(仅模拟输入有效, 对影刀浏览器该参数无效)，默认为50ms
• focus_timeout：点击文件选择输入框获取焦点的等待时间，单位（毫秒）

返回值：
无

示例1
在www.w3schools.com的文件输入框示例中，模拟文件上传

import xbot
from xbot import print, sleep
from .import package
def main(args):
    web_object = xbot.web.create("https://www.w3schools.com/tags/tryit.asp?filename=tryhtml5_input_type_file","chrome")
    web_object.find("上传按钮").upload([r'D:\logo.gif'])

download

自动完成点击下载按钮、在文件保存对话框中输入保存文件信息等系列操作

download(self, file_folder, *, file_name=None, wait_complete=True, wait_complete_timeout=300, simulative=False, clipboard_input=True, dialog_timeout=20, send_key_delay=50, focus_timeout=1000)
参数：

• file_folder, 保存下载文件的文件夹
• file_name, 自定义保存的文件名，若为空，用下载资源默认文件名
• wait_complete, 是否等待下载完成，默认为True
• wait_complete_timeout,等待下载超时时间，单位(秒)
• simulative, 模拟输入: 通过模拟人工的方式触发输入事件; 非模拟输入(自动化接口输入): 调用元素自身实现的自动化接口输入; 默认值为False
• clipboard_input, 文件选择对话框中输入file_names时，是否用剪贴板输入
• dialog_timeout, 点击上传按钮后，等待文件选择框的最大时间,单位（秒）
• send_key_delay, 两次按键之间的时间间隔，默认为50ms
• focus_timeout, 点击文件选择输入框获取焦点的等待时间，单位（毫秒）

返回值：
str 返回下载文件所在的位置

示例1
在百度搜索百度网盘，并下载到本地保存

import xbot
from xbot import print, sleep
from .import package
def main(args):
    web_object = xbot.web.create("www.baidu.com", "chrome")
    web_object.find("百度输入框").input("百度网盘{enter}", contains_hotkey=True)
    download_file_name = web_object.find("立即下载").download("D:\\", "BaiduNetdisk.exe", wait_complete=True,wait_complete_timeout=300)
    print(download_file_name)