--- title: 使用全螢幕模式 slug: Web/API/Fullscreen_API translation_of: Web/API/Fullscreen_API ---

{{DefaultAPISidebar("Fullscreen API")}}

全螢幕 API 提供一個簡便的方式使網頁可以使用佔用使用者的整個螢幕的方式來顯示內容。該 API 讓您能夠容易地指示瀏覽器使某個元素及其子系（如有）佔用整個螢幕，並隱藏螢幕上所有瀏覽器使用者介面及其他應用程式。

目前並非所有瀏覽器均使用 API 的沒有前綴的版本。請查閱有關前綴以及名稱差異的表格（您也可以使用 Fscreen 來提供跨瀏覽器 API 存取）。

啟動全螢幕模式

如果您有一個元素打算以全螢幕模式展示（例如 {{ HTMLElement("video") }}），您可以呼叫該元素之 {{ domxref("Element.requestFullscreen()") }} 方法使之以全螢幕模式顯示。

考慮此 {{ HTMLElement("video") }} 元素：

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

我們可以使用指令碼將此影片全螢幕顯示：

var elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
} else if (elem.msRequestFullscreen) {
  elem.msRequestFullscreen();
} else if (elem.mozRequestFullScreen) {
  elem.mozRequestFullScreen();
} else if (elem.webkitRequestFullscreen) {
  elem.webkitRequestFullscreen();
}

呈現差異

值得留意的是，Gecko 及 WebKit 的實作有關鍵分別：Gecko 會增加 CSS 規則讓全螢幕的元素展延至填滿整個螢幕："width: 100%; height: 100%"。WebKit 則不會執行此動作，取而代之的是把該元素置中，並以原先的大小顯示。要取得同樣的全螢幕行為，您需要為該元素自行添加 "width: 100%; height: 100%;" 的 CSS 規則：

#myvideo:-webkit-full-screen {
  width: 100%;
  height: 100%;
}

另一方面，如果您嘗試在 Gecko 上模擬 WebKit 的行為，您需要把呈現的元素放置在另一個實際調整為全螢幕的元素裡面，再使用 CSS 規則來調整內部元素至您想要的外觀。

通知

如果成功進入全螢幕模式，包含該元素的文件將會接收到 {{ event("fullscreenchange") }} 事件。當離開全螢幕模式時，則會收到 {{ event("fullscreenchange") }} 事件。注意 {{ event("fullscreenchange") }} 事件並不提供任何資訊指示進入或離開全螢幕模式，但如果文件的 {{ domxref("document.fullscreenElement", "fullscreenElement") }} 屬性的值不為 null，則表示您正在處於全螢幕模式。

全螢幕要求失敗

並不是所有情況下都保證可以進入全螢幕模式。例如，{{ HTMLElement("iframe") }} 元素含有 {{ HTMLAttrXRef("allowfullscreen", "iframe") }} 屬性來選擇是否容許其內容能以全螢幕方式呈現。而且，例如視窗式外掛程式等的某些內容並不可以在全螢幕模式中顯示。把無法呈現為全螢幕的元素設定為全螢幕模式的嘗試都沒有作用，而要求顯示為全螢幕的元素會接收到 mozfullscreenerror 事件。當全螢幕要求失敗時，Firefox 會在網頁主控台上紀錄一則錯誤訊息，解釋要求失敗的原因。但在 Chrome 以及新版的 Opera 上，則不會產生這些錯誤訊息。

注意：全螢幕要求必須在事件處理常式中呼叫，否則將會被拒絕。

離開全螢幕模式

使用者永遠可以自行離開全螢幕模式，詳見 Things your users want to know。您也可以呼叫 {{domxref("Document.exitFullscreen()")}} 方法來達到相同效果。

其他資訊

{{ domxref("document") }} 提供一些附加資訊，對於開發全螢幕網頁應用程式的時候非常有用：

{{ domxref("document.fullscreenElement", "fullscreenElement") }}
fullscreenElement 屬性傳回正在顯示為全螢幕模式的 {{ domxref("element") }}。如其為非 null 值，表示文件目前在全螢幕模式。如其為 null，表示文件目前不在全螢幕模式。
{{ domxref("document.fullscreenEnabled", "fullscreenEnabled") }}
fullscreenEnabled 屬性傳回文件是否容許您要求進入全螢幕訊息。

使用者可能想了解的訊息

您可能會讓使用者知道他們可以按 ESC 或 F11 鍵來離開全螢幕模式。

此外，瀏覽其他頁面、切換分頁、或切換到其他應用程式（例如按 鍵）亦會離開全螢幕模式。

範例

In this example, a video is presented in a web page. Pressing the Return or Enter key lets the user toggle between windowed and fullscreen presentation of the video.

查看示例

監視 Enter 鍵

When the page is loaded, this code is run to set up an event listener to watch for the 'enter' key.

document.addEventListener("keydown", function(e) {
  if (e.keyCode == 13) {
    toggleFullScreen();
  }
}, false);

Toggling fullscreen mode

This code is called when the user hits the Enter key, as seen above.

function toggleFullScreen() {
  if (!document.fullscreenElement &&    // alternative standard method
      !document.mozFullScreenElement && !document.webkitFullscreenElement && !document.msFullscreenElement ) {  // current working methods
    if (document.documentElement.requestFullscreen) {
      document.documentElement.requestFullscreen();
    } else if (document.documentElement.msRequestFullscreen) {
      document.documentElement.msRequestFullscreen();
    } else if (document.documentElement.mozRequestFullScreen) {
      document.documentElement.mozRequestFullScreen();
    } else if (document.documentElement.webkitRequestFullscreen) {
      document.documentElement.webkitRequestFullscreen(Element.ALLOW_KEYBOARD_INPUT);
    }
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    } else if (document.msExitFullscreen) {
      document.msExitFullscreen();
    } else if (document.mozCancelFullScreen) {
      document.mozCancelFullScreen();
    } else if (document.webkitExitFullscreen) {
      document.webkitExitFullscreen();
    }
  }
}

This starts by looking at the value of the fullscreenElement attribute on the {{ domxref("document") }} (checking it prefixed with both moz, ms, and webkit). If it's null, the document is currently in windowed mode, so we need to switch to fullscreen mode. Switching to fullscreen mode is done by calling either {{ domxref("element.mozRequestFullScreen()") }} msRequestFullscreen()or webkitRequestFullscreen(), depending on which is available.

If fullscreen mode is already active (fullscreenElement is non-null), we call {{ domxref("document.mozCancelFullScreen()") }}, msExitFullscreen or webkitExitFullscreen(), again depending on which browser is in use.

瀏覽器兼容性

Document.fullscreen

{{Compat("api.Document.fullscreen")}}

Document.fullscreenElement

{{Compat("api.Document.fullscreenElement")}}

Document.fullscreenEnabled

{{Compat("api.Document.fullscreenEnabled")}}

Document.exitFullscreen

{{Compat("api.Document.exitFullscreen")}}

Element.requestFullscreen

{{Compat("api.Element.requestFullscreen")}}

規範

Fullscreen API

非標準方法

These are some of the methods that browsers implemented before the standard was drafted. Having the standard methods described above it's better to avoid using the following ones:

參見