全屏 api 需用户手势触发，调用 requestfullscreen() 和 exitfullscreen() 并监听 fullscreenchange 事件同步状态，注意兼容前缀、移动端限制及 iframe 权限。
全屏 API 的基本调用方式
现代浏览器支持 Element.requestFullscreen() 和 document.exitFullscreen()，但要注意：全屏操作必须由用户手势（如点击）触发，不能在页面加载或定时器里自动调用，否则会被浏览器静默拒绝。
- 调用
requestFullscreen()时，目标元素（通常是document.documentElement或某个容器）会尝试进入全屏 - 成功后，
document.fullscreenElement会返回该元素；为null表示未全屏 -
exitFullscreen()总是作用于整个文档，不接受参数
const btn = document.getElementById('fullscreen-btn');
btn.addEventListener('click', () => {
if (!document.fullscreenElement) {
document.documentElement.requestFullscreen();
} else {
document.exitFullscreen();
}
});
兼容性处理：不同浏览器的前缀差异
旧版 Chrome、Firefox、Safari 曾使用带前缀的方法，虽然现在主流版本已统一支持无前缀 API，但若需兼容较老版本（如 Chrome ≤ 69、Firefox ≤ 63），得手动 fallback。
-
requestFullscreen可能是webkitRequestFullscreen、mozRequestFullScreen、msRequestFullscreen -
exitFullscreen对应webkitExitFullscreen、mozCancelFullScreen、msExitFullscreen -
fullscreenElement同样有前缀变体：webkitFullscreenElement、mozFullScreenElement、msFullscreenElement
建议封装一个简单判断逻辑，而不是盲目 polyfill：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
function toggleFullscreen() {
if (!document.fullscreenElement) {
document.documentElement.requestFullscreen?.() ||
document.documentElement.webkitRequestFullscreen?.() ||
document.documentElement.mozRequestFullScreen?.() ||
document.documentElement.msRequestFullscreen?.();
} else {
document.exitFullscreen?.() ||
document.webkitExitFullscreen?.() ||
document.mozCancelFullScreen?.() ||
document.msExitFullscreen?.();
}
}
按钮状态同步：如何实时更新“全屏/退出”文字
仅靠点击事件无法保证 UI 与实际状态一致——比如用户按 F11 或 Esc 退出全屏，JS 不会自动感知，除非监听事件。
- 必须监听
fullscreenchange事件（注意拼写，不是fullscreenChanged） - 该事件在进入/退出全屏时都触发，且在
requestFullscreen()或exitFullscreen()完成后异步派发 - 切勿在事件回调里再次调用全屏方法，可能引发循环或报错
TypeError: Document not active
document.addEventListener('fullscreenchange', () => {
const btn = document.getElementById('fullscreen-btn');
btn.textContent = document.fullscreenElement ? '退出全屏' : '全屏';
});
常见报错和权限限制
最常遇到的是控制台报错：Failed to execute 'requestFullscreen' on 'Element': API can't be initiated by a user gesture。这说明调用不在用户交互上下文中。
- 确保绑定事件的是原生 click（而非自定义事件、setTimeout 包裹、或 Promise resolve 后调用）
- Vue/React 中避免在 effect 或 computed 里触发全屏，应在
onClick回调内直接调用 - 移动端 Safari 对全屏支持极弱，基本只允许
<video></video>全屏播放，requestFullscreen()对普通元素无效 - 某些浏览器（如 Firefox）在 iframe 中默认禁用全屏，需添加
allow="fullscreen"属性
全屏不是样式切换，它会脱离正常渲染流，CSS 伪类 :fullscreen 可用于定制全屏下样式，但别指望它能替代 JS 状态管理。真正容易被忽略的，是用户通过系统快捷键（如 Mac 上的 Ctrl+Cmd+F）进出全屏时，你的按钮状态是否还能及时响应——这完全依赖 fullscreenchange 事件的可靠性，而它在部分 Android 浏览器上存在延迟或丢失。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
