xbot-api

name	xbot-api
description	影刀RPA平台的Python自动化开发技能。当用户需要开发影刀xbot自动化脚本、使用xbot API进行网页/桌面/移动端自动化、Excel/Word操作、数据库操作、AI集成、PDF处理等功能时使用此技能。

影刀XBot API 开发技能

概述

影刀XBot是一个企业级RPA（机器人流程自动化）平台，提供Python API用于开发自动化脚本。此技能涵盖了xbot的核心API使用方法、代码模板和最佳实践。

何时使用此技能：

• 开发影刀xbot自动化流程脚本
• 使用xbot API进行网页自动化（xbot.web）
• Windows桌面应用自动化（xbot.win32）
• 移动端自动化（xbot.mobile）
• Excel/Word文档操作（xbot.excel、xbot.word）
• 数据库操作（xbot.ado）
• AI能力集成（xbot.ai - 阿里云/百度/腾讯）
• PDF文件处理（xbot.pdf）
• FTP文件传输（xbot.ftp）

代码模板规范

基础模板结构

影刀xbot模块必须遵循以下格式：

# 使用提醒:
# 1. xbot包提供软件自动化、数据表格、Excel、日志、AI等功能
# 2. package包提供访问当前应用数据的功能，如获取元素、访问全局变量、获取资源文件等功能
# 3. 当此模块作为流程独立运行时执行main函数
# 4. 可视化流程中可以通过"调用模块"的指令使用此模块

import xbot
from xbot import print, sleep
from .import package
from .package import variables as glv

def main(args):
    # 在此编写自动化逻辑
    pass

重要约束：

• ❌ 不使用 if __name__ == "__main__":
• ✅ 必须使用 def main(args): 作为入口函数
• ✅ 必须导入 xbot 和 package 模块

核心API模块

1. package - 元素与资源管理

元素选择器

# 获取元素库中的元素
selector = package.selector('元素名称')

# 获取图像库中的图像
image_selector = package.image_selector('图像名称')

资源文件操作

# 读取文本资源
text = package.resources.get_text('data.txt', encoding='utf-8')

# 读取二进制资源
data = package.resources.get_bytes('image.png')

# 复制资源文件到本地
package.resources.copy_to('template.xlsx', 'D:\\output.xlsx')

# 添加资源文件到剪切板
package.resources.add_to_clipboard(['file1.txt', 'file2.xml'])

2. xbot.web - 网页自动化

浏览器操作

# 创建并打开网页
browser = xbot.web.create('https://example.com', mode='cef')

# 获取已打开的网页
browser = xbot.web.get(title='百度一下', url='baidu.com')
browser = xbot.web.get_active()  # 获取当前激活的网页

# 获取所有匹配的网页
browsers = xbot.web.get_all(url='example.com')

# 关闭所有网页
xbot.web.close_all()

网页导航

# 跳转
browser.navigate('https://newurl.com')

# 后退/前进
browser.go_back()
browser.go_forward()

# 刷新
browser.reload(ignore_cache=True)

# 获取信息
url = browser.get_url()
title = browser.get_title()
html = browser.get_html()
text = browser.get_text()

元素操作

# 查找元素
element = browser.find(package.selector('登录按钮'))
elements = browser.find_all_by_css('input[type="text"]')

# 元素交互
element.click(button='left', simulative=True)
element.input('username', simulative=True, append=False)
element.hover()

# 获取元素信息
text = element.get_text()
value = element.get_value()
attr = element.get_attribute('href')

# 下拉框操作
element.select('选项内容', mode='fuzzy')
element.select_by_index(0)

Cookie管理

# 获取Cookie
cookies = xbot.web.get_cookies(mode='cef', domain='.example.com')

# 设置Cookie
xbot.web.set_cookie(
    url='https://example.com',
    name='session_id',
    value='abc123',
    expires=3600
)

# 移除Cookie
xbot.web.remove_cookie('https://example.com', 'session_id')

对话框处理

# 处理JavaScript对话框
browser.handle_javascript_dialog(dialog_result='ok', text='输入内容')

# 处理下载对话框
xbot.web.handle_save_dialog(
    file_folder='D:\\downloads',
    file_name='report.pdf'
)

# 处理上传对话框
xbot.web.handle_upload_dialog('D:\\files\\upload.pdf')

3. xbot.win32 - Windows桌面自动化

窗口操作

# 获取窗口
window = xbot.win32.get(title='记事本', class_name='Notepad')
window = xbot.win32.get_by_selector(package.selector('窗口元素'))

# 窗口控制
window.activate()  # 激活
window.set_state('maximize')  # 最大化/最小化/正常
window.move(x=100, y=100)  # 移动
window.resize(width=800, height=600)  # 调整大小
window.close()  # 关闭

# 等待窗口状态
window.wait_active(timeout=20)
window.wait_exists(timeout=20)
window.wait_close(timeout=20)

元素操作

# 查找元素
element = window.find(package.selector('按钮元素'))
elements = window.find_all(package.selector('列表项'))

# 元素交互
element.click(button='left', simulative=True)
element.input('输入内容')
element.check(mode='check')  # 复选框
element.select('选项')  # 下拉框
element.hover()

# 拖拽
element.drag_to(simulative=True, top=50, left=100, delay_after=1)

