浏览器原生全屏 api 不会跨页面持久化状态，需结合 localstorage 手动保存与恢复全屏状态；本文详解实现方案，含完整代码示例、生命周期处理逻辑及 safari 兼容性说明。
浏览器原生全屏 api 不会跨页面持久化状态，需结合 localstorage 手动保存与恢复全屏状态；本文详解实现方案，含完整代码示例、生命周期处理逻辑及 safari 兼容性说明。
Web 应用中通过 Element.requestFullscreen() 启用的全屏模式本质上是会话级临时状态：一旦发生页面跳转（如 <a href="/dashboard">）、表单提交或刷新（F5 / location.reload()），浏览器会强制退出全屏，并清空当前全屏上下文——这是 W3C 规范明确要求的安全行为，无法绕过。因此，“维持全屏”实质上是“在新页面加载完成后自动重新触发全屏”，而非真正“持续不中断”。
✅ 解决方案：localStorage + 页面加载时自动恢复
核心思路是：
- 进入全屏时，向 localStorage 写入标志位（如 fullscreen: "true"）；
- 页面 load 事件触发时，检查该标志位，若为 "true" 则调用 document.documentElement.requestFullscreen()；
- 退出全屏时（监听 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);
}
},
// 监听全屏状态变更，同步 localStorage
initListeners() {
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();
}
});
});⚠️ 关键注意事项
- 安全限制不可绕过：requestFullscreen() 必须由用户手势（如 click）触发，且不能在 load 或 DOMContentLoaded 的同步上下文中直接调用。上述代码使用 setTimeout + visibilityState 检查，是规避 Safari 和新版 Chrome 报错的可靠方式。
- Safari 行为差异：Safari 对 requestFullscreen() 的调用时机更严格，需确保 DOM 已就绪、页面可见，且避免在 iframe 中调用（需 allow="fullscreen" 属性）。
- LocalStorage 同源限制：所有页面必须同域（协议+主机+端口一致），否则 localStorage 无法共享。
- 退出逻辑完整性：务必监听 fullscreenchange 事件清理标记，否则刷新后可能误触发全屏（尤其当用户手动按 ESC 退出时）。
- 移动端兼容性：iOS Safari 不支持 requestFullscreen()（仅部分 iPadOS 支持），建议添加 UA 检测降级提示。
✅ 总结
全屏状态无法真正“跨页面维持”，但通过 localStorage 标记 + load 事件自动恢复，可实现接近无缝的用户体验。本方案兼顾规范合规性、主流浏览器兼容性及可维护性，适用于 Admin 后台等需要沉浸式操作的场景。务必测试真实跳转流程（非单页路由），并针对 Safari 做好渐进增强处理。
