HTML
Living Standard — Last Updated 8 November 2024
Living Standard — Last Updated 8 November 2024
Window,
WindowProxy, and Location objectsWindow objectWindowProxy exotic objectLocation interfaceHistory interfaceNavigation interfaceNavigationHistoryEntry interfaceNavigationActivation interfacenavigate eventNotRestoredReasons interfaceWindow,
WindowProxy, and Location objectsAlthough typically objects cannot be accessed across origins, the web platform would not be true to itself if it did not have some legacy exceptions to that rule that the web depends upon.
This section uses the terminology and typographic conventions from the JavaScript specification. [JAVASCRIPT]
When perform a security check is invoked, with a platformObject, identifier, and type, run these steps:
If platformObject is not a Window or Location object,
then return.
For each e of CrossOriginProperties(platformObject):
If SameValue(e.[[Property]], identifier) is true, then:
If type is "method" and e has neither
[[NeedsGet]] nor [[NeedsSet]], then return.
Otherwise, if type is "getter" and
e.[[NeedsGet]] is true, then return.
Otherwise, if type is "setter" and
e.[[NeedsSet]] is true, then return.
If IsPlatformObjectSameOrigin(platformObject) is false, then
throw a "SecurityError" DOMException.
Window and Location objects both have a
[[CrossOriginPropertyDescriptorMap]] internal slot, whose value is initially an empty
map.
The [[CrossOriginPropertyDescriptorMap]] internal slot contains a map
with entries whose keys are (currentGlobal, objectGlobal,
propertyKey)-tuples and values are property descriptors, as a memoization of what is
visible to scripts when currentGlobal inspects a Window or
Location object from objectGlobal. It is filled lazily by
CrossOriginGetOwnPropertyHelper, which consults it on future lookups.
User agents should allow a value held in the map to be garbage collected along with its corresponding key when nothing holds a reference to any part of the value. That is, as long as garbage collection is not observable.
For example, with const href =
Object.getOwnPropertyDescriptor(crossOriginLocation, "href").set the value and its
corresponding key in the map cannot be garbage collected as that would be observable.
User agents may have an optimization whereby they remove key-value pairs from the map when
document.domain is set. This is not observable as document.domain cannot revisit an earlier value.
For example, setting document.domain
to "example.com" on www.example.com means user agents can remove all
key-value pairs from the map where part of the key is www.example.com, as that can never be part
of the origin again and therefore the corresponding value could never be retrieved
from the map.
If O is a Location object, then return «
{ [[Property]]: "href", [[NeedsGet]]: false, [[NeedsSet]]: true },
{ [[Property]]: "replace" } ».
Return «
{ [[Property]]: "window", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "self", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "location", [[NeedsGet]]: true, [[NeedsSet]]: true },
{ [[Property]]: "close" },
{ [[Property]]: "closed", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "focus" },
{ [[Property]]: "blur" },
{ [[Property]]: "frames", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "length", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "top", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "opener", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "parent", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "postMessage" } ».
This abstract operation does not return a Completion Record.
Indexed properties do not need to be safelisted in this algorithm, as they are
handled directly by the WindowProxy object.
A JavaScript property name P is a cross-origin accessible window property
name if it is "window", "self", "location", "close", "closed",
"focus", "blur", "frames",
"length", "top", "opener",
"parent", "postMessage", or an array index
property name.
If P is "then", %Symbol.toStringTag%,
%Symbol.hasInstance%, or %Symbol.isConcatSpreadable%, then return
PropertyDescriptor{
[[Value]]: undefined,
[[Writable]]: false,
[[Enumerable]]: false,
[[Configurable]]: true }.
Throw a "SecurityError" DOMException.
Return true if the current settings object's origin is same origin-domain with O's relevant settings object's origin, and false otherwise.
This abstract operation does not return a Completion Record.
Here the current settings object roughly corresponds to the "caller",
because this check occurs before the execution
context for the getter/setter/method in question makes its way onto the JavaScript
execution context stack. For example, in the code w.document, this
step is invoked before the document getter is reached as part
of the [[Get]] algorithm for the WindowProxy
w.
If this abstract operation returns undefined and there is no custom behavior, the
caller needs to throw a "SecurityError" DOMException. In
practice this is handled by the caller calling CrossOriginPropertyFallback.
Let crossOriginKey be a tuple consisting of the current settings object, O's relevant settings object, and P.
For each e of CrossOriginProperties(O):
If SameValue(e.[[Property]], P) is true, then:
If the value of the [[CrossOriginPropertyDescriptorMap]] internal slot of O contains an entry whose key is crossOriginKey, then return that entry's value.
Let originalDesc be OrdinaryGetOwnProperty(O, P).
Let crossOriginDesc be undefined.
If e.[[NeedsGet]] and e.[[NeedsSet]] are absent, then:
Let value be originalDesc.[[Value]].
If IsCallable(value) is true, then set value to an anonymous built-in function, created in the current realm, that performs the same steps as the IDL operation P on object O.
Set crossOriginDesc to PropertyDescriptor{ [[Value]]: value, [[Enumerable]]: false, [[Writable]]: false, [[Configurable]]: true }.
Otherwise:
Let crossOriginGet be undefined.
If e.[[NeedsGet]] is true, then set crossOriginGet to an anonymous built-in function, created in the current realm, that performs the same steps as the getter of the IDL attribute P on object O.
Let crossOriginSet be undefined.
If e.[[NeedsSet]] is true, then set crossOriginSet to an anonymous built-in function, created in the current realm, that performs the same steps as the setter of the IDL attribute P on object O.
Set crossOriginDesc to PropertyDescriptor{ [[Get]]: crossOriginGet, [[Set]]: crossOriginSet, [[Enumerable]]: false, [[Configurable]]: true }.
Create an entry in the value of the [[CrossOriginPropertyDescriptorMap]] internal slot of O with key crossOriginKey and value crossOriginDesc.
Return crossOriginDesc.
Return undefined.
This abstract operation does not return a Completion Record.
The reason that the property descriptors produced here are configurable is to preserve the invariants of the essential internal methods required by the JavaScript specification. In particular, since the value of the property can change as a consequence of navigation, it is required that the property be configurable. (However, see tc39/ecma262 issue #672 and references to it elsewhere in this specification for cases where we are not able to preserve these invariants, for compatibility with existing web content.) [JAVASCRIPT]
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.
Let desc be ? O.[[GetOwnProperty]](P).
Assert: desc is not undefined.
If IsDataDescriptor(desc) is true, then return desc.[[Value]].
Assert: IsAccessorDescriptor(desc) is true.
Let getter be desc.[[Get]].
If getter is undefined, then throw a "SecurityError"
DOMException.
Return ? Call(getter, Receiver).
Let desc be ? O.[[GetOwnProperty]](P).
Assert: desc is not undefined.
If desc.[[Set]] is present and its value is not undefined, then:
Perform ? Call(setter, Receiver, « V »).
Return true.
Throw a "SecurityError" DOMException.
Let keys be a new empty List.
For each e of CrossOriginProperties(O), append e.[[Property]] to keys.
Return the concatenation of keys and « "then",
%Symbol.toStringTag%, %Symbol.hasInstance%, %Symbol.isConcatSpreadable%
».
This abstract operation does not return a Completion Record.
Window objectSupport in all current engines.
[Global =Window ,
Exposed =Window ,
LegacyUnenumerableNamedProperties ]
interface Window : EventTarget {
// the current browsing context
[LegacyUnforgeable ] readonly attribute WindowProxy window ;
[Replaceable ] readonly attribute WindowProxy self ;
[LegacyUnforgeable ] readonly attribute Document document ;
attribute DOMString name ;
[PutForwards =href , LegacyUnforgeable ] readonly attribute Location location ;
readonly attribute History history ;
readonly attribute Navigation navigation ;
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 ;
undefined close ();
readonly attribute boolean closed ;
undefined stop ();
undefined focus ();
undefined blur ();
// other browsing contexts
[Replaceable ] readonly attribute WindowProxy frames ;
[Replaceable ] readonly attribute unsigned long length ;
[LegacyUnforgeable ] readonly attribute WindowProxy ? top ;
attribute any opener ;
[Replaceable ] readonly attribute WindowProxy ? parent ;
readonly attribute Element ? frameElement ;
WindowProxy ? open (optional USVString url = "", optional DOMString target = "_blank", optional [LegacyNullToEmptyString ] DOMString features = "");
// 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.
getter object (DOMString name );
// the user agent
readonly attribute Navigator navigator ;
[Replaceable ] readonly attribute Navigator clientInformation ; // legacy alias of .navigator
readonly attribute boolean originAgentCluster ;
// user prompts
undefined alert ();
undefined alert (DOMString message );
boolean confirm (optional DOMString message = "");
DOMString ? prompt (optional DOMString message = "", optional DOMString default = "");
undefined print ();
undefined postMessage (any message , USVString targetOrigin , optional sequence <object > transfer = []);
undefined postMessage (any message , optional WindowPostMessageOptions options = {});
// also has obsolete members
};
Window includes GlobalEventHandlers ;
Window includes WindowEventHandlers ;
dictionary WindowPostMessageOptions : StructuredSerializeOptions {
USVString targetOrigin = "/";
};window.windowSupport in all current engines.
window.framesSupport in all current engines.
window.selfSupport in all current engines.
These attributes all return window.
window.documentSupport in all current engines.
Returns the Document associated with window.
document.defaultViewSupport in all current engines.
Returns the Window associated with document, if there is one, or null otherwise.
The Window object 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.
A Window's browsing context is
its associated Document's browsing context. It is either null or a
browsing context.
A Window's navigable is
the navigable whose active document is the
Window's associated
Document's, or null if there is no such navigable.
The window, frames, and self getter steps are to return this's relevant realm.[[GlobalEnv]].[[GlobalThisValue]].
The document getter steps
are to return this's associated
Document.
The Document object associated with a Window object can
change in exactly one case: when the navigate algorithm creates a new Document object for the
first page loaded in a browsing context. In that specific case, the
Window object of the initial
about:blank page is reused and gets a new Document object.
The defaultView getter steps are:
If this's browsing context is null, then return null.
Return this's browsing context's
WindowProxy object.
Support in all current engines.
For historical reasons, Window objects must also have a writable, configurable,
non-enumerable property named HTMLDocument whose value is the
Document interface object.
window = window.open([ url [, target [, features ] ] ])Support in all current engines.
Opens a window to show url (defaults to "about:blank"), and returns
it. target (defaults to "_blank") gives the name of the new
window. If a window already exists with that name, it is reused. The features
argument can contain a set of comma-separated tokens:
noopener"noreferrer"These behave equivalently to the noopener and noreferrer link types on hyperlinks.
popup"Encourages user agents to provide a minimal web browser user interface for the new
window. (Impacts the visible getter on all
BarProp objects as well.)
globalThis. open( "https://email.example/message/CAOOOkFcWW97r8yg=SsWg7GgCmp4suVX9o85y8BvNRqMjuc5PXg" , undefined , "noopener,popup" ); window.name [ = value ]Support in all current engines.
Returns the name of the window.
Can be set, to change the name.
window.close()Support in all current engines.
Closes the window.
window.closedSupport in all current engines.
Returns true if the window has been closed, false otherwise.
window.stop()Support in all current engines.
Cancels the document load.
The window open steps, given a string url, a string target, and a string features, are as follows:
If the event loop's termination nesting level is nonzero, return null.
Let sourceDocument be the entry global object's associated Document.
If target is the empty string, then set target to "_blank".
Let tokenizedFeatures be the result of tokenizing features.
Let noopener and noreferrer be false.
If tokenizedFeatures["noopener"] exists, then:
Set noopener to the result of parsing
tokenizedFeatures["noopener"] as a boolean
feature.
Remove tokenizedFeatures["noopener"].
If tokenizedFeatures["noreferrer"] exists, then:
Set noreferrer to the result of parsing
tokenizedFeatures["noreferrer"] as a boolean
feature.
Remove tokenizedFeatures["noreferrer"].
Let referrerPolicy be the empty string.
If noreferrer is true, then set noopener to true and set
referrerPolicy to "no-referrer".
Let targetNavigable and windowType be the result of applying the rules for choosing a navigable given target, sourceDocument's node navigable, 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 targetNavigable is null, then return null.
If windowType is either "new and unrestricted" or "new with no opener", then:
Set targetNavigable's active browsing context's is popup to the result of checking if a popup window is requested, given tokenizedFeatures.
Set up browsing context features for targetNavigable's active browsing context given tokenizedFeatures. [CSSOMVIEW]
Let urlRecord be the URL record
about:blank.
If url is not the empty string, then set urlRecord to the result of encoding-parsing a URL given url, relative to the entry settings object.
If urlRecord is failure, then throw a "SyntaxError"
DOMException.
If urlRecord matches about:blank, then perform the
URL and history update steps given targetNavigable's active document and urlRecord.
This is necessary in case url is something like about:blank?foo. If url is just plain about:blank, this will do nothing.
Otherwise, navigate targetNavigable to urlRecord using sourceDocument, with referrerPolicy set to referrerPolicy and exceptionsEnabled set to true.
Otherwise:
If url is not the empty string, then:
Let urlRecord be the result of encoding-parsing a URL url, relative to the entry settings object.
If urlRecord is failure, then throw a
"SyntaxError" DOMException.
Navigate targetNavigable to urlRecord using sourceDocument, with referrerPolicy set to referrerPolicy and exceptionsEnabled set to true.
If noopener is false, then set targetNavigable's active browsing context's opener browsing context to sourceDocument's browsing context.
If noopener is true or windowType is "new with no
opener", then return null.
Return targetNavigable's active
WindowProxy.
The open(url, target,
features) method steps are to run the window open steps with
url, target, and features.
The method provides a mechanism for navigating an existing browsing context or opening and navigating an auxiliary browsing context.
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.
To check if a window feature is set, given tokenizedFeatures, featureName, and defaultValue:
If tokenizedFeatures[featureName] exists, then return the result of parsing tokenizedFeatures[featureName] as a boolean feature.
Return defaultValue.
To check if a popup window is requested, given tokenizedFeatures:
If tokenizedFeatures is empty, then return false.
If tokenizedFeatures["popup"] exists, then return the result of parsing
tokenizedFeatures["popup"] as a boolean
feature.
Let location be the result of checking if
a window feature is set, given tokenizedFeatures, "location", and false.
Let toolbar be the result of checking if
a window feature is set, given tokenizedFeatures, "toolbar", and false.
If location and toolbar are both false, then return true.
Let menubar be the result of checking if
a window feature is set, given tokenizedFeatures, "menubar", and false.
If menubar is false, then return true.
Let resizable be the result of checking if
a window feature is set, given tokenizedFeatures, "resizable", and true.
If resizable is false, then return true.
Let scrollbars be the result of checking
if a window feature is set, given tokenizedFeatures, "scrollbars", and false.
If scrollbars is false, then return true.
Let status be the result of checking if
a window feature is set, given tokenizedFeatures, "status", and false.
If status is false, then return true.
Return false.
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".
To parse a boolean feature given a string value:
If value is the empty string, then return true.
If value is "yes", then return
true.
If value is "true", then return
true.
Let parsed be the result of parsing value as an integer.
If parsed is an error, then set it to 0.
Return false if parsed is 0, and true otherwise.
The name getter steps are:
Return this's navigable's target name.
The name setter steps are:
Set this's navigable's active session history entry's document state's navigable target name to the given value.
The name gets reset when the navigable is navigated to another origin.
The close() method steps
are:
If thisTraversable is not a top-level traversable, then return.
If thisTraversable's is closing is true, then return.
Let browsingContext be thisTraversable's active browsing context.
Let sourceSnapshotParams be the result of snapshotting source snapshot params given thisTraversable's active document.
If all the following are true:
thisTraversable is script-closable;
the incumbent global object's browsing context is familiar with browsingContext; and
the incumbent global object's navigable is allowed by sandboxing to navigate thisTraversable, given sourceSnapshotParams,
then:
Set thisTraversable's is closing to true.
Queue a task on the DOM manipulation task source to definitely close thisTraversable.
A navigable is script-closable if its active browsing context 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 traversable whose session history entries's size is 1.
The closed getter
steps are to return true if this's browsing context
is null or its is closing is true; otherwise false.
The stop() method steps
are:
Window objectwindow.length