命令参考

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文字元素所属的包
clickabletrue 或 false节点的 clickable 值等于此值
long_clickabletrue 或 false节点的 long_clickable 值等于此值
checkabletrue 或 false节点的 checkable 值等于此值
checkedtrue 或 false节点的 checked 值等于此值
enabledtrue 或 false节点的 enabled 值等于此值
focusedtrue 或 false节点的 focused 值等于此值
selectedtrue 或 false节点的 selected 值等于此值
scrollabletrue 或 false节点的 scrollable 值等于此值
editabletrue 或 false节点的 editable 值等于此值
passwordtrue 或 false节点的 password 值等于此值
visibletrue 或 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

返回当前界面的节点树

名称类型默认值含义
pathstring保存为本地 JSON 文件
all_windowsboolfalse包含状态栏、键盘等系统窗口

返回: 包含以下字段的对象: package, activity, width, height, tree

需要: 无障碍服务

d.dump("screen.json")   # saved on your PC

screenshot

截取屏幕

Android 11 及以上使用无障碍截图,9-10 首次需要允许屏幕录制

名称类型默认值含义
pathstring保存到本地文件,扩展名决定 png 或 jpeg
formatstring png | jpeg"jpeg"图片格式
qualityint80JPEG 质量 1-100
scalenumber1缩放比例 0.1-1.0,移动网络下有用

返回: 包含以下字段的对象: format, width, height, data

需要: 无障碍服务

d.screenshot("shot.png")   # saved on your PC

record

开启或关闭点击和输入的录制

可选功能,开启前处于关闭状态。开启期间,手机会为其他应用中的每次点击、长按和文字变化发送 action 事件,并附带当时的界面;密码框不发送文字。到 minutes 后自动关闭。droidline inspect 用它在你使用手机时生成脚本

名称类型默认值含义
onbool必填true 开始,false 停止
minutesnumber30经过这么久后自动关闭

返回: 无

需要: 无障碍服务

d.record(True)

find_image

在屏幕上查找图片

可选功能,在电脑上运行:服务器获取截图后进行比较。请从同一台手机的截图中裁剪;屏幕密度不同的手机请传入 scales。Android 9 和 10 截图需要屏幕录制权限

在电脑上运行:服务器从手机获取截图,并通过手机点击。

名称类型默认值含义
imageimage必填要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64
thresholdnumber0.9匹配需要多接近,0 到 1
timeoutnumber10 s等待目标出现的秒数
regionlist<int>只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配
scaleslist<number>要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间
colorboolfalse还要求平均颜色一致,用来区分形状相同的红色和绿色按钮

返回: 包含以下字段的对象: x, y, bounds, score

错误: NOT_FOUND, NO_PERMISSION

d.find_image("ok-button.png")

tap_image

在屏幕上查找图片并点击其中心

可选功能,在电脑上运行:服务器获取截图后进行比较。请从同一台手机的截图中裁剪;屏幕密度不同的手机请传入 scales。Android 9 和 10 截图需要屏幕录制权限

在电脑上运行:服务器从手机获取截图,并通过手机点击。

名称类型默认值含义
imageimage必填要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64
thresholdnumber0.9匹配需要多接近,0 到 1
timeoutnumber10 s等待目标出现的秒数
regionlist<int>只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配
scaleslist<number>要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间
colorboolfalse还要求平均颜色一致,用来区分形状相同的红色和绿色按钮

返回: 包含以下字段的对象: x, y, score, ms

错误: NOT_FOUND, NO_PERMISSION

d.tap_image("ok-button.png", threshold=0.85)

image_exists

图片当前是否在屏幕上,不等待

可选功能,在电脑上运行:服务器获取截图后进行比较。请从同一台手机的截图中裁剪;屏幕密度不同的手机请传入 scales。Android 9 和 10 截图需要屏幕录制权限

在电脑上运行:服务器从手机获取截图,并通过手机点击。

名称类型默认值含义
imageimage必填要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64
thresholdnumber0.9匹配需要多接近,0 到 1
regionlist<int>只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配
scaleslist<number>要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间
colorboolfalse还要求平均颜色一致,用来区分形状相同的红色和绿色按钮

返回: 以下类型的值: bool

