JS_API.md

FPBrowser 页面 JS API

FPBrowser 在每个页面加载完成后自动注入 window.FPBrowser 对象，供页面脚本和内容脚本使用。

window.FPBrowser

sendMessage(op, payload)

向服务端发送消息，经过鉴权后广播给所有查看该屏幕的玩家。

// payload 可以是字符串或对象（对象会自动 JSON.stringify）
window.FPBrowser.sendMessage('my_event', { key: 'value' });
window.FPBrowser.sendMessage('my_event', 'raw string');

• 需要玩家有控制权限，否则服务端会拒绝。
• 异步，不阻塞页面。
• 广播后所有查看者的页面都会收到 fpbrowser:event 事件（包括发送者自己）。
• 错误处理：即使服务端未安装插件或不响应消息，客户端也不会崩溃或抛出异常。消息会被静默忽略。

sendNotify(op, payload)

向服务端发送通知消息，不需要控制权限，服务端不会广播给其他玩家，仅供服务端插件处理（如持久化全屏状态、播放进度等）。

window.FPBrowser.sendNotify('fullscreen', { value: true });
window.FPBrowser.sendNotify('progress', { currentTime: 42.5 });

• 任何能查看该屏幕的玩家均可发送，无需控制权限。
• 服务端通过 ManagerApi.NotifyEventListener 接收。
• 不会触发 fpbrowser:event，不会广播给其他玩家。
• 错误处理：即使服务端未安装插件或不响应消息，客户端也不会崩溃或抛出异常。消息会被静默忽略。

onServerEvent

赋值一个函数，接收服务端广播的事件（EVENT_EXEC）：

window.FPBrowser.onServerEvent = ({ op, payload }) => {
    console.log('received:', op, payload);
    // payload 是字符串，如需解析对象：JSON.parse(payload)
};

也可以监听 DOM 事件：

window.addEventListener('fpbrowser:event', (e) => {
    const { op, payload } = e.detail;
});

两种方式等价，onServerEvent 是对 DOM 事件的封装。

---

内置 Op

以下 op 由客户端 Mod 内部使用，页面脚本可以监听但通常不需要主动发送：

op	payload	说明
navigate	{"url":"https://..."}	操作者跳转链接时广播，其他人跟随导航
sync	{"currentTime":42.5,"paused":false,"playbackRate":1.0}	操作者每 2 秒广播媒体状态，其他人同步播放进度
input	见传输规范	鼠标/键盘输入事件

---

示例：自定义事件同步

// 发送自定义事件（需要控制权限）
document.getElementById('btn').addEventListener('click', () => {
    window.FPBrowser.sendMessage('button_click', { id: 'btn' });
});

// 所有查看者接收并响应
window.FPBrowser.onServerEvent = ({ op, payload }) => {
    if (op === 'button_click') {
        const data = JSON.parse(payload);
        console.log('button clicked:', data.id);
    }
};

示例：监听导航事件

window.FPBrowser.onServerEvent = ({ op, payload }) => {
    if (op === 'navigate') {
        const { url } = JSON.parse(payload);
        console.log('navigating to:', url);
    }
};

示例：监听播放同步

window.FPBrowser.onServerEvent = ({ op, payload }) => {
    if (op === 'sync') {
        const { currentTime, paused, playbackRate } = JSON.parse(payload);
        // 客户端 Mod 已自动同步，这里可以做额外处理
    }
};

---

注意事项

• window.FPBrowser 在 document_end 后注入，document_start 阶段不可用。
• 如果内容脚本的 runAt 是 document_start，需要等待 window.FPBrowser 就绪：

  function waitFPBrowser(cb) {
      if (window.FPBrowser) { cb(); return; }
      const t = setInterval(() => { if (window.FPBrowser) { clearInterval(t); cb(); } }, 50);
  }
  waitFPBrowser(() => {
      window.FPBrowser.onServerEvent = ({ op }) => console.log(op);
  });

• sendMessage 需要玩家有控制权限，无权限时服务端静默拒绝（不会抛出异常）。
• sendNotify 无需控制权限，但如果服务端未安装插件，消息会被静默忽略。
• payload 在 onServerEvent 回调中始终是字符串，需要手动 JSON.parse。
• 容错性：所有 API 调用都有完善的异常处理，即使服务端不在线、未安装插件或网络异常，客户端也不会崩溃或抛出 JavaScript 异常。