深入理解浏览器全屏 API：从 requestFullscreen 到全屏实战

前言

当我们在视频网站点 "全屏" 看电影、在数据大屏上看报表、在演示 PPT 里一键投屏，背后其实都是浏览器原生提供的 Fullscreen API（全屏 API）。它允许我们让任意一个元素（甚至整个页面）占据整个屏幕，无需任何插件。

你贴的这段代码正是全屏 API 最基础的用法：

复制代码

<button id="quan">全屏</button>
<button id="bbuq">不全屏</button>
<script>
    $('#quan').click(function () {
        document.documentElement.requestFullscreen(); // 让整个页面进入全屏
    })
    $('#bbuq').click(function () {
        document.exitFullscreen(); // 退出全屏
    })
</script>

短短几行就实现了全屏 / 退出全屏，但真实的项目里往往需要处理兼容性、事件监听、错误处理。这篇博客带你从入门到实战，把全屏 API 一次讲透。

一、全屏 API 核心三件套

1. 进入全屏：`element.requestFullscreen()`

作用：让调用它的元素进入全屏状态。

复制代码

// 让整个页面全屏
document.documentElement.requestFullscreen();

// 让指定元素全屏（比如一个视频容器）
document.getElementById('videoBox').requestFullscreen();

📌 谐音读法记忆 ：request 谐音 "瑞快斯特"（请求），合起来就是 "请求全屏"，请求成功则全屏。

2. 退出全屏：`document.exitFullscreen()`

作用：退出全屏状态，必须挂在 document 上（因为全屏状态属于整个文档）。

复制代码

document.exitFullscreen();

3. 切换全屏：自己封装 toggle

API 没有直接提供 "切换" 方法，需要结合属性判断：

复制代码

function toggleFullscreen() {
    if (document.fullscreenElement) {
        document.exitFullscreen();
    } else {
        document.documentElement.requestFullscreen();
    }
}

二、两个常用属性

表格

属性	作用	返回值
`document.fullscreenElement`	当前处于全屏的元素	有则返回该元素，无则返回 `null`
`document.fullscreenEnabled`	当前环境是否支持全屏	`true` / `false`

实战中常用来判断状态 和按钮文字切换：

复制代码

// 用 document.fullscreenElement 判断是否全屏
if (document.fullscreenElement) {
    console.log('当前在全屏状态');
} else {
    console.log('当前不在全屏状态');
}

三、全屏事件监听

1. `fullscreenchange` ------ 全屏状态变化时触发

当进入或退出全屏时都会触发，是做 UI 联动（比如切换按钮文案、显示 "按 Esc 退出" 提示）的关键：

复制代码

document.addEventListener('fullscreenchange', function () {
    if (document.fullscreenElement) {
        console.log('进入全屏');
        $('#quan').text('退出全屏');
    } else {
        console.log('退出全屏');
        $('#quan').text('全屏');
    }
});

2. `fullscreenerror` ------ 全屏请求失败时触发

比如被用户手势限制、iframe 没有 allowfullscreen 属性等：

复制代码

document.addEventListener('fullscreenerror', function () {
    console.error('全屏请求失败');
});

四、兼容性处理：旧浏览器前缀

全屏 API 是相对较新的规范，老版本的 Chrome、Firefox、Safari 需要加前缀（webkit、moz、ms）。生产环境建议封装一个兼容函数：

复制代码

function requestFullscreen(el) {
    el = el || document.documentElement;
    if (el.requestFullscreen) {
        el.requestFullscreen();
    } else if (el.webkitRequestFullscreen) { // Chrome / Safari 旧版
        el.webkitRequestFullscreen();
    } else if (el.msRequestFullscreen) {      // IE
        el.msRequestFullscreen();
    }
}

function exitFullscreen() {
    if (document.exitFullscreen) {
        document.exitFullscreen();
    } else if (document.webkitExitFullscreen) {
        document.webkitExitFullscreen();
    } else if (document.msExitFullscreen) {
        document.msExitFullscreen();
    }
}

对应的属性和事件也要带前缀：

复制代码

var isFull = document.fullscreenElement
          || document.webkitFullscreenElement
          || document.msFullscreenElement;

五、进阶：指定元素全屏（以视频为例）

全屏 API 最常见的应用是视频全屏：

复制代码

<video id="myVideo" controls src="./movie.mp4"></video>
<button id="videoFull">视频全屏</button>

