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');
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('已退出全屏');
  }
});
// 退出全屏的通用写法
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;
}
app:fullscreen * {
pointer-events: auto;
}

全屏 API 表面简单，实际坑集中在上下文限制、前缀兼容、状态同步和 CSS 重置这四点。最容易忽略的是：用户手动按 F11 退出后，你的页面状态没更新，按钮还显示“退出全屏”，点一下却没反应——因为 document.fullscreenElement 已是 null，但 UI 没同步。