pin_drop当前位置:知识文库 ❯ 图文
HTML5 API：HTML5 Fullscreen API - 完整教程与代码示例
一、教程简介
Fullscreen API 允许 Web 应用将指定元素以全屏方式展示,隐藏浏览器地址栏、工具栏等界面元素,为用户提供沉浸式的浏览体验。该 API 广泛应用于视频播放、图片查看、在线游戏、数据大屏展示、幻灯片演示等场景,是构建沉浸式 Web 应用的关键接口。
二、核心概念
全屏模式特性
-
隐藏浏览器 UI:全屏显示时,浏览器 UI(地址栏、标签栏、工具栏)会被隐藏
-
用户主动触发:只有用户主动操作才能触发全屏(安全限制)
-
ESC 退出:按 ESC 键可以退出全屏
-
自定义 UI:全屏模式下可以显示自定义 UI 覆盖层
-
事件监听:全屏状态变化时会触发事件
API 概览
CSS 伪类
代码示例
/* 全屏状态下的样式 */
:fullscreen {
background: #000;
}
/* 全屏下的背景样式(可覆盖其他元素) */
::backdrop {
background: rgba(0, 0, 0, 0.5);
}三、语法与用法
进入全屏
代码示例
// 将整个文档全屏
document.documentElement.requestFullscreen();
// 将指定元素全屏
document.getElementById('video').requestFullscreen();
// 带选项的全屏请求
element.requestFullscreen({ navigationUI: 'hide' }); // 隐藏导航UI
element.requestFullscreen({ navigationUI: 'show' }); // 显示导航UI(默认)
element.requestFullscreen({ navigationUI: 'auto' }); // 自动决定退出全屏
代码示例
if (document.fullscreenElement) {
document.exitFullscreen();
}检测全屏状态
代码示例
// 是否处于全屏
const isFullscreen = !!document.fullscreenElement;
// 全屏状态变化事件
document.addEventListener('fullscreenchange', function() {
if (document.fullscreenElement) {
console.log('进入全屏:', document.fullscreenElement);
} else {
console.log('退出全屏');
}
});前缀兼容
代码示例
// 兼容各浏览器前缀
function requestFullscreen(element) {
if (element.requestFullscreen) return element.requestFullscreen();
if (element.webkitRequestFullscreen) return element.webkitRequestFullscreen();
if (element.msRequestFullscreen) return element.msRequestFullscreen();
if (element.mozRequestFullScreen) return element.mozRequestFullScreen();
}
function exitFullscreen() {
if (document.exitFullscreen) return document.exitFullscreen();
if (document.webkitExitFullscreen) return document.webkitExitFullscreen();
if (document.msExitFullscreen) return document.msExitFullscreen();
if (document.mozCancelFullScreen) return document.mozCancelFullScreen();
}
function getFullscreenElement() {
return document.fullscreenElement ||
document.webkitFullscreenElement ||
document.msFullscreenElement ||
document.mozFullScreenElement ||
null;
}四、代码示例
示例一:全屏图片查看器
提示:完整代码示例请参考源文件中的图片查看器实现,包含画廊展示、全屏查看、键盘导航等功能。
示例二:全屏数据大屏
提示:完整代码示例请参考源文件中的数据大屏实现,包含实时数据监控、图表展示、全屏切换等功能。
五、浏览器兼容性
六、注意事项与最佳实践
1. 用户交互限制
全屏请求必须由用户操作触发,不能在页面加载时自动进入全屏:
代码示例
// 错误:自动全屏会被阻止
window.addEventListener('load', function() {
document.documentElement.requestFullscreen(); // 失败
});
// 正确:用户点击触发
button.addEventListener('click', function() {
document.documentElement.requestFullscreen();
});2. 全屏样式适配
代码示例
/* 全屏时的样式调整 */
:fullscreen video {
width: 100vw;
height: 100vh;
object-fit: contain;
}
/* 全屏背景 */
:fullscreen {
background: #000;
}
/* 全屏覆盖层 */
::backdrop {
background: rgba(0, 0, 0, 0.8);
}3. 移动端注意事项
-
iOS 限制:iOS Safari 对全屏支持有限
-
兼容性检查:某些移动浏览器可能不支持 Fullscreen API
-
降级方案:建议提供降级方案(如 CSS 模拟全屏)
4. 错误处理
代码示例
element.requestFullscreen().catch(function(error) {
switch (error.name) {
case 'NotAllowedError':
console.log('全屏请求被拒绝');
break;
case 'NotSupportedError':
console.log('不支持全屏');
break;
default:
console.log('全屏错误:', error.message);
}
});七、常见问题
常见问题
requestFullscreen 返回 rejected promise?
原因:可能是非用户操作触发、iframe 缺少 allowfullscreen 属性、或不支持全屏。
解决方案:确保由用户操作触发,iframe 添加 allowfullscreen,使用前检查 document.fullscreenEnabled。
iOS Safari 不支持 Fullscreen API?
解决方案:使用 CSS 模拟全屏作为降级方案:
代码示例
function enterFullscreen(element) {
if (element.requestFullscreen) {
element.requestFullscreen();
} else {
// CSS 降级方案
element.style.position = 'fixed';
element.style.top = '0';
element.style.left = '0';
element.style.width = '100vw';
element.style.height = '100vh';
element.style.zIndex = '9999';
}
}全屏模式下 ESC 键退出如何自定义?
解答:浏览器默认 ESC 退出全屏行为无法阻止。可以在退出后通过 fullscreenchange 事件重新进入全屏,但不推荐这样做,会损害用户体验。
八、总结
Fullscreen API 提供了将 Web 内容全屏展示的能力,适用于视频播放、图片查看、数据大屏等沉浸式场景。使用时需注意必须由用户操作触发、处理浏览器前缀兼容、适配全屏样式、以及移动端的降级方案。通过封装工具类可以简化 API 调用和事件监听,确保在各种浏览器环境下都能正常工作。
本文涉及AI创作
内容由AI创作，请仔细甄别
