Fullscreen API

介面

全屏 API 沒有自己的介面。相反，它擴充套件了幾個其他介面，以新增提供全屏功能所需的方法、屬性和事件處理程式。這些在以下各節中列出。

例項方法

全屏 API 向 Document 和 Element 介面添加了方法，以允許開啟和關閉全屏模式。

Document 介面上的例項方法

Document.exitFullscreen()

請求 使用者代理 從全屏模式切換回視窗模式。返回一個 Promise，在全屏模式完全關閉後得到解決。

Element 介面上的例項方法

Element.requestFullscreen()

請求使用者代理將指定元素（及其後代元素）置於全屏模式，移除所有瀏覽器 UI 元素以及螢幕上的所有其他應用程式。返回一個 Promise，在全屏模式啟用後得到解決。

例項屬性

Document.fullscreenElement / ShadowRoot.fullscreenElement

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

Document.fullscreenEnabled

fullscreenEnabled 屬性告訴你是否可以啟用全屏模式。如果由於任何原因（例如“fullscreen”功能不允許，或不支援全屏模式）全屏模式不可用，則此屬性為 false。

已廢棄的屬性

Document.fullscreen 已棄用

一個布林值，如果文件當前顯示全屏元素，則為 true；否則返回 false。

注意：請改用 fullscreenElement 屬性在 Document 或 ShadowRoot 上；如果不為 null，則表示當前以全屏模式顯示的 Element。

事件

fullscreenchange

當 Element 進入或退出全屏模式時傳送。

fullscreenerror

嘗試將 Element 切換到全屏模式或退出全屏模式時發生錯誤時傳送。

控制訪問

全屏模式的可用性可以透過 許可權策略 進行控制。全屏模式功能由字串 "fullscreen" 標識，預設允許列表值為 "self"，這意味著在頂級文件上下文中以及與最頂層文件同源的巢狀瀏覽上下文中允許全屏模式。

用法說明

使用者可以透過按 ESC（或 F11）鍵退出全屏模式，而不是等待網站或應用程式以程式設計方式執行此操作。請確保在使用者介面中提供適當的使用者介面元素，告知使用者此選項可用。

示例

簡單的全屏使用

在此示例中，影片在一個網頁中呈現。按 Enter 鍵可讓使用者在影片的視窗模式和全屏模式之間切換。

檢視即時示例

監聽 Enter 鍵

頁面載入時，執行此程式碼以設定事件監聽器來監聽 Enter 鍵。

const video = document.getElementById("video");

// On pressing ENTER call toggleFullScreen method
document.addEventListener("keydown", (e) => {
  if (e.key === "Enter") {
    toggleFullScreen(video);
  }
});

切換全屏模式

當用戶按下 Enter 鍵時，上面的事件處理程式會呼叫此程式碼。

function toggleFullScreen(video) {
  if (!document.fullscreenElement) {
    // If the document is not in full screen mode
    // make the video full screen
    video.requestFullscreen();
  } else {
    // Otherwise exit the full screen
    document.exitFullscreen?.();
  }
}

這首先檢視 document 的 fullscreenElement 屬性值。如果該值為 null，則表示文件當前處於視窗模式，因此我們需要切換到全屏模式；否則，它就是當前處於全屏模式的元素。透過在 <video> 元素上呼叫 Element.requestFullscreen() 來切換到全屏模式。

如果全屏模式已啟用（fullscreenElement 不為 null），我們將在 document 上呼叫 exitFullscreen() 來關閉全屏模式。

規範

瀏覽器相容性

api.Document.fullscreenElement

api.Document.fullscreenEnabled

api.Document.exitFullscreen

api.Element.requestFullscreen

api.Document.fullscreen

另見

• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen