Window
object
WindowProxy
exotic
object
Window
object
[Global=Window,
Exposed=Window,
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();
void postMessage(any message, USVString targetOrigin, optional sequence<object> transfer = []);
};
Window includes GlobalEventHandlers;
Window
includes
WindowEventHandlers
;
window
frames
self
These attributes all return window .
document
Returns
the
Document
associated
with
window
.
defaultView
Returns
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.
closed
Returns 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 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
stop
document
loading
of
the
browsing
context
of
the
given
this
Window
object
on
which
it
was
invoked.
object's
associated
Document
.
length
Returns 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
object
Returns 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
.
Otherwise, if objects has only one element, return that element.
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
Document
s
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).
To
discard
a
Document
document
:
Set document 's salvageable state to false.
Run any unloading document cleanup steps for document that are defined by this specification and other applicable specifications .
Abort document .
Remove any tasks associated with document in any task source , without running those tasks.
Discard all the child browsing contexts of document .
Lose the strong reference from document 's browsing context to document .
Remove
document
from
the
owner
set
of
each
WorkerGlobalScope
object
whose
set
contains
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 .
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
.
visible
Returns true if the location bar is visible; otherwise, returns false.
menubar
.
visible
Returns true if the menu bar is visible; otherwise, returns false.
personalbar
.
visible
Returns true if the personal bar is visible; otherwise, returns false.
scrollbars
.
visible
Returns true if the scroll bars are visible; otherwise, returns false.
statusbar
.
visible
Returns true if the status bar is visible; otherwise, returns false.
toolbar
.
visible
Returns 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
object
BarProp
object
BarProp
object
BarProp
object
BarProp
object
visible
attribute
may
return
false).
BarProp
object
visible
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
objects
When 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
object
A
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
index
th
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 ).