vdisplay 虚拟屏

约 4662 字大约 16 分钟道无涯i

vdisplay 虚拟屏

vdisplay 是 ScriptX 新增的虚拟屏模块。你可以把它先理解成一套“脚本里临时创建一个额外显示器，然后把点击、输入、截图、开应用这些动作都指到这个显示器上”的能力。

它当前已经不是单独孤零零的一个模块了，而是和下面这些地方接到了一起：

app.launchApp(...) / app.launch(...) / app.launchPackage(...)
app.openAppSetting(...) / app.openUrl(...) / app.uninstall(...)
app.startActivity(options)
images.captureScreen(...)
automator.takeScreenshot(...) / auto.takeScreenshot(...)
auto.setWindowFilter(...)
click(...) / longClick(...) / press(...) / swipe(...)
Tap(...) / Swipe(...)
back(...) / home(...)
keys.Home(...) / keys.Back(...) / keys.Text(...) / keys.KeyCode(...)

所以这一页不只是讲“怎么建一个虚拟屏”，也会把你后面怎么把其他 API 指到这个虚拟屏上，一起讲清楚。

先记住这 18 条

这个模块的全局对象名是 vdisplay，兼容别名是 $vdisplay。
vdisplay.create(...) 成功后返回的是一个会话对象，下面文档里统一叫“session”。
一个 session 里最关键的两个标识是：session.id 和 session.displayId。
session.id 形如 vdisplay-1、vdisplay-2；displayId 则是系统层真正的显示器 id。
vdisplay.create(...) 可以传对象，也可以直接按 (width, height, dpi) 这种位置参数写。
width / height 不传或传了无效值时，会回退到当前真实屏幕尺寸。
dpi 不传时，会回退到当前设备显示密度。
title 为空时，默认标题是 ScriptX Virtual Display。
backend 当前只有两种值："local" 和 "shell"。
vdisplay.get(...) / vdisplay.destroy(...) 认 3 类参数：session 对象、session id 字符串、displayId 数字。
showPreview(...) 需要悬浮窗权限；没权限会直接抛异常，不是返回 false。
showPreview(rotated, callback) 的回调拿到的是 (x, y, action, displayId)，不是 MotionEvent 对象本身。
capture(...) 返回 Image | null；captureToFile(...) / captureTo(...) 返回 boolean。
captureToFile(...) 当前实际写的是 PNG。
press(...) 本质上是“同一点的长时长 swipe”，默认按压时长是 350ms。
swipe(...) 默认时长是 260ms。
这组 API 里存在一批历史别名，比如 Create、GetDisplayId、LaunchApp、CaptureToFile，当前源码里它们确实还暴露着，所以这一页会全部列出来。
传给其他模块做虚拟屏目标参数时，最稳的做法永远是直接传 vdisplay.create() 返回的 session 对象。

这一页统一的 4 个词

后面几页里会反复提到虚拟屏相关参数。为了避免一会儿叫 target、一会儿叫 session、一会儿又叫作用域，这里先统一一下叫法：

统一叫法	具体指什么
`session 对象`	`vdisplay.create()` 返回的那个对象，例如 `screen`
`session id 字符串`	形如 `"vdisplay-1"` 的字符串
`虚拟屏目标参数`	一整类“用来指向某块显示器”的参数，通常可以是 `displayId`、session 对象、session id 字符串，或者 target 风格对象
`自动化显示作用域`	通过 `auto.setWindowFilter(screen)`、`auto.setWindowFilter(7)` 等写法绑定出来的当前默认显示器上下文

后面如果我写“它支持虚拟屏目标参数”，默认就按这一表理解，不再每次从头展开一遍。

虚拟屏到底是什么

最容易理解的方式是把它想成：

你平时手机上看的那个主屏幕，是 Display.DEFAULT_DISPLAY
vdisplay.create(...) 会再申请出一个额外显示器
这个显示器可以有自己的分辨率、自己的 displayId
你可以把应用启动到它上面，再往这个显示器里点、滑、发按键、输入文本、截图

它和“普通截图”或者“无障碍窗口过滤”不是一个层级：

截图模块解决的是“怎么拿到图”
无障碍模块解决的是“怎么找节点”
vdisplay 解决的是“动作和画面到底发生在哪块显示器上”

`vdisplay.create(options)` / `vdisplay.Create(options)`

创建一个新的虚拟屏 session。

