登录
首页 >  文章 >  前端

HTML5全屏API使用教程详解

时间：2026-01-31 15:15:34 285浏览 收藏

你在学习文章相关的知识吗？本文《HTML5全屏API调用教程》，主要介绍的内容就涉及到，如果你想提升自己的开发能力，就不要错过这篇文章，大家要知道编程理论基础和实战操作都是不可或缺的哦！

判断浏览器是否支持 Fullscreen API 需检查 document.fullscreenEnabled，其为 false 常因非 HTTPS、iframe 缺 allow="fullscreen" 或不支持的 WebView；全屏请求必须由用户手势触发，且需处理 requestFullscreen() 和 exitFullscreen() 的 Promise 拒绝及 fullscreenchange、fullscreenerror 事件。

html5如何实现网页全屏_ fullscreen api调用方法【教程】

如何判断浏览器是否支持 Fullscreen API

不是所有环境都支持全屏，尤其是 iOS Safari 和部分旧版 Android 浏览器会静默忽略调用。必须先检查 document.fullscreenEnabled（注意拼写是 fullscreen，不是 fullsceen 或 fullScreen）：

if (!document.fullscreenEnabled) {
  console.warn('当前浏览器不支持 Fullscreen API');
  return;
}

这个值为 false 的常见情况包括：页面未通过 HTTPS 加载、iframe 未设置 allow="fullscreen"、或运行在不支持该 API 的 WebView 中。

调用 requestFullscreen() 必须由用户手势触发

现代浏览器强制要求全屏请求必须来自用户直接交互（如 click、touchend），不能在定时器、AJAX 回调或 load 事件中调用，否则会抛出 TypeError: Document not active 或静默失败。

  • ✅ 正确：绑定在按钮的 onclick 里
  • ❌ 错误：放在 setTimeout(() => el.requestFullscreen(), 100) 中
  • ⚠️ 注意：requestFullscreen() 返回 Promise，应处理拒绝情况
button.addEventListener('click', () => {
  videoEl.requestFullscreen()
    .catch(err => console.error('全屏请求被拒绝：', err));
});

fullscreenchange 事件监听与状态判断

不要依赖 document.fullscreenElement 的“真值”做条件判断——它在非全屏时是 null，但某些旧版 Chrome 曾返回 undefined。稳妥写法是显式比较：

document.addEventListener('fullscreenchange', () => {
  if (document.fullscreenElement === null) {
    console.log('已退出全屏');
  } else {
    console.log('当前全屏元素：', document.fullscreenElement);
  }
});

另外，fullscreenerror 事件必须监听，因为用户可能手动按 Esc 拒绝，或系统策略阻止（如弹窗拦截器）。

退出全屏的正确方式与兼容性细节

退出全屏统一用 document.exitFullscreen()，不要尝试调用元素上的 exitFullscreen()（不存在）。该方法也返回 Promise，需捕获错误：

document.exitFullscreen()
  .catch(err => console.error('退出全屏失败：', err));

注意几个易错点：

  • document.fullscreenElement 是只读属性，无法手动赋值
  • CSS 中可用 :fullscreen 伪类定制样式，但 Safari 需用 ::-webkit-full-screen
  • 移动端（尤其 iOS）即使调用成功，也可能仅放大视频区域而非真正“网页级全屏”

真正的难点不在调用本身，而在降级处理和跨端行为差异——比如安卓 Chrome 允许

全屏，而 iOS Safari 只允许 或