xbot-api

# 影刀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模块必须遵循以下格式： ```python # 使用提醒: # 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 - 元素与资源管理 #### 元素选择器 ```python # 获取元素库中的元素 selector = package.selector('元素名称') # 获取图像库中的图像 image_selector = package.image_selector('图像名称') ``` #### 资源文件操作 ```python # 读取文本资源 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 - 网页自动化 #### 浏览器操作 ```python # 创建并打开网页 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() ``` #### 网页导航 ```python # 跳转 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() ``` #### 元素操作 ```python # 查找元素 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管理 ```python # 获取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') ``` #### 对话框处理 ```python # 处理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桌面自动化 #### 窗口操作 ```python # 获取窗口 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) ``` #### 元素操作 ```python # 查找元素 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) ``` #### 鼠标键盘操作 ```python # 鼠标操作 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') ``` #### 图像识别 ```python # 等待图像出现 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('菜单')]) ``` #### 剪切板操作 ```python clipboard = xbot.win32.Clipboard # 设置/获取文本 clipboard.set_text('复制的内容') text = clipboard.get_text() # 清空剪切板 clipboard.clear() # 设置文件 clipboard.set_file(['D:\\file1.txt', 'D:\\file2.pdf']) ``` #### 截图操作 ```python # 屏幕截图 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操作 #### 工作簿操作 ```python # 创建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() ``` #### 工作表操作 ```python # 获取工作表 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('旧名称', '新名称') ``` #### 单元格操作 ```python # 读取单元格 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') ``` #### 其他功能 ```python # 获取行列数 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操作 #### 文档操作 ```python # 创建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() ``` #### 内容操作 ```python # 获取选择区域 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(