如何在页面跳转或刷新后保持全屏模式

浏览器原生全屏 API 不会跨页面持久化状态，需结合 localStorage 手动保存与恢复全屏状态；本文详解实现方案，含完整代码示例、生命周期处理逻辑及 Safari 兼容性说明。

浏览器原生全屏 API 不会跨页面持久化状态，需结合 localStorage 手动保存与恢复全屏状态；本文详解实现方案，含完整代码示例、生命周期处理逻辑及 Safari 兼容性说明。

Web 应用中通过 Element.requestFullscreen() 启用的全屏模式本质上是会话级临时状态：一旦发生页面跳转（如 <a href="/dashboard">）、表单提交或刷新（F5 / location.reload()），浏览器会强制退出全屏，并清空当前全屏上下文——这是 W3C 规范明确要求的安全行为，无法绕过。因此，“维持全屏”实质上是“在新页面加载完成后自动重新触发全屏”，而非真正“持续不中断”。

✅ 解决方案：localStorage + 页面加载时自动恢复

核心思路是：

1. 进入全屏时，向 localStorage 写入标志位（如 fullscreen: "true"）；
2. 页面 load 事件触发时，检查该标志位，若为 "true" 则调用 document.documentElement.requestFullscreen()；
3. 退出全屏时（监听 fullscreenchange 事件），同步清除标志位。

以下为完整可落地的实现代码（兼容 Chrome/Firefox/Edge，已适配 Safari 的差异）：

// 全屏状态管理模块const FullscreenManager = {flagKey: 'app_fullscreen_active',// 进入全屏并持久化标记enterFullscreen() {const elem = document.documentElement;if (elem.requestFullscreen) {elem.requestFullscreen().then(() => localStorage.setItem(this.flagKey, 'true')).catch(err => console.warn('Fullscreen request rejected:', err));}},// 退出全屏并清除标记exitFullscreen() {if (document.exitFullscreen) {document.exitFullscreen().then(() => localStorage.removeItem(this.flagKey)).catch(err => console.warn('Exit fullscreen failed:', err));}},// 页面加载时尝试恢复全屏restoreOnLoad() {if (localStorage.getItem(this.flagKey) === 'true') {// Safari 需确保在用户交互后调用（但 load 事件非交互触发），故加延迟+可见性检查setTimeout(() => {if (document.visibilityState === 'visible') {this.enterFullscreen();}}, 100);}},// 监听全屏状态变更，同步 localStorageinitListeners() {document.addEventListener('fullscreenchange', () => {if (!document.fullscreenElement) {localStorage.removeItem(this.flagKey);}});}};// 初始化：页面加载后恢复，绑定监听器document.addEventListener('DOMContentLoaded', () => {FullscreenManager.restoreOnLoad();FullscreenManager.initListeners();});// 绑定到你的 Font Awesome 按钮（支持多次点击切换）document.querySelectorAll('[data-widget="fullscreen"]').forEach(btn => {btn.addEventListener('click', (e) => {e.preventDefault();if (!document.fullscreenElement) {FullscreenManager.enterFullscreen();} else {FullscreenManager.exitFullscreen();}});});

⚠️ 关键注意事项

1. 安全限制不可绕过：requestFullscreen() 必须由用户手势（如 click）触发，且不能在 load 或 DOMContentLoaded 的同步上下文中直接调用。上述代码使用 setTimeout + visibilityState 检查，是规避 Safari 和新版 Chrome 报错的可靠方式。
2. Safari 行为差异：Safari 对 requestFullscreen() 的调用时机更严格，需确保 DOM 已就绪、页面可见，且避免在 iframe 中调用（需 allow="fullscreen" 属性）。
3. LocalStorage 同源限制：所有页面必须同域（协议+主机+端口一致），否则 localStorage 无法共享。
4. 退出逻辑完整性：务必监听 fullscreenchange 事件清理标记，否则刷新后可能误触发全屏（尤其当用户手动按 ESC 退出时）。
5. 移动端兼容性：iOS Safari 不支持 requestFullscreen()（仅部分 iPadOS 支持），建议添加 UA 检测降级提示。

✅ 总结

全屏状态无法真正“跨页面维持”，但通过 localStorage 标记 + load 事件自动恢复，可实现接近无缝的用户体验。本方案兼顾规范合规性、主流浏览器兼容性及可维护性，适用于 Admin 后台等需要沉浸式操作的场景。务必测试真实跳转流程（非单页路由），并针对 Safari 做好渐进增强处理。