全屏状态检测：screenfull.isFullscreen与element属性应用
项目地址: https://gitcode.com/gh_mirrors/sc/screenfull 你是否曾遇到过网页全屏功能失效却找不到原因？或者需要在用户进入全屏时展示特定内容，退出时恢复默认状态？screenfull.js 库提供的 isFullscreen 属性和 element 属性正是解决这些问题的关键工具。本文将通过实际场景案例，详细讲解如何利用这两个属性实现精准的全屏状态管理，让你轻松掌握全屏交互的核心技术点。
核心属性解析
screenfull.js 作为 JavaScript Fullscreen API 的跨浏览器封装库，提供了两个核心属性用于状态检测：
isFullscreen：布尔值属性，直接返回当前是否处于全屏状态element：对象属性，返回当前处于全屏状态的 DOM 元素（若未全屏则返回undefined）
这两个属性在 index.js 中通过 Object.defineProperties 定义，代码如下：
Object.defineProperties(screenfull, {
isFullscreen: {
get: () => Boolean(document[nativeAPI.fullscreenElement]),
},
element: {
enumerable: true,
get: () => document[nativeAPI.fullscreenElement] ?? undefined,
},
// ...其他属性
});
基础检测实现
状态显示功能
在 index.html 的演示页面中，通过以下代码实时展示全屏状态：
function fullscreenchange() {
$('#status').text(`Is fullscreen: ${screenfull.isFullscreen}`);
if (element) {
$('#element').text(`Element: ${element.localName}${element.id ? `#${element.id}` : ''}`);
}
}
// 初始化状态显示
fullscreenchange();
// 监听全屏变化事件
screenfull.on('change', fullscreenchange);
这段代码实现了两个关键功能：页面加载时显示初始状态，以及在全屏状态变化时自动更新显示内容。
实际效果展示
在演示页面中，这两个属性的检测结果会显示在状态面板中：
<ul>
<li id="supported"></li>
<li id="status"></li> <!-- 显示 isFullscreen 状态 -->
<li id="element"></li> <!-- 显示当前全屏元素 -->
</ul>
当用户点击 "Toggle" 按钮切换全屏状态时，这两个值会实时更新，帮助开发者直观了解当前全屏状态。
高级应用场景
全屏状态条件执行
利用 isFullscreen 属性可以实现在全屏状态变化时执行特定逻辑。例如在退出全屏时清理资源或恢复页面状态：
$('#exit').click(async () => {
await screenfull.exit();
if (!screenfull.isFullscreen) {
// 退出全屏后的清理工作
console.log('Browser exited fullscreen mode');
// 恢复页面滚动
document.body.style.overflow = 'auto';
// 移除可能添加的全屏专用元素
$('#external-iframe').remove();
}
});
元素级全屏控制
element 属性允许我们精确控制哪个元素进入全屏状态，这在视频播放器、图片查看器等场景中非常有用：
// 图片点击全屏功能
$('#demo-img').click(() => {
screenfull.toggle($('#demo-img')[0]);
// 检查当前全屏元素
if (screenfull.isFullscreen && screenfull.element === $('#demo-img')[0]) {
console.log('图片已进入全屏模式');
// 可以在这里添加图片全屏专属控制逻辑
}
});
多元素全屏管理
当页面中有多个可全屏元素时，可以通过 element 属性判断当前哪个元素处于全屏状态，从而执行针对性操作：
if (screenfull.isFullscreen) {
const currentElement = screenfull.element;
if (currentElement.id === 'video-player') {
// 视频元素全屏时的特殊处理
showVideoControls();
} else if (currentElement.id === 'image-viewer') {
// 图片查看器全屏时的特殊处理
hideImageOverlays();
}
}
常见问题解决方案
跨浏览器兼容性
screenfull.js 已经处理了不同浏览器的前缀差异，通过 index.js 中的 methodMap 数组映射不同浏览器的 API：
const methodMap = [
[
'requestFullscreen',
'exitFullscreen',
'fullscreenElement', // 标准属性
'fullscreenEnabled',
'fullscreenchange',
'fullscreenerror',
],
// WebKit 浏览器前缀版本
[
'webkitRequestFullscreen',
'webkitExitFullscreen',
'webkitFullscreenElement', // WebKit 前缀属性
// ...
],
// ...其他浏览器前缀
];
权限检查
在使用全屏功能前，应先检查浏览器是否支持并允许全屏操作：
if (!screenfull.isEnabled) {
alert('全屏功能在当前浏览器中不受支持或被禁用');
return;
}
// 安全的全屏操作
try {
await screenfull.toggle(element);
} catch (err) {
console.error('全屏操作失败:', err);
}
完整应用示例
以下是一个综合运用 isFullscreen 和 element 属性的完整示例，实现了带状态反馈的全屏切换功能：
// 切换全屏并记录日志
$('#toggle').click(async () => {
const element = $('#container')[0];
await screenfull.toggle(element);
if (screenfull.isFullscreen) {
console.log(`已进入全屏模式，当前元素: ${screenfull.element.id}`);
// 全屏状态下的UI调整
element.style.backgroundColor = '#000';
} else {
console.log('已退出全屏模式');
// 恢复正常状态
element.style.backgroundColor = '';
}
});
这个示例展示了如何结合使用两个属性，实现完整的全屏状态管理逻辑。
最佳实践总结
- 状态监听优先：始终通过
change事件监听全屏状态变化，而非仅依赖用户操作触发 - 操作前检查：执行全屏操作前检查
isEnabled属性，确保浏览器支持 - 错误处理：使用 try/catch 包裹全屏操作，处理可能的异常情况
- 元素验证：通过
element属性验证实际全屏元素，避免多元素冲突 - 资源管理：在退出全屏时清理专用资源，恢复页面原始状态
通过合理运用 isFullscreen 和 element 属性，你可以构建出健壮、用户友好的全屏交互体验，满足视频播放、图片浏览、演示文稿等多种场景需求。更多高级用法可以参考项目的 index.html 演示页面和 index.js 源代码。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
