android-bot
Version:
Android-bot is built on the AutoBot JavaScript library and provides features such as wireless screen casting and real-time control within a local network, key simulation, screen recording, screenshot capture, layout analysis, file management, application
318 lines (257 loc) • 20.2 kB
Markdown
# 翻译
[中文](./README.md) | [英文-GPT](https://github.com/automan-bot/android-bot/blob/master/README-EN.md)
# android-bot
android-bot 是基于 AutoBot 得 JavaScript SDK，同时支持 浏览器环境 和 Node 环境，Node 环境下，支持自动扫描局域网客户端
[NPM](https://www.npmjs.com/package/android-bot)| [Github](https://github.com/automan-bot/android-bot)| [AutoBot 文档](https://mobile.tntok.top/autobot_doc)
### 目前已经实现了什么功能 API？
- 获取系统信息（型号信息，硬件信息...）
- 屏幕图像（支持 jpg，base64，支持 websocket 实时输出）
- 触控输入（单指手势，多指手势，支持 websocket 实时输入）
- 按键输入（按键模拟，文字输入，支持中文）
- 屏幕布局（支持 XML，JSON）
- 文件管理（上传，查询，删除）
- 剪切板管理（读取和修改）
- 应用管理（安装，卸载，清除数据，启动停止，详情查看）
- 联系人管理 (增删改查)
- 录制屏幕，熄屏控制，播放音乐，短信查询等
- 通知监听，剪切板监听等
### 成功案例
- [Tntok 投屏（一个可以脱离 adb 的投屏工具）](https://www.tntok.top)
### 相关案例
- [AutoJS PC 版（一键自动化生成 autox.js 代码）](https://mobile.tntok.top/autojs)
- [Autox.js-集成 autobot 版本（不用无障碍实现自动化）](https://github.com/automan-bot/AutoX)
### 它可以用来干什么？
- 局域网内无线投屏/实时控制,按键模拟，录制屏幕，布局分析，文件管理，应用管理，通讯录管理
- 通过 NodeJS，Python，Java，C++等语言，只需要调用 Http Api，即可开发譬如：远程投屏控制，自动化测试，自动化运营、批量处理、机器人、自动回复等等
### 支持浏览器和 NodeJS 环境
在 Node 环境下，支持局域网的网络发现，能自动扫描同个局域网下的设备，
在浏览器环境下，则需要获取设备的 ip 和端口，手动连接
## 使用方法
### 准备工作
需要设备安装 AutoBot APP，且成功运行服务，具体可以参考[AutoBot 官网](https://mobile.tntok.top/autobot_doc)->准备工作部分
重要的事情说三遍：
- 此库是基于 AutoBot 官方 Http API 和 WebSocket API 封装，请你务必先仔细阅读[AutoBot 文档](https://mobile.tntok.top/autobot_doc)
- 此库是基于 AutoBot 官方 Http API 和 WebSocket API 封装，请你务必先仔细阅读[AutoBot 文档](https://mobile.tntok.top/autobot_doc)
- 此库是基于 AutoBot 官方 Http API 和 WebSocket API 封装，请你务必先仔细阅读[AutoBot 文档](https://mobile.tntok.top/autobot_doc)
### 安装支持库
```
npm i android-bot -s
```
### 浏览器内使用
- 浏览器环境下由于不支持 udp，需要主动创建设备
```javascript
//引入库
import { BrowserWebSocket, Device } from "android-bot";
async function main() {
//创建一个设备，设备的ip和端口来源于AutoBot APP，此处需要修改为你自己设备的ip和端口
const device = new Device("192.168.1.100:18080");
//获取屏幕信息
let iScreenInfo = await device.screenInfo();
//获取屏幕截图
let screenImg = await device.screenShot();
//获取系统信息
let iDeviceInfo = await device.getSystemInfo();
//获取屏幕ui布局的JSON格式
let iuiObjectJSON = await device.screenJson();
//获取屏幕ui布局的XML格式，可以使用
let iuiObjectXML = await device.screenXml();
//手势滑动（左滑）
await device.gesture({
duration: 200,
points: [
{ x: 168, y: 558 },
{ x: 172, y: 562 },
{ x: 276, y: 562 },
{ x: 306, y: 560 },
{ x: 348, y: 552 },
{ x: 390, y: 548 },
{ x: 442, y: 540 },
{ x: 470, y: 540 },
{ x: 500, y: 538 },
{ x: 520, y: 538 },
{ x: 548, y: 538 },
{ x: 566, y: 538 },
{ x: 596, y: 540 },
],
});
//....
}
main();
```
### Node 使用
- Node 环境下，可以使用 AdbDevice 扫描局域网内的设备
```javascript
import { AdbDevice, NodeWebSocket, Device } from "android-bot";
import FormData from "form-data";
import fs from "fs";
async function main() {
//node环境下可以自动扫描局域网内的设备
const devices = await AdbDevice.listWifiDevices();
if (devices[0]) {
let device = devices[0];
//使用Node环境下的websocket client
device.setWebSocketClient(new NodeWebSocket());
let mScreenControl = device.mScreenControl;
//监听屏幕方向发生改变的消息
mScreenControl.addScreenOrentationChangeListener(function (
width,
height,
rotation,
isLandscape
) {
console.log(
"屏幕发生改变:" +
`宽度：${width},高度：${height},是否横屏:${isLandscape},方向:${rotation}`
);
});
//获取屏幕截图
let screenImg = await device.screenShot();
//获取系统信息
let iDeviceInfo = await device.getSystemInfo();
console.log(iDeviceInfo);
//获取屏幕ui布局的JSON格式
let iuiObject = await device.screenJson();
}
}
main();
```
### 实时屏幕图像
```javascript
//引入库
import { BrowserWebSocket, Device } from "android-bot";
async function main() {
//创建一个设备，设备的 ip 和端口来源于 AutoBot APP
const device = new Device("192.168.7.119:18080");
//如果你需要实时；投屏控制（实时屏幕 jpg 图像流，实时触摸文本输入），通知监听，剪切板监听
//那么你需要设置 websocket client，Node 环境下使用 NodeWebSocket，浏览器环境下你需要使用 BrowserWebSocket
//mScreenControl 为实时信息的代理对象，你可以用来监听屏幕图像，通知，剪切版信息
device.setWebSocketClient(new BrowserWebSocket());
//接收到新的通知信息
device.mScreenControl.addNotificationChangeListener(function (
notificationMessage
) {
console.log("接收到新的通知：", notificationMessage);
});
//接收到剪切板发生改变的信息
device.mScreenControl.addClipTextChangeListener(function (text) {
console.log("接收到粘贴板发生改变通知：", text);
});
//实时的屏幕图像回调，注意浏览器环境下 img 为 Blob，Node 环境下为 arrayBuffer
device.mScreenControl.addScreenChangeListener(function (screenImg) {
console.log("接收到新的屏幕图像：", screenImg);
});
//弱网环境下使用被动式屏幕帧，网络好的情况下可以使用主动式获取屏幕图像帧；
//只有调用了下边2种方法，屏幕图像的回调才能收到消息
//device.mScreenControl.startScreenStream();//主动式
device.mScreenControl.startScreenStreamByPassive(); //被动式
}
main();
```
### [更多案例](https://github.com/automan-bot/android-bot/tree/master/demo)
## 核心类
### Device
| function | 含义 | 备注 |
| ---------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| addErrorListener | 添加全局错误监听 |
| setWebSocketClient | 设置 websocket client | Node 环境下使用 NodeWebSocket，浏览器环境下你需要使用 BrowserWebSocket |
| hello | 欢迎信息 |
| version | 获取核心库版本 |
| checkNotification | 检查此设备是否能监听通知 | 监听通知需要 android 系统版本>=android9 |
| getDeviceId | 获取设备的 DeviceId | 此 Id 有 AutoBot 生成，非 andorid id |
| startRecoreScreen | 启动屏幕录像 |
| stopRecoreScreen | 停止屏幕录像 |
| getSystemInfo | 获取系统信息 |
| screenInfo | 屏幕信息 |
| screenJson | 屏幕 UI 布局的 json 格式 |
| screenXml | 屏幕 Ui 布局的 XML 格式 |
| screenShotBase64 | 屏幕截图的 jpeg base64 格式 |
| screenShot | 屏幕截图 jpeg 二进制 |
| screenRotation | 屏幕旋转方向 |
| getAllContact | 获取所有的联系人 |
| insertContact | 插入新的联系人 |
| deleteContact | 删除联系人 |
| getClipText | 获取粘贴板数据 |
| setClipText | 设置粘贴板数据 |
| clearText | 清除输入框数据 | 需要设备的输入框处于获取焦点的状态，类似 ctrl+A,然后在执行 delete 的效果 |
| turnScreenOff | 开启熄屏控制模式 |
| getIp | 获取设备的所有 ip |
| getAllSms | 获取所有的短信，支持获取指定号码的短信 |
| deleteSms | ~~删除短信~~ | 此方法已弃用 ，由于 android 设备安全限制，请到短信应用删除短信 |
| getTopActivity | 获取设备顶层的活动 Activity 信息 |
| getStartActivity | 根据包名获取启动类 | 不传获取顶层 activity 的启动 activity 信息 |
| startPackage | 根据包名启动应用 |
| stopPackage | 根据包名停止应用 |
| clearPackage | 根据包名清除应用数据 |
| getAllPackage | 获取设备应用所有应用列表 |
| getPackageInfo | 根据包名获取详细的应用信息 |
| cancelAllNotifications | ~~移除所有的通知 ~~ | 此方法已弃用 |
| callPhone | 拨打电话 |
| endCall | 挂断电话 |
| inputText | 输入字符串，支持多种语言 |
| inputChar | 输入字符仅支持 ACSII 码 |
| execCmd | 执行 shell 命令 |
| pressKeyCode | 模拟按键 | 查询对应的 keyCode 可以参考 adb 用法文档,也可以参考 android sdk 的 KeyEvent.java 类 |
| click | 点击 | 支持百分比坐标和绝对坐标 |
| longClick | 长按 | 支持百分比坐标和绝对坐标 |
| press | 长按 x 毫秒 | 支持百分比坐标和绝对坐标 |
| swipe | 滑动 | 支持百分比坐标和绝对坐标 |
| gesture | 单指手势 |
| gestures | 多指手势 |
| listFile | 列出文件夹 |
| turnSafeModeOn | 开启安全模式 | 安全模式下无法使获取屏幕布局，无法使用文字查找，选择器查找功能，且 websocket 通知信息将不再通知用 |
| turnSafeModeOff | 关闭安全模式 |
| isSafeMode | 判断是否是安全模式 |
| upload | 上传一个文件 | |
| uploadUrl | 获取上传文件得 url | 需要构建一个 FormData 对象，file 为 file 对象，path 为要上传到得文件夹 |
| delFile | 删除一个文件或文件夹 | 传入一个路径，文件夹：/sdcard/tmp，文件/sdcard/hello.txt |
| downloadUrl | 获取一个文件得下载路径 | 传入一个路径，获取下载链接，浏览器环境你可以直接打开这个链接进行下载，node 环境下你可以使用 download 库或其他一些下载库 |
| getDisplayName | 获取设置的自定义设备名称 |
| setDisplayName | 设置的自定义设备名称 |
| playMusic | 播放网络音乐 | 传入一个音乐的 url 实现自定义播放网络音乐 ，此接口需要 android 版本>=9.0 |
| stopMusic | 停止播放网络音乐 | 停止正在播放的网络音乐 ，此接口需要 android 版本>=9.0 |
| execScript | 执行 autox.js 脚本 | 注意调用此功能必去安装带 autox 执行环境的 autobot，否则无法运行 |
| stopAllScript | 停止所有的 autox.js 脚本 | 注意调用此功能必去安装带 autox 执行环境的 autobot，否则无法运行 |
| exit | 停止 AutoBot 服务端 | 注意，停止后你将无法调用任何接口，你需要重新在 AutoBot 端激活服务端 |
### ScreenControl
| function | 含义 | 备注 |
| --------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| startScreenStream | 通知服务端主动推送屏幕图像 |
| startScreenStreamByPassive | 被动式通知服务端推送屏幕图像 | 弱网环境下，主动式推送屏幕图像会有较大的延迟，被动式会在接受到屏幕图像后，发送消息通知服务端传输新的屏幕图像，因此获取的屏幕图像更及时 |
| setScreenStreamConfig | 设置屏幕图像的帧率，缩放和压缩比 | 注意这里的 fps 为延迟多少 ms（毫秒）收取新的屏幕图像 |
| stopScreenStream | 停止屏幕图像推送 |
| pressKeyCode | 模拟按键 | 和 Device 的 pressKeyCode 参数一致，不一样的是这里通过 websocket 发送数据，因此实时性更高 |
| sendSpaceKey | 发送空格按键 | |
| sendBackSpaceKey | 发送退格按键 | |
| sendInputText | 输入字符串，支持多种语言 | |
| sendInputChar | 输入字符仅支持 ACSII 码 ，按键模拟方式实现，支持屏幕密码解锁，支付密码输入等场景 | |
| addScreenOrentationChangeListener | 添加屏幕方向发生改变的监听 | 此通知会在初次链连接成功后就通知一次，方便你为渲染做好准备 |
| addNotificationChangeListener | 添加通知消息发生改变的监听 | |
| addScreenChangeListener | 添加屏幕图像的监听 | 当你调用主动式（startScreenStream）或者被动式（startScreenStreamByPassive）通知服务端传输屏幕图像后，此监听才有数据返回 |
| addClipTextChangeListener | 添加粘贴板发生改变的监听 | |
## FAQ
### 我使用了实例代码，为什么代码报错？
由于 Node 环境默认是不支持 websocket 的，需要通过第三方库来实现 WebSocket，因此 Node 环境下的 WebSocket 和浏览器环境下的 WebSocket 有少许不一样
- 因此，如果你的代码在浏览器环境运行请导入 BrowserWebSocket，在 Node 环境下请导入 NodeWebSocket，另外请一定不要导入多余的对象，比如在浏览器环境下错误的导入了 AdbDevice，NodeWebSocket
- Node 导入示例
```javascript
import { AdbDevice, NodeWebSocket, Device } from "android-bot";
```
- 浏览器导入示例
```javascript
import { BrowserWebSocket, Device } from "android-bot";
```
### 有些方法的参数我还是有疑问？
`android-bot`是对 AutoBot 的 Http API 和 WebSocket API 的封装，你可以查看对应的[AutoBot 官](https://mobile.tntok.top/autobot_doc)
## 二次开发
### 获取代码
```shell
git clone https://github.com/automan-bot/android-bot.git
npm i
```
### NPM scripts
- `demo_browser`:运行浏览器 demo
- `demo_node`:运行 Node 环境下 demo
- `dev`: 以监听模式监听 src/的文件改变，在 dist 下生成新的 Node 环境编译包
- `dev:browser`:以监听模式监听 src/的文件改变，在 dist 下生成浏览器环境编译包
- `build `: 编译生成 Node 环境和浏览器环境的编译包
- `clean `: 清空/dist 目录