MDN Web API 全屏模式指南：深入理解 Fullscreen API

什么是 Fullscreen API？

Fullscreen API 是现代浏览器提供的一组 JavaScript 接口，允许开发者将任意 HTML 元素（如视频、游戏画布或整个页面）切换到全屏显示模式。这种技术广泛应用于视频播放、网页游戏和富媒体应用中，为用户提供沉浸式的浏览体验。

核心概念解析

全屏模式的特点

当元素进入全屏模式时，浏览器会：

1. 自动填充整个屏幕空间
2. 隐藏浏览器界面元素（如地址栏、标签页等）
3. 将该元素置于浏览器视图的最顶层
4. 应用特殊的 :fullscreen CSS 伪类样式

兼容性考虑

虽然现代浏览器普遍支持 Fullscreen API，但不同浏览器可能存在前缀差异。在实际开发中，我们需要做好兼容性处理。

如何使用 Fullscreen API

1. 进入全屏模式

要将元素设为全屏，只需调用其 requestFullscreen() 方法：

const videoElement = document.getElementById('my-video');

if (videoElement.requestFullscreen) {
    videoElement.requestFullscreen().catch(err => {
        console.error(`全屏请求失败: ${err.message}`);
    });
}

最佳实践提示：

• 始终检查方法是否存在
• 处理可能的 Promise 拒绝
• 在用户交互事件（如点击）中触发全屏请求

2. 退出全屏模式

退出全屏有两种方式：

1. 用户手动按 Esc 键或 F11 键
2. 程序调用 document.exitFullscreen()

if (document.exitFullscreen) {
    document.exitFullscreen();
}

3. 全屏状态检测

通过以下属性可以检测当前全屏状态：

// 检查是否支持全屏
const isFullscreenSupported = document.fullscreenEnabled;

// 获取当前全屏元素
const fullscreenElement = document.fullscreenElement;

全屏事件处理

Fullscreen API 提供了两个重要事件：

1. fullscreenchange - 当进入或退出全屏时触发
2. fullscreenerror - 当全屏请求失败时触发

示例代码：

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

document.addEventListener('fullscreenerror', (e) => {
    console.error('全屏模式切换失败:', e);
});

特殊场景处理

iframe 中的全屏

要使 iframe 内容能够全屏显示，必须添加 allowfullscreen 属性：

<iframe src="..." allowfullscreen></iframe>

移动端注意事项

在移动设备上：

• 全屏模式可能禁用缩放功能
• 某些浏览器会隐藏状态栏
• 横竖屏切换行为可能不同

用户体验优化建议

1. 明确提示：告知用户可以通过 Esc 键退出全屏
2. 优雅降级：在不支持全屏的环境下提供替代方案
3. 样式适配：利用 :fullscreen 伪类优化全屏样式
4. 状态同步：在全屏变化时更新界面状态

常见问题解答

Q: 为什么我的全屏请求被拒绝了？ A: 可能原因包括：

• 未在用户交互事件中触发
• 元素或其父元素不允许全屏
• 浏览器安全限制

Q: 如何检测浏览器是否支持全屏API？ A: 检查 document.fullscreenEnabled 属性

Q: 多个元素可以同时全屏吗？ A: 可以，但会形成堆叠，只有最上层元素可见

总结

Fullscreen API 为网页应用提供了强大的全屏展示能力。通过合理使用这一API，开发者可以创建更具沉浸感的用户体验。记住要始终考虑兼容性和用户控制权，确保功能在各种环境下都能良好工作。

在实际项目中，建议结合具体需求设计全屏交互流程，并充分测试不同设备和浏览器的表现，以确保最佳的用户体验。