错误: NO_PERMISSION

find_images

图片在屏幕上出现的所有位置

未设置 timeout 时立即返回,没有匹配时返回空列表。按匹配程度由高到低返回,且互不重叠。在电脑上运行;屏幕密度不同的手机请传入 scales

在电脑上运行:服务器从手机获取截图,并通过手机点击。

名称类型默认值含义
imageimage必填要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64
thresholdnumber0.9匹配需要多接近,0 到 1
timeoutnumber0 s等待至少一个匹配的秒数。0 表示立即返回
regionlist<int>只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配
scaleslist<number>要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间
colorboolfalse还要求平均颜色一致,用来区分形状相同的红色和绿色按钮
maxint20最多返回的数量

返回: 以下类型的值: list<image_match>

错误: NO_PERMISSION

wait_image_gone

等待图片从屏幕上消失

可选功能,在电脑上运行:服务器获取截图后进行比较。请从同一台手机的截图中裁剪;屏幕密度不同的手机请传入 scales。Android 9 和 10 截图需要屏幕录制权限

在电脑上运行:服务器从手机获取截图,并通过手机点击。

名称类型默认值含义
imageimage必填要查找内容的 PNG 或 JPEG,从同一台手机的截图中裁剪。SDK 和 CLI 接受文件路径,传输时为 base64
thresholdnumber0.9匹配需要多接近,0 到 1
timeoutnumber10 s等待目标出现的秒数
regionlist<int>只在这个区域内查找,按屏幕像素依次为左、上、右、下。更快,区域外的内容不会被匹配
scaleslist<number>要尝试的图片尺寸,1 为裁剪时的原尺寸。屏幕密度不同的手机可用 0.8、1、1.25 等。每多一个尺寸就多花一些时间
colorboolfalse还要求平均颜色一致,用来区分形状相同的红色和绿色按钮

返回: 包含以下字段的对象: ms

错误: TIMEOUT, NO_PERMISSION

ocr

用 OCR 读取屏幕上的文字

可选功能,在电脑上用 Tesseract 运行。Tesseract 和所需的语言数据需要自行安装,不会自动安装。Android 9 和 10 截图需要屏幕录制权限

在电脑上运行:服务器从手机获取截图,并通过手机点击。

名称类型默认值含义
langstring"eng"Tesseract 语言,例如 chi_sim+eng。每种语言都需要安装对应的语言数据

返回: 包含以下字段的对象: text, lines

错误: OCR_UNAVAILABLE, NO_PERMISSION

d.ocr("chi_sim+eng")

ocr_find

等待 OCR 在屏幕上读到文字并返回其位置

可选功能,在电脑上用 Tesseract 运行。Tesseract 和所需的语言数据需要自行安装,不会自动安装。Android 9 和 10 截图需要屏幕录制权限

在电脑上运行:服务器从手机获取截图,并通过手机点击。

名称类型默认值含义
textstring必填要查找的文字:完整的单词,或一行中的一部分
langstring"eng"Tesseract 语言,例如 chi_sim+eng。每种语言都需要安装对应的语言数据
timeoutnumber10 s等待目标出现的秒数

返回: 包含以下字段的对象: text, x, y, bounds

错误: NOT_FOUND, OCR_UNAVAILABLE, NO_PERMISSION

d.ocr_find("下一步", "chi_sim+eng")

ocr_tap

等待 OCR 在屏幕上读到文字并点击

可选功能,在电脑上用 Tesseract 运行。Tesseract 和所需的语言数据需要自行安装,不会自动安装。Android 9 和 10 截图需要屏幕录制权限

在电脑上运行:服务器从手机获取截图,并通过手机点击。

名称类型默认值含义
textstring必填要查找的文字:完整的单词,或一行中的一部分
langstring"eng"Tesseract 语言,例如 chi_sim+eng。每种语言都需要安装对应的语言数据
timeoutnumber10 s等待目标出现的秒数

返回: 包含以下字段的对象: text, x, y, ms

错误: NOT_FOUND, OCR_UNAVAILABLE, NO_PERMISSION

d.ocr_tap("开始", "chi_sim+eng")

current

前台包名和 Activity

返回: 包含以下字段的对象: package, activity

需要: 无障碍服务

