Element: requestFullscreen() 方法
Element.requestFullscreen() 方法發出非同步請求，使元素以全屏模式顯示。
不能保證元素將進入全屏模式。如果允許進入全屏模式，返回的 Promise 將解析，元素將收到 fullscreenchange 事件，告知它現在已處於全屏模式。如果拒絕許可，Promise 將被拒絕，元素將收到 fullscreenerror 事件。如果元素已從原始文件中分離，則文件將收到這些事件。
語法
requestFullscreen()
requestFullscreen(options)
引數
options可選-
一個控制全屏模式轉換行為的物件。可用的選項有：
-
控制元素在全屏模式下是否顯示導航 UI。預設值為
"auto"，表示瀏覽器應自行決定。 screen可選 實驗性-
指定要將元素置於全屏模式的螢幕。這接受一個
ScreenDetailed物件作為值，表示所選螢幕。
-
返回值
一個 Promise，在完成全屏轉換時以 undefined 值解析。
異常
requestFullscreen() 過程透過拒絕其返回的 Promise 來宣佈錯誤情況，而不是丟擲傳統異常。拒絕處理程式接收以下異常值之一：
TypeError-
TypeError異常可能在以下任何情況下發生：- 包含元素的文件未完全啟用；也就是說，它不是當前活動的文件。
- 元素不包含在文件中。
- 元素不允許使用
fullscreen功能，無論是由於 許可權策略 配置還是其他訪問控制功能。 - 元素及其文件是同一個節點。
- 元素是一個 彈出視窗，已經透過
HTMLElement.showPopover()顯示。
安全
需要瞬時使用者啟用。使用者必須與頁面或 UI 元素進行互動才能使此功能正常工作。
用法說明
相容元素
您希望置於全屏模式的元素必須滿足少數幾個簡單要求：
- 它必須是標準 HTML 元素之一，或者是
<svg>或<math>。 - 它不是
<dialog>元素。 - 它必須位於頂級文件中，或位於已應用
allowfullscreen屬性的<iframe>中。
此外，任何設定的許可權策略都必須允許使用此功能。
檢測全屏啟用
您可以透過使用 requestFullscreen() 返回的 Promise 來確定您嘗試切換到全屏模式是否成功，如下面的示例所示。
要了解何時其他程式碼已切換全屏模式的開啟和關閉，您應該在 Document 上為 fullscreenchange 事件建立監聽器。監聽 fullscreenchange 也很重要，以便在使用者手動切換全屏模式或使用者切換應用程式導致您的應用程式暫時退出全屏模式時瞭解情況。
示例
請求全屏模式
此示例在按下 Enter 或 Shift + F 鍵時，將 <video> 元素切換進出全屏模式。指令碼使用 document.fullscreenElement 檢查文件當前是否處於全屏狀態。如果文件處於全屏狀態，它會呼叫 document.exitFullscreen() 退出。否則，它會在 <video> 元素上呼叫 requestFullscreen()。
const video = document.querySelector("video");
document.addEventListener("keydown", (event) => {
// Note that "F" is case-sensitive (uppercase):
if (event.key === "Enter" || event.key === "F") {
// Check if we're in fullscreen mode
if (document.fullscreenElement) {
document.exitFullscreen();
return;
}
// Otherwise enter fullscreen mode
video.requestFullscreen().catch((err) => {
console.error(`Error enabling fullscreen: ${err.message}`);
});
}
});
<p>
The video element below shows a time-lapse of a flower blooming. You can
toggle fullscreen on and off using <kbd>Enter</kbd> or <kbd>Shift</kbd> +
<kbd>F</kbd> (uppercase "F"). The embedded document needs to have
<a
href="https://mdn.club.tw/en-US/docs/Web/API/Element/focus_event">
focus
</a>
for the example to work.
</p>
<video controls loop src="/shared-assets/videos/flower.mp4" width="420"></video>
使用 navigationUI
在此示例中，透過在文件的 Document.documentElement（即文件的根 <html> 元素）上呼叫 requestFullscreen()，將整個文件置於全屏模式。
let elem = document.documentElement;
elem
.requestFullscreen({ navigationUI: "show" })
.then(() => {})
.catch((err) => {
alert(
`An error occurred while trying to switch into fullscreen mode: ${err.message} (${err.name})`,
);
});
Promise 的解析處理程式不執行任何操作，但如果 Promise 被拒絕，則透過呼叫 alert() 顯示錯誤訊息。
使用螢幕選項
如果您想在主作業系統螢幕上全屏顯示元素，可以使用以下程式碼：
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 物件。
規範
| 規範 |
|---|
| Fullscreen API # ref-for-dom-element-requestfullscreen① |
瀏覽器相容性
載入中…