全屏API调用失败常见报错是TypeError: Document not active或SecurityError，因必须由用户手势同步触发，异步调用会静默失败；requestFullscreen()是标准API，webkitEnterFullscreen()仅iOS Safari支持且行为受限；沉浸式全屏需viewport-fit=cover、playsinline等配合；退出后需监听fullscreenchange重置overflow等样式。
全屏 API 调用失败常见报错是什么
直接调用 element.requestFullscreen() 却没反应？大概率是触发时机或权限问题。浏览器强制要求全屏必须由用户手势（如 click、keydown）驱动，异步回调（如 setTimeout、Promise.then）里调用会静默失败，控制台通常抛出 TypeError: Document not active 或 SecurityError。
- 确保在事件处理器内同步调用，例如：
button.addEventListener('click', () => video.requestFullscreen()) - 避免封装成独立函数后脱离事件上下文；若需复用，把
event传入并检查event.isTrusted === true - 部分浏览器（如 Safari）对
<iframe></iframe>内容启用全屏有额外限制，需添加allow="fullscreen"属性
requestFullscreen() 和 webkitEnterFullscreen() 有什么区别
requestFullscreen() 是标准 API，适用于大多数现代浏览器；而 webkitEnterFullscreen() 是旧版 iOS Safari 专有方法，仅对 <video></video> 元素有效，且行为更接近“原生播放器全屏”，不等同于 DOM 全屏 —— 它不会拉伸容器、不触发 fullscreenchange 事件，也无法自定义 UI。
- 优先用标准 API：支持
document.fullscreenElement检测状态，可监听fullscreenchange做样式/逻辑切换 - iOS Safari 下若标准 API 对
<video></video>无效（如未设置playsinline），才降级使用webkitEnterFullscreen() - 注意：Chrome Android 已废弃
webkitEnterFullscreen()，只认标准 API
如何让全屏真正“沉浸”而不只是放大
单纯调用全屏 API 只改变视口尺寸，但默认会有地址栏、状态栏、系统导航键遮挡，尤其在移动端。真正的沉浸需组合多个控制点：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 页面级：添加
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">，配合 CSSenv(safe-area-inset-*)避免被刘海/圆角裁切 - 视频类内容：务必加
playsinline属性，否则 iOS 会强制跳转原生播放器，失去控制权 - 隐藏浏览器 UI：Android Chrome 支持
navigator.standalone+ PWA manifest，但仅限已添加到主屏幕的场景；iOS 无通用方案，依赖viewport-fit=cover和内容适配
退出全屏后样式错乱怎么修复
全屏退出时，document.fullscreenElement 变为 null，但 CSS 中基于 :fullscreen 的规则可能残留影响，或因 viewport 缩放未恢复导致布局异常。最常踩的坑是忘记重置 body 的 overflow 或 height。
立即学习“前端免费学习笔记（深入）”；
- 监听
fullscreenchange事件，在退出时显式还原关键样式：document.body.style.overflow = '' - 避免在全屏态下修改
html或body的height: 100vh—— 退出后vh单位会因地址栏显示而跳变，改用100%或min-height: 100vh - 某些安卓机型退出后触发两次
resize，建议节流处理或用requestAnimationFrame延迟样式修正
全屏不是开关一按就完事，它本质是和浏览器 UI 抢控制权的过程。真正沉浸的关键不在“是否全屏”，而在能否预判各平台对 fullscreenchange、resize、orientationchange 的响应节奏，并提前封堵那些不报错但悄悄失效的环节。
