翻譯不完整。請協助 翻譯此英文文件。
這是一個實驗中的功能
此功能在某些瀏覽器尚在開發中,請參考兼容表格以得到不同瀏覽器用的前輟。
fullscreen API 提供一個容易的方式讓網頁內容可以使用全螢幕呈現. 這篇文章介紹使用 fullscreen API 的方法.
The API lets you easily direct the browser to make an element and its children, if any, occupy the fullscreen, eliminating all browser user interface and other applications from the screen for the duration.
啟動全螢幕模式
Given an element that you'd like to present in fullscreen mode (such as a <video>
, for example), you can present it in fullscreen mode by simply calling its requestFullscreen()
method; this method is implemented in Gecko as element.mozRequestFullScreen()
, in Trident as element.msRequestFullscreen()
and in WebKit as element.webkitRequestFullscreen()
.
Note: The specification uses the label, "Fullscreen" as in "requestFullscreen" or "fullscreenEnabled" - without a capital 's'. The implementation described here and other prefixed implementations may use a capital 'S'.
Let's consider this <video>
element:
<video controls id="myvideo"> <source src="somevideo.webm"></source> <source src="somevideo.mp4"></source> </video>
We can put that video into fullscreen mode with script like this:
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(); }
表現差異
It's worth noting a key difference here between the Gecko and WebKit implementations at this time: Gecko automatically adds CSS rules to the element to stretch it to fill the screen: "width: 100%; height: 100%
". WebKit doesn't do this; instead, it centers the fullscreen element at the same size in a screen that's otherwise black. To get the same fullscreen behavior in WebKit, you need to add your own "width: 100%; height: 100%;
" CSS rules to the element yourself:
#myvideo:-webkit-full-screen { width: 100%; height: 100%; }
On the other hand, if you're trying to emulate WebKit's behavior on Gecko, you need to place the element you want to present inside another element, which you'll make fullscreen instead, and use CSS rules to adjust the inner element to match the appearance you want.
通知
When fullscreen mode is successfully engaged, the document which contains the element receives a mozfullscreenchange
event. When fullscreen mode is exited, the document again receives a mozfullscreenchange
event. Note that the mozfullscreenchange
event doesn't provide any information itself as to whether the document is entering or exiting fullscreen mode, but if the document has a non null mozFullScreenElement
, you know you're in fullscreen mode.
全螢幕要求失敗
It's not guaranteed that you'll be able to switch into fullscreen mode. For example, <iframe>
elements have the mozallowfullscreen
attribute (webkitallowfullscreen
, etc) in order to opt-in to allowing their content to be displayed in fullscreen mode. In addition, certain kinds of content, such as windowed plug-ins, cannot be presented in fullscreen mode. Attempting to put an element which can't be displayed in fullscreen mode (or the parent or descendant of such an element) won't work. Instead, the element which requested fullscreen will receive a mozfullscreenerror
event. When a fullscreen request fails, Firefox will log an error message to the Web Console explaining why the request failed. In Chrome and newer versions of Opera however, no such warning is generated.
NOTE: Fullscreen requests need to be called from within an event handler or otherwise they will be denied.
取消全螢幕模式
The user always has the ability to exit fullscreen mode of their own accord; see Things your users want to know. You can also do so programmatically by calling the exitFullscreen()
method; this is implemented in Gecko as mozCancelFullScreen()
, WebKit as webkitExitFullscreen(),
and Trident as msExitFullscreen()
.
其他資訊
The document
provides some additional information that can be useful when developing fullscreen web applications:
fullscreenElement
- The
fullscreenElement
attribute tells you theelement
that's currently being displayed fullscreen. If this is non-null, the document is in fullscreen mode. If this is null, the document is not in fullscreen mode. fullscreenEnabled
- The
fullscreenEnabled
attribute tells you whether or not the document is currently in a state that would allow fullscreen mode to be requested.
使用者可能想了解的訊息
You'll want to be sure to let your users know that they can press the ESC key (or F11) to exit fullscreen mode.
In addition, navigating to another page, changing tabs, or switching to another application (using, for example, Alt-Tab) while in fullscreen mode exits fullscreen mode as well.
範例
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 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 element.mozRequestFullScreen()
msRequestFullscreen()
or webkitRequestFullscreen()
, depending on which is available.
If fullscreen mode is already active (fullscreenElement
is non-null
), we call document.mozCancelFullScreen()
, msExitFullscreen
or webkitExitFullscreen()
, again depending on which browser is in use.
瀏覽器兼容性
Although Gecko , Trident, and WebKit implement a draft of this API, there are some subtle differences. This document doesn't necessarily try to call them all into focus. The article will be revised as the spec and implementations fall closer into alignment with one another.
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | 15 -webkit | 9.0 (9.0) -moz | 11 -ms | 12.10 | 5.0 -webkit |
fullscreenEnabled |
20 -webkit | 10.0 (10.0) -moz | 11 -ms | 12.10 | 5.1 -webkit |
Feature | Android | Chrome | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | ? | 28 -webkit | 9.0 (9.0)-moz | ? | ? | ? |
fullscreenEnabled |
? | 28 -webkit | 10.0 (10.0) moz | ? | ? | ? |
Gecko notes
Although this API was introduced in Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6), it's not enabled by default in that release. To enable it, set the full-screen-api.enabled
preference to true
. The API is enabled by default in Gecko 10.0 (Firefox 10.0 / Thunderbird 10.0 / SeaMonkey 2.7). In Gecko all the API is spelt "fullScreen".
規範
非標準方法
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:
window.fullScreen
(Firefox)HTMLMediaElement.webkitDisplayingFullscreen
HTMLMediaElement.webkitEnterFullscreen
HTMLMediaElement.webkitExitFullscreen
HTMLMediaElement.webkitSupportsFullscreen