d.current()

坐标

taplong_tapswipe

tap

点击坐标

名称类型默认值含义
xint必填屏幕像素 X
yint必填屏幕像素 Y

返回: 包含以下字段的对象: ms

需要: 无障碍服务

d.tap(540, 1200)

long_tap

长按坐标

名称类型默认值含义
xint必填屏幕像素 X
yint必填屏幕像素 Y
msint800按住时长(毫秒)

返回: 包含以下字段的对象: ms

需要: 无障碍服务

d.long_tap(540, 1200, 800)

swipe

在两点之间或按方向滑动

名称类型默认值含义
x1int|string必填起点 X,或方向:up、down、left、right
y1int起点 Y
x2int终点 X
y2int终点 Y
msint300时长(毫秒)

返回: 包含以下字段的对象: ms

需要: 无障碍服务

d.swipe(540, 1600, 540, 400, 300)

元素

touchlong_touchscroll_to

touch

等待元素出现并点击

节点拒绝点击时改为点击 bounds 中心。via 表示成功方式:node、parent 或 gesture

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
nthint0多个元素匹配时的序号,从 0 开始
timeoutnumber10 s等待目标出现的秒数

返回: 包含以下字段的对象: via, ms

简写: touchById(value), touchByText(value), touchByDesc(value)

错误: NOT_FOUND, NOT_CLICKABLE, NO_ACCESSIBILITY

需要: 无障碍服务

d.touch("text", "登录")

long_touch

等待元素出现并长按

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
msint800按住时长(毫秒)
nthint0多个元素匹配时的序号,从 0 开始
timeoutnumber10 s等待目标出现的秒数

返回: 包含以下字段的对象: via, ms

需要: 无障碍服务

d.long_touch("text", "消息")

scroll_to

滚动直到元素可见

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
directionstring down | up | left | right"down"滚动方向
max_swipesint20滑动这么多次后放弃
nthint0多个元素匹配时的序号,从 0 开始

返回: 包含以下字段的对象: swipes

需要: 无障碍服务

d.scroll_to("text", "设置")

输入

inputclearsendkey

input

等待输入框并填入文字

使用无障碍设置文本操作;忽略该操作的输入框在选择了 Droidline 键盘时改用键盘输入

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
textstring必填要输入的文字
appendboolfalse保留原有文字并追加
nthint0多个元素匹配时的序号,从 0 开始
timeoutnumber10 s等待目标出现的秒数

返回: 包含以下字段的对象: via, ms

需要: 无障碍服务

d.input("id", "email", "me@example.com")

clear

清空输入框

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
nthint0多个元素匹配时的序号,从 0 开始
timeoutnumber10 s等待目标出现的秒数

返回: 包含以下字段的对象: ms

需要: 无障碍服务

d.clear("id", "email")

sendkey

发送按键名、键码或文字

back、home、recents、notifications、quick_settings、lock 使用无障碍全局操作;其他按键和文字通过 Droidline 键盘发送到焦点输入框

名称类型默认值含义
keystring|int按键名(enter、tab、del、space、escape、up、down、left、right、back、home 等)、Android 键码或要输入的文字
textstring按字面输入,即使与按键名相同

返回: 包含以下字段的对象: via

错误: NO_IME, BAD_ARGS

需要: 无障碍服务

d.sendkey("enter")

检查

existswaitwait_gonewait_idlefindfind_allget_text

exists

元素当前是否在屏幕上,不等待

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
nthint0多个元素匹配时的序号,从 0 开始

返回: 以下类型的值: bool

需要: 无障碍服务

d.exists("text", "关闭广告")

wait

等待元素出现

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
timeoutnumber10 s等待目标出现的秒数
nthint0多个元素匹配时的序号,从 0 开始

返回: 包含以下字段的对象: ms

错误: NOT_FOUND

需要: 无障碍服务

d.wait("text", "完成", timeout=30)

wait_gone

等待元素消失

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
timeoutnumber10 s等待目标出现的秒数

返回: 包含以下字段的对象: ms

错误: TIMEOUT

需要: 无障碍服务

d.wait_gone("text", "加载中")

wait_idle

等待界面不再变化

