全屏 API 调用必须由用户手势触发，需在 click、touchstart、keydown 等事件回调中调用；移动端推荐 touchstart；禁止在异步回调中调用；iframe 嵌套时父页面需添加 allowfullscreen 属性。
全屏 API 调用必须由用户手势触发
浏览器明确禁止脚本自动进入全屏，requestFullscreen() 必须在 click、touchstart、keydown 等用户主动交互事件回调中调用。否则会静默失败或抛出 TypeError: Document not active 或 SecurityError。
常见错误写法：
gameCanvas.requestFullscreen(); // ❌ 页面加载后直接调用，必然失败
正确做法：
- 绑定按钮点击：
fullscreenBtn.addEventListener('click', () => canvas.requestFullscreen()); - 移动端需注意
touchstart比click更可靠（尤其 iOS） - 避免在异步回调（如
setTimeout、Promise.then）中调用，即使它紧接在 click 后——浏览器会丢失“用户手势上下文”
iframe 嵌套场景下需显式声明 allowfullscreen
如果游戏运行在 内（例如嵌入到 CMS 或活动页），父页面的 iframe 标签必须带 allowfullscreen 属性，否则子页面调用 requestFullscreen() 会被拒绝。
立即学习“前端免费学习笔记（深入）”；
错误示例（父页）：
正确写法：
补充说明：
- Chrome 95+ 还要求
allow="fullscreen"（与allowfullscreen共存更稳妥） - 若使用 sandbox 属性，必须包含
allow-scripts allow-same-origin，否则全屏 API 不可用
移动端 Safari 对 requestFullscreen() 的特殊限制
iOS Safari 默认不支持 不要只依赖调用成功与否判断是否进入全屏。应始终检查 调试建议： 全屏不是“调了就成”的功能，它高度依赖上下文合法性——用户动作、容器权限、平台策略三者缺一不可。最容易被忽略的是：iOS 上 Canvas 无法真全屏，以及 iframe 中漏掉 或普通 元素调用（且需 playsinline 和用户手势）。HTML5 小游戏若想在 iOS 全屏，有两条路径：
webkitEnterFullscreen()（仅限 ，不适用于 Canvas 游戏）width: 100vw; height: 100vh; + position: fixed;，并隐藏地址栏（window.scrollTo(0, 1)）
检查
document.fullscreenElement 与权限状态document.fullscreenElement 是否为当前元素，并监听 fullscreenchange 事件做状态同步。
document.fullscreenElement 查看当前全屏节点（返回 null 表示未全屏）document.addEventListener('fullscreenerror', () => console.error('Fullscreen failed'))
chrome.webview.getWebView().settings.setJavaScriptEnabled(true)（仅限 Cordova/ Capacitor 环境）allowfullscreen 导致整个功能静默失效。
