构建一个属于屏幕的应用

注入的运行时是否附加。每个文档开始为 inert，当播放器握手和上下文到达时变为 active；尚未显示在屏幕上的页面保持 inert。等待 active 使用 screenrig.waitUntilActive()；加载时不要将 inert 视为“屏幕外”。在 failed，或 window.screenrig 缺失时，渲染自己的内容并跳过下面的表面，因此相同构建也可在 screenRIG 外运行。处于 inert、ready()、log()、emit()、emitConfirmed()、nextPage()、skip() 以及 kv 读写时会抛出或拒绝，代码为 inert；kv.onChange 可随时注册。

类型

"inert" | "active" | "failed"

此文档运行位置。

context 是描述信息，不是请求内容。其中任何内容都不应签名、转发或返回给 screenRIG；下方方法会携带运行时所需内容。

启动参数不属于 context：播放列表可以为应用提供 params（参见iframe 地址和应用参数中的屏幕令牌），播放器会将每一项作为查询参数追加到页面地址中 ticket 之后。请从 location.search 读取，例如 new URLSearchParams(location.search).get("kiosk")。它们是提示而非凭据，任何能打开该页面的人都可以发送任意值，因此应视为不受信任的输入；要了解正在播放的是哪个屏幕，仍应使用 context.screen_id。Qt、Android、Apple 和 Windows 播放器从本地包加载应用，该包没有启动地址，也不向其传递参数。

十个布尔值表示哪些受限方法会对该激活执行操作。键名带点，使用括号表示法读取。

if (window.screenrig.capabilities["kv.write"]) {
  saveButton.hidden = false;
}

使用 onCapabilities 订阅，而不是启动时一次性读取标志。

类型

布尔值对象

首先调用，优先于其他方法，并在等待时渲染 UI。当播放器激活此页面时解析，或运行时已 active 时立即解析，且不声明应用已渲染。timeoutMs（默认 10000，最大 300000）后若未解析则以 activation_timeout 拒绝；等待轮次的页面可继续等待。请在其解析后再开始播放声音，因为播放器会在页面显示之前加载应用：浏览器允许自动播放的屏幕会立即开始播放，拒绝自动播放的屏幕会使 play() 以 NotAllowedError 拒绝，因此请捕获该错误并静音播放。

const sr = window.screenrig;
async function start() {
  render(); // the UI works with or without screenRIG
  if (!sr) return;
  for (;;) {
    try { await sr.waitUntilActive(60000); break; }
    catch (err) { if (err.code !== "activation_timeout") return; }
  }
  await sr.ready();
  // From here: emit, emitConfirmed, log, kv, nextPage.
}
start();

在事件处理程序、计时器或 catch 调用 SDK 之前检查 readyState === "active"，并排队早于它到达的输入。在 inert 运行时的处理程序抛出 log()，这可能导致启动前未发送任何事件。

返回

Promise<void>

在 waitUntilActive() 解析后且依赖 context、kv 或 nextPage 之前调用，一旦应用具备上屏所需条件。调用时若 inert，则抛出异常。

await window.screenrig.waitUntilActive();
await window.screenrig.ready();

返回

Promise<void>

仅在此原语为控制器的应用前进页面调用，当应用完成其轮次。一次调用对应一次激活。

window.screenrig.nextPage();

该方法用于 advance.mode 为 application 的页面，此原语为控制器：

{
  "advance": { "mode": "application", "max_ms": 60000 },
  "primitives": [
    {
      "id": "app",
      "primitive": "application",
      "release_id": "rel_01EXAMPLERELEASE000000000",
      "rect": { "x": 0, "y": 0, "width": 1920, "height": 1080 },
      "layer": 0,
      "content_fit": "fill",
      "controller": true
    }
  ]
}

该页面上恰好有一个原语携带 controller: true，且必须是应用原语。页面上的 max_ms 推进对象边界。

需要

capabilities["page.advance"]

返回

Promise<void>

当应用程序暂时没有内容可显示时，请调用它来代替 ready()。屏幕会立即以页面的常规过渡切换到下一页，此次出现不计为播放。这是启动时的决定：请在激活后十秒内、在 ready() 之前调用。

await window.screenrig.waitUntilActive();
const events = await loadToday();
if (events.length === 0) {
  await window.screenrig.skip("no events today");
} else {
  render(events);
  await window.screenrig.ready();
}

页面的控制器，或该页面上唯一的应用程序，在没有图片或视频的页面上拥有此能力。没有该能力时方法以 capability_denied 拒绝；已调用 ready() 之后以 skip_after_ready 拒绝；播放器不支持时以 not_supported 拒绝。当播放器保留该页面时（操作员正在保持它、显示器已熄灭、没有其他页面可播放，或其他所有页面也都已跳过）以 forbidden 拒绝。此时请渲染您的后备内容并调用 ready()。全部跳过的图块播放列表会完整显示最后一个，而不是循环切换。可选的 reason（最多 64 个字符）会作为 player.application_skipped 出现在项目的播放器日志中。skip() 随 app pack 和 app upload 注入的运行时提供，因此请重新打包版本以获得该方法。

需要

capabilities["page.skip"]

返回

Promise<void>

当智能体应知晓事件发生时使用：页面完成步骤、提交自助终端表单、应用确认运行。这是命名的应用事件，记录在项目事件日志中，智能体通过捆绑 CLI 的 events list 或 events follow 观看。仅代码，无消息体。

log 不是替代品。诊断不是应用事件，读取事件日志的智能体不会看到它。

window.screenrig.emit("menu.rendered");

SDK 的 emit() 和 emitConfirmed() 会添加以屏幕为资源的 application.event 记录。使用 --type application.event 读取，可选择添加 --screen-id。返回的 details.primitive_id 和 details.code 标识发出事件的图元和命名操作。--app-id 选择应用资源、发布版本和 K/V 事件，因此不包含这些屏幕事件。

screenrig events list --type application.event --screen-id scr_SCREEN

返回

void

当应用必须确认事件已到达时使用：自助终端订单已下、表单已发送、访问已结束。发送与 emit 相同的命名应用事件，且仅当播放器确认后端接受事件时，承诺才解决。

事件被拒绝时返回后端问题，10 秒无回复后返回 ack_timeout。超时后勿自动重试：后端可能已接受事件。收据证明事件已入项目事件日志，但不代表已执行。

收据适用于运行应用的每个播放器。

await window.screenrig.emitConfirmed("order.placed");

返回

Promise<void>

用于诊断：debug、info、warn 和 error 是播放器和运行时在应用显示时收集的文本。注入的运行时日志通过此方法自身记录。日志限制：每客户端 32 行，且每条消息最多 2048 字节。记录调试时需要的信息，而非每帧一行。

当你想用 emit 时，不要使用 log。智能体不将日志行视为应用事件，智能体需要处理的内容应放在 emit 代码中。

window.screenrig.log({
  level: "warn",
  code: "menu.stale",
  message: "Falling back to the cached menu."
});

返回

void

当布局可能变化时订阅，而非只读取一次 context。处理程序接收 { viewport, primitive }，与 context 传递的两个对象相同，调用返回结束订阅的函数。

const stopResize = window.screenrig.onResize(function (size) {
  render(size.viewport, size.primitive);
});

stopResize();

返回

取消订阅功能

当授予的功能可能变化时订阅，而非启动时一次决定。在处理程序内读取 screenrig.capabilities 当前布尔值，启用或隐藏相关控件；调用返回结束订阅的函数。

const stopCapabilities = window.screenrig.onCapabilities(function () {
  saveButton.hidden = !window.screenrig.capabilities["kv.write"];
});

返回

取消订阅功能

应用完成运行时拆除监听器。 运行完整周期并允许播放器替换文档的应用无需调用。

返回

void

应用的键值存储，用于存活超过一次激活的实时应用状态。五种自身方法：get、list、set、delete 和 onChange。详见下文 键值存储。

类型

命名空间

读取实时应用状态。 等待 Promise。

const entry = await window.screenrig.kv.get("menu");

需要

capabilities["kv.read"]

返回

promise

在尚未知晓密钥时读取实时应用状态： 列出应用已存储的密钥。等待 Promise。

const keys = await window.screenrig.kv.list();

需要

capabilities["kv.read"]

返回

promise

写入实时应用状态。 value 是字符串或 Uint8Array；options 可选。

await window.screenrig.kv.set("menu", JSON.stringify(menu), {
  contentType: "application/json"
});

await window.screenrig.kv.set("badge.png", pngBytes, {
  contentType: "image/png"
});

需要

capabilities["kv.write"]

返回

promise

写入实时应用状态 通过删除条目。expectedRevision 可选：省略以删除当前条目，或提供以拒绝并发更改。

await window.screenrig.kv.delete("menu");

需要

capabilities["kv.write"]

返回

promise

在实时应用状态变化时更新，而非轮询。处理程序在此应用的任何键变化时运行，无论是谁写的：带有 kv set 的智能体、通过 键值 webhook 的外部系统，或任何屏幕上的此应用。它接收哪个键改变，而非值，因此用 kv.get 读取新值。调用返回结束订阅的函数。

const sr = window.screenrig;

async function showMenu() {
  render(await sr.kv.get("menu"));
}

const stopChanges = sr.kv.onChange(function (change) {
  if (change.key === "menu" && !change.deleted) showMenu();
});

await sr.waitUntilActive();
await sr.ready();
await showMenu();

在首次读取前订阅，以免错过读取时发生的更改；激活前注册的处理程序在页面激活后开始运行。调用 stopChanges() 结束订阅。

更改在几秒内传达到所有播放该应用的屏幕。对同一键的多次快速写入可能合并为携带最新修订的单次更改，因此将更改视为“重新读取此键”，而非写入计数。更改是信号，不是历史：应用启动时读取所需内容，然后跟踪更改。

需要

capabilities["kv.read"]；没有它处理程序永远不会运行

返回

取消订阅功能

调暗、熄灭或唤醒显示器。brightness 取值 0 到 1（0 是背光能达到的最低亮度，并非关闭）；on: false 会让屏幕变暗，on: true 会让它重新亮起。省略某个成员则保持其原状。屏幕变暗时，触摸仍会传到应用程序，因此一次触摸即可将其唤醒。让屏幕保持熄灭的显示计划优先于应用程序，页面离开屏幕时播放器会恢复显示。

await window.screenrig.device.display.set({ brightness: 0.3 });
await window.screenrig.device.display.set({ on: false });

解析为

{ on, brightness }，即调用之后的显示器状态（播放器无法读取时 brightness 为 null）；set({}) 仅读取，屏幕变暗期间 brightness 保持其值

需要

capabilities["device.display"]

当前显示器状态，格式为 { on, brightness }。

需要

capabilities["device.display"]

每当显示器发生变化时，以 { on, brightness } 调用，无论是此应用程序、显示计划还是操作员所做的更改。

返回

取消订阅功能

需要

capabilities["device.display"]

当设备检测到有人在屏幕前移动时调用，每秒最多一次。播放器读取设备上的摄像头，不保留任何图像：不存储、不记录、也不发送任何图像。只有在注册了处理程序时，摄像头才会运行。

window.screenrig.device.onPresence(function () {
  window.screenrig.device.display.set({ on: true, brightness: 1 });
});

返回

取消订阅功能

需要

capabilities["device.presence"]

每次按下硬件音量键（包括重复按键）时，以 "volume_up" 或 "volume_down" 调用。注册处理程序期间，按键归应用程序所有，设备音量保持不变。

返回

取消订阅功能

需要

capabilities["device.keys"]

以环境光照度（单位 lux）调用：先是处理程序注册后的第一个读数，之后每当光线变化至少 10% 或跨越 1 lux 时再调用，每秒最多一次。设备需要具备光线传感器。

window.screenrig.device.onLight(function (lux) {
  document.body.classList.toggle("dim-room", lux < 10);
});

返回

取消订阅功能

需要

capabilities["device.light"]

每当设备获得或失去系统已验证的互联网连接时，以 true 或 false 调用；注册第一个处理程序时，会立即以当前状态调用。

window.screenrig.device.onNetwork(function (online) {
  offlineBadge.hidden = online;
});

返回

取消订阅功能

需要

capabilities["device.network"]

播放一次触觉轻震。 ms 是 1 到 200 之间的整数毫秒数，默认为 12。播放器开始振动后，Promise 以无值兑现；对于任何其他 ms，则以 invalid_request 拒绝，且不发送任何内容。

await window.screenrig.device.vibrate();
await window.screenrig.device.vibrate(40);

解析为

无值

需要

capabilities["device.haptics"]