命令参考
Droidline 全部命令的参数、返回值、错误,以及在 Python、Node.js、C#、CLI 和 HTTP 中的同一调用。
本页为译文。如与英文版不一致,以英文版为准。 English
每条命令都列出它的作用、参数、返回值和可能的错误,然后给出各个接口中的同一调用。在任意示例中选择一种语言,整页都会跟着切换。Python 示例假定已经执行了 d = connect()(服务器命令为 dl = Droidline()),Node.js 示例假定已经执行了 const d = await connect()(const dl = new Droidline()),C# 示例假定已经执行了 await using var d = await DroidlineClient.ConnectAsync()(using var client = new DroidlineClient())。
查询
以对象形式书写的选择器。所有条件必须在同一个元素上成立。作为 by 传入,省略 value.
| 键 | 类型 | 含义 |
|---|---|---|
text | 文字 | text 完全匹配 |
textContains | 文字 | text 的一部分 |
textMatches | 文字 | 匹配整个 text 的正则表达式 |
id | 文字 | resource-id,或只写 :id/ 后面的名称 |
desc | 文字 | content-desc 完全匹配 |
descContains | 文字 | content-desc 的一部分 |
descMatches | 文字 | 匹配整个 content-desc 的正则表达式 |
class | 文字 | class 名称完全匹配 |
package | 文字 | 元素所属的包 |
clickable | true 或 false | 节点的 clickable 值等于此值 |
long_clickable | true 或 false | 节点的 long_clickable 值等于此值 |
checkable | true 或 false | 节点的 checkable 值等于此值 |
checked | true 或 false | 节点的 checked 值等于此值 |
enabled | true 或 false | 节点的 enabled 值等于此值 |
focused | true 或 false | 节点的 focused 值等于此值 |
selected | true 或 false | 节点的 selected 值等于此值 |
scrollable | true 或 false | 节点的 scrollable 值等于此值 |
editable | true 或 false | 节点的 editable 值等于此值 |
password | true 或 false | 节点的 password 值等于此值 |
visible | true 或 false | 元素是否在屏幕内。列表会把刚超出边缘的项也留在树里,visible: true 会跳过它们 |
bounds | [left, top, right, bottom] | 与 dump 和 find 返回的 bounds [left, top, right, bottom] 完全相同 |
has | 另一个查询 | 某个后代元素匹配此查询 |
inside | 另一个查询 | 某个祖先元素匹配此查询 |
row | 另一个查询 | 它所在的行里有匹配此查询的元素。行是最近列表(RecyclerView、ListView、GridView,或有多个子元素的可滚动视图)中的一项;不在列表中时是最近的可点击祖先 |
below | 另一个查询 | 中心位于此查询第一个结果的下方。结果按由近到远排列 |
above | 另一个查询 | 中心位于此查询第一个结果的上方。结果按由近到远排列 |
left_of | 另一个查询 | 中心位于此查询第一个结果的左侧。结果按由近到远排列 |
right_of | 另一个查询 | 中心位于此查询第一个结果的右侧。结果按由近到远排列 |
界面
dumpscreenshotrecordfind_imagetap_imageimage_existsfind_imageswait_image_goneocrocr_findocr_tapcurrent
dump
返回当前界面的节点树
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
path | string | 保存为本地 JSON 文件 | |
all_windows | bool | false | 包含状态栏、键盘等系统窗口 |
返回: 包含以下字段的对象: package, activity, width, height, tree
d.dump("screen.json") # saved on your PCawait d.dump("screen.json"); // saved on your PCawait d.DumpAsync("screen.json"); // saved on your PCdroidline dump screen.jsoncurl -s -X POST localhost:8780/devices/_/dump \
-H 'content-type: application/json' > screen.json{"id":1,"cmd":"dump"}screenshot
截取屏幕
Android 11 及以上使用无障碍截图,9-10 首次需要允许屏幕录制
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
path | string | 保存到本地文件,扩展名决定 png 或 jpeg | |
format | string png | jpeg | "jpeg" | 图片格式 |
quality | int | 80 | JPEG 质量 1-100 |
scale | number | 1 | 缩放比例 0.1-1.0,移动网络下有用 |
返回: 包含以下字段的对象: format, width, height, data
d.screenshot("shot.png") # saved on your PCawait d.screenshot("shot.png"); // saved on your PCawait d.ScreenshotAsync("shot.png"); // saved on your PCdroidline screenshot shot.pngcurl -s localhost:8780/devices/_/screenshot.png -o shot.png{"id":1,"cmd":"screenshot"}record
开启或关闭点击和输入的录制
可选功能,开启前处于关闭状态。开启期间,手机会为其他应用中的每次点击、长按和文字变化发送 action 事件,并附带当时的界面;密码框不发送文字。到 minutes 后自动关闭。droidline inspect 用它在你使用手机时生成脚本
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
on | bool | 必填 | true 开始,false 停止 |
minutes | number | 30 | 经过这么久后自动关闭 |
返回: 无
d.record(True)await d.record(true);await d.RecordAsync(true);droidline record truecurl -s -X POST localhost:8780/devices/_/record \
-H 'content-type: application/json' \
-d '{"on":true}'{"id":1,"cmd":"record","on":true}find_image
在屏幕上查找图片
可选功能,在电脑上运行:服务器获取截图后进行比较。请从同一台手机的截图中裁剪;屏幕密度不同的手机请传入 scales。Android 9 和 10 截图需要屏幕录制权限
在电脑上运行:服务器从手机获取截图,并通过手机点击。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
image | image | 必填 | 要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64 |
threshold | number | 0.9 | 匹配需要多接近,0 到 1 |
timeout | number | 10 s | 等待目标出现的秒数 |
region | list<int> | 只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配 | |
scales | list<number> | 要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间 | |
color | bool | false | 还要求平均颜色一致,用来区分形状相同的红色和绿色按钮 |
返回: 包含以下字段的对象: x, y, bounds, score
错误: NOT_FOUND, NO_PERMISSION
d.find_image("ok-button.png")await d.findImage("ok-button.png");await d.FindImageAsync("ok-button.png");droidline find_image ok-button.pngcurl -s -X POST localhost:8780/devices/_/find_image \
-H 'content-type: application/json' \
-d '{"image":"<base64 of the PNG>"}'{"id":1,"cmd":"find_image","image":"<base64 of the PNG>"}tap_image
在屏幕上查找图片并点击其中心
可选功能,在电脑上运行:服务器获取截图后进行比较。请从同一台手机的截图中裁剪;屏幕密度不同的手机请传入 scales。Android 9 和 10 截图需要屏幕录制权限
在电脑上运行:服务器从手机获取截图,并通过手机点击。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
image | image | 必填 | 要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64 |
threshold | number | 0.9 | 匹配需要多接近,0 到 1 |
timeout | number | 10 s | 等待目标出现的秒数 |
region | list<int> | 只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配 | |
scales | list<number> | 要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间 | |
color | bool | false | 还要求平均颜色一致,用来区分形状相同的红色和绿色按钮 |
返回: 包含以下字段的对象: x, y, score, ms
错误: NOT_FOUND, NO_PERMISSION
d.tap_image("ok-button.png", threshold=0.85)await d.tapImage("ok-button.png", { threshold: 0.85 });await d.TapImageAsync("ok-button.png", threshold: 0.85);droidline tap_image ok-button.png --threshold 0.85curl -s -X POST localhost:8780/devices/_/tap_image \
-H 'content-type: application/json' \
-d '{"image":"<base64 of the PNG>","threshold":0.85}'{"id":1,"cmd":"tap_image","image":"<base64 of the PNG>","threshold":0.85}image_exists
图片当前是否在屏幕上,不等待
可选功能,在电脑上运行:服务器获取截图后进行比较。请从同一台手机的截图中裁剪;屏幕密度不同的手机请传入 scales。Android 9 和 10 截图需要屏幕录制权限
在电脑上运行:服务器从手机获取截图,并通过手机点击。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
image | image | 必填 | 要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64 |
threshold | number | 0.9 | 匹配需要多接近,0 到 1 |
region | list<int> | 只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配 | |
scales | list<number> | 要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间 | |
color | bool | false | 还要求平均颜色一致,用来区分形状相同的红色和绿色按钮 |
返回: 以下类型的值: bool
错误: NO_PERMISSION
find_images
图片在屏幕上出现的所有位置
未设置 timeout 时立即返回,没有匹配时返回空列表。按匹配程度由高到低返回,且互不重叠。在电脑上运行;屏幕密度不同的手机请传入 scales
在电脑上运行:服务器从手机获取截图,并通过手机点击。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
image | image | 必填 | 要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64 |
threshold | number | 0.9 | 匹配需要多接近,0 到 1 |
timeout | number | 0 s | 等待至少一个匹配的秒数。0 表示立即返回 |
region | list<int> | 只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配 | |
scales | list<number> | 要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间 | |
color | bool | false | 还要求平均颜色一致,用来区分形状相同的红色和绿色按钮 |
max | int | 20 | 最多返回的数量 |
返回: 以下类型的值: list<image_match>
错误: NO_PERMISSION
wait_image_gone
等待图片从屏幕上消失
可选功能,在电脑上运行:服务器获取截图后进行比较。请从同一台手机的截图中裁剪;屏幕密度不同的手机请传入 scales。Android 9 和 10 截图需要屏幕录制权限
在电脑上运行:服务器从手机获取截图,并通过手机点击。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
image | image | 必填 | 要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64 |
threshold | number | 0.9 | 匹配需要多接近,0 到 1 |
timeout | number | 10 s | 等待目标出现的秒数 |
region | list<int> | 只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配 | |
scales | list<number> | 要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间 | |
color | bool | false | 还要求平均颜色一致,用来区分形状相同的红色和绿色按钮 |
返回: 包含以下字段的对象: ms
错误: TIMEOUT, NO_PERMISSION
ocr
用 OCR 读取屏幕上的文字
可选功能,在电脑上用 Tesseract 运行。Tesseract 和所需的语言数据需要自行安装,不会自动安装。Android 9 和 10 截图需要屏幕录制权限
在电脑上运行:服务器从手机获取截图,并通过手机点击。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
lang | string | "eng" | Tesseract 语言,例如 chi_sim+eng。每种语言都需要安装对应的语言数据 |
返回: 包含以下字段的对象: text, lines
错误: OCR_UNAVAILABLE, NO_PERMISSION
d.ocr("chi_sim+eng")await d.ocr("chi_sim+eng");await d.OcrAsync("chi_sim+eng");droidline ocr chi_sim+engcurl -s -X POST localhost:8780/devices/_/ocr \
-H 'content-type: application/json' \
-d '{"lang":"chi_sim+eng"}'{"id":1,"cmd":"ocr","lang":"chi_sim+eng"}ocr_find
等待 OCR 在屏幕上读到文字并返回其位置
可选功能,在电脑上用 Tesseract 运行。Tesseract 和所需的语言数据需要自行安装,不会自动安装。Android 9 和 10 截图需要屏幕录制权限
在电脑上运行:服务器从手机获取截图,并通过手机点击。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
text | string | 必填 | 要查找的文字:完整的单词,或一行中的一部分 |
lang | string | "eng" | Tesseract 语言,例如 chi_sim+eng。每种语言都需要安装对应的语言数据 |
timeout | number | 10 s | 等待目标出现的秒数 |
返回: 包含以下字段的对象: text, x, y, bounds
错误: NOT_FOUND, OCR_UNAVAILABLE, NO_PERMISSION
d.ocr_find("下一步", "chi_sim+eng")await d.ocrFind("下一步", "chi_sim+eng");await d.OcrFindAsync("下一步", "chi_sim+eng");droidline ocr_find "下一步" chi_sim+engcurl -s -X POST localhost:8780/devices/_/ocr_find \
-H 'content-type: application/json' \
-d '{"text":"下一步","lang":"chi_sim+eng"}'{"id":1,"cmd":"ocr_find","text":"下一步","lang":"chi_sim+eng"}ocr_tap
等待 OCR 在屏幕上读到文字并点击
可选功能,在电脑上用 Tesseract 运行。Tesseract 和所需的语言数据需要自行安装,不会自动安装。Android 9 和 10 截图需要屏幕录制权限
在电脑上运行:服务器从手机获取截图,并通过手机点击。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
text | string | 必填 | 要查找的文字:完整的单词,或一行中的一部分 |
lang | string | "eng" | Tesseract 语言,例如 chi_sim+eng。每种语言都需要安装对应的语言数据 |
timeout | number | 10 s | 等待目标出现的秒数 |
返回: 包含以下字段的对象: text, x, y, ms
错误: NOT_FOUND, OCR_UNAVAILABLE, NO_PERMISSION
d.ocr_tap("开始", "chi_sim+eng")await d.ocrTap("开始", "chi_sim+eng");await d.OcrTapAsync("开始", "chi_sim+eng");droidline ocr_tap "开始" chi_sim+engcurl -s -X POST localhost:8780/devices/_/ocr_tap \
-H 'content-type: application/json' \
-d '{"text":"开始","lang":"chi_sim+eng"}'{"id":1,"cmd":"ocr_tap","text":"开始","lang":"chi_sim+eng"}current
前台包名和 Activity
返回: 包含以下字段的对象: package, activity
d.current()await d.current();await d.CurrentAsync();droidline currentcurl -s -X POST localhost:8780/devices/_/current \
-H 'content-type: application/json'{"id":1,"cmd":"current"}坐标
tap
点击坐标
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
x | int | 必填 | 屏幕像素 X |
y | int | 必填 | 屏幕像素 Y |
返回: 包含以下字段的对象: ms
d.tap(540, 1200)await d.tap(540, 1200);await d.TapAsync(540, 1200);droidline tap 540 1200curl -s -X POST localhost:8780/devices/_/tap \
-H 'content-type: application/json' \
-d '{"x":540,"y":1200}'{"id":1,"cmd":"tap","x":540,"y":1200}long_tap
长按坐标
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
x | int | 必填 | 屏幕像素 X |
y | int | 必填 | 屏幕像素 Y |
ms | int | 800 | 按住时长(毫秒) |
返回: 包含以下字段的对象: ms
d.long_tap(540, 1200, 800)await d.longTap(540, 1200, 800);await d.LongTapAsync(540, 1200, 800);droidline long_tap 540 1200 800curl -s -X POST localhost:8780/devices/_/long_tap \
-H 'content-type: application/json' \
-d '{"x":540,"y":1200,"ms":800}'{"id":1,"cmd":"long_tap","x":540,"y":1200,"ms":800}swipe
在两点之间或按方向滑动
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
x1 | int|string | 必填 | 起点 X,或方向:up、down、left、right |
y1 | int | 起点 Y | |
x2 | int | 终点 X | |
y2 | int | 终点 Y | |
ms | int | 300 | 时长(毫秒) |
返回: 包含以下字段的对象: ms
d.swipe(540, 1600, 540, 400, 300)await d.swipe(540, 1600, 540, 400, 300);await d.SwipeAsync(540, 1600, 540, 400, 300);droidline swipe 540 1600 540 400 300curl -s -X POST localhost:8780/devices/_/swipe \
-H 'content-type: application/json' \
-d '{"x1":540,"y1":1600,"x2":540,"y2":400,"ms":300}'{"id":1,"cmd":"swipe","x1":540,"y1":1600,"x2":540,"y2":400,"ms":300}元素
touch
等待元素出现并点击
节点拒绝点击时改为点击 bounds 中心。via 表示成功方式:node、parent 或 gesture
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
timeout | number | 10 s | 等待目标出现的秒数 |
返回: 包含以下字段的对象: via, ms
简写: touchById(value), touchByText(value), touchByDesc(value)
错误: NOT_FOUND, NOT_CLICKABLE, NO_ACCESSIBILITY
d.touch("text", "登录")await d.touch("text", "登录");await d.TouchAsync("text", "登录");droidline touch text "登录"curl -s -X POST localhost:8780/devices/_/touch \
-H 'content-type: application/json' \
-d '{"by":"text","value":"登录"}'{"id":1,"cmd":"touch","by":"text","value":"登录"}long_touch
等待元素出现并长按
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
ms | int | 800 | 按住时长(毫秒) |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
timeout | number | 10 s | 等待目标出现的秒数 |
返回: 包含以下字段的对象: via, ms
d.long_touch("text", "消息")await d.longTouch("text", "消息");await d.LongTouchAsync("text", "消息");droidline long_touch text "消息"curl -s -X POST localhost:8780/devices/_/long_touch \
-H 'content-type: application/json' \
-d '{"by":"text","value":"消息"}'{"id":1,"cmd":"long_touch","by":"text","value":"消息"}scroll_to
滚动直到元素可见
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
direction | string down | up | left | right | "down" | 滚动方向 |
max_swipes | int | 20 | 滑动这么多次后放弃 |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
返回: 包含以下字段的对象: swipes
d.scroll_to("text", "设置")await d.scrollTo("text", "设置");await d.ScrollToAsync("text", "设置");droidline scroll_to text "设置"curl -s -X POST localhost:8780/devices/_/scroll_to \
-H 'content-type: application/json' \
-d '{"by":"text","value":"设置"}'{"id":1,"cmd":"scroll_to","by":"text","value":"设置"}输入
input
等待输入框并填入文字
使用无障碍设置文本操作;忽略该操作的输入框在选择了 Droidline 键盘时改用键盘输入
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
text | string | 必填 | 要输入的文字 |
append | bool | false | 保留原有文字并追加 |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
timeout | number | 10 s | 等待目标出现的秒数 |
返回: 包含以下字段的对象: via, ms
d.input("id", "email", "me@example.com")await d.input("id", "email", "me@example.com");await d.InputAsync("id", "email", "me@example.com");droidline input id email me@example.comcurl -s -X POST localhost:8780/devices/_/input \
-H 'content-type: application/json' \
-d '{"by":"id","value":"email","text":"me@example.com"}'{"id":1,"cmd":"input","by":"id","value":"email","text":"me@example.com"}clear
清空输入框
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
timeout | number | 10 s | 等待目标出现的秒数 |
返回: 包含以下字段的对象: ms
d.clear("id", "email")await d.clear("id", "email");await d.ClearAsync("id", "email");droidline clear id emailcurl -s -X POST localhost:8780/devices/_/clear \
-H 'content-type: application/json' \
-d '{"by":"id","value":"email"}'{"id":1,"cmd":"clear","by":"id","value":"email"}sendkey
发送按键名、键码或文字
back、home、recents、notifications、quick_settings、lock 使用无障碍全局操作;其他按键和文字通过 Droidline 键盘发送到焦点输入框
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
key | string|int | 按键名(enter、tab、del、space、escape、up、down、left、right、back、home 等)、Android 键码或要输入的文字 | |
text | string | 按字面输入,即使与按键名相同 |
返回: 包含以下字段的对象: via
d.sendkey("enter")await d.sendkey("enter");await d.SendkeyAsync("enter");droidline sendkey entercurl -s -X POST localhost:8780/devices/_/sendkey \
-H 'content-type: application/json' \
-d '{"key":"enter"}'{"id":1,"cmd":"sendkey","key":"enter"}检查
existswaitwait_gonewait_idlefindfind_allget_text
exists
元素当前是否在屏幕上,不等待
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
返回: 以下类型的值: bool
d.exists("text", "关闭广告")await d.exists("text", "关闭广告");await d.ExistsAsync("text", "关闭广告");droidline exists text "关闭广告"curl -s -X POST localhost:8780/devices/_/exists \
-H 'content-type: application/json' \
-d '{"by":"text","value":"关闭广告"}'{"id":1,"cmd":"exists","by":"text","value":"关闭广告"}wait
等待元素出现
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
timeout | number | 10 s | 等待目标出现的秒数 |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
返回: 包含以下字段的对象: ms
错误: NOT_FOUND
d.wait("text", "完成", timeout=30)await d.wait("text", "完成", { timeout: 30 });await d.WaitAsync("text", "完成", timeout: 30);droidline wait text "完成" --timeout 30curl -s -X POST localhost:8780/devices/_/wait \
-H 'content-type: application/json' \
-d '{"by":"text","value":"完成","timeout":30}'{"id":1,"cmd":"wait","by":"text","value":"完成","timeout":30}wait_gone
等待元素消失
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
timeout | number | 10 s | 等待目标出现的秒数 |
返回: 包含以下字段的对象: ms
错误: TIMEOUT
d.wait_gone("text", "加载中")await d.waitGone("text", "加载中");await d.WaitGoneAsync("text", "加载中");droidline wait_gone text "加载中"curl -s -X POST localhost:8780/devices/_/wait_gone \
-H 'content-type: application/json' \
-d '{"by":"text","value":"加载中"}'{"id":1,"cmd":"wait_gone","by":"text","value":"加载中"}wait_idle
等待界面不再变化
等待前台应用在 ms 毫秒内没有新的绘制。在会加载内容的操作之后使用,代替固定的 sleep。一直有动画的界面会以 TIMEOUT 结束
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
ms | int | 500 ms | 界面需要保持不变的时长 |
timeout | number | 10 s | 放弃前等待的秒数 |
返回: 包含以下字段的对象: ms
错误: TIMEOUT
d.wait_idle()await d.waitIdle();await d.WaitIdleAsync();droidline wait_idlecurl -s -X POST localhost:8780/devices/_/wait_idle \
-H 'content-type: application/json'{"id":1,"cmd":"wait_idle"}find
等待元素出现并返回该元素
SDK 返回带有 click、input、find 和节点字段的元素对象。节点不含 children
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
timeout | number | 10 s | 等待目标出现的秒数 |
返回: 以下类型的值: node
错误: NOT_FOUND
d.find("text", "登录")await d.find("text", "登录");await d.FindAsync("text", "登录");droidline find text "登录"curl -s -X POST localhost:8780/devices/_/find \
-H 'content-type: application/json' \
-d '{"by":"text","value":"登录"}'{"id":1,"cmd":"find","by":"text","value":"登录"}find_all
当前所有匹配的元素
未设置 timeout 时立即返回,没有匹配时返回空列表。方向查询按距离由近到远返回
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
timeout | number | 0 s | 等待至少一个匹配的秒数。0 表示立即返回 |
返回: 以下类型的值: list<node>
d.find_all("id", "title")await d.findAll("id", "title");await d.FindAllAsync("id", "title");droidline find_all id titlecurl -s -X POST localhost:8780/devices/_/find_all \
-H 'content-type: application/json' \
-d '{"by":"id","value":"title"}'{"id":1,"cmd":"find_all","by":"id","value":"title"}get_text
元素的文字,不存在时为空字符串
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
返回: 以下类型的值: string
d.get_text("id", "balance")await d.getText("id", "balance");await d.GetTextAsync("id", "balance");droidline get_text id balancecurl -s -X POST localhost:8780/devices/_/get_text \
-H 'content-type: application/json' \
-d '{"by":"id","value":"balance"}'{"id":1,"cmd":"get_text","by":"id","value":"balance"}条件
checkedenabledselectedcountwhichin_appkeyboard_shownlast_toastcolor
checked
开关或复选框为开启时返回 true
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
返回: 以下类型的值: bool
d.checked("id", "auto_login")await d.checked("id", "auto_login");await d.CheckedAsync("id", "auto_login");droidline checked id auto_logincurl -s -X POST localhost:8780/devices/_/checked \
-H 'content-type: application/json' \
-d '{"by":"id","value":"auto_login"}'{"id":1,"cmd":"checked","by":"id","value":"auto_login"}enabled
元素可点击时返回 true
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
返回: 以下类型的值: bool
d.enabled("text", "下一步")await d.enabled("text", "下一步");await d.EnabledAsync("text", "下一步");droidline enabled text "下一步"curl -s -X POST localhost:8780/devices/_/enabled \
-H 'content-type: application/json' \
-d '{"by":"text","value":"下一步"}'{"id":1,"cmd":"enabled","by":"text","value":"下一步"}selected
标签或项目被选中时返回 true
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 | |
nth | int | 0 | 多个元素匹配时的序号,从 0 开始 |
返回: 以下类型的值: bool
d.selected("text", "首页")await d.selected("text", "首页");await d.SelectedAsync("text", "首页");droidline selected text "首页"curl -s -X POST localhost:8780/devices/_/selected \
-H 'content-type: application/json' \
-d '{"by":"text","value":"首页"}'{"id":1,"cmd":"selected","by":"text","value":"首页"}count
匹配元素的数量
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | selector | 必填 | 按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象 |
value | string | 要匹配的值。by 为查询对象时省略 |
返回: 以下类型的值: int
d.count("class", "android.widget.CheckBox")await d.count("class", "android.widget.CheckBox");await d.CountAsync("class", "android.widget.CheckBox");droidline count class android.widget.CheckBoxcurl -s -X POST localhost:8780/devices/_/count \
-H 'content-type: application/json' \
-d '{"by":"class","value":"android.widget.CheckBox"}'{"id":1,"cmd":"count","by":"class","value":"android.widget.CheckBox"}which
最先出现的候选项序号,没有则为 -1
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
candidates | list<selector_pair> | 必填 | [条件, 值] 对或查询对象的列表 |
timeout | number | 10 s | 等待任一候选出现的秒数 |
返回: 以下类型的值: int
d.which([("text", "登录"), ("id", "main_tab")], timeout=15)await d.which([["text", "登录"], ["id", "main_tab"]], { timeout: 15 });await d.WhichAsync(new object[] { ("text", "登录"), ("id", "main_tab") }, timeout: 15);droidline which text="登录" id=main_tab --timeout 15curl -s -X POST localhost:8780/devices/_/which \
-H 'content-type: application/json' \
-d '{"candidates":[["text","登录"],["id","main_tab"]],"timeout":15}'{"id":1,"cmd":"which","candidates":[["text","登录"],["id","main_tab"]],"timeout":15}in_app
该应用在前台时返回 true
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
package | string | 必填 | 包名,例如 com.android.chrome |
返回: 以下类型的值: bool
d.in_app("com.android.chrome")await d.inApp("com.android.chrome");await d.InAppAsync("com.android.chrome");droidline in_app com.android.chromecurl -s -X POST localhost:8780/devices/_/in_app \
-H 'content-type: application/json' \
-d '{"package":"com.android.chrome"}'{"id":1,"cmd":"in_app","package":"com.android.chrome"}keyboard_shown
软键盘显示时返回 true
返回: 以下类型的值: bool
d.keyboard_shown()await d.keyboardShown();await d.KeyboardShownAsync();droidline keyboard_showncurl -s -X POST localhost:8780/devices/_/keyboard_shown \
-H 'content-type: application/json'{"id":1,"cmd":"keyboard_shown"}last_toast
最近一条 Toast 的文字,没有则为空字符串
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
max_age | number | 30 s | 忽略早于此秒数的 Toast |
返回: 以下类型的值: string
d.last_toast()await d.lastToast();await d.LastToastAsync();droidline last_toastcurl -s -X POST localhost:8780/devices/_/last_toast \
-H 'content-type: application/json'{"id":1,"cmd":"last_toast"}color
坐标处的像素颜色(#RRGGBB)
用于没有无障碍节点的界面(如游戏)
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
x | int | 必填 | 屏幕像素 X |
y | int | 必填 | 屏幕像素 Y |
返回: 以下类型的值: string
d.color(540, 1200)await d.color(540, 1200);await d.ColorAsync(540, 1200);droidline color 540 1200curl -s -X POST localhost:8780/devices/_/color \
-H 'content-type: application/json' \
-d '{"x":540,"y":1200}'{"id":1,"cmd":"color","x":540,"y":1200}设备
screen_onlockedwakelockbatteryorientationinfo
screen_on
屏幕亮着时返回 true
返回: 以下类型的值: bool
d.screen_on()await d.screenOn();await d.ScreenOnAsync();droidline screen_oncurl -s -X POST localhost:8780/devices/_/screen_on \
-H 'content-type: application/json'{"id":1,"cmd":"screen_on"}locked
处于锁屏时返回 true
返回: 以下类型的值: bool
d.locked()await d.locked();await d.LockedAsync();droidline lockedcurl -s -X POST localhost:8780/devices/_/locked \
-H 'content-type: application/json'{"id":1,"cmd":"locked"}wake
点亮屏幕并解除无密码的锁屏
屏幕关闭时手势会失败。PIN、图案或密码锁需要用户解锁
返回: 包含以下字段的对象: screen_on, locked
d.wake()await d.wake();await d.WakeAsync();droidline wakecurl -s -X POST localhost:8780/devices/_/wake \
-H 'content-type: application/json'{"id":1,"cmd":"wake"}lock
关闭屏幕并锁定
返回: 无
d.lock()await d.lock();await d.LockAsync();droidline lockcurl -s -X POST localhost:8780/devices/_/lock \
-H 'content-type: application/json'{"id":1,"cmd":"lock"}battery
电量和充电状态
返回: 包含以下字段的对象: level, charging, temperature
d.battery()await d.battery();await d.BatteryAsync();droidline batterycurl -s -X POST localhost:8780/devices/_/battery \
-H 'content-type: application/json'{"id":1,"cmd":"battery"}orientation
屏幕方向:portrait 或 landscape
返回: 以下类型的值: string
d.orientation()await d.orientation();await d.OrientationAsync();droidline orientationcurl -s -X POST localhost:8780/devices/_/orientation \
-H 'content-type: application/json'{"id":1,"cmd":"orientation"}info
型号、Android 版本、屏幕尺寸和权限状态
返回: 包含以下字段的对象: model, manufacturer, sdk, release, agent, width, height, ready
d.info()await d.info();await d.InfoAsync();droidline infocurl -s -X POST localhost:8780/devices/_/info \
-H 'content-type: application/json'{"id":1,"cmd":"info"}网络
network
连接类型(wifi、mobile、none)和飞行模式
返回: 包含以下字段的对象: type, airplane, metered
d.network()await d.network();await d.NetworkAsync();droidline networkcurl -s -X POST localhost:8780/devices/_/network \
-H 'content-type: application/json'{"id":1,"cmd":"network"}proxy
通过按应用 VPN 让指定应用走上游代理
支持 http://(CONNECT)和 socks5://,可带 user:pass。传 null 或 "off" 关闭。同一时间仅一个上游。忽略代理设置的应用会断网而不是泄漏
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
url | string|null | 必填 | socks5://user:pass@host:port、http://host:port、@kr1 这样的已保存配置,或 off |
app | string|list<string> | 要走代理的包(可多个) |
返回: 包含以下字段的对象: active, apps
错误: NO_PERMISSION, PROXY_FAILED, UNSUPPORTED
d.proxy("@kr1", app="com.android.chrome")await d.proxy("@kr1", { app: "com.android.chrome" });await d.ProxyAsync("@kr1", app: "com.android.chrome");droidline proxy @kr1 --app com.android.chromecurl -s -X POST localhost:8780/devices/_/proxy \
-H 'content-type: application/json' \
-d '{"url":"@kr1","app":"com.android.chrome"}'{"id":1,"cmd":"proxy","url":"@kr1","app":"com.android.chrome"}proxy_check
按应用代理状态和外部看到的 IP
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
app | string | 要检查的包 |
返回: 包含以下字段的对象: active, ip, upstream, error
d.proxy_check("com.android.chrome")await d.proxyCheck("com.android.chrome");await d.ProxyCheckAsync("com.android.chrome");droidline proxy_check com.android.chromecurl -s -X POST localhost:8780/devices/_/proxy_check \
-H 'content-type: application/json' \
-d '{"app":"com.android.chrome"}'{"id":1,"cmd":"proxy_check","app":"com.android.chrome"}应用
launchopen_urlintentclear_dataappsinstalled
launch
启动应用,可指定 Activity
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
package | string | 必填 | 包名,例如 com.android.chrome |
activity | string | Activity 名称,完整名称或以点开头 |
返回: 包含以下字段的对象: ms
错误: APP_NOT_FOUND, ACTIVITY_BLOCKED
d.launch("com.android.settings")await d.launch("com.android.settings");await d.LaunchAsync("com.android.settings");droidline launch com.android.settingscurl -s -X POST localhost:8780/devices/_/launch \
-H 'content-type: application/json' \
-d '{"package":"com.android.settings"}'{"id":1,"cmd":"launch","package":"com.android.settings"}open_url
打开 URL 或深层链接
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
url | string | 必填 | http(s) 地址或应用深层链接 |
package | string | 仅用此应用打开 |
返回: 无
d.open_url("https://droidline.dev")await d.openUrl("https://droidline.dev");await d.OpenUrlAsync("https://droidline.dev");droidline open_url https://droidline.devcurl -s -X POST localhost:8780/devices/_/open_url \
-H 'content-type: application/json' \
-d '{"url":"https://droidline.dev"}'{"id":1,"cmd":"open_url","url":"https://droidline.dev"}intent
按 intent action 打开界面,例如某个设置页面
可以打开任何允许其他应用打开的界面,例如 android.settings.WIFI_SETTINGS,或把 data 设为 package:com.example 的 android.settings.APPLICATION_DETAILS_SETTINGS。界面会重新打开,并关闭同一应用的其他界面。之后要点什么因厂商和语言而异,所以 Wi-Fi、飞行模式、强行停止和清除数据以文档中的示例提供,而不是命令
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
action | string | 必填 | Intent action,例如 android.settings.WIFI_SETTINGS |
data | string | 数据 URI,例如 package:com.example | |
package | string | 只让这个应用处理 |
返回: 无
错误: APP_NOT_FOUND, BAD_ARGS
d.intent("android.settings.WIFI_SETTINGS")await d.intent("android.settings.WIFI_SETTINGS");await d.IntentAsync("android.settings.WIFI_SETTINGS");droidline intent android.settings.WIFI_SETTINGScurl -s -X POST localhost:8780/devices/_/intent \
-H 'content-type: application/json' \
-d '{"action":"android.settings.WIFI_SETTINGS"}'{"id":1,"cmd":"intent","action":"android.settings.WIFI_SETTINGS"}clear_data
在设备所有者模式下清除应用数据
可选,仅在设备所有者模式下可用,手机不打开设置直接清除。不在该模式时返回 NO_PERMISSION;经由设置界面的做法见文档中的示例
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
package | string | 必填 | 包名,例如 com.android.chrome |
返回: 包含以下字段的对象: ms
错误: APP_NOT_FOUND, NO_PERMISSION
d.clear_data("com.android.chrome")await d.clearData("com.android.chrome");await d.ClearDataAsync("com.android.chrome");droidline clear_data com.android.chromecurl -s -X POST localhost:8780/devices/_/clear_data \
-H 'content-type: application/json' \
-d '{"package":"com.android.chrome"}'{"id":1,"cmd":"clear_data","package":"com.android.chrome"}apps
已安装的包列表
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
system | bool | false | 包含系统包 |
返回: 以下类型的值: list<app>
d.apps()await d.apps();await d.AppsAsync();droidline appscurl -s -X POST localhost:8780/devices/_/apps \
-H 'content-type: application/json'{"id":1,"cmd":"apps"}installed
已安装时返回版本名,否则为空字符串
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
package | string | 必填 | 包名,例如 com.android.chrome |
返回: 以下类型的值: string
d.installed("com.android.chrome")await d.installed("com.android.chrome");await d.InstalledAsync("com.android.chrome");droidline installed com.android.chromecurl -s -X POST localhost:8780/devices/_/installed \
-H 'content-type: application/json' \
-d '{"package":"com.android.chrome"}'{"id":1,"cmd":"installed","package":"com.android.chrome"}系统
backhomerecentsopen_notificationsquick_settingsclipboardbatch
back
返回
返回: 无
d.back()await d.back();await d.BackAsync();droidline backcurl -s -X POST localhost:8780/devices/_/back \
-H 'content-type: application/json'{"id":1,"cmd":"back"}home
主屏幕
返回: 无
d.home()await d.home();await d.HomeAsync();droidline homecurl -s -X POST localhost:8780/devices/_/home \
-H 'content-type: application/json'{"id":1,"cmd":"home"}recents
最近任务
返回: 无
d.recents()await d.recents();await d.RecentsAsync();droidline recentscurl -s -X POST localhost:8780/devices/_/recents \
-H 'content-type: application/json'{"id":1,"cmd":"recents"}open_notifications
下拉通知栏
返回: 无
d.open_notifications()await d.openNotifications();await d.OpenNotificationsAsync();droidline open_notificationscurl -s -X POST localhost:8780/devices/_/open_notifications \
-H 'content-type: application/json'{"id":1,"cmd":"open_notifications"}quick_settings
打开快捷设置
返回: 无
d.quick_settings()await d.quickSettings();await d.QuickSettingsAsync();droidline quick_settingscurl -s -X POST localhost:8780/devices/_/quick_settings \
-H 'content-type: application/json'{"id":1,"cmd":"quick_settings"}clipboard
写入剪贴板;不带文字调用时读取
Android 10 及以上读取需要 Droidline 键盘为当前输入法
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
text | string | 要复制的文字,省略则读取 |
返回: 以下类型的值: string
错误: NO_IME
d.clipboard("你好")await d.clipboard("你好");await d.ClipboardAsync("你好");droidline clipboard "你好"curl -s -X POST localhost:8780/devices/_/clipboard \
-H 'content-type: application/json' \
-d '{"text":"你好"}'{"id":1,"cmd":"clipboard","text":"你好"}batch
在手机上一次执行多条命令,离线时也会继续
步骤为 [命令, 参数...] 列表或 {cmd, ...} 对象。sleep(ms) 只能在 batch 中使用。如果步骤会断开手机的网络,例如关闭再打开 Wi-Fi,请传入 cuts_network:手机先返回 accepted,离线时执行这些步骤,重连后再返回结果
使用 cuts_network 时,同时传入 wait 可直接得到最终结果,而不是 accepted。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
steps | list<step> | 必填 | 按顺序执行的命令 |
stop_on_error | bool | true | 遇到失败步骤即停止 |
cuts_network | bool | false | 这些步骤会断开手机的连接。先返回 accepted,重连后再发送结果 |
返回: 包含以下字段的对象: results
d.batch([("home",), ("sleep", 500), ("recents",)])await d.batch([["home"], ["sleep", 500], ["recents"]]);await d.BatchAsync(new object[] { new object[] { "home" }, ("sleep", 500), new object[] { "recents" } });droidline batch '[["home"],["sleep",500],["recents"]]'curl -s -X POST localhost:8780/devices/_/batch \
-H 'content-type: application/json' \
-d '{"steps":[["home"],["sleep",500],["recents"]]}'{"id":1,"cmd":"batch","steps":[["home"],["sleep",500],["recents"]]}Chrome
chrome.go
在 Chrome 中打开网址
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
url | string | 必填 | 网址,缺少 https:// 时自动补全 |
new_tab | bool | false | 在新标签页打开 |
返回: 包含以下字段的对象: ms
错误: APP_NOT_FOUND
d.chrome.go("droidline.dev")await d.chrome.go("droidline.dev");await d.Chrome.GoAsync("droidline.dev");droidline chrome.go droidline.devcurl -s -X POST localhost:8780/devices/_/chrome.go \
-H 'content-type: application/json' \
-d '{"url":"droidline.dev"}'{"id":1,"cmd":"chrome.go","url":"droidline.dev"}通知
notificationshas_notificationwait_notificationnotification_replynotification_clicknotification_dismissnotify_filteron_notification
notifications
当前显示的通知列表
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
package | string | 仅此应用 |
返回: 以下类型的值: list<notification>
d.notifications()await d.notifications();await d.NotificationsAsync();droidline notificationscurl -s -X POST localhost:8780/devices/_/notifications \
-H 'content-type: application/json'{"id":1,"cmd":"notifications"}has_notification
当前通知中有匹配项时返回 true
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | string text | textContains | title | package | 必填 | text 和 textContains 同时匹配标题和正文 |
value | string | 要匹配的值。by 为查询对象时省略 |
返回: 以下类型的值: bool
d.has_notification("textContains", "发货")await d.hasNotification("textContains", "发货");await d.HasNotificationAsync("textContains", "发货");droidline has_notification textContains "发货"curl -s -X POST localhost:8780/devices/_/has_notification \
-H 'content-type: application/json' \
-d '{"by":"textContains","value":"发货"}'{"id":1,"cmd":"has_notification","by":"textContains","value":"发货"}wait_notification
等待匹配的通知并返回其内容
由 PC 服务器处理,不会阻塞发往手机的其他命令。只能看到用 notify_filter 选择的应用的通知,默认一个也没有。Android 15 及以上系统会对应用隐藏验证码,只能得知通知到达
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
by | string text | textContains | title | package | 必填 | text 和 textContains 同时匹配标题和正文 |
value | string | 要匹配的值。by 为查询对象时省略 | |
timeout | number | 60 s | 等待秒数 |
package | string | 仅来自此应用 |
返回: 以下类型的值: notification
错误: TIMEOUT
dl.wait_notification("textContains", "验证码", 60)await dl.waitNotification("textContains", "验证码", 60);await client.WaitNotificationAsync("textContains", "验证码", 60);droidline wait_notification textContains "验证码" 60curl -s -X POST localhost:8780/server/wait_notification \
-H 'content-type: application/json' \
-d '{"by":"textContains","value":"验证码","timeout":60}'{"id":1,"cmd":"wait_notification","by":"textContains","value":"验证码","timeout":60}notification_reply
直接回复带回复按钮的通知
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
key | string | 必填 | 来自 notifications() 或通知事件的 key |
text | string | 必填 | 回复内容 |
返回: 无
n = d.notifications()[0]
d.notification_reply(n["key"], "我在路上")const [n] = await d.notifications();
await d.notificationReply(n.key, "我在路上");var n = (await d.NotificationsAsync())[0];
await d.NotificationReplyAsync((string)n.Key!, "我在路上");KEY=$(droidline --json notifications | jq -r '.value[0].key')
droidline notification_reply "$KEY" "我在路上"curl -s -X POST localhost:8780/devices/_/notification_reply \
-H 'content-type: application/json' \
-d '{"key":"KEY","text":"我在路上"}'{"id":1,"cmd":"notification_reply","key":"KEY","text":"我在路上"}notification_click
点击通知打开对应界面
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
key | string | 必填 | 来自 notifications() 或通知事件的 key |
返回: 无
n = d.notifications()[0]
d.notification_click(n["key"])const [n] = await d.notifications();
await d.notificationClick(n.key);var n = (await d.NotificationsAsync())[0];
await d.NotificationClickAsync((string)n.Key!);KEY=$(droidline --json notifications | jq -r '.value[0].key')
droidline notification_click "$KEY"curl -s -X POST localhost:8780/devices/_/notification_click \
-H 'content-type: application/json' \
-d '{"key":"KEY"}'{"id":1,"cmd":"notification_click","key":"KEY"}notification_dismiss
清除通知
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
key | string | 必填 | 来自 notifications() 或通知事件的 key |
返回: 无
n = d.notifications()[0]
d.notification_dismiss(n["key"])const [n] = await d.notifications();
await d.notificationDismiss(n.key);var n = (await d.NotificationsAsync())[0];
await d.NotificationDismissAsync((string)n.Key!);KEY=$(droidline --json notifications | jq -r '.value[0].key')
droidline notification_dismiss "$KEY"curl -s -X POST localhost:8780/devices/_/notification_dismiss \
-H 'content-type: application/json' \
-d '{"key":"KEY"}'{"id":1,"cmd":"notification_dismiss","key":"KEY"}notify_filter
选择哪些应用的通知发送到 PC,默认不发送任何应用
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
packages | list<string> | 允许的包,省略则读取当前列表 |
返回: 以下类型的值: list<string>
d.notify_filter(["com.android.chrome", "com.google.android.gm"])await d.notifyFilter(["com.android.chrome", "com.google.android.gm"]);await d.NotifyFilterAsync(new[] { "com.android.chrome", "com.google.android.gm" });droidline notify_filter com.android.chrome,com.google.android.gmcurl -s -X POST localhost:8780/devices/_/notify_filter \
-H 'content-type: application/json' \
-d '{"packages":["com.android.chrome","com.google.android.gm"]}'{"id":1,"cmd":"notify_filter","packages":["com.android.chrome","com.google.android.gm"]}on_notification
每当有匹配的通知时调用函数
仅 SDK,基于 subscribe 实现。CLI 会以 JSON 行输出匹配的通知
在 SDK 内运行,服务器收到的是一行 subscribe。
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
package | string | 仅来自此应用 | |
textContains | string | 仅当标题或正文包含此文字 |
返回: 无
stop = d.on_notification(package="com.google.android.gm", callback=print)
# ... later
stop()const stop = await d.onNotification({ package: "com.google.android.gm" }, (n) => console.log(n.title, n.text));
// ... later
stop();var stop = await d.OnNotificationAsync(n => Console.WriteLine($"{n.Title} {n.Text}"), package: "com.google.android.gm");
// ... later
stop.Dispose();droidline on_notification --package com.google.android.gm{"id":1,"cmd":"subscribe","events":["notification"]}短信、通话和联系人
sms
手机上存储的短信,按时间从新到旧
可选功能。请先在应用的设置页允许短信,在此之前返回 NO_PERMISSION。读取短信和彩信中的文字。聊天消息(RCS)由短信应用自己保存,不包含在内。MCP 服务器只有在 --tools 写了这个名称时才列出此工具
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
box | string inbox | sent | all | "inbox" | 收到的、发出的,或两者 |
address | string | 只要号码或发件人包含此文字的。忽略空格和 - | |
contains | string | 只要正文包含此文字的,不区分大小写 | |
within | number | 0 s | 只要最近这么多秒内的。0 表示不限时间 |
max | int | 20 | 最多返回的条数,最大 500 |
返回: 以下类型的值: list<sms>
calls
通话记录,按时间从新到旧
可选功能。请先在应用的设置页允许通话记录,在此之前返回 NO_PERMISSION。只列出通过电话应用拨打和接听的通话,即时通讯等应用内的通话通常不在其中。MCP 服务器只有在 --tools 写了这个名称时才列出此工具
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
type | string all | incoming | outgoing | missed | rejected | blocked | "all" | 哪类通话 |
number | string | 只要号码或已存名称包含此文字的。忽略空格和 - | |
within | number | 0 s | 只要最近这么多秒内的。0 表示不限时间 |
max | int | 20 | 最多返回的条数,最大 500 |
返回: 以下类型的值: list<call>
contacts
手机上保存的联系人,按名称排序
可选功能。请先在应用的设置页允许联系人,在此之前返回 NO_PERMISSION。MCP 服务器只有在 --tools 写了这个名称时才列出此工具
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
query | string | 只要名称、号码或邮箱包含此文字的联系人,不区分大小写。号码中的空格和 - 会被忽略 | |
max | int | 50 | 最多返回的条数,最大 500 |
返回: 以下类型的值: list<contact>
服务器
devicesleasereleasepairpair_qrrenamerevokesubscribeserver_infoauth
devices
已配对设备及其在线状态和连接方式
返回: 以下类型的值: list<device>
dl.devices()await dl.devices();await client.DevicesAsync();droidline devicescurl -s localhost:8780/devices{"id":1,"cmd":"devices"}lease
借用一台空闲手机,其他脚本无法使用
可选功能。没人租用的手机照常工作。租用期间,只有携带该 lease 的请求有效,其他请求以 DEVICE_LEASED 失败。调用 release,或 ttl 秒内没有命令时结束
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
device | string | 指定手机的 ID 或名称。省略则任选一台空闲手机 | |
wait | number | 30 s | 等待手机空闲的秒数 |
ttl | number | 300 s | 超过这么多秒没有命令时 lease 结束 |
min_sdk | int | 只选 Android API 级别不低于此值的手机,例如 33 | |
model | string | 只选型号包含此文字的手机 |
返回: 包含以下字段的对象: lease, device, name, ttl
错误: NO_FREE_DEVICE, DEVICE_NOT_FOUND
dl.lease(wait=60)await dl.lease({ wait: 60 });await client.LeaseAsync(wait: 60);droidline lease --waitcurl -s -X POST localhost:8780/server/lease \
-H 'content-type: application/json'{"id":1,"cmd":"lease"}release
归还租用的手机
传入 lease;如果持有手机的脚本已崩溃,可传入 device 强制释放
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
lease | string | lease 返回的值 | |
device | string | 无论哪个 lease 持有,都释放这台手机 |
返回: 无
dl.release("l-3f9a1c0d2e4b")await dl.release("l-3f9a1c0d2e4b");await client.ReleaseAsync("l-3f9a1c0d2e4b");droidline release l-3f9a1c0d2e4bcurl -s -X POST localhost:8780/server/release \
-H 'content-type: application/json' \
-d '{"lease":"l-3f9a1c0d2e4b"}'{"id":1,"cmd":"release","lease":"l-3f9a1c0d2e4b"}pair
批准显示此 6 位代码的手机
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
code | string | 必填 | 手机上显示的代码 |
name | string | 设备名称 |
返回: 以下类型的值: device
错误: PAIRING_FAILED
dl.pair("482913", name="shelf-01")await dl.pair("482913", { name: "shelf-01" });await client.PairAsync("482913", name: "shelf-01");droidline pair 482913 --name shelf-01curl -s -X POST localhost:8780/server/pair \
-H 'content-type: application/json' \
-d '{"code":"482913","name":"shelf-01"}'{"id":1,"cmd":"pair","code":"482913","name":"shelf-01"}pair_qr
生成 10 分钟内有效的一次性配对二维码
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
name | string | 设备名称 |
返回: 包含以下字段的对象: uri, expires
dl.pair_qr()await dl.pairQr();await client.PairQrAsync();droidline pair # shows the QR code in the terminalcurl -s -X POST localhost:8780/server/pair_qr \
-H 'content-type: application/json'{"id":1,"cmd":"pair_qr"}rename
重命名设备
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
device | string | 必填 | 设备 ID 或名称 |
name | string | 必填 | 新名称 |
返回: 以下类型的值: device
dl.rename("k7d2q9xa", "shelf-01")await dl.rename("k7d2q9xa", "shelf-01");await client.RenameAsync("k7d2q9xa", "shelf-01");droidline rename k7d2q9xa shelf-01curl -s -X POST localhost:8780/server/rename \
-H 'content-type: application/json' \
-d '{"device":"k7d2q9xa","name":"shelf-01"}'{"id":1,"cmd":"rename","device":"k7d2q9xa","name":"shelf-01"}revoke
取消配对设备,需要重新配对才能连接
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
device | string | 必填 | 设备 ID 或名称 |
返回: 无
dl.revoke("shelf-01")await dl.revoke("shelf-01");await client.RevokeAsync("shelf-01");droidline revoke shelf-01curl -s -X POST localhost:8780/server/revoke \
-H 'content-type: application/json' \
-d '{"device":"shelf-01"}'{"id":1,"cmd":"revoke","device":"shelf-01"}subscribe
在此连接上接收事件
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
events | list<string> | 必填 | 可选 notification、screen、toast、device、result、action |
device | string | 仅此设备,省略则全部 |
返回: 无
dl.subscribe(["notification"])await dl.subscribe(["notification"]);await client.SubscribeAsync(new[] { "notification" });{"id":1,"cmd":"subscribe","events":["notification"]}server_info
服务器版本、端口和监听地址
返回: 包含以下字段的对象: version, server, name, proto, agent_port, client_port
dl.server_info()await dl.serverInfo();await client.ServerInfoAsync();droidline server_infocurl -s -X POST localhost:8780/server/server_info \
-H 'content-type: application/json'{"id":1,"cmd":"server_info"}auth
使用令牌认证此客户端连接
| 名称 | 类型 | 默认值 | 含义 |
|---|---|---|---|
token | string | 必填 | 由 droidline token 生成的客户端令牌 |
返回: 无
dl.auth("your-client-token")await dl.auth("your-client-token");await client.AuthAsync("your-client-token");{"id":1,"cmd":"auth","token":"your-client-token"}