HTML5 全屏浏览器兼容方案

原创

除除

发布于 2025-12-01 13:56:54

1650

文章被收录于专栏：除除的专栏除除的专栏

内容声明

本文仅用于技术分享和学习交流，内容不包含任何广告、推广、引流、付费课程或外链信息。所有示例和配置均为技术实践，欢迎参考和自定义。

本文介绍了 HTML5 全屏 API 的使用方法，包括 requestFullscreen() 和 exitFullscreen() 的调用方式及注意事项，提供了浏览器兼容性处理方案，并通过代码示例演示了全屏请求与退出的实现，适配主流浏览器的不同方法。

背景

最近一个项目有页面全屏的的需求，搜索了下有 HTML5 的全屏 API 可用，不过各浏览器的支持不一样。

Standard	Webkit	Firefox	IE
Element.requestFullscreen()	webkitRequestFullscreen	mozRequestFullScreen	msRequestFullscreen
Document.exitFullscreen()	webkitExitFullscreen	mozCancelFullScreen	msExitFullscreen
Document.fullscreenElement	webkitFullscreenElement	mozFullScreenElement	msFullscreenElement
Document.fullscreenEnabled	webkitFullscreenEnabled	mozFullScreenEnabled	msFullscreenEnabled
Document.fullscreenchange	webkitfullscreenchange	mozfullscreenchange	MSFullscreenChange
Document.fullscreenerror	webkitfullscreenerror	mozfullscreenerror	MSFullscreenError

MDN Fullscreen API: The Fullscreen API provides an easy way for web content to be presented using the user's entire screen. The API lets you easily direct the browser to make an element and its children, if any, occupy the fullscreen, eliminating all browser user interface and other applications from the screen for the duration.

全屏接口提供了简单的方式通过用户整个屏幕展示浏览器的内容。这个接口让开发者很轻松的引导浏览器使一个元素和他的子元素占据整个屏幕，并且从屏幕上消除所有浏览器用户界面和其他应用程序。

接口使用 (以谷歌浏览器为例)

requestFullscreen()

全屏请求方法，使用方法: Element.requestFullscreen()。

<div id="example">
    <img src="html5.png">
    <button type="button" id="requestFullscreen">requestFullscreen</button>
</div>

<script>
// 全屏
document.getElementById('requestFullscreen').addEventListener('click', () => {
    document.querySelector('img').webkitRequestFullscreen();
});
</script>

触发事件后会有按 ESC 即可退出全屏模式的文字提示。

注意:

MDN Element.requestFullscreen(): Only elements which are in the HTML namespace (that is, elements which are standard HTML), plus the <svg> and <math> elements, which are located in the top-level document or in an <iframe> with the allowfullscreen attribute can be displayed full-screen. This means that elements inside a <frame> or an <object> can't.Only elements which are in the HTML namespace (that is, elements which are standard HTML), plus the <svg> and <math> elements, which are located in the top-level document or in an <iframe> with the allowfullscreen attribute can be displayed full-screen. This means that elements inside a <frame> or an <object> can't.

在 <iframe> 框架中使用全屏需要加 allowfullscreen 属性。
全屏请求只能通过用户操作触发，否则会出现 Failed to execute 'requestFullscreen' on 'Element': API can only be initiated by a user gesture. 这样的警告，解决办法是将此方法绑定到某个用户操作事件上，例如点击事件 click。

(function () {
    document.documentElement.webkitRequestFullscreen();
})();

exitFullscreen()

退出全屏模式的方法，使用方法: document.exitFullscreen()，除了 requestFullscreen() 其他方法和属性都是基于 document 的。

<div id="example">
    <img src="html5.png">
    <button type="button" id="requestFullscreen">requestFullscreen</button>
    <button type="button" id="exitFullscreen">exitFullscreen</button>
</div>

<script>
// 退出全屏
document.getElementById('exitFullscreen').addEventListener('click', () => {
    document.webkitExitFullscreen();
});
</script>

