掌握这个API，让你的网页展示效果提升10倍

Hey, 我是沉浸式趣谈
本文首发于【沉浸式趣谈】，我的个人博客 https://yaolifeng.com 也同步更新。
转载请在文章开头注明出处和版权信息。
如果本文对您有所帮助，请点赞、评论、转发，支持一下，谢谢！

如何原生实现让任意 div 全屏展示

最近在做一个项目，需要实现点击按钮让某个 div 全屏展示的功能。

第一反应是用 CSS 设置 position: fixed 加上宽高 100%，但这样并不是真正的全屏，因为浏览器的工具栏还在。

后来发现浏览器原生就提供了 Fullscreen API，可以让任意元素真正全屏展示，今天就来聊聊这个有趣的 API。

基础用法：让元素全屏

先来看最简单的使用方式。假设我们有一个文章阅读器，想让用户能够专注阅读：

1<div id="reader">
2    <article>
3        <h1>一篇很棒的文章</h1>
4        <p>这是文章的正文内容...</p>
5    </article>
6    <button id="fullscreenBtn">
7        <span>进入阅读模式</span>
8        <svg viewBox="0 0 24 24" width="16" height="16">
9            <path d="M7 14H5v5h5v-2H7v-3zm-2-4h2V7h3V5H5v5zm12 7h-3v2h5v-5h-2v3zM14 5v2h3v3h2V5h-5z" />
10        </svg>
11    </button>
12</div>
13
14<script>
15    const reader = document.getElementById('reader');
16    const fullscreenBtn = document.getElementById('fullscreenBtn');
17
18    fullscreenBtn.addEventListener('click', () => {
19        // 请求全屏
20        reader.requestFullscreen().catch(err => {
21            console.log('全屏展示失败:', err);
22        });
23    });
24</script>
25
26<style>
27    #reader {
28        max-width: 800px;
29        margin: 0 auto;
30        padding: 20px;
31        background: #fff;
32    }
33
34    #fullscreenBtn {
35        display: flex;
36        align-items: center;
37        gap: 5px;
38        padding: 8px 16px;
39        border: none;
40        background: #f0f0f0;
41        cursor: pointer;
42        border-radius: 4px;
43    }
44
45    #fullscreenBtn:hover {
46        background: #e0e0e0;
47    }
48</style>

就这么简单！调用元素的 requestFullscreen() 方法就能让它全屏展示了。不过要注意，这是个异步操作，返回的是 Promise，所以最好加上 catch 来处理可能的错误。

退出全屏怎么搞？

有进就要有出。退出全屏的方法也很简单，但这里有个小坑：退出全屏的方法是在 document 上调用，而不是在元素上：

1// 错误示范 ❌
2reader.exitFullscreen();
3
4// 正确方式 ✅
5document.exitFullscreen().catch(err => {
6    console.log('退出全屏失败:', err);
7});

来看个完整的示例，实现全屏切换功能：

