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" / n | url、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-100 | video、audio | 音量设为值 / 音量 ±值(clamp 0-100) |
| seek | 整型秒 | video、audio | 进度到第 N 秒 / 进度 ±N 秒 |
| refresh | 字符串 | url | ""/"auto" 普通刷新;"force" 强制刷新(WebView 硬刷,忽略自身 HTTP 缓存);其余值报错(delta 无效) |
| interval | 整型秒 | url | 自动刷新间隔,0 = 停止(delta 无效) |
| send | 任意 JSON | url、plugin | API 专用透传(见下;delta 无效) |
注:document 的 scroll 语义为缩放后平移(pdf.js 自渲染,未放大时滚动无效);page 钳到 [1, 总页数]。
action 命令(无参数动作)
| action | 适用内容 | 语义 |
|---|---|---|
| play / pause / stop | video、audio | 播放 / 暂停 / 暂停并归零(stop 保留于 API;遥控器面板的对应按钮是 toggle 盲控) |
| toggle | video、audio | 播放/暂停翻转(盲控入口) |
| back / forward | url | 历史后退/前进 |
| 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 事件)。