全屏 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
如果游戏运行在 <iframe></iframe> 内（例如嵌入到 CMS 或活动页），父页面的 iframe 标签必须带 allowfullscreen 属性，否则子页面调用 requestFullscreen() 会被拒绝。
立即学习“前端免费学习笔记（深入）”；
错误示例（父页）：
把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。
<iframe src="game.html"></iframe> <!-- ❌ 缺少 allowfullscreen -->
正确写法：
<iframe src="game.html" allowfullscreen></iframe>
补充说明：
- Chrome 95+ 还要求
allow="fullscreen"（与allowfullscreen共存更稳妥） - 若使用 sandbox 属性，必须包含
allow-scripts allow-same-origin，否则全屏 API 不可用
移动端 Safari 对 requestFullscreen() 的特殊限制
iOS Safari 默认不支持 <canvas></canvas> 或普通 <div> 全屏，只允许 <code><video></video> 元素调用（且需 playsinline 和用户手势）。HTML5 小游戏若想在 iOS 全屏，有两条路径：
- 改用
webkitEnterFullscreen()（仅限<video></video>，不适用于 Canvas 游戏） - 退而求其次：用 CSS 模拟“伪全屏”——监听屏幕方向 + 设置
width: 100vw; height: 100vh;+position: fixed;，并隐藏地址栏（window.scrollTo(0, 1)） - 确保 viewport meta 正确：
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
检查 document.fullscreenElement 与权限状态
不要只依赖调用成功与否判断是否进入全屏。应始终检查 document.fullscreenElement 是否为当前元素，并监听 fullscreenchange 事件做状态同步。
调试建议：
- 在控制台执行
document.fullscreenElement查看当前全屏节点（返回null表示未全屏） - 监听失败原因：
document.addEventListener('fullscreenerror', () => console.error('Fullscreen failed')) - 部分 Android WebView 需额外配置：在初始化时调用
chrome.webview.getWebView().settings.setJavaScriptEnabled(true)（仅限 Cordova/ Capacitor 环境）
全屏不是“调了就成”的功能，它高度依赖上下文合法性——用户动作、容器权限、平台策略三者缺一不可。最容易被忽略的是：iOS 上 Canvas 无法真全屏，以及 iframe 中漏掉 allowfullscreen 导致整个功能静默失效。
