MDN Web API 全屏模式技术详解：Fullscreen API 完全指南

什么是 Fullscreen API

Fullscreen API 是一组允许网页元素进入全屏状态的浏览器接口，它能够将特定 DOM 元素及其子元素扩展到整个屏幕显示，同时隐藏浏览器界面和其他应用程序。这项技术特别适合需要沉浸式体验的场景，比如在线游戏、视频播放器或演示应用。

核心概念解析

全屏模式的特点

1. 独占显示：全屏元素会占据整个屏幕空间
2. 界面简化：浏览器工具栏、地址栏等UI元素会被隐藏
3. 专注模式：其他应用程序窗口会被暂时遮挡
4. 可控退出：用户可通过ESC键或程序控制退出全屏

适用场景

• 视频播放器全屏观看
• 网页游戏沉浸式体验
• 幻灯片演示展示
• 任何需要最大化显示区域的网页应用

API 接口详解

关键方法

Element.requestFullscreen()

const element = document.getElementById('fullscreen-element');
element.requestFullscreen();

此方法请求浏览器将指定元素设置为全屏模式。注意：

• 必须在用户交互事件(如click)中调用
• 返回一个Promise对象
• 可能因权限策略被拒绝

Document.exitFullscreen()

document.exitFullscreen();

退出全屏模式，同样返回Promise对象。

重要属性

document.fullscreenElement

if (document.fullscreenElement) {
    console.log('当前全屏元素:', document.fullscreenElement);
} else {
    console.log('未处于全屏模式');
}

此只读属性返回当前全屏显示的DOM元素，若为null则表示不在全屏状态。

document.fullscreenEnabled

if (document.fullscreenEnabled) {
    console.log('浏览器支持全屏功能');
} else {
    console.log('全屏功能不可用');
}

检测浏览器是否允许使用全屏API。

事件监听

fullscreenchange

document.addEventListener('fullscreenchange', (event) => {
    if (document.fullscreenElement) {
        console.log('进入全屏模式');
    } else {
        console.log('退出全屏模式');
    }
});

当全屏状态发生变化时触发。

fullscreenerror

document.addEventListener('fullscreenerror', (event) => {
    console.error('全屏操作出错:', event);
});

全屏操作失败时触发。

实际应用示例

基础全屏切换实现

<video id="myVideo" controls width="640">
    <source src="video.mp4" type="video/mp4">
</video>
<button id="fullscreenBtn">全屏切换</button>

<script>
    const video = document.getElementById('myVideo');
    const btn = document.getElementById('fullscreenBtn');
    
    btn.addEventListener('click', () => {
        if (!document.fullscreenElement) {
            video.requestFullscreen().catch(err => {
                console.error(`全屏错误: ${err.message}`);
            });
        } else {
            document.exitFullscreen();
        }
    });
</script>

进阶功能：全屏样式定制

/* 全屏状态下的特殊样式 */
#myVideo:-webkit-full-screen {
    background-color: black;
}

#myVideo:-moz-full-screen {
    background-color: black;
}

#myVideo:-ms-fullscreen {
    background-color: black;
}

#myVideo:fullscreen {
    background-color: black;
    display: flex;
    align-items: center;
    justify-content: center;
}

安全与权限控制

浏览器对全屏API有以下限制：

1. 用户交互要求：必须在用户触发的事件(如click)中调用
2. 权限策略：可通过HTTP头控制是否允许全屏
3. 跨域限制：iframe内容需要添加allowfullscreen属性
4. 视觉提示：浏览器通常会提供退出全屏的提示

最佳实践建议

1. 提供明确的UI控制：不要让用户猜测如何退出全屏
2. 处理Promise拒绝：全屏请求可能失败，需要适当处理
3. 考虑移动设备：移动端全屏行为可能与桌面不同
4. 优雅降级：为不支持全屏的浏览器提供替代方案
5. 用户引导：首次使用时给予适当提示

常见问题解答

Q: 为什么我的全屏请求不起作用？ A: 常见原因包括：未在用户交互事件中调用、被浏览器权限策略阻止、元素不可见或尺寸为零。

Q: 如何检测浏览器是否支持全屏API？ A: 检查document.fullscreenEnabled属性，同时注意不同浏览器的前缀差异。

Q: 全屏状态下如何保持元素比例？ A: 使用CSS的object-fit属性或通过JavaScript动态计算尺寸。

Q: 能否在页面加载时自动进入全屏？ A: 出于用户体验考虑，浏览器禁止自动全屏，必须由用户主动触发。

通过掌握Fullscreen API，开发者可以为用户创造更加沉浸式的网页体验，但同时也应尊重用户的选择权，提供清晰的控制方式和退出途径。