1<!DOCTYPE html>
2<html>
3    <head>
4        <title>阅读模式切换示例</title>
5        <style>
6            #reader {
7                max-width: 800px;
8                margin: 20px auto;
9                padding: 30px;
10                background: #fff;
11                box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
12            }
13
14            #reader.dark-mode {
15                background: #1a1a1a;
16                color: #fff;
17            }
18
19            #toggleBtn {
20                display: flex;
21                align-items: center;
22                gap: 5px;
23                padding: 8px 16px;
24                border: none;
25                background: #f0f0f0;
26                cursor: pointer;
27                border-radius: 4px;
28                margin: 20px 0;
29            }
30
31            #toggleBtn:hover {
32                background: #e0e0e0;
33            }
34
35            /* 全屏时的样式 */
36            #reader:fullscreen {
37                padding: 50px;
38                max-width: none;
39                box-shadow: none;
40            }
41
42            #reader:fullscreen #toggleBtn {
43                position: fixed;
44                top: 20px;
45                right: 20px;
46                background: rgba(240, 240, 240, 0.8);
47            }
48        </style>
49    </head>
50    <body>
51        <div id="reader">
52            <article>
53                <h1>深入理解 JavaScript 闭包</h1>
54                <p>闭包是 JavaScript 中最强大的特性之一，它允许函数访问其词法作用域之外的变量...</p>
55                <p
56                    >让我们通过一个简单的例子来理解闭包：当我们创建一个函数时，它不仅包含函数的代码，还包含对其周围作用域中变量的引用...</p
57                >
58                <p>这种特性使得我们可以创建私有变量、数据封装，以及实现模块化的代码结构...</p>
59            </article>
60
61            <button id="toggleBtn">
62                <span>切换阅读模式</span>
63                <svg viewBox="0 0 24 24" width="16" height="16">
64                    <path d="M7 14H5v5h5v-2H7v-3zm-2-4h2V7h3V5H5v5zm12 7h-3v2h5v-5h-2v3zM14 5v2h3v3h2V5h-5z" />
65                </svg>
66            </button>
67        </div>
68
69        <script>
70            const reader = document.getElementById('reader');
71            const toggleBtn = document.getElementById('toggleBtn');
72            const btnText = toggleBtn.querySelector('span');
73
74            toggleBtn.addEventListener('click', () => {
75                if (!document.fullscreenElement) {
76                    // 当前不是全屏，进入全屏
77                    reader
78                        .requestFullscreen()
79                        .then(() => {
80                            btnText.textContent = '退出阅读模式';
81                            reader.classList.add('dark-mode');
82                        })
83                        .catch(err => {
84                            console.log('进入全屏失败:', err);
85                        });
86                } else {
87                    // 当前是全屏，退出全屏
88                    document
89                        .exitFullscreen()
90                        .then(() => {
91                            btnText.textContent = '切换阅读模式';
92                            reader.classList.remove('dark-mode');
93                        })
94                        .catch(err => {
95                            console.log('退出全屏失败:', err);
96                        });
97                }
98            });
99        </script>
100    </body>
101</html>

全屏状态的监听和样式调整

有时候我们需要知道元素是否处于全屏状态，比如要在全屏时显示不同的 UI。浏览器提供了 fullscreenchange 事件来监听全屏状态的变化：

1document.addEventListener('fullscreenchange', () => {
2    if (document.fullscreenElement) {
3        console.log('进入全屏啦！');
4        console.log('全屏的元素是：', document.fullscreenElement);
5    } else {
6        console.log('退出全屏啦！');
7    }
8});

CSS 中也有专门的选择器 :fullscreen 来设置元素在全屏时的样式：

1#player {
2    background: #f0f0f0;
3    padding: 20px;
4}
5
6/* 全屏时的样式 */
7#player:fullscreen {
8    background: #000;
9    padding: 50px;
10}

实战示例：图片查看器

来做个实用的例子 —— 点击图片查看大图，再点击退出全屏：

1<!DOCTYPE html>
2<html>
3    <head>
4        <title>图片查看器</title>
5        <style>
6            .image-viewer {
7                cursor: pointer;
8                /* 使用 flex 布局让提示文字在图片下方 */
9                display: flex;
10                flex-direction: column;
11                align-items: center;
12                gap: 10px;
13            }
14
15            .image-viewer img {
16                max-width: 300px;
17                transition: transform 0.3s;
18            }
19
20            /* 提示文字样式 */
21            .image-viewer .hint {
22                color: #666;
23                font-size: 14px;
24                padding: 8px;
25                background: #f5f5f5;
26                border-radius: 4px;
27                display: flex;
28                align-items: center;
29                gap: 5px;
30            }
31
32            /* 添加一个小图标 */
33            .hint svg {
34                width: 16px;
35                height: 16px;
36                fill: #666;
37            }
38
39            .image-viewer:fullscreen {
40                background: rgba(0, 0, 0, 0.9);
41                display: flex;
42                align-items: center;
43                justify-content: center;
44            }
45
46            .image-viewer:fullscreen img {
47                max-width: 90vw;
48                max-height: 90vh;
49                object-fit: contain;
50            }
51
52            /* 全屏时隐藏提示文字 */
53            .image-viewer:fullscreen .hint {
54                display: none;
55            }
56        </style>
57    </head>
58    <body>
59        <div class="image-viewer" id="imageViewer">
60            <img src="your-image.jpg" alt="示例图片" />
61            <div class="hint">
62                <svg viewBox="0 0 24 24">
63                    <path d="M7 14H5v5h5v-2H7v-3zm-2-4h2V7h3V5H5v5zm12 7h-3v2h5v-5h-2v3zM14 5v2h3v3h2V5h-5z" />
64                </svg>
65                <span>点击图片可全屏查看</span>
66            </div>
67        </div>
68
69        <script>
70            const imageViewer = document.getElementById('imageViewer');
71
72            imageViewer.addEventListener('click', e => {
73                // 如果点击的是提示文字，不触发全屏
74                if (e.target.closest('.hint')) return;
75
76                if (!document.fullscreenElement) {
77                    imageViewer.requestFullscreen().catch(err => {
78                        console.log('进入全屏失败:', err);
79                    });
80                } else {
81                    document.exitFullscreen().catch(err => {
82                        console.log('退出全屏失败:', err);
83                    });
84                }
85            });
86        </script>
87    </body>
88</html>

