如何使用现代 API 实现 Ruffle 播放器的全屏状态同步-html教程-PHP中文网

如何使用现代 API 实现 Ruffle 播放器的全屏状态同步

本文介绍如何通过标准的 fullscreenchange 事件和 document.fullscreenElement 属性，准确监听浏览器全屏状态变化，并自动同步 RufflePlayer 的全屏行为，替代已废弃的 window.fullScreen 等旧式检测方式。

本文介绍如何通过标准的 `fullscreenchange` 事件和 `document.fullscreenelement` 属性，准确监听浏览器全屏状态变化，并自动同步 ruffleplayer 的全屏行为，替代已废弃的 `window.fullscreen` 等旧式检测方式。

在 Web 开发中，实现 Flash 内容（如 Ruffle 播放器）与浏览器原生全屏状态的实时同步，是提升用户体验的关键环节。过去常有人尝试用 window.innerWidth === screen.width && window.innerHeight === screen.height 或已废弃的 window.fullScreen / document.fullScreen 属性进行判断，但这些方法不可靠、不跨浏览器，且已被现代浏览器移除或弃用。

✅ 正确做法是使用标准化的全屏 API：

✅ document.fullscreenElement：返回当前处于全屏模式的 DOM 元素（null 表示未全屏），是唯一推荐的全屏状态检测方式；
✅ fullscreenchange 事件：在用户通过 F11、requestFullscreen() 或退出全屏时触发，具备良好的兼容性（Chrome 71+、Firefox 69+、Edge 79+、Safari 15.4+）。

以下是完整、健壮的实现代码：

function handleFullscreenChange() {
  if (document.fullscreenElement) {
    // 浏览器进入全屏 → 同步启用 Ruffle 全屏
    if (typeof window.RufflePlayer?.enterFullscreen === 'function') {
      window.RufflePlayer.enterFullscreen();
    }
  } else {
    // 浏览器退出全屏 → 同步关闭 Ruffle 全屏
    if (typeof window.RufflePlayer?.exitFullscreen === 'function') {
      window.RufflePlayer.exitFullscreen();
    }
  }
}

// 绑定事件监听器（注意大小写：'fullscreenchange'，非 'fullscreenchanged'）
document.addEventListener('fullscreenchange', handleFullscreenChange);

// 【可选】页面加载后手动触发一次，确保初始状态一致
// handleFullscreenChange();

⚠️ 注意事项：

事件名拼写必须准确：是 'fullscreenchange'，不是 'fullscreenchanged'（原答案中存在笔误，已修正）；
Ruffle 加载时机：确保 window.RufflePlayer 已就绪再绑定事件，建议在 <script></script> 加载完成或 DOMContentLoaded 后执行；
安全上下文要求：enterFullscreen()/exitFullscreen() 只能在用户交互（如点击）触发的上下文中调用；若需主动同步，应确保该操作由合法的用户手势（例如按钮点击）发起；
错误防护：添加 typeof ... === 'function' 判断，避免 Ruffle 未加载完成时调用报错；
移动端适配：目前主流移动浏览器不支持 F11 或 document.fullscreenElement（受限于系统 UI），该方案主要适用于桌面端。

? 小结：摒弃过时的尺寸比对与废弃属性，拥抱标准 fullscreenchange 事件 + document.fullscreenElement，不仅能提高代码可靠性与可维护性，还能确保与 Ruffle 等现代播放器生态良好协同。如需进一步控制全屏目标元素（如仅对 <ruffle-player></ruffle-player> 自身请求全屏），可结合 element.requestFullscreen() 使用。