鼠标键盘操作

# 鼠标操作
xbot.win32.mouse_move(500, 300, move_speed='fast')
xbot.win32.mouse_click(button='left', click_type='click')
xbot.win32.mouse_wheel(wheel_direction='down', wheel_times=3)

# 键盘操作
xbot.win32.send_keys('Ctrl+C')
xbot.win32.send_keys('Hello World')

# 获取鼠标位置
pos = xbot.win32.get_mouse_position(relative_to='screen')

图像识别

# 等待图像出现
xbot.win32.Image.wait_appear(
    image_selectors=[package.image_selector('确认按钮')],
    timeout=20
)

# 点击图像
xbot.win32.Image.click(
    image_selectors=[package.image_selector('图标')],
    button='left'
)

# 图像悬停
xbot.win32.Image.hover([package.image_selector('菜单')])

剪切板操作

clipboard = xbot.win32.Clipboard

# 设置/获取文本
clipboard.set_text('复制的内容')
text = clipboard.get_text()

# 清空剪切板
clipboard.clear()

# 设置文件
clipboard.set_file(['D:\\file1.txt', 'D:\\file2.pdf'])

截图操作

# 屏幕截图
xbot.win32.Screenshot.save_screen_to_file(
    'D:\\screenshot.png',
    image_format='png'
)
xbot.win32.Screenshot.save_screen_to_clipboard()

# 窗口截图
xbot.win32.Screenshot.save_window_to_file(
    hwnd=window.handle,
    image_path='D:\\window.png',
    image_format='png'
)

4. xbot.excel - Excel操作

工作簿操作

# 创建Excel
workbook = xbot.excel.create(kind='office', visible=True)

# 打开Excel
workbook = xbot.excel.open('D:\\data.xlsx', kind='office', visible=True)

# 获取活动工作簿
workbook = xbot.excel.get_active_workbook(kind='office')

# 保存/另存
workbook.save()
workbook.save_as('D:\\output.xlsx')

# 关闭
workbook.close()

工作表操作

# 获取工作表
sheet = workbook.get_active_sheet()
sheet = workbook.get_sheet_by_name('Sheet1')
sheet = workbook.get_sheet_by_index(1)

# 创建工作表
workbook.create_sheet('新工作表', create_way='last')

# 激活工作表
workbook.active_sheet_by_name('Sheet1')

# 删除/复制/重命名
workbook.delete_sheet('旧工作表')
workbook.copy_sheet('源工作表', '目标工作表')
workbook.rename_sheet('旧名称', '新名称')

单元格操作

# 读取单元格
value = sheet.get_cell(1, 'A')  # 行号,列名
row = sheet.get_row(1)  # 获取整行
column = sheet.get_column('A')  # 获取整列
range_data = sheet.get_range(1, 'A', 5, 'C')  # 区域数据

# 写入单元格
sheet.set_cell(1, 'A', '标题')
sheet.set_row(1, ['A', 'B', 'C'], begin_column_name='A')
sheet.set_column('A', [1, 2, 3, 4], begin_row_num=1)
sheet.set_range(1, 'A', [[1, 2], [3, 4]])  # 二维数组

# 追加/插入行
sheet.append_row(['新', '数', '据'])
sheet.insert_row(3, ['插入', '数据'])

# 删除行列
sheet.remove_row(5)
sheet.remove_column('C')

# 清空
sheet.clear()
sheet.clear_range(1, 'A', 10, 'Z')

其他功能

# 获取行列数
row_count = sheet.get_row_count()
col_count = sheet.get_column_count()

# 获取第一个空闲行/列
free_row = sheet.get_first_free_row()
free_col = sheet.get_first_free_column()

# 选中区域
sheet.select_range(1, 'A', 10, 'C')

# 复制粘贴
sheet.copy_range(1, 'A', 5, 'C')
sheet.paste_range(1, 'D')

5. xbot.word - Word操作

文档操作

# 创建Word
doc = xbot.word.create(kind='office', visible=True)

# 打开Word
doc = xbot.word.open(
    'D:\\document.docx',
    kind='office',
    visible=True,
    open_password='',
    edit_password=''
)

# 保存/另存
doc.save()
doc.save_as('D:\\output.docx')

# 导出PDF
doc.export_to_pdf(
    'D:\\output.pdf',
    export_range=0,  # 0=全部, 1=当前页, 2=指定范围
    page_from=1,
    page_to=5
)

# 关闭
doc.close()

内容操作

# 获取选择区域
selection = doc.get_selection()

# 写入文本
selection.write_text('Hello World', newline=True)

# 读取文本
text = selection.read_text()

# 插入图片
selection.insert_picture(
    image_source='local',  # local/file_url/clipboard
    image_path='D:\\image.png',
    image_scale=100,  # 缩放百分比
    newline=True
)

# 插入超链接
doc.insert_hyperlink('点击这里', 'https://example.com')

# 插入表格
doc.insert_table(
    table_data=[['A', 'B'], ['1', '2']],
    table_data_format=None,
    grid=True,
    newline=True
)

# 替换文本
selection.replace_text(
    search_text='旧文本',
    replace_text='新文本',
    replace_all=True,
    case_sensitive=False
)

# 移动光标
selection.move_cursor(