浏览器兼容性处理

虽然现代浏览器都支持 Fullscreen API，但有些老浏览器可能需要加前缀。这里提供一个兼容性更好的封装：

1function requestFullscreen(element) {
2    const requestMethod =
3        element.requestFullscreen ||
4        element.webkitRequestFullscreen || // Chrome, Safari
5        element.mozRequestFullScreen || // Firefox
6        element.msRequestFullscreen; // IE/Edge
7
8    if (requestMethod) {
9        return requestMethod.call(element);
10    }
11
12    return Promise.reject('当前浏览器不支持全屏 API');
13}
14
15function exitFullscreen() {
16    const exitMethod =
17        document.exitFullscreen ||
18        document.webkitExitFullscreen ||
19        document.mozCancelFullScreen ||
20        document.msExitFullscreen;
21
22    if (exitMethod) {
23        return exitMethod.call(document);
24    }
25
26    return Promise.reject('当前浏览器不支持全屏 API');
27}
28
29// 判断是否支持全屏
30function isFullscreenEnabled() {
31    return (
32        document.fullscreenEnabled ||
33        document.webkitFullscreenEnabled ||
34        document.mozFullScreenEnabled ||
35        document.msFullscreenEnabled
36    );
37}
38
39// 获取当前全屏元素
40function getFullscreenElement() {
41    return (
42        document.fullscreenElement ||
43        document.webkitFullscreenElement ||
44        document.mozFullScreenElement ||
45        document.msFullscreenElement
46    );
47}

使用封装后的方法：

1const myElement = document.getElementById('myElement');
2
3// 检查是否支持全屏
4if (!isFullscreenEnabled()) {
5    console.log('抱歉，您的浏览器不支持全屏功能');
6    return;
7}
8
9// 进入全屏
10requestFullscreen(myElement).catch(err => {
11    console.log('进入全屏失败:', err);
12});
13
14// 退出全屏
15exitFullscreen().catch(err => {
16    console.log('退出全屏失败:', err);
17});

一些注意事项

全屏请求必须由用户触发 浏览器出于安全考虑，requestFullscreen() 必须由用户操作触发（如点击事件），不能在页面加载时自动触发。
iframe 的全屏限制 如果要在 iframe 中使用全屏功能，需要给 iframe 添加 allowfullscreen 属性：
```
1<iframe src="page.html" allowfullscreen></iframe>
```
全屏元素的样式 进入全屏后，元素默认会占满整个屏幕。如果想保持原有布局，需要自己设置合适的样式。
键盘事件 在全屏模式下，某些键盘快捷键可能会被浏览器接管（如 ESC 退出全屏），要注意这一点。

总结

Fullscreen API 虽然看起来简单，但用好了真的很强大。关键点：

element.requestFullscreen() 进入全屏
document.exitFullscreen() 退出全屏
fullscreenchange 事件监听状态变化
:fullscreen 选择器设置全屏样式
注意浏览器兼容性处理

希望这篇文章对你有帮助！如果觉得不错，别忘了点个赞 👍