fullscreen.spec.whatwg.orgFullscreen API Standard

Fullscreen API Living Standard — Last Updated 18 January 2021 Participate: GitHub whatwg/fullscreen ( new issue , open issues ) IRC: #whatwg on Freenode Commits: GitHub whatwg/fullscreen/commits Snapshot as of this commit @fullscreenapi Tests: web-platform-tests fullscreen/ ( ongoing work ) Translations (non-normative) : 日本語 Abstract The Fullscreen API standard defines an API for elements to display themselves fullscreen. Table of Contents 1 Terminology 2 Model 3 API 4 UI 5 Rendering 5.1 New stacking layer 5.2 ::backdrop pseudo-element 5.3 :fullscreen pseudo-class 5.4 User-agent level style sheet defaults 6 Permissions Policy Integration 7 Security and Privacy Considerations Acknowledgments Intellectual property rights Index Terms defined by this specification Terms defined by reference References Normative References IDL Index 1. Terminology This specification depends on the Infra Standard. [INFRA] Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [CSS] [DOM] [HTML] [WEBIDL] A browsing context A is called a descendant browsing context of a browsing context B if and only if B is an ancestor browsing context of A . 2. Model All elements have an associated fullscreen flag . Unless stated otherwise it is unset. All iframe elements have an associated iframe fullscreen flag . Unless stated otherwise it is unset. All documents have an associated fullscreen element . The fullscreen element is the topmost element in the document ’s top layer whose fullscreen flag is set, if any, and null otherwise. All documents have an associated list of pending fullscreen events , which is an ordered set of ( string , element ) pairs . It is initially empty. To fullscreen an element , set element ’s fullscreen flag and add it to its node document ’s top layer . To unfullscreen an element , unset element ’s fullscreen flag and iframe fullscreen flag (if any), and remove it from its node document ’s top layer . To unfullscreen a document , unfullscreen all elements , within document ’s top layer , whose fullscreen flag is set. To fully exit fullscreen a document document , run these steps: If document ’s fullscreen element is null, terminate these steps. Unfullscreen elements whose fullscreen flag is set, within document ’s top layer , except for document ’s fullscreen element . Exit fullscreen document . Whenever the removing steps run with a removedNode , run these steps: Let document be removedNode ’s node document . Let nodes be removedNode ’s shadow-including inclusive descendants that have their fullscreen flag set, in shadow-including tree order . For each node in nodes : If node is document ’s fullscreen element , exit fullscreen document . Otherwise, unfullscreen node . If document ’s top layer contains node , remove node from document ’s top layer . Other specifications can add and remove elements from top layer , so node might not be document ’s fullscreen element . For example, node could be an open dialog element. Whenever the unloading document cleanup steps run with a document , fully exit fullscreen document . Fullscreen is supported if there is no previously-established user preference, security risk, or platform limitation. To run the fullscreen steps for a document document , run these steps: Let pairs be document ’s list of pending fullscreen events . Empty document ’s list of pending fullscreen events . For each ( type , element ) in pairs : Let target be element if element is connected and its node document is document , and otherwise let target be document . Fire an event named type , with its bubbles and composed attributes set to true, at target . These steps integrate with the event loop defined in HTML. [HTML] 3. API ✔ MDN Element In all current engines. Firefox 1+ Safari 1.3+ Chrome 1+ Opera 8+ Edge 79+ Edge (Legacy) 12+ IE 4+ Firefox for Android 4+ iOS Safari 1+ Chrome for Android 18+ Android WebView 1+ Samsung Internet 1.0+ Opera Mobile 10.1+ MDN FullscreenOptions/navigationUI Firefox 64+ Safari ? Chrome 71+ Opera ? Edge 79+ Edge (Legacy) None IE None Firefox for Android 64+ iOS Safari ? Chrome for Android 71+ Android WebView 71+ Samsung Internet 10.0+ Opera Mobile ? enum FullscreenNavigationUI { "auto" , "show" , "hide" }; dictionary FullscreenOptions { FullscreenNavigationUI navigationUI = "auto"; }; partial interface Element { Promise < undefined > requestFullscreen ( optional FullscreenOptions options = {}); attribute EventHandler onfullscreenchange ; attribute EventHandler onfullscreenerror ; }; partial interface Document { [ LegacyLenientSetter ] readonly attribute boolean fullscreenEnabled ; [ LegacyLenientSetter , Unscopable ] readonly attribute boolean fullscreen ; // historical Promise < undefined > exitFullscreen (); attribute EventHandler onfullscreenchange ; attribute EventHandler onfullscreenerror ; }; partial interface mixin DocumentOrShadowRoot { [ LegacyLenientSetter ] readonly attribute Element ? fullscreenElement ; }; promise = element . requestFullscreen([ options ]) Displays element fullscreen and resolves promise when done. When supplied, options ’s navigationUI member indicates whether showing navigation UI while in fullscreen is preferred or not. If set to " show ", navigation simplicity is preferred over screen space, and if set to " hide ", more screen space is preferred. User agents are always free to honor user preference over the application’s. The default value " auto " indicates no application preference. document . fullscreenEnabled Returns true if document has the ability to display elements fullscreen and fullscreen is supported , or false otherwise. promise = document . exitFullscreen() Stops document ’s fullscreen element from being displayed fullscreen and resolves promise when done. document . fullscreenElement Returns document ’s fullscreen element . shadowroot . fullscreenElement Returns shadowroot ’s fullscreen element . A fullscreen element ready check for an element element returns true if all of the following are true, and false otherwise: element is connected . element ’s node document is allowed to use the " fullscreen " feature. MDN Element/requestFullscreen Firefox 64+ Safari None Chrome 71+ Opera 58+ Edge 79+ Edge (Legacy) None IE None Firefox for Android 64+ iOS Safari None Chrome for Android 71+ Android WebView 71+ Samsung Internet 10.0+ Opera Mobile 50+ The requestFullscreen( options ) method, when invoked, must run these steps: Let pending be the context object . Let pendingDoc be pending ’s node document . Let promise be a new promise. If pendingDoc is not fully active , then reject promise with a TypeError exception and return promise . Let error be false. If any of the following conditions are false, then set error to true: pending ’s namespace is the HTML namespace or pending is an SVG svg or MathML math element. [SVG] [MATHML] pending is not a dialog element. The fullscreen element ready check for pending returns true. Fullscreen is supported . pending ’s relevant global object has transient activation or the algorithm is triggered by a user generated orientation change . Return promise , and run the remaining steps in parallel . If error is false, then resize pendingDoc ’s top-level browsing context ’s active document ’s viewport’s dimensions, optionally taking into account options ’s navigationUI member: value viewport dimensions " hide " full dimensions of the screen of the output device " show " dimensions of the screen of the output device clamped to allow the user agent to show page navigation controls " auto " user-agent defined, but matching one of the above Optionally display a message how the end user can revert this. If any of the following conditions are false, then set error to true: pending ’s node document is pendingDoc . The fullscreen element ready check for pending returns true. If error is true: Append ( fullscreenerror , pending ) to pendingDoc ’s list of pending fullscreen events . Reject promise with a TypeError exception ...