const screen = vdisplay.create({
  width: 720,
  height: 1280,
  dpi: 320,
  title: "登录流程测试屏"
});

支持的两种写法

1. 对象写法

const screen = vdisplay.create({
  width: 720,
  height: 1280,
  dpi: 320,
  title: "Demo"
});

2. 位置参数写法

const screen = vdisplay.create(720, 1280, 320);
const screen2 = vdisplay.Create(1080, 1920);

参数

字段 / 位置	类型	可填值	默认值	说明
`width` / 第 1 个参数	`number`	`> 0` 的整数	当前真实屏幕宽度	虚拟屏宽度
`height` / 第 2 个参数	`number`	`> 0` 的整数	当前真实屏幕高度	虚拟屏高度
`dpi` / `densityDpi` / 第 3 个参数	`number`	`> 0` 的整数	当前设备 densityDpi	虚拟屏密度
`title`	`string`	任意非空文本	`ScriptX Virtual Display`	预览窗口标题和会话标题

字段	类型	说明
`id`	`string`	session id 字符串，例如 `vdisplay-1`
`displayId`	`number`	系统显示器 id
`width`	`number`	宽度
`height`	`number`	高度
`densityDpi`	`number`	密度
`backend`	`string`	`"local"` 或 `"shell"`
`title`	`string`	当前标题
`previewVisible`	`boolean`	当前有没有预览悬浮窗

可传值	例子	说明
session 对象	`vdisplay.get(screen)`	最稳的写法
session id 字符串	`vdisplay.get("vdisplay-1")`	直接按 id 查
displayId 数字	`vdisplay.get(7)`	直接按显示器 id 查

结果	含义
`true`	找到并成功销毁
`false`	没找到对应 session，或销毁前就已经不存在

值	含义
`"local"`	本地虚拟屏后端
`"shell"`	shell 托管虚拟屏后端

字段	类型	说明
`success`	`boolean`	是否成功
`via`	`string`	常见为 `context` 或 `shell`
`displayId`	`number`	目标虚拟屏 displayId
`sessionId`	`string`	当前 session id 字符串
`packageName`	`string`	你传入的包名
`shellMode`	`string`	某些 shell 路径下会带出来，例如当前 shell 工作模式
`error`	`string`	失败原因
`stdout`	`string`	某些 shell 路径的输出
`contextError`	`string`	先尝试 context 启动失败时的错误信息

参数	类型	默认值	说明
`x`	`number`	无	横坐标
`y`	`number`	无	纵坐标
`durationMs`	`number`	`350`	按压时长，单位毫秒

参数	类型	默认值	说明
`x1`	`number`	无	起点 X
`y1`	`number`	无	起点 Y
`x2`	`number`	无	终点 X
`y2`	`number`	无	终点 Y
`durationMs`	`number`	`260`	滑动时长

参数	类型	默认值	说明
`rotated`	`boolean`	`false`	是否把预览画面旋转 90 度显示
`callback`	`function`	`null`	触摸预览画面时的回调

位置	类型	含义
第 1 个参数	`number`	映射回虚拟屏后的 X
第 2 个参数	`number`	映射回虚拟屏后的 Y
第 3 个参数	`number`	`MotionEvent.actionMasked`
第 4 个参数	`number`	当前虚拟屏 `displayId`

结果	含义
`true`	当前有预览并且已关闭
`false`	当前根本没开预览

值	含义
`0`	`ACTION_DOWN`
`1`	`ACTION_UP`
`2`	`ACTION_MOVE`

写法	例子	是否推荐	说明
直接传 session 对象	`app.openUrl(url, screen)`	最推荐	最不容易写错
直接传 session id 字符串	`images.captureScreen("vdisplay-1")`	推荐	前提是 session 还存在
直接传 `displayId` 数字	`Tap(100, 200, screen.displayId)`	推荐	更底层
对象里写 `target`	`app.startActivity({ target: screen, ... })`	推荐	最常见的 options 写法
对象里写 `screen`	`images.captureScreen({ screen, path })`	推荐	明确表达“这是屏幕目标”
对象里写 `display` / `vdisplay` / `session`	`auto.takeScreenshot({ display: screen })`	可用	当前源码都认
对象里写 `displayId`	`app.startActivity({ displayId: 7, ... })`	可用	直接写数字也行

参数	类型	默认值	说明
`path`	`string`	无	输出文件路径
`timeoutMs`	`number`	`1500`	截图超时