Window object[PrimaryGlobal, LegacyUnenumerableNamedProperties]
interface Window : EventTarget {
// the current browsing context
[Unforgeable] readonly attribute WindowProxy window;
[Replaceable] readonly attribute WindowProxy self;
[Unforgeable] readonly attribute Document document;
attribute DOMString name;
[PutForwards=href, Unforgeable] readonly attribute Location location;
readonly attribute History history;
readonly attribute CustomElementRegistry customElements;
[Replaceable] readonly attribute BarProp locationbar;
[Replaceable] readonly attribute BarProp menubar;
[Replaceable] readonly attribute BarProp personalbar;
[Replaceable] readonly attribute BarProp scrollbars;
[Replaceable] readonly attribute BarProp statusbar;
[Replaceable] readonly attribute BarProp toolbar;
attribute DOMString status;
void close();
readonly attribute boolean closed;
void stop();
void focus();
void blur();
// other browsing contexts
[Replaceable] readonly attribute WindowProxy frames;
[Replaceable] readonly attribute unsigned long length;
[Unforgeable] readonly attribute WindowProxy? top;
attribute any opener;
[Replaceable] readonly attribute WindowProxy? parent;
readonly attribute Element? frameElement;
WindowProxy? open(optional USVString url = "about:blank", optional DOMString target = "_blank", optional [TreatNullAs=EmptyString] DOMString features = "");
getter object (DOMString name);
// Since this is the global object, the IDL named getter adds a NamedPropertiesObject exotic
// object on the prototype chain. Indeed, this does not make the global object an exotic object.
// Indexed access is taken care of by the WindowProxy exotic object.
// the user agent
readonly attribute Navigator navigator;
readonly attribute ApplicationCache applicationCache;
// user prompts
void alert();
void alert(DOMString message);
boolean confirm(optional DOMString message = "");
DOMString? prompt(optional DOMString message = "", optional DOMString default = "");
void print();
unsigned long requestAnimationFrame(FrameRequestCallback callback);
void cancelAnimationFrame(unsigned long handle);
void postMessage(any message, USVString targetOrigin, optional sequence<object> transfer = []);
};
Window implements GlobalEventHandlers;
Window implements WindowEventHandlers;
callback FrameRequestCallback = void (DOMHighResTimeStamp time);
windowframesselfThese attributes all return window.
documentReturns the Document associated with window.
defaultViewReturns the Window object of the active document.
The Window has an associated
Document, which is a Document object. It is set when the
Window object is created, and only ever changed during navigation from the initial about:blank
Document.
The window, frames, and self IDL
attributes, on getting, must all return this Window object's browsing
context's WindowProxy object.
The document IDL attribute, on getting, must
return this Window object's associated
Document.
The Document object associated with a Window object can
change in exactly one case: when the navigate algorithm initializes a new Document object for the first page loaded
in a browsing context. In that specific case, the Window object of the
original about:blank page is reused and gets a new Document object.
The defaultView IDL attribute of the
Document interface, on getting, must return this Document's browsing context's WindowProxy object, if this
Document has an associated browsing context, or null otherwise.
For historical reasons, Window objects must also have a writable, configurable,
non-enumerable property named HTMLDocument whose value is the
Document interface object.
open( [ url [, target [, features ] ] ] )Opens a window to show url (defaults to about:blank), and returns it.
The target argument gives the name of the new window. If a window exists with that
name already, it is reused. The features argument can be used to influence the
rendering of the new window.
name [ = value ]Returns the name of the window.
Can be set, to change the name.
close()Closes the window.
closedReturns true if the window has been closed, false otherwise.
stop()Cancels the document load.
The window open steps, given a string url, a string target, and a string features, are as follows:
Let entry settings be the entry settings object.
Let source browsing context be the responsible browsing context specified by entry settings.
If target is the empty string, then set target to "_blank".
Let tokenizedFeatures be the result of tokenizing features.
Let noopener be true if tokenizedFeatures contains an entry with the key "noopener"
Let target browsing context and new be the result of applying the rules for choosing a browsing context given target, source browsing context, and noopener.
If there is a user agent that supports control-clicking a link to open it in
a new tab, and the user control-clicks on an element whose onclick handler uses the window.open() API to open a page in an iframe element, the
user agent could override the selection of the target browsing context to instead target a new
tab.
If target browsing context is null, then return null.
If new is true, then set up browsing context features for target browsing context given tokenizedFeatures. [CSSOMVIEW]
Let resource be the URL "about:blank".
If url is not the empty string or new is true, then:
If url is not the empty string, then parse
url relative to entry settings, and set resource to the
resulting URL record, if any. If the parse a URL algorithm failed,
then throw a "SyntaxError" DOMException.
If resource is "about:blank" and new is true, then
queue a task to fire an event named load at target browsing context's Window
object, with the legacy target override flag set.
Otherwise, navigate target browsing context to resource, with the exceptions enabled flag set. If new is true, then replacement must be enabled. The source browsing context is source browsing context. Rethrow any exceptions.
If noopener is true, then disown target browsing context's opener and return null.
Return target browsing context's WindowProxy object.
The open(url,
target, features) method on Window objects
provides a mechanism for navigating an existing browsing
context or opening and navigating an auxiliary browsing context.
When the method is invoked, the user agent must run the window open steps with url, target, and features.
To tokenize the features argument:
Let tokenizedFeatures be a new ordered map.
Let position point at the first code point of features.
While position is not past the end of features:
Let name be the empty string.
Let value be the empty string.
Collect a sequence of code points that are feature separators from features given position. This skips past leading separators before the name.
Collect a sequence of code points that are not feature separators from features given position. Set name to the collected characters, converted to ASCII lowercase.
Set name to the result of normalizing the feature name name.
While position is not past the end of features and the code point at position in features is not U+003D (=):
If the code point at position in features is U+002C (,), or if it is not a feature separator, then break.
Advance position by 1.
This skips to the first U+003D (=) but does not skip past a U+002C (,) or a non-separator.
If the code point at position in features is a feature separator:
While position is not past the end of features and the code point at position in features is a feature separator:
If the code point at position in features is U+002C (,), then break.
Advance position by 1.
This skips to the first non-separator but does not skip past a U+002C (,).
Collect a sequence of code points that are not feature separators code points from features given position. Set value to the collected code points, converted to ASCII lowercase.
If name is not the empty string, then set tokenizedFeatures[name] to value.
Return tokenizedFeatures.
A code point is a feature separator if it is ASCII whitespace, U+003D (=), or U+002C (,).
For legacy reasons, there are some aliases of some feature names. To normalize a feature name name, switch on name:
screenx"
left".
screeny"
top".
innerwidth"
width".
innerheight"
height".
The name attribute of the Window object
must, on getting, return the current name of the
browsing context; and, on setting, set the name of the browsing context to the new value.
The name gets reset when the browsing context is navigated to another origin.
The close() method on Window
objects should, if all the following conditions are met, close the browsing context A:
A browsing context is script-closable if it is an auxiliary
browsing context that was created by a script (as opposed to by an action of the user), or
if it is a top-level browsing context whose session history contains
only one Document.
The closed attribute on Window
objects must return true if the Window object's browsing context has
been discarded, and false otherwise.
The stop() method on Window
objects should, if there is an existing attempt to navigate the browsing
context and that attempt is not currently running the unload a document
algorithm, cancel that navigation; then, it must abort the active document of the browsing
context of the Window object on which it was invoked.
lengthReturns the number of document-tree child browsing contexts.
Returns the indicated document-tree child browsing context.
The number of document-tree child browsing
contexts of a Window object W is the number of document-tree child browsing contexts of
W's associated Document's
browsing context.
The length IDL attribute's getter must return the
number of document-tree child browsing contexts of this Window
object.
Indexed access to document-tree child browsing contexts is defined through the [[GetOwnProperty]] internal method of the
WindowProxy object.
Window objectReturns the indicated element or collection of elements.
As a general rule, relying on this will lead to brittle code. Which IDs end up mapping to
this API can vary over time, as new features are added to the Web platform, for example. Instead
of this, use document.getElementById() or document.querySelector().
The document-tree child browsing context
name property set of a Window object window is the return value of
running these steps:
Let activeDocument be window's browsing context's active document.
Let childBrowsingContexts be all document-tree child browsing contexts of activeDocument's browsing context whose browsing context name is not the empty string, in order, and including only the first document-tree child browsing context with a given name if multiple document-tree child browsing contexts have the same one.
Remove each browsing context from childBrowsingContexts whose
active document's origin is not same origin with
activeDocument's origin and whose browsing context name does
not match the name of its browsing context container's name
content attribute value.
Return the browsing context names of childBrowsingContexts, in the same order.
This means that in the following example, hosted on https://example.org/, assuming https://elsewhere.example/
sets window.name to "spices", evaluating
window.spices after everything has loaded will yield undefined:
<iframe src=https://elsewhere.example.com/></iframe> <iframe name=spices></iframe>
The Window object supports named
properties. The supported property names of a Window object
window at any moment consist of the following, in tree order according to
the element that contributed them, ignoring later duplicates:
window's document-tree child browsing context name property set;
the value of the name content attribute for all embed,
form, frameset, img, and object elements that
have a non-empty name content attribute and are in a document
tree with window's browsing context's active document
as their root; and
the value of the id content attribute for all HTML
elements that have a non-empty id content attribute and are
in a document tree with window's browsing context's
active document as their root.
To determine the value of a named property
name in a Window, the user agent must return the value obtained using the
following steps:
Let objects be the list of named objects with the name name.
There will be at least one such object, by definition.
If objects contains a nested browsing context, then return
the WindowProxy object of the nested browsing context corresponding to
the first browsing context container in tree order whose
nested browsing context is in objects, and abort these steps.
Otherwise, if objects has only one element, return that element and abort these steps.
Otherwise return an HTMLCollection rooted at the Document node,
whose filter matches only named objects with
the name name. (By definition, these will all be elements.)
Named objects with the name name, for the purposes of the above algorithm, consist of the following:
document-tree child browsing contexts of the active document whose name is name;
embed, form, frameset, img, or
object elements that have a name content attribute whose
value is name and are in a document tree with the active
document as their root; and
HTML elements that have an id content attribute
whose value is name and are in a document tree with the active
document as their root.
A browsing context has a strong reference to each of its Documents
and its WindowProxy object, and the user agent itself has a strong reference to its
top-level browsing contexts.
A Document has a strong reference to its Window object.
A Window object has a strong
reference to its Document object through its document attribute. Thus, references from other scripts to either of
those objects will keep both alive. Similarly, both Document and Window
objects have implied strong references to the
WindowProxy object.
Each script has a strong reference to its settings object, and each environment settings object has strong references to its global object, responsible browsing context, and responsible document (if any).
When a browsing context is to discard a
Document, the user agent must run the following steps:
Set the Document's salvageable state to false.
Run any unloading document cleanup steps for the Document that
are defined by this specification and other applicable specifications.
Remove any tasks associated with the
Document in any task source, without running those tasks.
Discard all the child browsing contexts of the Document.
Lose the strong reference from the Document's browsing context to the Document.
Whenever a Document object is discarded, it is also removed from the owner set of each worker
whose set contains that Document.
When a browsing context is discarded, the strong reference
from the user agent itself to the browsing context must be severed, and all the
Document objects for all the entries in the browsing context's session
history must be discarded as well.
User agents may discard top-level browsing contexts at any time (typically, in
response to user requests, e.g. when a user force-closes a window containing one or more top-level browsing contexts). Other browsing contexts must be discarded once their
WindowProxy object is eligible for garbage collection, in addition to the other
places where this specification requires them to be discarded.
A WindowProxy does not have a strong reference to the browsing
context it was created alongside. In particular, it is possible for a nested
browsing context to be discarded even
if JavaScript code holds a reference to its WindowProxy object.
To close a browsing context browsingContext, run these steps:
Prompt to unload browsingContext's active document. If the user refused to allow the document to be unloaded, then return.
Unload browsingContext's active document with the recycle parameter set to false.
Remove browsingContext from the user interface (e.g., close or hide its tab in a tabbed browser).
Discard browsingContext.
User agents should offer users the ability to arbitrarily close any top-level browsing context.
To allow Web pages to integrate with Web browsers, certain Web browser interface elements are exposed in a limited way to scripts in Web pages.
Each interface element is represented by a BarProp object:
[Exposed=Window]
interface BarProp {
readonly attribute boolean visible;
};
locationbar . visibleReturns true if the location bar is visible; otherwise, returns false.
menubar . visibleReturns true if the menu bar is visible; otherwise, returns false.
personalbar . visibleReturns true if the personal bar is visible; otherwise, returns false.
scrollbars . visibleReturns true if the scroll bars are visible; otherwise, returns false.
statusbar . visibleReturns true if the status bar is visible; otherwise, returns false.
toolbar . visibleReturns true if the toolbar is visible; otherwise, returns false.
The visible attribute, on getting, must return either true or a value determined by the user agent to most accurately represent the visibility state of the user interface element that the object represents, as described below.
The following BarProp objects exist for each Document object in a
browsing context. Some of the user interface elements represented by these objects
might have no equivalent in some user agents; for those user agents, except when otherwise
specified, the object must act as if it was present and visible (i.e. its visible attribute must return true).
BarProp objectBarProp objectBarProp objectBarProp objectBarProp objectvisible attribute may return false).BarProp objectvisible attribute may return
false).The locationbar attribute must return
the location bar BarProp object.
The menubar attribute must return the
menu bar BarProp object.
The personalbar attribute must return
the personal bar BarProp object.
The scrollbars attribute must return
the scrollbar BarProp object.
The statusbar attribute must return
the status bar BarProp object.
The toolbar attribute must return the
toolbar BarProp object.
For historical reasons, the status attribute
on the Window object must, on getting, return the last string it was set to, and on
setting, must set itself to the new value. When the Window object is created, the
attribute must be set to the empty string. It does not do anything else.
Window objectsWhen the user agent is required to set up a window environment settings object, given a JavaScript execution context execution context and an optional environment reserved environment, it must run the following steps:
Let realm be the value of execution context's Realm component.
Let window be realm's global object.
Let url be a copy of the URL of
window's associated
Document.
Let settings object be a new environment settings object whose algorithms are defined as follows:
Return execution context.
Return the module map of
window's associated
Document.
Return the browsing context with which window is associated.
Return the event loop that is associated with the unit of related similar-origin browsing contexts to which window's browsing context belongs.
Return window's associated
Document.
Return the current character encoding
of window's associated
Document.
Return the current base URL of window's
associated Document.
Return the origin of window's associated Document.
Return the HTTPS state of
window's associated
Document.
Let document be the Document with which window is
currently associated.
While document is an iframe
srcdoc document and document's
referrer policy is the empty
string, set document to document's
browsing context's
browsing context container's node document.
Return document's referrer policy.
If reserved environment is given, then:
Set settings object's id to reserved environment's id, settings object's creation URL to reserved environment's creation URL, settings object's target browsing context to reserved environment's target browsing context, and settings object's active service worker to reserved environment's active service worker.
Set reserved environment's id to the empty string.
The identity of the reserved environment is considered to be fully transferred to the created environment settings object. The reserved environment is not searchable by the environment’s id from this point on.
Otherwise, set settings object's id to a new unique opaque string, settings object's creation URL to url, settings object's target browsing context to null, and settings object's active service worker to null.
Set realm's [[HostDefined]] field to settings object.
Return settings object.
WindowProxy exotic objectA WindowProxy is an exotic
object that wraps a Window ordinary object, indirecting most operations through to
the wrapped object. Each browsing context has an associated WindowProxy
object. When the browsing context is navigated, the
Window object wrapped by the browsing context's associated
WindowProxy object is changed.
There is no WindowProxy interface object.
Every WindowProxy object has a
[[Window]] internal slot representing the wrapped
Window object.
The WindowProxy object internal methods are described in the subsections
below.
Although WindowProxy is named as a "proxy", it does not do
polymorphic dispatch on its target's internal methods as a real proxy would, due to a desire to
reuse machinery between WindowProxy and Location objects. As long as the
Window object remains an ordinary object this is unobservable and can be implemented
either way.
Let W be the value of the [[Window]] internal slot of this.
If ! IsPlatformObjectSameOrigin(W) is true, then return ! OrdinaryGetPrototypeOf(W).
Return null.
Return ! SetImmutablePrototype(this, V).
Return true.
Return false.
Let W be the value of the [[Window]] internal slot of this.
If P is an array index property name, then:
Let index be ! ToUint32(P).
Let maxProperties be the number of document-tree child browsing contexts of W.
Let value be undefined.
If maxProperties is greater than 0 and index is less than maxProperties, then:
Let document be W's associated Document.
Set value to the WindowProxy object of the indexth
document-tree child browsing context of document's browsing context, sorted in the order
that their browsing context container
elements were most recently inserted into document, the
WindowProxy object of the most recently inserted browsing context
container's nested browsing context being last.
If value is undefined, then return undefined.
Return PropertyDescriptor{ [[Value]]: value, [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: true }.
If ! IsPlatformObjectSameOrigin(W) is true, then return ! OrdinaryGetOwnProperty(W, P).
This is a willful violation of the JavaScript specification's invariants of the essential internal methods to maintain compatibility with existing Web content. See tc39/ecma262 issue #672 for more information. [JAVASCRIPT]
Let property be ! CrossOriginGetOwnPropertyHelper(W, P).
If property is not undefined, then return property.
If property is undefined and P is in W's document-tree child browsing context name property set, then:
Let value be the WindowProxy object of the
named object with the name P.
Return PropertyDescriptor{ [[Value]]: value, [[Enumerable]]: false, [[Writable]]: false, [[Configurable]]: true }.
The reason the property descriptors are non-enumerable, despite this mismatching the same-origin behavior, is for compatibility with existing Web content. See issue #3183 for details.
Throw a "SecurityError" DOMException.
Let W be the value of the [[Window]] internal slot of this.
If ! IsPlatformObjectSameOrigin(W) is true, then:
If P is an array index property name, return false.
Return ? OrdinaryDefineOwnProperty(W, P, Desc).
This is a willful violation of the JavaScript specification's invariants of the essential internal methods to maintain compatibility with existing Web content. See tc39/ecma262 issue #672 for more information. [JAVASCRIPT]
Throw a "SecurityError" DOMException.
Let W be the value of the [[Window]] internal slot of this.
If ! IsPlatformObjectSameOrigin(W) is true, then return ? OrdinaryGet(this, P, Receiver).
Return ? CrossOriginGet(this, P, Receiver).
Let W be the value of the [[Window]] internal slot of this.
If ! IsPlatformObjectSameOrigin(W) is true, then return ? OrdinarySet(W, this, Receiver).
Return ? CrossOriginSet(this, P, V, Receiver).
Let W be the value of the [[Window]] internal slot of this.
If ! IsPlatformObjectSameOrigin(W) is true, then:
If P is an array index property name, then:
Let desc be ! this.[[GetOwnProperty]](P).
If desc is undefined, then return true.
Return false.
Return ? OrdinaryDelete(W, P).
Throw a "SecurityError" DOMException.
Let W be the value of the [[Window]] internal slot of this.
Let keys be a new empty List.
Let maxProperties be the number of document-tree child browsing contexts of W.
Let index be 0.
Repeat while index < maxProperties,
Add ! ToString(index) as the last element of keys.
Increment index by 1.
If ! IsPlatformObjectSameOrigin(W) is true, then return the concatenation of keys and ! OrdinaryOwnPropertyKeys(W).
Return the concatenation of keys and ! CrossOriginOwnPropertyKeys(W).