触发后退出全屏恢复页面原来的样子，也可以按 ESC 退出；另外 F11 也可以使页面全屏显示和退出，但这应该属于浏览器的功能，不在 HTML5 API 的范畴之内。

fullscreenElement

若是全屏模式下，显示全屏的元素，若不是，返回 null。

<div id="example">
    <img src="html5.png">
    <button type="button" id="requestFullscreen">requestFullscreen</button>
    <button type="button" id="exitFullscreen">exitFullscreen</button>
    <button type="button" id="fullscreenElement">fullscreenElement</button>
</div>

<script>
// 显示全屏元素
document.getElementById('fullscreenElement').addEventListener('click', () => {
    console.log(document.webkitFullscreenElement); // <div id=...></div> 或 null
});
</script>

fullscreenEnabled

返回一个布尔值 true/false，判断是否可用全屏模式。

<div id="example">
    <img src="html5.png">
    <button type="button" id="fullscreenEnabled">fullscreenEnabled</button>
</div>

<script>
// 全屏是否可用
document.getElementById('fullscreenEnabled').addEventListener('click', () => {
    console.log(document.webkitFullscreenEnabled); // true
});
</script>

浏览器兼容

由于各主流浏览器调用全屏接口的方法不一致，所以调用之前需要判断一下当前浏览器适用的方法。

简单的做了下请求全屏和退出全屏的适配。

const MAZEY_FULL_SCREEN = function () {
    let prefixArr = ['', 'webkit', 'moz', 'ms'], // 浏览器前缀
        isRightRequest, // 是否找到适配的方法
        isRightExit,
        requestMethod, // 全屏方法
        exitMethod, // 退出全屏方法
        lowerFirst = function (str) {
            return str.slice(0, 1).toLowerCase() + str.slice(1);
        },
        requestSuffixArr = ['RequestFullscreen', 'RequestFullScreen'], // 后缀
        exitSuffixArr = ['ExitFullscreen', 'CancelFullScreen'],
        searchRightMethod = function (prefix, suffixArr, documentParent) {
            let methodArr = suffixArr.map((suffix) => {
                return prefix + suffix;
            }),
            method,
            isRight;
            methodArr.forEach((wholePrefix) => {
                if (isRight) return;
                if (prefix.length === 0) {
                    wholePrefix = lowerFirst(wholePrefix)
                }
                if (wholePrefix in documentParent) {
                    method = wholePrefix;
                    isRight = true;
                    // console.log(method);
                }
            });
            return method;
        };
    prefixArr.forEach((prefix) => {
        if (isRightRequest && isRightExit) return;
        // 查找请求
        requestMethod = searchRightMethod(prefix, requestSuffixArr, document.documentElement);
        isRightRequest = Boolean(requestMethod);
        // 查找退出
        exitMethod = searchRightMethod(prefix, exitSuffixArr, document);
        isRightExit = Boolean(exitMethod);
    });
    this.request = function (element) {
        let domEle = document.querySelector(element) || document.documentElement;
        domEle[requestMethod]();
    };
    this.exit = function () {
        document[exitMethod]();
    };
};

let fullscreen = new MAZEY_FULL_SCREEN();

使用示例:

<h1 id="h1">html5 - 全屏</h1>
<button id="request">请求</button>
<button id="exit">退出</button>
<script src="mazey-full-screen.js"></script>

<script>
// 请求全屏
document.getElementById('request').addEventListener('click', () => {
    fullscreen.request();
});
// 退出全屏
document.getElementById('exit').addEventListener('click', () => {
    fullscreen.exit();
});
</script>

更新记录

本文首次编辑于 2018-01-02，最近更新于 2025-11-26。

本文为原创文章，作者保留版权。转载请保留本文完整内容，并以超链接形式注明作者及原文出处。

作者: 除除

原文: http://blog.mazey.net/799.html

(完)

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

html5