<script>
    $('#videoFull').click(function () {
        var video = document.getElementById('myVideo');
        if (video.requestFullscreen) {
            video.requestFullscreen(); // 只让视频元素全屏
        }
    });
</script>

注意：让某个局部元素全屏时，全屏画面只显示该元素，其余部分不可见。这也是做 "大屏看板单模块放大" 功能的核心思路。

六、容易踩的坑（重点）

必须由用户手势触发 ：requestFullscreen() 必须在点击 / 键盘等用户操作的回调里调用，否则浏览器会拒绝并触发 fullscreenerror。异步延时（如 setTimeout）后调用也会失败。
Esc 键可直接退出全屏 ：用户按 Esc 或 F11，浏览器会自动退出，此时会触发 fullscreenchange，所以状态一定要靠事件同步，不能只靠点击逻辑。
iframe 全屏限制 ：父页面内嵌的 iframe 默认不能进入全屏，需要给 iframe 加 allow="fullscreen" 属性。
全屏样式用 :fullscreen 伪类：元素进入全屏后可以单独设置样式，全屏时撑满、非全屏时恢复正常：

#videoBox:fullscreen {
width: 100vw;
height: 100vh;
background: #000;
}
/* 旧前缀写法 */
#videoBox:-webkit-full-screen {
width: 100vw;
height: 100vh;
}
全屏元素是 "画布" 不是 "弹层"：全屏会把整个屏幕铺满，底层页面内容不可见，不要指望它像弹窗一样悬浮。

七、完整实战：带状态同步的全屏按钮

把上面的知识点整合成一段可直接运行的完整代码（兼容 jQuery 写法）：

复制代码

<!DOCTYPE html>
<html lang="zh">
<head>
    <meta charset="UTF-8">
    <title>全屏实战 Demo</title>
    <script src="./jquery-3.7.1.min.js"></script>
    <style>
        #content {
            width: 800px;
            height: 500px;
            background: #f5f5f5;
            text-align: center;
            line-height: 500px;
            font-size: 24px;
        }
        #content:fullscreen {
            background: #2c3e50;
            color: #fff;
            width: 100vw;
            height: 100vh;
        }
    </style>
</head>
<body>
    <div id="content">全屏内容区域</div>
    <button id="toggleBtn">全屏</button>

    <script>
        // 切换全屏
        function toggleFullscreen() {
            if (document.fullscreenElement) {
                document.exitFullscreen();
            } else {
                document.documentElement.requestFullscreen();
            }
        }

        // 点击切换（兼容性写法）
        $('#toggleBtn').click(function () {
            var el = document.documentElement;
            if (el.requestFullscreen) {
                toggleFullscreen();
            } else if (el.webkitRequestFullscreen) {
                el.webkitRequestFullscreen();
            } else if (el.msRequestFullscreen) {
                el.msRequestFullscreen();
            }
        });

        // 监听状态变化，同步按钮文字
        document.addEventListener('fullscreenchange', function () {
            if (document.fullscreenElement) {
                $('#toggleBtn').text('退出全屏');
            } else {
                $('#toggleBtn').text('全屏');
            }
        });
    </script>
</body>
</html>

八、总结

全屏 API 的核心其实就三点：

进入：element.requestFullscreen()
退出：document.exitFullscreen()
状态：document.fullscreenElement + fullscreenchange 事件

配上兼容前缀处理、用户手势触发、:fullscreen 样式，就能在视频播放、数据大屏、在线演示、游戏页面等场景做出丝滑的全屏体验。

你贴的那段代码已经是最精简的入门写法，把它升级成带事件监听和兼容处理的版本，就是一份可以直接用于项目的全屏模块了。

深入理解浏览器全屏 API：从 requestFullscreen 到全屏实战

前言

一、全屏 API 核心三件套

1. 进入全屏：element.requestFullscreen()

2. 退出全屏：document.exitFullscreen()

3. 切换全屏：自己封装 toggle

二、两个常用属性

三、全屏事件监听

1. fullscreenchange ------ 全屏状态变化时触发

2. fullscreenerror ------ 全屏请求失败时触发

四、兼容性处理：旧浏览器前缀

五、进阶：指定元素全屏（以视频为例）

六、容易踩的坑（重点）

七、完整实战：带状态同步的全屏按钮

八、总结

1. 进入全屏：`element.requestFullscreen()`

2. 退出全屏：`document.exitFullscreen()`

1. `fullscreenchange` ------ 全屏状态变化时触发

2. `fullscreenerror` ------ 全屏请求失败时触发