screen 命令管理显示区域与窗口。布局只在设备本地持久化,云端不存储——需要布局时用 list 查询。旧键
oper 已更名为 action(见命令册首页说明)。布局操作
| action | 命令样例 | 说明 |
|---|---|---|
| add | {"screen":{"action":"add","area":"a5","position":[0,0,960,540]}} | 添加区域;area 省略时自动命名(a1 起补空缺);position 可含第 5 个 layer 值。应答含分配的名称与 position |
| update | {"screen":{"action":"update","area":"a5","position":[0,0,1280,720,2]}} | 修改区域位置尺寸(含 layer) |
| rename | {"screen":{"action":"rename","area":"a5","name":"a6"}} | 改名(英文+数字,不可重复,不可用 default;默认区域被改名时默认跟随) |
| remove | {"screen":{"action":"remove","area":"a5"}} | 删除该区域;最后一个区域不可删除(报 error) |
| default | {"screen":{"action":"default","area":"a5"}} | 设为默认显示区域 |
| default | {"screen":{"action":"default"}} | 查询当前默认显示区域 → {"default":"a1"} |
| list | {"screen":{"action":"list"}} | 查询全部区域 → {"a5":[t,l,w,h,layer],...}(像素) |
| display | {"screen":{"action":"display"}} | 查询物理屏幕组成(虚拟坐标系,原点=各屏包围盒左上角)→ [[t,l,w,h],...] |
| info | {"screen":{"action":"info","area":"a6"}} | 查询单个区域 → [t,l,w,h,layer](像素);{"screen":{"area":"a6"}} 是其简写(两种格式都支持);不带 area 等同 list |
窗口操作(三态语义)
每个显示区域为 已关闭 / 已打开-可见 / 已打开-隐藏 三态之一。命令只在合法状态迁移时生效,非法迁移应答 {"ret":"error","msg":"invalid state"};旧键 minimize/restore 已废弃(不再兼容)。
| action | 命令样例 | 说明 |
|---|---|---|
| clear | {"screen":{"action":"clear","area":"a5"}} | 任意状态:清空该区域内容(恢复空占位,不删区域);不带 area 清空全部 |
| open | {"screen":{"action":"open","area":"a5"}} | 仅已关闭有效:打开窗体;「启动时恢复显示」配置开启时恢复上次内容 |
| close | {"screen":{"action":"close","area":"a5"}} | 仅已打开(可见或隐藏)有效:销毁窗体但保留内容记录(Android 单窗口:清空窗体保留记录) |
| hide | {"screen":{"action":"hide","area":"a5"}} | 仅已打开-可见有效:隐藏窗体不销毁,内容保持加载(Android:隐藏) |
| show | {"screen":{"action":"show","area":"a5"}} | 仅已打开-隐藏有效:窗体重新可见,不涉及内容恢复 |
未指定 area 时作用于全部区域(逐一对合法目标执行)。
注意事项
- 首次启动自动创建覆盖整个显示器的区域
a1并设为默认;区域至少保留一个 - 桌面端每个区域是一个独立窗口实例;Android 为单窗口(close 全部 = 清空内容,hide = 隐藏)
- 区域没有内容时,中央显示灰色半透明占位信息(区域名、分辨率、位置)
- 校验:名称限英文+数字且不重复;区域不越界(换算后 0~1 范围内)。失败应答
{"ret":"error","msg":...} - 任一侧(设备本地编辑或云端命令)变更布局后,设备都会经 event 上报
change事件(删除时 data 为[])