等待前台应用在 ms 毫秒内没有新的绘制。在会加载内容的操作之后使用,代替固定的 sleep。一直有动画的界面会以 TIMEOUT 结束

名称类型默认值含义
msint500 ms界面需要保持不变的时长
timeoutnumber10 s放弃前等待的秒数

返回: 包含以下字段的对象: ms

错误: TIMEOUT

需要: 无障碍服务

d.wait_idle()

find

等待元素出现并返回该元素

SDK 返回带有 click、input、find 和节点字段的元素对象。节点不含 children

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
nthint0多个元素匹配时的序号,从 0 开始
timeoutnumber10 s等待目标出现的秒数

返回: 以下类型的值: node

错误: NOT_FOUND

需要: 无障碍服务

d.find("text", "登录")

find_all

当前所有匹配的元素

未设置 timeout 时立即返回,没有匹配时返回空列表。方向查询按距离由近到远返回

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
timeoutnumber0 s等待至少一个匹配的秒数。0 表示立即返回

返回: 以下类型的值: list<node>

需要: 无障碍服务

d.find_all("id", "title")

get_text

元素的文字,不存在时为空字符串

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
nthint0多个元素匹配时的序号,从 0 开始

返回: 以下类型的值: string

需要: 无障碍服务

d.get_text("id", "balance")

条件

checkedenabledselectedcountwhichin_appkeyboard_shownlast_toastcolor

checked

开关或复选框为开启时返回 true

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
nthint0多个元素匹配时的序号,从 0 开始

返回: 以下类型的值: bool

需要: 无障碍服务

d.checked("id", "auto_login")

enabled

元素可点击时返回 true

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
nthint0多个元素匹配时的序号,从 0 开始

返回: 以下类型的值: bool

需要: 无障碍服务

d.enabled("text", "下一步")

selected

标签或项目被选中时返回 true

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略
nthint0多个元素匹配时的序号,从 0 开始

返回: 以下类型的值: bool

需要: 无障碍服务

d.selected("text", "首页")

count

匹配元素的数量

名称类型默认值含义
byselector必填按哪个 dump 字段查找(text、textContains、textMatches、id、desc、descContains、descMatches、class),或包含多个条件的查询对象
valuestring要匹配的值。by 为查询对象时省略

返回: 以下类型的值: int

需要: 无障碍服务

d.count("class", "android.widget.CheckBox")

which

最先出现的候选项序号,没有则为 -1

名称类型默认值含义
candidateslist<selector_pair>必填[条件, 值] 对或查询对象的列表
timeoutnumber10 s等待任一候选出现的秒数

返回: 以下类型的值: int

需要: 无障碍服务

d.which([("text", "登录"), ("id", "main_tab")], timeout=15)

in_app

该应用在前台时返回 true

名称类型默认值含义
packagestring必填包名,例如 com.android.chrome

返回: 以下类型的值: bool

需要: 无障碍服务

d.in_app("com.android.chrome")

keyboard_shown

软键盘显示时返回 true

返回: 以下类型的值: bool

需要: 无障碍服务

d.keyboard_shown()

last_toast

最近一条 Toast 的文字,没有则为空字符串

名称类型默认值含义
max_agenumber30 s忽略早于此秒数的 Toast

返回: 以下类型的值: string

需要: 无障碍服务

d.last_toast()

color

