Presentation API：显示屏与会话边界

当受控浏览器暴露相关方法并由明确的用户操作发起请求时，BotBrowser 可以验证经过授权的 Presentation API 流程。它不能制造接收端或物理显示屏、替用户选择接收者，也不能证明消息已经送达。可靠的边界是可见状态：页面发起请求，浏览器负责中介，展示可能连接；任何边界拒绝时，页面内的同一任务仍然可用。

TL;DR

Presentation API 把控制浏览上下文连接到展示屏幕，但不会把屏幕变成页面可以寻址的设备。先检测 PresentationRequest，把 PresentationAvailability 当作运行时信号，再从明确的点击或按键中调用 start()。connected、closed、terminated、被拒绝的 Promise 以及没有可用屏幕都是正常状态。始终保留页面内的预览或控制界面。

W3C Presentation API 规范描述启动、重连、可用性监控、连接事件和消息交换。MDN 将其标记为有限可用。BotBrowser 可以记录浏览器暴露的状态，但不能证明存在第二块物理屏幕，也不能证明有人看到了消息。

内容导航

• 可用性不是显示屏清单
• 只在用户激活边界内启动
• 建模完整会话生命周期
• 受限消息与页面内回退
• 使用决策表
• 用 BotBrowser 测试浏览器可见边界
• 结论

可用性不是显示屏清单

PresentationRequest 包含浏览器可以在所选接收端加载的展示 URL。PresentationAvailability 只表示用户代理是否认为存在兼容的展示屏幕。它不是电视、投影仪、接收器或附近人员的清单。availability.value === true 可以用于启用按钮，却不能识别具体屏幕。

屏幕选择属于浏览器。不要枚举接收端，也不要保存假定的设备名称。URL 是应用路由，不是硬件地址。如果构造函数不存在、策略阻止 API 或可用性为 false，就在当前页面显示相同任务。屏幕与 viewport 属性指南区分了几何信息与身份；Presentation API 增加的是浏览器中介会话，而不是显示屏指纹。

const presentation =
  'PresentationRequest' in window ? new PresentationRequest(['/present/board', '/present/fallback']) : null;

let displayAvailable = false;
if (presentation) {
  try {
    const availability = await presentation.getAvailability();
    displayAvailable = availability.value;
    availability.onchange = () => {
      displayAvailable = availability.value;
      renderPresentationControl({ displayAvailable });
    };
  } catch {
    renderPresentationControl({ displayAvailable: false });
  }
}

只在用户激活边界内启动

在按钮或键盘事件中调用 presentation.start()。不要在加载、定时器或网络回调中启动。浏览器可能因支持、激活、策略或显示屏选择而拒绝 Promise。无关的等待会让瞬时激活过期。

async function startPresentation() {
  if (!presentation) return showInline('unsupported');
  if (!displayAvailable) return showInline('unavailable');
  setPresentationState('starting');
  try {
    const connection = await presentation.start();
    attachConnection(connection);
    setPresentationState(connection.state);
  } catch (error) {
    setPresentationState(classifyPresentationError(error));
    showInline('fallback');
  }
}
startButton.addEventListener('click', startPresentation);

可用性只是点击前的提示；start() 的结果决定本次尝试。用 starting 阻止重复请求，结果返回后再显示重试。对于另一种浏览器中介交接，Web Share API：权限边界与安全回退同样区分能力、激活和交付。

建模完整会话生命周期

连接可以经历 connecting、connected、closed 和 terminated。处理 onconnect、onclose、onterminate、onmessage，并在关闭时释放监听器。重连是单独的用户操作：展示标识符是不透明的，可能过期，不能证明恢复了同一块物理屏幕。

function attachConnection(connection) {
  connection.onconnect = () => setPresentationState('connected');
  connection.onclose = () => {
    setPresentationState('closed');
    showInline('fallback');
  };
  connection.onterminate = () => {
    setPresentationState('terminated');
    showInline('fallback');
  };
  connection.onmessage = event => acceptBoundedMessage(event.data);
}

可用性变为 false 时，不要在连接自身报告前就宣布会话关闭。收到 close 或 terminate 后，也不要永久显示“已连接”。页面应继续保留工作内容。Document Picture-in-Picture：权限与窗口边界可用于对比另一类辅助窗口生命周期。

受限消息与页面内回退

定义包含 version、revision、类型白名单和大小限制的消息封装。拒绝未知类型、旧版本和过大的数据。收到消息只是协议事件，不是像素渲染或人工阅读的证明。接收端要验证路由和版本，转义内容；协议未知时应关闭连接。

const MAX_MESSAGE_BYTES = 16_384;
let revision = 0;
function makeMessage(type, content) {
  const message = { version: 1, revision: ++revision, type, content };
  const encoded = JSON.stringify(message);
  if (new TextEncoder().encode(encoded).length > MAX_MESSAGE_BYTES) throw new Error('message-too-large');
  return encoded;
}

业务模型应留在页面的正常状态存储中，再从中派生精简的展示视图。连接关闭后页面继续编辑；重连成功时只发送当前版本，而不是重播全部历史。有限超时和一次恢复快照可以避免无限重试。

使用决策表

观察状态	安全动作	不应声称
没有 PresentationRequest	显示页面内视图	所有浏览器都支持
可用性为 false	保留回退或禁用启动	任何地方都没有物理屏幕
start() 被拒绝	记录错误类别并保留任务	某个命名设备拒绝了请求
connected	发送受限版本	每个像素都已渲染
收到消息	验证封装和版本	某个人确认了消息
close 或 terminate	释放资源并提供重试	屏幕仍然可用
重连被拒绝	达到预算后清除过期令牌	恢复了同一块屏幕

用 BotBrowser 测试浏览器可见边界

BotBrowser 可用于测试受控上下文中的确定性按钮，记录构造函数、可用性、状态迁移和回退是否可见；但 BotBrowser 不能把测试运行器变成物理接收端，也不能保证交付。unsupported、unavailable 或 start-rejected 都是有效结果，只要页面保持可用。BotBrowser 高级功能文档说明了这一边界。

{
  "request": "PresentationRequest",
  "availability": "unknown",
  "states": ["starting", "fallback"],
  "messagesAccepted": 0,
  "fallbackVisible": true,
  "delivery": "not-observed",
  "physicalDisplay": "not-asserted"
}

每次只改变一个变量重复 fixture：浏览器版本、激活路径、显示可用性、网络或会话标识符。比较第一次分叉的状态，不要把本地运行扩大成所有系统的承诺。

结论

页面负责状态，浏览器负责显示屏中介。检测支持，在可见操作中启动，限制消息，并把关闭、终止和重连失败视为预期状态。BotBrowser 可以在授权的受控上下文中重放并比较这一浏览器可见契约；它不能创建第二块屏幕、选择接收者或保证交付。

公开来源

• Presentation API，W3C
• Presentation API，MDN
• BotBrowser 高级功能

延伸阅读

阅读 Document Picture-in-Picture：权限与窗口边界 和 Web Share API：权限边界与安全回退。