control 命令操控区域当前内容:滚动/缩放/翻页/音量/进度/刷新/透传。区域按当前内容类型裁决命令是否适用,不适用即应答 unsupported。设计原则:投放命令保留类型键,操控命令一律走 control。
信封(拍平,无 commands 层)
保留键说明
area必选。单区域 "a3" 或多区域数组 ["a3","a4"](逐一下发,任一失败应答 error 并指明区域)
delta可选。布尔兼容。1 = 本条消息内所有数值为增量;缺省 = 绝对量
action可选。无参数动作命令,值为字符串枚举(见下表)

其余每个 key 都是一条参数命令;一条消息可携带多个参数命令,action 至多一个;未知 key 应答 invalid param: <key>。

参数命令表
key值类型适用内容绝对量语义(默认)/ 增量语义(delta:1)
scroll[x,y] / "x,y" / nurl、text、document、plugin滚动到位置 / 相对滚动位移
scroll_x / scroll_y数值url、text、document、plugin单轴滚动到 / 单轴相对位移
zoom浮点倍率image、document缩放到倍率 / 当前倍率 × 值
pan[x,y] %image平移到位置 / 相对平移(百分比 = 显示区域尺寸的百分比)
fit字符串image适应方式:contain/cover/fill/none/scale-down(delta 无效)
size浮点倍率text字号缩放到倍率 / 当前倍率 × 值
padding整型百分比text边距设为百分比(如 10 = 10%),实时生效不重投(delta 无效)
page整型document跳转到第 N 页(超界钳到末页)/ ±N 翻页
volume整型 0-100video、audio音量设为值 / 音量 ±值(clamp 0-100)
seek整型秒video、audio进度到第 N 秒 / 进度 ±N 秒
refresh字符串url""/"auto" 普通刷新;"force" 强制刷新(WebView 硬刷,忽略自身 HTTP 缓存);其余值报错(delta 无效)
interval整型秒url自动刷新间隔,0 = 停止(delta 无效)
send任意 JSONurl、pluginAPI 专用透传(见下;delta 无效)

注:document 的 scroll 语义为缩放后平移(pdf.js 自渲染,未放大时滚动无效);page 钳到 [1, 总页数]。

action 命令(无参数动作)
action适用内容语义
play / pause / stopvideo、audio播放 / 暂停 / 暂停并归零(stop 保留于 API;遥控器面板的对应按钮是 toggle 盲控)
togglevideo、audio播放/暂停翻转(盲控入口)
back / forwardurl历史后退/前进
reset全部类型重置回刚投放时的状态(见下表)

reset 按类型回投放态:image=缩放/平移/适应方式;video/audio=进度/音量/播放状态;text=字号与滚动;document=页码/缩放/滚动;url/plugin=回到首次投放的地址(与 refresh 刷新当前页不同)。

send 命令(API 专用)

载荷原样透传到区域页面的 JS 桥(SS.onCommand / superscreen 事件),结构由页面作者解释。适用 url/plugin 页面;模板媒体类型无 JS 桥,应答 unsupported。遥控器面板不提供此功能,仅供开放平台/接口调用。

类型裁决与样例

命令送达区域后按当前内容类型裁决,不适用即应答 {"ret":"error","msg":"unsupported"}。参数兼容规则(数组/布尔/数值的宽松写法)见官网协议文档;非法值报 invalid param: <key>,不静默忽略。

页面 → 平台方向:页面可调用 SS.report(data)(设备封装为 user 事件上报,限频 30 次/分钟),详见《插件》册「插件开发参考」。旧接口 superScreenEvent 兼容保留(封装为 custom 事件)。