History
interface
Location
interface
The
sequence
of
Document
s
in
a
browsing
context
is
its
session
history
.
Each
browsing
context
,
including
nested
browsing
contexts
,
has
a
distinct
session
history.
A
browsing
context
's
session
history
consists
of
a
flat
list
of
session
history
entries
.
Each
session
history
entry
consists,
at
a
minimum,
of
a
URL
,
and
each
entry
may
in
addition
have
serialized
state
,
a
title,
a
Document
object,
form
data,
a
scroll
restoration
mode
,
a
scroll
position,
a
browsing
context
name
,
and
other
information
associated
with
it.
Each
entry,
when
first
created,
has
a
Document
.
However,
when
a
Document
is
not
active
,
it's
possible
for
it
to
be
discarded
to
free
resources.
The
URL
and
other
data
in
a
session
history
entry
is
then
used
to
bring
a
new
Document
into
being
to
take
the
place
of
the
original,
in
case
the
user
agent
finds
itself
having
to
reactivate
that
Document
.
Titles
associated
with
session
history
entries
need
not
have
any
relation
with
the
current
title
of
the
Document
.
The
title
of
a
session
history
entry
is
intended
to
explain
the
state
of
the
document
at
that
point,
so
that
the
user
can
navigate
the
document's
history.
URLs without associated serialized state are added to the session history as the user (or script) navigates from page to page.
Each
Document
object
in
a
browsing
context
's
session
history
is
associated
with
a
unique
History
object
which
must
all
model
the
same
underlying
session
history
.
The
history
attribute
of
the
Window
interface
must
return
the
object
implementing
the
History
interface
for
this
Window
object's
associated
Document
.
Serialized state is a serialization (via StructuredSerializeForStorage ) of an object representing a user interface state. We sometimes informally refer to "state objects", which are the objects representing user interface state supplied by the author, or alternately the objects created by deserializing (via StructuredDeserialize ) serialized state.
Pages can add serialized state to the session history. These are then deserialized and returned to the script when the user (or script) goes back in the history, thus enabling authors to use the "navigation" metaphor even in one-page applications.
Serialized
state
is
intended
to
be
used
for
two
main
purposes:
first,
storing
a
preparsed
description
of
the
state
in
the
URL
so
that
in
the
simple
case
an
author
doesn't
have
to
do
the
parsing
(though
one
would
still
need
the
parsing
for
handling
URLs
passed
around
by
users,
so
it's
only
a
minor
optimization).
Second,
so
that
the
author
can
store
state
that
one
wouldn't
store
in
the
URL
because
it
only
applies
to
the
current
Document
instance
and
it
would
have
to
be
reconstructed
if
a
new
Document
were
opened.
An
example
of
the
latter
would
be
something
like
keeping
track
of
the
precise
coordinate
from
which
a
pop-up
div
was
made
to
animate,
so
that
if
the
user
goes
back,
it
can
be
made
to
animate
to
the
same
location.
Or
alternatively,
it
could
be
used
to
keep
a
pointer
into
a
cache
of
data
that
would
be
fetched
from
the
server
based
on
the
information
in
the
URL
,
so
that
when
going
back
and
forward,
the
information
doesn't
have
to
be
fetched
again.
At any point, one of the entries in the session history is the current entry . This is the entry representing the active document of the browsing context . Which entry is the current entry is changed by the algorithms defined in this specification, e.g. during session history traversal .
The
current
entry
is
usually
an
entry
for
the
URL
of
the
Document
.
However,
it
can
also
be
one
of
the
entries
for
serialized
state
added
to
the
history
by
that
document.
An entry with persisted user state is one that also has user-agent defined state. This specification does not specify what kind of state can be stored.
For example, some user agents might want to persist the scroll position, or the values of form controls.
User
agents
that
persist
the
value
of
form
controls
are
encouraged
to
also
persist
their
directionality
(the
value
of
the
element's
dir
attribute).
This
prevents
values
from
being
displayed
incorrectly
after
a
history
traversal
when
the
user
had
originally
entered
the
values
with
an
explicit,
non-default
directionality.
An entry's scroll restoration mode indicates whether the user agent should restore the persisted scroll position (if any) when traversing to it. The scroll restoration mode may be one of the following:
auto
"
manual
"
If
unspecified,
the
scroll
restoration
mode
of
a
new
entry
must
be
set
to
"
auto
".
Entries
that
contain
serialized
state
share
the
same
Document
as
the
entry
for
the
page
that
was
active
when
they
were
added.
Contiguous
entries
that
differ
just
by
their
URLs
'
fragments
also
share
the
same
Document
.
All
entries
that
share
the
same
Document
(and
that
are
therefore
merely
different
states
of
one
particular
document)
are
contiguous
by
definition.
Each
Document
in
a
browsing
context
can
also
have
a
latest
entry
.
This
is
the
entry
for
that
Document
to
which
the
browsing
context
's
session
history
was
most
recently
traversed.
When
a
Document
is
created,
it
initially
has
no
latest
entry
.
User
agents
may
discard
the
Document
objects
of
entries
other
than
the
current
entry
that
are
not
referenced
from
any
script,
reloading
the
pages
afresh
when
the
user
or
script
navigates
back
to
such
pages.
This
specification
does
not
specify
when
user
agents
should
discard
Document
objects
and
when
they
should
cache
them.
Entries
that
have
had
their
Document
objects
discarded
must,
for
the
purposes
of
the
algorithms
given
below,
act
as
if
they
had
not.
When
the
user
or
script
navigates
back
or
forwards
to
a
page
which
has
no
in-memory
DOM
objects,
any
other
entries
that
shared
the
same
Document
object
with
it
must
share
the
new
object
as
well.
History
interface
enum ScrollRestoration { "auto", "manual" };
[Exposed=Window]
interface History {
readonly attribute unsigned long length;
attribute ScrollRestoration scrollRestoration;
readonly attribute any state;
void go(optional long delta = 0);
void back();
void forward();
void pushState(any data, DOMString title, optional USVString? url = null);
void replaceState(any data, DOMString title, optional USVString? url = null);
};
history
.
length
Returns the number of entries in the joint session history .
history
.
scrollRestoration
[
=
value
]
Returns the scroll restoration mode of the current entry in the session history .
Can be set, to change the scroll restoration mode of the current entry in the session history .
history
.
state
Returns the current serialized state , deserialized into an object.
history
.
go
(
[
delta
]
)
Goes back or forward the specified number of steps in the joint session history .
A zero delta will reload the current page.
If the delta is out of range, does nothing.
history
.
back
()
Goes back one step in the joint session history .
If there is no previous page, does nothing.
history
.
forward
()
Goes forward one step in the joint session history .
If there is no next page, does nothing.
history
.
pushState
(
data
,
title
[,
url
]
)
Pushes the given data onto the session history, with the given title, and, if provided and not null, the given URL.
history
.
replaceState
(
data
,
title
[,
url
]
)
Updates the current entry in the session history to have the given data, title, and, if provided and not null, URL.
The
joint
session
history
of
a
top-level
browsing
context
is
the
union
of
all
the
session
histories
of
all
browsing
contexts
of
all
the
fully
active
Document
objects
that
share
that
top-level
browsing
context
,
with
all
the
entries
that
are
current
entries
in
their
respective
session
histories
removed
except
for
the
current
entry
of
the
joint
session
history
.
The current entry of the joint session history is the entry that most recently became a current entry in its session history .
Entries in the joint session history are ordered chronologically by the time they were added to their respective session histories . Each entry has an index; the earliest entry has index 0, and the subsequent entries are numbered with consecutively increasing integers (1, 2, 3, etc).
Since
each
Document
in
a
browsing
context
might
have
a
different
event
loop
,
the
actual
state
of
the
joint
session
history
can
be
somewhat
nebulous.
For
example,
two
sibling
iframe
elements
could
both
traverse
from
one
unique
origin
to
another
at
the
same
time,
so
their
precise
order
might
not
be
well-defined;
similarly,
since
they
might
only
find
out
about
each
other
later,
they
might
disagree
about
the
length
of
the
joint
session
history
.
The
length
attribute
of
the
History
interface,
on
getting,
must
return
the
number
of
entries
in
the
top-level
browsing
context
's
joint
session
history
.
If
this
History
object
is
associated
with
a
Document
that
is
not
fully
active
,
getting
must
instead
throw
a
"
SecurityError
"
DOMException
.
The actual entries are not accessible from script.
The
scrollRestoration
attribute
of
the
History
interface,
on
getting,
must
return
the
scroll
restoration
mode
of
the
current
entry
in
the
session
history
.
On
setting,
the
scroll
restoration
mode
of
the
current
entry
in
the
session
history
must
be
set
to
the
new
value.
If
this
History
object
is
associated
with
a
Document
that
is
not
fully
active
,
both
getting
and
setting
must
instead
throw
a
"
SecurityError
"
DOMException
.
The
state
attribute
of
the
History
interface,
on
getting,
must
return
the
last
value
it
was
set
to
by
the
user
agent.
If
this
History
object
is
associated
with
a
Document
that
is
not
fully
active
,
getting
must
instead
throw
a
"
SecurityError
"
DOMException
.
Initially,
its
value
must
be
null.
When
the
go(
delta
)
method
is
invoked,
if
delta
is
zero,
the
user
agent
must
act
as
if
the
location.reload()
method
was
called
instead.
Otherwise,
the
user
agent
must
traverse
the
history
by
a
delta
whose
value
is
delta
.
If
this
History
object
is
associated
with
a
Document
that
is
not
fully
active
,
invoking
must
instead
throw
a
"
SecurityError
"
DOMException
.
When
the
back()
method
is
invoked,
the
user
agent
must
traverse
the
history
by
a
delta
−1.
If
this
History
object
is
associated
with
a
Document
that
is
not
fully
active
,
invoking
must
instead
throw
a
"
SecurityError
"
DOMException
.
When
the
forward()
method
is
invoked,
the
user
agent
must
traverse
the
history
by
a
delta
+1.
If
this
History
object
is
associated
with
a
Document
that
is
not
fully
active
,
invoking
must
instead
throw
a
"
SecurityError
"
DOMException
.
Each top-level browsing context has a session history traversal queue , initially empty, to which tasks can be added.
Each top-level browsing context , when created, must begin running the following algorithm, known as the session history event loop for that top-level browsing context , in parallel :
Wait until this top-level browsing context 's session history traversal queue is not empty.
Pull the first task from this top-level browsing context 's session history traversal queue , and execute it.
Return to the first step of this algorithm.
The session history event loop helps coordinate cross-browsing-context transitions of the joint session history : since each browsing context might, at any particular time, have a different event loop (this can happen if the user agent has more than one event loop per unit of related browsing contexts ), transitions would otherwise have to involve cross-event-loop synchronization.
To traverse the history by a delta delta , the user agent must append a task to this top-level browsing context 's session history traversal queue , the task consisting of running the following steps:
If the index of the current entry of the joint session history plus delta is less than zero or greater than or equal to the number of items in the joint session history , then return.
Let specified entry be the entry in the joint session history whose index is the sum of delta and the index of the current entry of the joint session history .
Let specified browsing context be the browsing context of the specified entry .
If the specified browsing context 's active document 's unload a document algorithm is currently running, return.
Queue a task that consists of running the following substeps. The relevant event loop is that of the specified browsing context 's active document . The task source for the queued task is the history traversal task source .
If
there
is
an
ongoing
attempt
to
navigate
specified
browsing
context
that
has
not
yet
matured
(i.e.
it
has
not
passed
the
point
of
making
its
Document
the
active
document
),
then
cancel
that
attempt
to
navigate
the
browsing
context
.
If
the
specified
browsing
context
's
active
document
is
not
the
same
Document
as
the
Document
of
the
specified
entry
,
then
run
these
substeps:
Prompt to unload the active document of the specified browsing context . If the user refused to allow the document to be unloaded , then return.
Unload
the
active
document
of
the
specified
browsing
context
with
the
recycle
parameter
set
to
false.
.
Traverse the history of the specified browsing context to the specified entry with the history-navigation flag set.
When the user navigates through a browsing context , e.g. using a browser's back and forward buttons, the user agent must traverse the history by a delta equivalent to the action specified by the user.
The
pushState(
data
,
title
,
url
)
method
adds
a
state
object
entry
to
the
history.
Support: history Chrome for Android 67+ Chrome 5+ iOS Safari 5.0+ UC Browser for Android 11.8+ Firefox 4+ IE 10+ Opera Mini None Safari 6+ Edge 12+ Samsung Internet 4+ Android Browser 4.2+ Opera 11.5+
Source: caniuse.com
The
replaceState(
data
,
title
,
url
)
method
updates
the
state
object,
title,
and
optionally
the
URL
of
the
current
entry
in
the
history.
When either of these methods is invoked, the user agent must run the following steps:
Let
document
be
the
unique
Document
object
this
History
object
is
associated
with.
If
document
is
not
fully
active
,
throw
a
"
SecurityError
"
DOMException
.
Optionally, return. (For example, the user agent might disallow calls to these methods that are invoked on a timer, or from event listeners that are not triggered in response to a clear user action, or that are invoked in rapid succession.)
Let
targetRealm
be
this
History
object's
relevant
Realm
.
Let serializedData be StructuredSerializeForStorage ( data ). Rethrow any exceptions.
If the third argument is not null, run these substeps:
History
object.
SecurityError
"
DOMException
.
Let new URL be the resulting URL record .
SecurityError
"
DOMException
.
SecurityError
"
DOMException
.(This
prevents
sandboxed
content
from
spoofing
other
pages
on
the
same
origin.)
If the third argument is null, then let new URL be the URL of the current entry .
If
the
method
invoked
was
the
pushState()
method:
Remove all the entries in the browsing context 's session history after the current entry . If the current entry is the last entry in the session history, then no entries are removed.
This doesn't necessarily have to affect the user agent's user interface.
Remove
any
tasks
queued
by
the
history
traversal
task
source
that
are
associated
with
any
Document
objects
in
the
top-level
browsing
context
's
document
family
.
If appropriate, update the current entry to reflect any state that the user agent wishes to persist. The entry is then said to be an entry with persisted user state .
Add a session history entry entry to the session history, after the current entry , with serializedData as the serialized state , the given title as the title, new URL as the URL of the entry, and the scroll restoration mode of the current entry in the session history as the scroll restoration mode.
Update the current entry to be this newly added entry.
Otherwise,
if
the
method
invoked
was
the
replaceState()
method:
Update the current entry in the session history so that serializedData is the entry's new serialized state , the given title is the new title, and new URL is the entry's new URL .
If the current entry in the session history represents a non-GET request (e.g. it was the result of a POST submission) then update it to instead represent a GET request.
Set document 's URL to new URL .
Since
this
is
neither
a
navigation
of
the
browsing
context
nor
a
history
traversal
,
it
does
not
cause
a
hashchange
event
to
be
fired.
Let state be StructuredDeserialize ( serializedData , targetRealm ). If this throws an exception, catch it, ignore the exception, and set state to null.
Set
history.state
to
state
.
Set
the
current
entry
's
Document
object's
latest
entry
to
the
current
entry
.
The title is purely advisory. User agents might use the title in the user interface.
User
agents
may
limit
the
number
of
state
objects
added
to
the
session
history
per
page.
If
a
page
hits
the
UA-defined
limit,
user
agents
must
remove
the
entry
immediately
after
the
first
entry
for
that
Document
object
in
the
session
history
after
having
added
the
new
entry.
(Thus
the
state
history
acts
as
a
FIFO
buffer
for
eviction,
but
as
a
LIFO
buffer
for
navigation.)
Consider a game where the user can navigate along a line, such that the user is always at some coordinate, and such that the user can bookmark the page corresponding to a particular coordinate, to return to it later.
A static page implementing the x=5 position in such a game could look like the following:
<!DOCTYPE HTML>
<!-- this is https://example.com/line?x=5 -->
<html lang="en">
<title>Line Game - 5</title>
<p>You are at coordinate 5 on the line.</p>
<p>
<a href="?x=6">Advance to 6</a> or
<a href="?x=4">retreat to 4</a>?
</p>
The problem with such a system is that each time the user clicks, the whole page has to be reloaded. Here instead is another way of doing it, using script:
<!DOCTYPE HTML>
<!-- this starts off as https://example.com/line?x=5 -->
<html lang="en">
<title>Line Game - 5</title>
<p>You are at coordinate <span id="coord">5</span> on the line.</p>
<p>
<a href="?x=6" onclick="go(1); return false;">Advance to 6</a> or
<a href="?x=4" onclick="go(-1); return false;">retreat to 4</a>?
</p>
<script>
var currentPage = 5; // prefilled by server
function go(d) {
setupPage(currentPage + d);
history.pushState(currentPage, document.title, '?x=' + currentPage);
}
onpopstate = function(event) {
setupPage(event.state);
}
function setupPage(page) {
currentPage = page;
document.title = 'Line Game - ' + currentPage;
document.getElementById('coord').textContent = currentPage;
document.links[0].href = '?x=' + (currentPage+1);
document.links[0].textContent = 'Advance to ' + (currentPage+1);
document.links[1].href = '?x=' + (currentPage-1);
document.links[1].textContent = 'retreat to ' + (currentPage-1);
}
</script>
In systems without script, this still works like the previous example. However, users that do have script support can now navigate much faster, since there is no network access for the same experience. Furthermore, contrary to the experience the user would have with just a naïve script-based approach, bookmarking and navigating the session history still work.
In
the
example
above,
the
data
argument
to
the
pushState()
method
is
the
same
information
as
would
be
sent
to
the
server,
but
in
a
more
convenient
form,
so
that
the
script
doesn't
have
to
parse
the
URL
each
time
the
user
navigates.
Applications
might
not
use
the
same
title
for
a
session
history
entry
as
the
value
of
the
document's
title
element
at
that
time.
For
example,
here
is
a
simple
page
that
shows
a
block
in
the
title
element.
Clearly,
when
navigating
backwards
to
a
previous
state
the
user
does
not
go
back
in
time,
and
therefore
it
would
be
inappropriate
to
put
the
time
in
the
session
history
title.
<!DOCTYPE HTML>
<HTML LANG=EN>
<TITLE>Line</TITLE>
<SCRIPT>
setInterval(function () { document.title = 'Line - ' + new Date(); }, 1000);
var i = 1;
function inc() {
set(i+1);
history.pushState(i, 'Line - ' + i);
}
function set(newI) {
i = newI;
document.forms.F.I.value = newI;
}
</SCRIPT>
<BODY ONPOPSTATE="set(event.state)">
<FORM NAME=F>
State: <OUTPUT NAME=I>1</OUTPUT> <INPUT VALUE="Increment" TYPE=BUTTON ONCLICK="inc()">
</FORM>
Most
applications
want
to
use
the
same
scroll
restoration
mode
value
for
all
of
their
history
entries.
To
achieve
this
they
can
set
the
scrollRestoration
attribute
as
soon
as
possible
(e.g.,
in
the
first
script
element
in
the
document's
head
element)
to
ensure
that
any
entry
added
to
the
history
session
gets
the
desired
scroll
restoration
mode.
<head>
<script>
if ('scrollRestoration' in history)
history.scrollRestoration = 'manual';
</script>
</head>
This section is non-normative.
The
History
interface
is
not
meant
to
place
restrictions
on
how
implementations
represent
the
session
history
to
the
user.
For
example,
session
history
could
be
implemented
in
a
tree-like
manner,
with
each
page
having
multiple
"forward"
pages.
This
specification
doesn't
define
how
the
linear
list
of
pages
in
the
history
object
are
derived
from
the
actual
session
history
as
seen
from
the
user's
perspective.
Similarly,
a
page
containing
two
iframe
s
has
a
history
object
distinct
from
the
iframe
s'
history
objects,
despite
the
fact
that
typical
Web
browsers
present
the
user
with
just
one
"Back"
button,
with
a
session
history
that
interleaves
the
navigation
of
the
two
inner
frames
and
the
outer
page.
Security
:
It
is
suggested
that
to
avoid
letting
a
page
"hijack"
the
history
navigation
facilities
of
a
UA
by
abusing
pushState()
,
the
UA
provide
the
user
with
a
way
to
jump
back
to
the
previous
page
(rather
than
just
going
back
to
the
previous
state).
For
example,
the
back
button
could
have
a
drop
down
showing
just
the
pages
in
the
session
history,
and
not
showing
any
of
the
states.
Similarly,
an
aural
browser
could
have
two
"back"
commands,
one
that
goes
back
to
the
previous
state,
and
one
that
jumps
straight
back
to
the
previous
page.
For
both
pushState()
and
replaceState()
,
user
agents
are
encouraged
to
prevent
abuse
of
these
APIs
via
too-frequent
calls
or
over-large
state
objects.
As
detailed
above,
the
algorithm
explicitly
allows
user
agents
to
ignore
any
such
calls
when
appropriate.
Location
interface
Each
Window
object
is
associated
with
a
unique
instance
of
a
Location
object,
allocated
when
the
Window
object
is
created.
The
Location
exotic
object
is
defined
through
a
mishmash
of
IDL,
invocation
of
JavaScript
internal
methods
post-creation,
and
overridden
JavaScript
internal
methods.
Coupled
with
its
scary
security
policy,
please
take
extra
care
while
implementing
this
excrescence.
To
create
a
Location
object,
run
these
steps:
Let
location
be
a
new
Location
platform
object
.
Perform
!
location
.[[DefineOwnProperty]]("
valueOf
",
{
[[Value]]:
%ObjProto_valueOf%
,
[[Writable]]:
false,
[[Enumerable]]:
false,
[[Configurable]]:
false
}).
Perform ! location .[[DefineOwnProperty]]( @@toPrimitive , { [[Value]]: undefined, [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }).
Set the value of the [[DefaultProperties]] internal slot of location to location .[[OwnPropertyKeys]]().
Return location .
The
addition
of
valueOf
and
@@toPrimitive
own
data
properties,
as
well
as
the
fact
that
all
of
Location
's
IDL
attributes
are
marked
[Unforgeable]
,
is
required
by
legacy
code
that
consulted
the
Location
interface,
or
stringified
it,
to
determine
the
document
URL
,
and
then
used
it
in
a
security-sensitive
way.
In
particular,
the
valueOf
,
@@toPrimitive
,
and
[Unforgeable]
stringifier
mitigations
ensure
that
code
such
as
foo[location]
=
bar
or
location
+
""
cannot
be
misdirected.
location
[
=
value
]
location
[
=
value
]
Returns
a
Location
object
with
the
current
page's
location.
Can be set, to navigate to another page.
The
Document
object's
location
attribute's
getter
must
return
this
Document
object's
relevant
global
object
's
Location
object,
if
this
Document
object
is
fully
active
,
and
null
otherwise.
The
Window
object's
location
attribute's
getter
must
return
this
Window
object's
Location
object.
Location
objects
provide
a
representation
of
the
URL
of
the
active
document
of
their
Document
's
browsing
context
,
and
allow
the
current
entry
of
the
browsing
context
's
session
history
to
be
changed,
by
adding
or
replacing
entries
in
the
history
object.
[Exposed=Window]
interface Location { // but see also additional creation steps and overridden internal methods
[Unforgeable] stringifier attribute USVString href;
[Unforgeable] readonly attribute USVString origin;
[Unforgeable] attribute USVString protocol;
[Unforgeable] attribute USVString host;
[Unforgeable] attribute USVString hostname;
[Unforgeable] attribute USVString port;
[Unforgeable] attribute USVString pathname;
[Unforgeable] attribute USVString search;
[Unforgeable] attribute USVString hash;
[Unforgeable] void assign(USVString url);
[Unforgeable] void replace(USVString url);
[Unforgeable] void reload();
[Unforgeable, SameObject] readonly attribute DOMStringList ancestorOrigins;
};
toString()
href
Returns
the
Location
object's
URL.
Can be set, to navigate to the given URL.
origin
Returns
the
Location
object's
URL's
origin.
protocol
Returns
the
Location
object's
URL's
scheme.
Can be set, to navigate to the same URL with a changed scheme.
host
Returns
the
Location
object's
URL's
host
and
port
(if
different
from
the
default
port
for
the
scheme).
Can be set, to navigate to the same URL with a changed host and port.
hostname
Returns
the
Location
object's
URL's
host.
Can be set, to navigate to the same URL with a changed host.
port
Returns
the
Location
object's
URL's
port.
Can be set, to navigate to the same URL with a changed port.
pathname
Returns
the
Location
object's
URL's
path.
Can be set, to navigate to the same URL with a changed path.
search
Returns
the
Location
object's
URL's
query
(includes
leading
"
?
"
if
non-empty).
Can
be
set,
to
navigate
to
the
same
URL
with
a
changed
query
(ignores
leading
"
?
").
hash
Returns
the
Location
object's
URL's
fragment
(includes
leading
"
#
"
if
non-empty).
Can
be
set,
to
navigate
to
the
same
URL
with
a
changed
fragment
(ignores
leading
"
#
").
assign
(
url
)
Navigates to the given URL.
replace
(
url
)
Removes the current page from the session history and navigates to the given URL.
reload
()
Reloads the current page.
ancestorOrigins
Returns
a
DOMStringList
object
listing
the
origins
of
the
ancestor
browsing
contexts
,
from
the
parent
browsing
context
to
the
top-level
browsing
context
.
A
Location
object
has
an
associated
relevant
Document
,
which
is
this
Location
object's
associated
Document
object's
browsing
context
's
active
document
.
A
Location
object
has
an
associated
url
,
which
is
this
Location
object's
relevant
Document
's
URL
.
A
Location
object
has
an
associated
ancestor
origins
list
.
When
a
Location
object
is
created,
its
ancestor
origins
list
must
be
set
to
a
DOMStringList
object
whose
associated
list
is
the
list
of
strings
that
the
following
steps
would
produce:
Let output be a new list of strings.
Let
current
be
the
browsing
context
of
the
Document
with
which
this
Location
object
is
associated.
Loop : If current has no parent browsing context , jump to the step labeled end .
Let current be current 's parent browsing context .
Append the serialization of current 's active document 's origin to output .
Return to the step labeled loop .
End : Return output .
A
Location
object
has
an
associated
Location
-object-setter
navigate
algorithm,
which
given
a
url
,
runs
these
steps:
If any of the following conditions are met, let replacement flag be unset; otherwise, let it be set:
Location
object's
relevant
Document
has
completely
loaded
,
or
click
event's
isTrusted
attribute
is
true,
or
click
event,
whose
isTrusted
attribute
is
true,
is
being
handled.
Location
-object
navigate
,
given
url
and
replacement
flag
.
To
Location
-object
navigate
,
given
a
url
and
replacement
flag
,
run
these
steps:
The source browsing context is the responsible browsing context specified by the incumbent settings object .
Navigate the browsing context to url , with the exceptions enabled flag set. Rethrow any exceptions.
If
the
replacement
flag
is
set
or
the
browsing
context
's
session
history
contains
only
one
Document
,
and
that
was
the
about:blank
Document
created
when
the
browsing
context
was
created,
then
the
navigation
must
be
done
with
replacement
enabled
.
The
href
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
Return
this
Location
object's
url
,
serialized
.
The
href
attribute's
setter
must
run
these
steps:
Parse
the
given
value
relative
to
the
entry
settings
object
.
If
that
failed,
throw
a
TypeError
exception.
Location
-object-setter
navigate
to
the
resulting
URL
record
.
The
href
attribute
setter
intentionally
has
no
security
check.
The
origin
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
Return
the
serialization
of
this
Location
object's
url
's
origin
.
The
protocol
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
Return
this
Location
object's
url
's
scheme
,
followed
by
"
:
".
The
protocol
attribute's
setter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
Let
possibleFailure
be
the
result
of
basic
URL
parsing
the
given
value,
followed
by
"
:
",
with
copyURL
as
url
and
scheme
start
state
as
state
override
.
Because
the
URL
parser
ignores
multiple
consecutive
colons,
providing
a
value
of
"
https:
"
(or
even
"
https::::
")
is
the
same
as
providing
a
value
of
"
https
".
If
possibleFailure
is
failure,
then
throw
a
"
SyntaxError
"
DOMException
.
If copyURL 's scheme is not an HTTP(S) scheme , then terminate these steps.
Location
-object-setter
navigate
to
copyURL
.
The
host
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If url 's host is null, return the empty string.
If url 's port is null, return url 's host , serialized .
Return
url
's
host
,
serialized
,
followed
by
"
:
"
and
url
's
port
,
serialized
.
The
host
attribute's
setter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If copyURL 's cannot-be-a-base-URL flag is set, terminate these steps.
Basic URL parse the given value, with copyURL as url and host state as state override .
Location
-object-setter
navigate
to
copyURL
.
The
hostname
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If
this
Location
object's
url
's
host
is
null,
return
the
empty
string.
Return
this
Location
object's
url
's
host
,
serialized
.
The
hostname
attribute's
setter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If copyURL 's cannot-be-a-base-URL flag is set, terminate these steps.
Basic URL parse the given value, with copyURL as url and hostname state as state override .
Location
-object-setter
navigate
to
copyURL
.
The
port
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If
this
Location
object's
url
's
port
is
null,
return
the
empty
string.
Return
this
Location
object's
url
's
port
,
serialized
.
The
port
attribute's
setter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If copyURL cannot have a username/password/port , then return.
If the given value is the empty string, then set copyURL 's port to null.
Otherwise, basic URL parse the given value, with copyURL as url and port state as state override .
Location
-object-setter
navigate
to
copyURL
.
The
pathname
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If url 's cannot-be-a-base-URL flag is set, return the first string in url 's path .
If url 's path is empty, then return the empty string.
Return
"
/
",
followed
by
the
strings
in
url
's
path
(including
empty
strings),
separated
from
each
other
by
"
/
".
The
pathname
attribute's
setter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If copyURL 's cannot-be-a-base-URL flag is set, terminate these steps.
Set copyURL 's path to the empty list.
Basic URL parse the given value, with copyURL as url and path start state as state override .
Location
-object-setter
navigate
to
copyURL
.
The
search
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If
this
Location
object's
url
's
query
is
either
null
or
the
empty
string,
return
the
empty
string.
Return
"
?
",
followed
by
this
Location
object's
url
's
query
.
The
search
attribute's
setter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If the given value is the empty string, set copyURL 's query to null.
Otherwise, run these substeps:
Let
input
be
the
given
value
with
a
single
leading
"
?
"
removed,
if
any.
Set copyURL 's query to the empty string.
Basic
URL
parse
input
,
with
copyURL
as
url
and
query
state
as
state
override
,
and
the
relevant
Document
's
document's
character
encoding
as
encoding
override
.
Location
-object-setter
navigate
to
copyURL
.
The
hash
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
If
this
Location
object's
url
's
fragment
is
either
null
or
the
empty
string,
return
the
empty
string.
Return
"
#
",
followed
by
this
Location
object's
url
's
fragment
.
The
hash
attribute's
setter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
Let
input
be
the
given
value
with
a
single
leading
"
#
"
removed,
if
any.
Set copyURL 's fragment to the empty string.
Basic URL parse input , with copyURL as url and fragment state as state override .
Location
-object-setter
navigate
to
copyURL
.
Unlike
the
equivalent
API
for
the
a
and
area
elements,
the
hash
attribute's
setter
does
not
special
case
the
empty
string
to
remain
compatible
with
deployed
scripts.
When
the
assign(
url
)
method
is
invoked,
the
user
agent
must
run
the
following
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
Parse
url
relative
to
the
entry
settings
object
.
If
that
failed,
throw
a
"
SyntaxError
"
DOMException
.
When
the
replace(
url
)
method
is
invoked,
the
user
agent
must
run
the
following
steps:
Parse
url
relative
to
the
entry
settings
object
.
If
that
failed,
throw
a
"
SyntaxError
"
DOMException
.
Location
-object
navigate
to
the
resulting
URL
record
with
the
replacement
flag
set.
The
replace()
method
intentionally
has
no
security
check.
When
the
reload()
method
is
invoked,
the
user
agent
must
run
the
appropriate
steps
from
the
following
list:
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
Throw
a
"
SecurityError
"
DOMException
.
resize
event
in
response
to
the
user
resizing
the
browsing
context
Repaint the browsing context and return.
iframe
srcdoc
document
Reprocess
the
iframe
attributes
of
the
browsing
context
's
browsing
context
container
.
Perform an overridden reload , with the browsing context being navigated as the responsible browsing context . Rethrow any exceptions.
Navigate
the
browsing
context
to
this
Location
object's
relevant
Document
's
URL
to
perform
an
entry
update
of
the
browsing
context
's
current
entry
,
with
the
exceptions
enabled
flag
set.
The
source
browsing
context
must
be
the
browsing
context
being
navigated.
This
is
a
reload-triggered
navigation
.
Rethrow
any
exceptions.
When
a
user
requests
that
the
active
document
of
a
browsing
context
be
reloaded
through
a
user
interface
element,
the
user
agent
should
navigate
the
browsing
context
to
the
same
resource
as
that
Document
,
to
perform
an
entry
update
of
the
browsing
context
's
current
entry
.
This
is
a
reload-triggered
navigation
.
In
the
case
of
non-idempotent
methods
(e.g.
HTTP
POST),
the
user
agent
should
prompt
the
user
to
confirm
the
operation
first,
since
otherwise
transactions
(e.g.
purchases
or
database
modifications)
could
be
repeated.
User
agents
may
allow
the
user
to
explicitly
override
any
caches
when
reloading.
If
browsing
context
's
active
document
's
reload
override
flag
is
set,
then
the
user
agent
may
instead
perform
an
overridden
reload
rather
than
the
navigation
described
in
this
paragraph
(with
the
browsing
context
being
reloaded
as
the
source
browsing
context
).
The
ancestorOrigins
attribute's
getter
must
run
these
steps:
If
this
Location
object's
relevant
Document
's
origin
is
not
same
origin-domain
with
the
entry
settings
object
's
origin
,
then
throw
a
"
SecurityError
"
DOMException
.
Otherwise,
return
this
Location
object's
ancestor
origins
list
.
The
details
of
how
the
ancestorOrigins
attribute
works
are
still
controversial
and
might
change.
See
issue
#1918
for
more
information.
As
explained
earlier,
the
Location
exotic
object
requires
additional
logic
beyond
IDL
for
security
purposes.
The
internal
slot
and
internal
methods
Location
objects
must
implement
are
defined
below.
Every
Location
object
has
a
[[DefaultProperties]]
internal
slot
representing
its
own
properties
at
time
of
its
creation.
If ! IsPlatformObjectSameOrigin ( this ) is true, then return ! OrdinaryGetPrototypeOf ( this ).
Return null.
Return ! SetImmutablePrototype ( this , V ).
Return true.
Return false.
If ! IsPlatformObjectSameOrigin ( this ) is true, then:
Let desc be ! OrdinaryGetOwnProperty ( this , P ).
If the value of the [[DefaultProperties]] internal slot of this contains P , then set desc .[[Configurable]] to true.
Return desc .
Let property be ! CrossOriginGetOwnPropertyHelper ( this , P ).
If property is not undefined, return property .
Throw
a
"
SecurityError
"
DOMException
.
If ! IsPlatformObjectSameOrigin ( this ) is true, then:
If the value of the [[DefaultProperties]] internal slot of this contains P , then return false.
Return ? OrdinaryDefineOwnProperty ( this , P , Desc ).
Throw
a
"
SecurityError
"
DOMException
.
If ! IsPlatformObjectSameOrigin ( this ) is true, then return ? OrdinaryGet ( this , P , Receiver ).
Return ? CrossOriginGet ( this , P , Receiver ).
If ! IsPlatformObjectSameOrigin ( this ) is true, then return ? OrdinarySet ( this , P , Receiver ).
Return ? CrossOriginSet ( this , P , V , Receiver ).
If ! IsPlatformObjectSameOrigin ( this ) is true, then return ? OrdinaryDelete ( this , P ).
Throw
a
"
SecurityError
"
DOMException
.
If ! IsPlatformObjectSameOrigin ( this ) is true, then return ! OrdinaryOwnPropertyKeys ( this ).
Return ! CrossOriginOwnPropertyKeys ( this ).