HTML全屏API需在用户手势中调用element.requestFullscreen()，兼容各浏览器前缀；通过document.fullscreenElement检测状态，用document.exitFullscreen()退出；F11与API互斥，CSS需用:fullscreen伪类重置样式。
HTML 全屏 API 的正确调用方式
浏览器原生全屏不是靠快捷键“触发”的，而是通过 Element.requestFullscreen() 方法由 JavaScript 主动发起。用户必须在用户手势（如点击、按键）上下文中调用，否则会被浏览器静默拒绝。
常见错误是直接在页面加载时调用，或在异步回调（如 setTimeout、fetch 成功后）里调用 —— 这些都不算有效用户激活上下文。
- 只支持挂载到 DOM 元素上，不能对整个 HTML 文档直接调用（
document.documentElement.requestFullscreen()是合法的，但本质仍是元素） - 必须处理不同浏览器前缀：
requestFullscreen（标准）、webkitRequestFullscreen（Safari）、msRequestFullscreen（旧 Edge） - 调用前建议检查兼容性：
if (element.requestFullscreen)，避免报错
const btn = document.getElementById('fullscreen-btn');
const container = document.getElementById('app');
<p>btn.addEventListener('click', () => {
if (container.requestFullscreen) {
container.requestFullscreen();
} else if (container.webkitRequestFullscreen) {
container.webkitRequestFullscreen();
} else if (container.msRequestFullscreen) {
container.msRequestFullscreen();
}
});如何检测和退出全屏状态
全屏状态不可靠地靠视觉判断，必须监听 fullscreenchange 事件并检查 document.fullscreenElement（注意拼写是 fullscreen，不是 fullScreen 或 full-screen）。
退出全屏不能靠“再点一次按钮”硬调用，应统一用 document.exitFullscreen()，它同样有前缀变体。
立即学习“前端免费学习笔记（深入）”；
-
document.fullscreenElement为null表示未全屏；否则返回当前全屏的 DOM 元素 - 不要依赖
document.webkitIsFullScreen等已废弃属性 -
document.exitFullscreen()在非全屏状态下调用不会报错，可安全使用
document.addEventListener('fullscreenchange', () => {
if (document.fullscreenElement) {
console.log('已进入全屏：', document.fullscreenElement);
} else {
console.log('已退出全屏');
}
});
<p>// 退出全屏的通用写法
function exitFullscreen() {
if (document.exitFullscreen) {
document.exitFullscreen();
} else if (document.webkitExitFullscreen) {
document.webkitExitFullscreen();
} else if (document.msExitFullscreen) {
document.msExitFullscreen();
}
}F11 快捷键不是 HTML 控制的，别混淆
按 F11（Windows/Linux）或 Ctrl+Cmd+F（macOS）触发的是浏览器窗口级全屏，和 HTML 全屏 API 完全无关。它绕过所有网页逻辑，也不触发 fullscreenchange 事件，JS 无法监听、无法阻止、也无法感知是否被用户手动切出。
这意味着：你用 JS 开启了全屏，用户按 F11 会强制退出你的全屏；反之，用户先按 F11，你的 requestFullscreen() 调用会失败（因为浏览器不允许嵌套全屏）。
- 两者互斥，且生命周期独立
- 不要在文档里写“按 F11 即可全屏”误导用户——那不是你的页面行为
- 若需强提示，只说“点击按钮启用全屏”，并确保按钮有明确视觉反馈
CSS 全屏样式适配要点
进入全屏后，浏览器会自动给全屏元素加一层 :-webkit-full-screen（Safari/Chrome）或 :fullscreen（标准）伪类，可用于覆盖默认样式。但注意：这些选择器不支持子元素继承，必须显式写。
- 必须重置
margin、padding和overflow，否则可能留白或滚动条残留 -
width: 100vw; height: 100vh;在全屏下不一定生效，优先用100%或直接依赖全屏容器撑满 - Safari 对
:fullscreen支持较晚，仍需保留:-webkit-full-screen
/* 标准 + Safari 兼容写法 */
#app:fullscreen,
#app:-webkit-full-screen {
width: 100%;
height: 100%;
margin: 0;
padding: 0;
overflow: hidden;
}
<h1>app:fullscreen * {</h1><p>pointer-events: auto;
}全屏 API 表面简单，实际坑集中在上下文限制、前缀兼容、状态同步和 CSS 重置这四点。最容易忽略的是：用户手动按 F11 退出后，你的页面状态没更新，按钮还显示“退出全屏”，点一下却没反应——因为 document.fullscreenElement 已是 null，但 UI 没同步。
