全屏 API 指南

啟用全屏模式

對於您希望以全屏模式顯示的元素（例如 <video> 元素），您可以透過呼叫其 requestFullscreen() 方法將其置於全屏模式。

讓我們考慮這個 <video> 元素

<video controls id="my-video">
  <source src="somevideo.webm" />
  <source src="somevideo.mp4" />
</video>

我們可以如下將該影片置於全屏模式：

const elem = document.getElementById("my-video");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}

此程式碼在呼叫 requestFullscreen() 方法之前會檢查該方法的存在性。

一旦元素進入全屏模式，它就會被 :fullscreen 匹配，這會為其提供一些預設樣式，例如佔據整個螢幕。它還會被放置在頂層。

如果同時請求多個元素進入全屏模式，它們都會被 :fullscreen 匹配，並都位於頂層。它們會堆疊在一起，最近請求的元素會覆蓋較舊的元素。最近請求的元素會被顯示，並且可以透過 Document.fullscreenElement 獲取。

Notification

當全屏模式成功啟用時，包含該元素的文件會接收一個 fullscreenchange 事件。當退出全屏模式時，文件會再次接收一個 fullscreenchange 事件。請注意，fullscreenchange 事件本身不會提供有關文件是進入還是退出全屏模式的任何資訊，但如果文件具有非空的 fullscreenElement，您就知道它處於全屏模式。

全屏請求失敗時

不能保證您能夠切換到全屏模式。例如，<iframe> 元素需要設定 allowfullscreen 屬性才能選擇允許其內容顯示在全屏模式下。此外，某些型別的內容，例如視窗化外掛，無法以全屏模式顯示。嘗試將無法以全屏模式顯示（或此類元素的父元素或子元素）的元素置於全屏模式將不起作用。相反，請求全屏的元素將接收一個 fullscreenerror 事件。當全屏請求失敗時，Firefox 會在 Web 控制檯中記錄一條錯誤訊息，解釋請求失敗的原因。然而，在 Chrome 和較新版本的 Opera 中，不會生成此類警告。

退出全屏模式

使用者始終可以自行決定退出全屏模式；請參閱您的使用者想知道的事情。您也可以透過呼叫 Document.exitFullscreen() 方法來以程式設計方式退出。

如果多個元素處於全屏模式，呼叫 exitFullscreen() 只會退出最頂層的元素，顯示它下面的下一個元素。按下 Esc 或 F11 將退出所有全屏元素。

其他資訊

Document 提供了一些額外的、在開發全屏 Web 應用程式時可能很有用的資訊。

Document.fullscreenElement / ShadowRoot.fullscreenElement

fullscreenElement 屬性會告訴您當前正在全屏顯示的Element。如果此值為非 null，則文件（或 shadow DOM）處於全屏模式。如果此值為 null，則文件（或 shadow DOM）未處於全屏模式。

Document.fullscreenEnabled

fullscreenEnabled 屬性會告訴您文件當前是否處於允許請求全屏模式的狀態。

移動瀏覽器中的視口縮放

某些移動瀏覽器在全屏模式下會忽略視口 meta 標籤設定並阻止使用者縮放；例如：在全屏模式下顯示的頁面上，“捏合縮放”手勢可能不起作用——即使在非全屏模式下，頁面也可以透過捏合縮放進行縮放。

您的使用者想知道的事情

您應該確保告知使用者他們可以透過按 Esc 鍵（或 F11）退出全屏模式。

此外，在全屏模式下導航到其他頁面、切換標籤頁或切換到其他應用程式（例如使用 Alt-Tab）也會退出全屏模式。

示例

mdn/dom-examples GitHub 倉庫 包含全屏 API 的完整示例。

執行示例並瀏覽原始碼。

規範

瀏覽器相容性

api.Document.fullscreenEnabled

api.Document.fullscreen

另見

• 使用全屏模式
• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen