Fullscreen API
Element.requestFullscreen() 方法用于发出异步请求使元素进入全屏模式。
调用此方法并不能保证元素一定能够进入全屏模式。如果元素被允许进入全屏幕模式,返回的 Promise 会兑现,并且该元素会收到一个 Element/fullscreenchange_event 事件,通知它已经进入全屏模式。如果全屏请求被拒绝,返回的 promise 会被拒绝并且该元素会收到一个 Element/fullscreenerror_event 事件。如果该元素已经从原来的文档中分离,那么该文档将会收到这些事件。
语法
requestFullscreen()
requestFullscreen(options)
参数
options- : 控制全屏模式转换行为的对象。可用选项包括:
navigationUI- : 控制元素处于全屏模式时是否显示导航 UI。默认值为
"auto",表示浏览器应该决定要做什么。"hide"- : 浏览器的导航界面将被隐藏,并且整个屏幕尺寸将分配给显示元素。
"show"- : 浏览器将显示页面导航控件和可能的其他用户界面;元素的尺寸(以及感知的屏幕尺寸)将被限制以便为该用户界面留出空间。
"auto"- : 浏览器将选择应用上述哪种设置。这是默认值。
- : 控制元素处于全屏模式时是否显示导航 UI。默认值为
screen- : 指定要在哪个屏幕上将元素置于全屏模式。这需要代表所选屏幕的 ScreenDetailed 对象作为值。
- : 控制全屏模式转换行为的对象。可用选项包括:
返回值
一个 Promise,当全屏模式完成时,兑现 undefined。
异常
requestFullscreen() 通过拒绝返回的 Promise来生成错误条件,而不是抛出一个传统的异常。拒绝处理器接收以下的某一个值:
- TypeError
安全性
需要瞬态用户激活。用户必须与页面或 UI 元素进行交互才能使用此功能。
使用说明
兼容元素
你希望置于全屏模式的元素必须满足一些简单的要求:
- 它必须是标准 HTML 元素之一或 svg 或 math。
- 它不是 dialog 元素。
- 它必须位于顶级文档中或已应用
allowfullscreen属性的 iframe 元素。
此外,任何设置的权限策略都必须允许使用此特性。
检测全屏激活
你可以使用 requestFullscreen() 返回的 Promise 来确定切换到全屏模式的尝试是否成功,如下面的示例所示。
要了解其他代码何时打开和关闭全屏模式,你应该为 Document 上的 Document/fullscreenchange_event 事件创建监听器。监听 fullscreenchange 也很重要,例如,当用户手动切换全屏模式时,或者当用户切换应用程序时,导致应用程序暂时退出全屏模式。
示例
请求全屏模式
此函数可将文档中找到的第一个 video 元素切换为全屏模式或退出全屏模式。
function toggleFullscreen() {
let elem = document.querySelector("video");
if (!document.fullscreenElement) {
elem.requestFullscreen().catch((err) => {
alert(`尝试启用全屏模式时出错:${err.message}(${err.name})`);
});
} else {
document.exitFullscreen();
}
}
如果文档尚未处于全屏模式(通过查看 document.fullscreenElement 是否有值来检测),我们将调用视频的 requestFullscreen() 方法。如果成功,我们不需要做任何特殊的事情,但如果请求失败,我们的 promise 的 catch() 处理器会显示带有适当错误消息的警报。
另一方面,如果全屏模式已经生效,我们将调用 document.exitFullscreen() 来禁用全屏模式。
你可以在 Glitch 上查看此示例的实际操作或查看或重新混合代码。
使用 navigationUI
在此示例中,通过在文档的 Document.documentElement(即文档的根 html 元素)上调用 requestFullscreen(),将整个文档置于全屏模式。
let elem = document.documentElement;
elem
.requestFullscreen({ navigationUI: "show" })
.then(() => {})
.catch((err) => {
alert(`尝试切换到全屏模式时发生错误:${err.message}(${err.name})`);
});
promise 的解析处理器不执行任何操作,但如果 promise 被拒绝,则会通过调用 Window.alert 显示错误消息。
使用 screen 选项
如果你想让元素在主操作系统屏幕上全屏显示,你可以使用如下代码:
try {
const primaryScreen = (await getScreenDetails()).screens.find(
(screen) => screen.isPrimary,
);
await document.body.requestFullscreen({ screen: primaryScreen });
} catch (err) {
console.error(err.name, err.message);
}
Window.getScreenDetails() 方法用于检索当前设备的 ScreenDetails 对象,其中包含代表不同可用屏幕的 ScreenDetailed 对象。
规范
浏览器兼容性
参见
- 全屏 API
- Document.exitFullscreen()
- Document.fullscreen
- Document.fullscreenElement
- :fullscreen
allowfullscreen
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