坐标处的像素颜色(#RRGGBB)

用于没有无障碍节点的界面(如游戏)

名称类型默认值含义
xint必填屏幕像素 X
yint必填屏幕像素 Y

返回: 以下类型的值: string

需要: 无障碍服务

d.color(540, 1200)

设备

screen_onlockedwakelockbatteryorientationinfo

screen_on

屏幕亮着时返回 true

返回: 以下类型的值: bool

d.screen_on()

locked

处于锁屏时返回 true

返回: 以下类型的值: bool

d.locked()

wake

点亮屏幕并解除无密码的锁屏

屏幕关闭时手势会失败。PIN、图案或密码锁需要用户解锁

返回: 包含以下字段的对象: screen_on, locked

d.wake()

lock

关闭屏幕并锁定

返回: 无

需要: 无障碍服务

d.lock()

battery

电量和充电状态

返回: 包含以下字段的对象: level, charging, temperature

d.battery()

orientation

屏幕方向:portrait 或 landscape

返回: 以下类型的值: string

d.orientation()

info

型号、Android 版本、屏幕尺寸和权限状态

返回: 包含以下字段的对象: model, manufacturer, sdk, release, agent, width, height, ready

d.info()

网络

networkproxyproxy_check

network

连接类型(wifi、mobile、none)和飞行模式

返回: 包含以下字段的对象: type, airplane, metered

d.network()

proxy

通过按应用 VPN 让指定应用走上游代理

支持 http://(CONNECT)和 socks5://,可带 user:pass。传 null 或 "off" 关闭。同一时间仅一个上游。忽略代理设置的应用会断网而不是泄漏

名称类型默认值含义
urlstring|null必填socks5://user:pass@host:port、http://host:port、@kr1 这样的已保存配置,或 off
appstring|list<string>要走代理的包(可多个)

返回: 包含以下字段的对象: active, apps

错误: NO_PERMISSION, PROXY_FAILED, UNSUPPORTED

需要: VPN 权限 · Android API 29+

d.proxy("@kr1", app="com.android.chrome")

proxy_check

按应用代理状态和外部看到的 IP

名称类型默认值含义
appstring要检查的包

返回: 包含以下字段的对象: active, ip, upstream, error

d.proxy_check("com.android.chrome")

应用

launchopen_urlintentclear_dataappsinstalled

launch

启动应用,可指定 Activity

名称类型默认值含义
packagestring必填包名,例如 com.android.chrome
activitystringActivity 名称,完整名称或以点开头

返回: 包含以下字段的对象: ms

错误: APP_NOT_FOUND, ACTIVITY_BLOCKED

d.launch("com.android.settings")

open_url

打开 URL 或深层链接

名称类型默认值含义
urlstring必填http(s) 地址或应用深层链接
packagestring仅用此应用打开

返回: 无

d.open_url("https://droidline.dev")

intent

按 intent action 打开界面,例如某个设置页面

可以打开任何允许其他应用打开的界面,例如 android.settings.WIFI_SETTINGS,或把 data 设为 package:com.example 的 android.settings.APPLICATION_DETAILS_SETTINGS。界面会重新打开,并关闭同一应用的其他界面。之后要点什么因厂商和语言而异,所以 Wi-Fi、飞行模式、强行停止和清除数据以文档中的示例提供,而不是命令

名称类型默认值含义
actionstring必填Intent action,例如 android.settings.WIFI_SETTINGS
datastring数据 URI,例如 package:com.example
packagestring只让这个应用处理

返回: 无

错误: APP_NOT_FOUND, BAD_ARGS

d.intent("android.settings.WIFI_SETTINGS")

clear_data

在设备所有者模式下清除应用数据

可选,仅在设备所有者模式下可用,手机不打开设置直接清除。不在该模式时返回 NO_PERMISSION;经由设置界面的做法见文档中的示例

名称类型默认值含义
packagestring必填包名,例如 com.android.chrome

返回: 包含以下字段的对象: ms

错误: APP_NOT_FOUND, NO_PERMISSION

d.clear_data("com.android.chrome")

apps

已安装的包列表

名称类型默认值含义
systemboolfalse包含系统包

返回: 以下类型的值: list<app>

d.apps()

installed

已安装时返回版本名,否则为空字符串

名称类型默认值含义
packagestring必填包名,例如 com.android.chrome

返回: 以下类型的值: string

d.installed("com.android.chrome")

系统

backhomerecentsopen_notificationsquick_settingsclipboardbatch

back

返回

返回: 无

需要: 无障碍服务

d.back()

home

主屏幕

返回: 无

需要: 无障碍服务

d.home()

recents

最近任务

返回: 无

需要: 无障碍服务

d.recents()

open_notifications

下拉通知栏

返回: 无

需要: 无障碍服务

d.open_notifications()

quick_settings

打开快捷设置

返回: 无

需要: 无障碍服务

d.quick_settings()

clipboard

写入剪贴板;不带文字调用时读取

Android 10 及以上读取需要 Droidline 键盘为当前输入法

名称类型默认值含义
textstring要复制的文字,省略则读取

返回: 以下类型的值: string

错误: NO_IME

d.clipboard("你好")

batch

在手机上一次执行多条命令,离线时也会继续

步骤为 [命令, 参数...] 列表或 {cmd, ...} 对象。sleep(ms) 只能在 batch 中使用。如果步骤会断开手机的网络,例如关闭再打开 Wi-Fi,请传入 cuts_network:手机先返回 accepted,离线时执行这些步骤,重连后再返回结果

使用 cuts_network 时,同时传入 wait 可直接得到最终结果,而不是 accepted。

名称类型默认值含义
stepslist<step>必填按顺序执行的命令
stop_on_errorbooltrue遇到失败步骤即停止
cuts_networkboolfalse这些步骤会断开手机的连接。先返回 accepted,重连后再发送结果

返回: 包含以下字段的对象: results

d.batch([("home",), ("sleep", 500), ("recents",)])

Chrome

chrome.go

chrome.go

在 Chrome 中打开网址

名称类型默认值含义
urlstring必填网址,缺少 https:// 时自动补全
new_tabboolfalse在新标签页打开

返回: 包含以下字段的对象: ms

错误: APP_NOT_FOUND

d.chrome.go("droidline.dev")

通知

notificationshas_notificationwait_notificationnotification_replynotification_clicknotification_dismissnotify_filteron_notification

notifications

当前显示的通知列表

名称类型默认值含义
packagestring仅此应用

返回: 以下类型的值: list<notification>

需要: 通知使用权

d.notifications()

has_notification

当前通知中有匹配项时返回 true

名称类型默认值含义
bystring text | textContains | title | package必填text 和 textContains 同时匹配标题和正文
valuestring要匹配的值。by 为查询对象时省略

返回: 以下类型的值: bool

需要: 通知使用权

d.has_notification("textContains", "发货")

wait_notification

等待匹配的通知并返回其内容

由 PC 服务器处理,不会阻塞发往手机的其他命令。只能看到用 notify_filter 选择的应用的通知,默认一个也没有。Android 15 及以上系统会对应用隐藏验证码,只能得知通知到达

名称类型默认值含义
bystring text | textContains | title | package必填text 和 textContains 同时匹配标题和正文
valuestring要匹配的值。by 为查询对象时省略
timeoutnumber60 s等待秒数
packagestring仅来自此应用

返回: 以下类型的值: notification

错误: TIMEOUT

需要: 通知使用权

dl.wait_notification("textContains", "验证码", 60)

notification_reply

直接回复带回复按钮的通知

名称类型默认值含义
keystring必填来自 notifications() 或通知事件的 key
textstring必填回复内容

返回: 无

需要: 通知使用权

n = d.notifications()[0]
d.notification_reply(n["key"], "我在路上")

notification_click

点击通知打开对应界面

名称类型默认值含义
keystring必填来自 notifications() 或通知事件的 key

返回: 无

需要: 通知使用权

n = d.notifications()[0]
d.notification_click(n["key"])

notification_dismiss

清除通知

名称类型默认值含义
keystring必填来自 notifications() 或通知事件的 key

返回: 无

需要: 通知使用权

n = d.notifications()[0]
d.notification_dismiss(n["key"])

notify_filter

选择哪些应用的通知发送到 PC,默认不发送任何应用

名称类型默认值含义
packageslist<string>允许的包,省略则读取当前列表

返回: 以下类型的值: list<string>

需要: 通知使用权

d.notify_filter(["com.android.chrome", "com.google.android.gm"])

on_notification

每当有匹配的通知时调用函数

仅 SDK,基于 subscribe 实现。CLI 会以 JSON 行输出匹配的通知

在 SDK 内运行,服务器收到的是一行 subscribe。

名称类型默认值含义
packagestring仅来自此应用
textContainsstring仅当标题或正文包含此文字

返回: 无

需要: 通知使用权

stop = d.on_notification(package="com.google.android.gm", callback=print)
# ... later
stop()

短信、通话和联系人

smscallscontacts

sms

手机上存储的短信,按时间从新到旧

可选功能。请先在应用的设置页允许短信,在此之前返回 NO_PERMISSION。读取短信和彩信中的文字。聊天消息(RCS)由短信应用自己保存,不包含在内。MCP 服务器只有在 --tools 写了这个名称时才列出此工具

名称类型默认值含义
boxstring inbox | sent | all"inbox"收到的、发出的,或两者
addressstring只要号码或发件人包含此文字的。忽略空格和 -
containsstring只要正文包含此文字的,不区分大小写
withinnumber0 s只要最近这么多秒内的。0 表示不限时间
maxint20最多返回的条数,最大 500

返回: 以下类型的值: list<sms>

需要: 短信

calls

通话记录,按时间从新到旧

可选功能。请先在应用的设置页允许通话记录,在此之前返回 NO_PERMISSION。只列出通过电话应用拨打和接听的通话,即时通讯等应用内的通话通常不在其中。MCP 服务器只有在 --tools 写了这个名称时才列出此工具

名称类型默认值含义
typestring all | incoming | outgoing | missed | rejected | blocked"all"哪类通话
numberstring只要号码或已存名称包含此文字的。忽略空格和 -
withinnumber0 s只要最近这么多秒内的。0 表示不限时间
maxint20最多返回的条数,最大 500

返回: 以下类型的值: list<call>

需要: 通话记录

contacts

手机上保存的联系人,按名称排序

可选功能。请先在应用的设置页允许联系人,在此之前返回 NO_PERMISSION。MCP 服务器只有在 --tools 写了这个名称时才列出此工具

名称类型默认值含义
querystring只要名称、号码或邮箱包含此文字的联系人,不区分大小写。号码中的空格和 - 会被忽略
maxint50最多返回的条数,最大 500

返回: 以下类型的值: list<contact>

需要: 联系人

服务器

devicesleasereleasepairpair_qrrenamerevokesubscribeserver_infoauth

devices

已配对设备及其在线状态和连接方式

返回: 以下类型的值: list<device>

dl.devices()

lease

借用一台空闲手机,其他脚本无法使用

可选功能。没人租用的手机照常工作。租用期间,只有携带该 lease 的请求有效,其他请求以 DEVICE_LEASED 失败。调用 release,或 ttl 秒内没有命令时结束

名称类型默认值含义
devicestring指定手机的 ID 或名称。省略则任选一台空闲手机
waitnumber30 s等待手机空闲的秒数
ttlnumber300 s超过这么多秒没有命令时 lease 结束
min_sdkint只选 Android API 级别不低于此值的手机,例如 33
modelstring只选型号包含此文字的手机

返回: 包含以下字段的对象: lease, device, name, ttl

错误: NO_FREE_DEVICE, DEVICE_NOT_FOUND

dl.lease(wait=60)

release

归还租用的手机

传入 lease;如果持有手机的脚本已崩溃,可传入 device 强制释放

名称类型默认值含义
leasestringlease 返回的值
devicestring无论哪个 lease 持有,都释放这台手机

返回: 无

dl.release("l-3f9a1c0d2e4b")

pair

批准显示此 6 位代码的手机

名称类型默认值含义
codestring必填手机上显示的代码
namestring设备名称

返回: 以下类型的值: device

错误: PAIRING_FAILED

dl.pair("482913", name="shelf-01")

pair_qr

生成 10 分钟内有效的一次性配对二维码

名称类型默认值含义
namestring设备名称

返回: 包含以下字段的对象: uri, expires

dl.pair_qr()

rename

重命名设备

名称类型默认值含义
devicestring必填设备 ID 或名称
namestring必填新名称

返回: 以下类型的值: device

dl.rename("k7d2q9xa", "shelf-01")

revoke

取消配对设备,需要重新配对才能连接

名称类型默认值含义
devicestring必填设备 ID 或名称

返回: 无

dl.revoke("shelf-01")

subscribe

在此连接上接收事件

名称类型默认值含义
eventslist<string>必填可选 notification、screen、toast、device、result、action
devicestring仅此设备,省略则全部

返回: 无

dl.subscribe(["notification"])

server_info

服务器版本、端口和监听地址

返回: 包含以下字段的对象: version, server, name, proto, agent_port, client_port

dl.server_info()

auth

使用令牌认证此客户端连接

名称类型默认值含义
tokenstring必填由 droidline token 生成的客户端令牌

返回: 无

dl.auth("your-client-token")