Living Standard — Last Updated 24 March 2023
Window
, WindowProxy
, and Location
objectsWindow
オブジェクトWindowProxy
外来オブジェクトLocation
インターフェイスHistory
インターフェイスWindow
, 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
", @@toStringTag, @@hasInstance, or @@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
", @@toStringTag, @@hasInstance, @@isConcatSpreadable ».
This abstract operation does not return a Completion Record.
Window
オブジェクトSupport 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 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 = "");
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 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.window
Support in all current engines.
window.frames
Support in all current engines.
window.self
Support in all current engines.
これらの属性はすべてwindowを返す。
window.document
Support in all current engines.
windowと関連するDocument
を返す。
document.defaultView
Support in all current engines.
documentに関連付けられたWindow
がある場合はそれを返し、そうでなければnullを返す。
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.
url(デフォルトで"about:blank
")を表示するためのウィンドウを開き、それを返す。target(デフォルトで"_blank
")は、新しいウィンドウの名前を示す。すでにその名前をもつウィンドウが存在する場合、それが再利用される。features引数はコンマ区切りトークンの集合を含むことができる:
noopener
"noreferrer
"これらは、ハイパーリンク上のnoopener
およびnoreferrer
リンクタイプと同等に動作する。
popup
"ユーザーエージェントに、新しいウィンドウに最小限のウェブブラウザーユーザーインターフェイスを提供するように促す。 (すべてのBarProp
オブジェクトにもvisible
ゲッターに影響を与える。)
globalThis. open( "https://email.example/message/CAOOOkFcWW97r8yg=SsWg7GgCmp4suVX9o85y8BvNRqMjuc5PXg" , undefined , "noopener,popup" );
window.name [ = value ]
Support in all current engines.
ウィンドウの名前を返す。
名前を変更する設定が可能である。
window.close()
Support in all current engines.
ウィンドウを閉じる。
window.closed
Support in all current engines.
ウィンドウが閉じられている場合はtrueを返し、そうでなければfalseを返す。
window.stop()
Support in all current engines.
ドキュメントの読み込みを中止する。
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 parse url relative to the entry settings object, and set urlRecord to the resulting URL record, if any. If the parse a URL algorithm failed, 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 URL record about:blank
.
Parse url relative to the entry settings object, and set urlRecord to the resulting URL record, if any. If the parse a URL algorithm failed, 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.
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:
Let thisTraversable be null.
For each top-level traversable traversable of the user agent's top-level traversable set: if traversable's active document's relevant global object equals this, then set thisTraversable to traversable and break.
If thisTraversable is null, then return.
In this case the method is being called on a Window
that does not correspond to a top-level traversable, and so closing is not allowed.
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:
then:
Set thisTraversable's is closing to true.
Queue a task on the DOM manipulation task source to 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
オブジェクトのインデックス付きアクセスwindow.length
Support in all current engines.
文書ツリーの子ナビゲート可能の数を返す。
window[index]
指定された文書ツリーの子ナビゲート可能に対応するWindowProxy
を返す。
The length
getter steps are to return this's associated Document
's document-tree child navigables's size.
Indexed access to document-tree child navigables is defined through the [[GetOwnProperty]] internal method of the WindowProxy
object.
Window
オブジェクトの名前付きアクセスwindow[name]
指示された要素または要素のコレクションを返す。
一般的な規則として、これに依存することはもろいコードを導く。たとえば、新しい機能がウェブプラットフォームに加えられるように、いずれかのIDがこのAPIのマッピングで終わることは時間をかけて変化できる。この代わりに、document.getElementById()
またはdocument.querySelector()
を使用する。
The document-tree child navigable target name property set of a Window
object window is the return value of running these steps:
Let children be the document-tree child navigables of window's associated Document
.
Let firstNamedChildren be an empty ordered set.
For each navigable of children:
Let name be navigable's target name.
If name is the empty string, then continue.
If firstNamedChildren contains a navigable whose target name is name, then continue.
Append navigable to firstNamedChildren.
Let names be an empty ordered set.
For each navigable of firstNamedChildren:
Let name be navigable's target name.
If navigable's active document's origin is same origin with window's relevant settings object's origin, then append name to names.
Return names.
The two seperate iterations mean 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 navigable target name property set;
the value of the name
content attribute for all embed
, form
, img
, and object
elements that have a non-empty name
content attribute and are in a document tree with window's associated 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 associated Document
as their root.
To determine the value of a named property name in a Window
object window, the user agent must return the value obtained using the following steps:
Let objects be the list of named objects of window with the name name.
There will be at least one such object, by definition.
If objects contains a navigable, then:
Let container be the first navigable container in window's associated Document
's descendants whose content navigable is in objects.
Return container's content navigable's active WindowProxy
.
Otherwise, if objects has only one element, return that element.
Otherwise return an HTMLCollection
rooted at window's associated Document
, whose filter matches only named objects of window with the name name. (By definition, these will all be elements.)
Named objects of Window
object window with the name name, for the purposes of the above algorithm, consist of the following:
document-tree child navigables of window's associated Document
whose target name is name;
embed
, form
, img
, or object
elements that have a name
content attribute whose value is name and are in a document tree with window's associated Document
as their root; and
HTML elements that have an id
content attribute whose value is name and are in a document tree with window's associated Document
as their root.
window.top
Support in all current engines.
window.opener [ = value ]
Support in all current engines.
オープナーブラウジングコンテキストに対するWindowProxy
を返す。
存在しないまたはnullが設定されている場合、nullを返す。
nullに設定可能である。
window.parent
Support in all current engines.
親ナビゲート可能に対するWindowProxy
を返す。
window.frameElement
Support in all current engines.
ナビゲート可能コンテナー要素を返す。
存在しない場合、生成元をまたいだ状況でnullを返す。
The top
getter steps are:
Return this's navigable's top-level traversable's active WindowProxy
.
The opener
getter steps are:
Let current be this's browsing context.
If current is null, then return null.
If current's opener browsing context is null, then return null.
Return current's opener browsing context's WindowProxy
object.
The opener
setter steps are:
If the given value is null and this's browsing context is non-null, then set this's browsing context's opener browsing context to null.
If the given value is non-null, then return ? OrdinaryDefineOwnProperty(this, "opener
", { [[Value]]: the given value, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true }).
Setting window.opener
to null clears the opener browsing context reference. In practice, this prevents future scripts from accessing their opener browsing context's Window
object.
By default, scripts can access their opener browsing context's Window
object through the window.opener
getter. E.g., a script can set window.opener.location
, causing the opener browsing context to navigate.
The parent
getter steps are:
If navigable is null, then return null.
If navigable's parent is not null, then set navigable to navigable's parent.
Return navigable's active WindowProxy
.
The frameElement
getter steps are:
Let current be this's node navigable.
If current is null, then return null.
Let container be current's container.
If container is null, then return null.
If container's node document's origin is not same origin-domain with the current settings object's origin, then return null.
Return container.
An example of when these properties can return null is as follows:
<!DOCTYPE html>
< iframe ></ iframe >
< script >
"use strict" ;
const element = document. querySelector( "iframe" );
const iframeWindow = element. contentWindow;
element. remove();
console. assert( iframeWindow. top === null );
console. assert( iframeWindow. parent === null );
console. assert( iframeWindow. frameElement === null );
</ script >
Here the browsing context corresponding to iframeWindow
was nulled out when element
was removed from the document.
歴史的な理由から、Window
インターフェイスには、特定のウェブブラウザーインターフェイス要素の可視性を表すいくつかのプロパティがあった。
プライバシーと相互運用性の理由から、これらのプロパティは、Window
のブラウジングコンテキストのポップアッププロパティがtrueかfalseかを表す値を返すようになった。
各インターフェイス要素はBarProp
オブジェクトによって表される:
Support in all current engines.
[Exposed =Window ]
interface BarProp {
readonly attribute boolean visible ;
};
window.locationbar.visible
Support in all current engines.
window.menubar.visible
Support in all current engines.
window.personalbar.visible
Support in all current engines.
window.scrollbars.visible
Support in all current engines.
window.statusbar.visible
Support in all current engines.
window.toolbar.visible
Support in all current engines.
Window
がポップアップでない場合はtrueを返す。そうでなければfalseを返す。
Support in all current engines.
The visible
getter steps are:
Let browsingContext be this's relevant global object's browsing context.
If browsingContext is null, then return true.
Return the negation of browsingContext's top-level browsing context's is popup.
The following BarProp
objects must exist for each Window
object:
BarProp
objectBarProp
objectBarProp
objectBarProp
objectBarProp
objectBarProp
objectThe 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
objectsTo set up a window environment settings object, given a URL creationURL, a JavaScript execution context execution context, null or an environment reservedEnvironment, a URL topLevelCreationURL, and an origin topLevelOrigin, run these steps:
Let realm be the value of execution context's Realm component.
Let window be realm's global object.
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 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 policy container of window's associated Document
.
Return true if both of the following hold, and false otherwise:
realm's agent cluster's cross-origin-isolation mode is "concrete
", and
window's associated Document
is allowed to use the "cross-origin-isolated
" feature.
Return window's associated Document
's load timing info's navigation start time.
If reservedEnvironment is non-null, then:
Set settings object's id to reservedEnvironment's id, target browsing context to reservedEnvironment's target browsing context, and active service worker to reservedEnvironment's active service worker.
Set reservedEnvironment'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 target browsing context to null, and settings object's active service worker to null.
Set settings object's creation URL to creationURL, settings object's top-level creation URL to topLevelCreationURL, and settings object's top-level origin to topLevelOrigin.
Set realm's [[HostDefined]] field to settings object.
WindowProxy
外来オブジェクトWindowProxy
は、Window
の通常のオブジェクトをラップする外来オブジェクトであり、ほとんどの操作をラップされたオブジェクトに間接的に転送する。各ブラウジングコンテキストは、関連するWindowProxy
オブジェクトを持つ。ブラウジングコンテキストがナビゲートされるとき、ブラウジングコンテキストの関連付けられ WindowProxy
オブジェクトによってラップされたWindow
オブジェクトが変更される。
The WindowProxy
exotic object must use the ordinary internal methods except where it is explicitly specified otherwise below.
There is no WindowProxy
interface object.
Every WindowProxy
object has a [[Window]] internal slot representing the wrapped Window
object.
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.
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 children be the document-tree child navigables of W's associated Document
.
Let value be undefined.
If index is less than children's size, then:
Sort children in ascending order, with navigableA being less than navigableB if navigableA's container was inserted into W's associated Document
earlier than navigableB's container was.
Set value to children[index]'s active WindowProxy
.
If value is undefined, then:
If IsPlatformObjectSameOrigin(W) is true, then return undefined.
Throw a "SecurityError
" DOMException
.
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 navigable target name property set, then:
Let value be the active WindowProxy
of the named object of W 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.
Return ? CrossOriginPropertyFallback(P).
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.
Check if an access between two browsing contexts should be reported, given the current global object's browsing context, W's browsing context, P, and the current settings object.
If IsPlatformObjectSameOrigin(W) is true, then return ? OrdinaryGet(this, P, Receiver).
Return ? CrossOriginGet(this, P, Receiver).
this is passed rather than W as OrdinaryGet and CrossOriginGet will invoke the [[GetOwnProperty]] internal method.
Let W be the value of the [[Window]] internal slot of this.
Check if an access between two browsing contexts should be reported, given the current global object's browsing context, W's browsing context, P, and the current settings object.
If IsPlatformObjectSameOrigin(W) is true, then:
If P is an array index property name, then return false.
Return ? OrdinarySet(W, P, V, Receiver).
Return ? CrossOriginSet(this, P, V, Receiver).
this is passed rather than W as CrossOriginSet will invoke the [[GetOwnProperty]] internal method.
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.
falseを返す。
Return ? OrdinaryDelete(W, P).
Throw a "SecurityError
" DOMException
.
Let W be the value of the [[Window]] internal slot of this.
Let maxProperties be W's associated Document
's document-tree child navigables's size.
Let keys be the range 0 to maxProperties, exclusive.
If IsPlatformObjectSameOrigin(W) is true, then return the concatenation of keys and OrdinaryOwnPropertyKeys(W).
Return the concatenation of keys and ! CrossOriginOwnPropertyKeys(W).
Location
インターフェイスSupport in all current engines.
Support in all current engines.
Support in all current engines.
各Window
オブジェクトは、Location
オブジェクトの一意なインスタンスに関連付けられており、Window
オブジェクトの作成時に割り当てられる。
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.
Let valueOf be location's relevant realm.[[Intrinsics]].[[%Object.prototype.valueOf%]].
Perform ! location.[[DefineOwnProperty]]("valueOf
", { [[Value]]: 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 [LegacyUnforgeable]
, 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 [LegacyUnforgeable]
stringifier mitigations ensure that code such as foo[location] = bar
or location + ""
cannot be misdirected.
document.location [ = value ]
window.location [ = value ]
現在のページの位置とLocation
オブジェクトを返す。
別のページにナビゲートするために、設定可能である。
The Document
object's location
getter steps are to return this's relevant global object's Location
object, if this is fully active, and null otherwise.
The Window
object's location
getter steps are to return this's Location
object.
Location
objects provide a representation of the URL of their associated Document
, as well as methods for navigating and reloading the associated navigable.
[Exposed =Window ]
interface Location { // but see also additional creation steps and overridden internal methods
[LegacyUnforgeable ] stringifier attribute USVString href ;
[LegacyUnforgeable ] readonly attribute USVString origin ;
[LegacyUnforgeable ] attribute USVString protocol ;
[LegacyUnforgeable ] attribute USVString host ;
[LegacyUnforgeable ] attribute USVString hostname ;
[LegacyUnforgeable ] attribute USVString port ;
[LegacyUnforgeable ] attribute USVString pathname ;
[LegacyUnforgeable ] attribute USVString search ;
[LegacyUnforgeable ] attribute USVString hash ;
[LegacyUnforgeable ] undefined assign (USVString url );
[LegacyUnforgeable ] undefined replace (USVString url );
[LegacyUnforgeable ] undefined reload ();
[LegacyUnforgeable , SameObject ] readonly attribute DOMStringList ancestorOrigins ;
};
location.toString()
location.href
Support in all current engines.
Support in all current engines.
Location
オブジェクトのURLを返す。
与えられたURLにナビゲートするように、設定可能である。
location.origin
Support in all current engines.
Location
オブジェクトの生成元を返す。
location.protocol
Support in all current engines.
Location
オブジェクトのスキームを返す。
変更されたスキームと同じURLにナビゲートするように、設定可能である。
location.host
Support in all current engines.
Location
オブジェクトのURLのホストとポートを返す(スキームのデフォルトポートと異なる場合)。
変更されたホストおよびポートと同じURLにナビゲートするように、設定可能である。
location.hostname
Support in all current engines.
Location
オブジェクトのホストを返す。
変更されたホストと同じURLにナビゲートするように、設定可能である。
location.port
Support in all current engines.
Location
オブジェクトのポートを返す。
変更されたポートと同じURLにナビゲートするように、設定可能である。
location.pathname
Support in all current engines.
Location
オブジェクトのパスを返す。
変更されたパスと同じURLにナビゲートするように、設定可能である。
location.search
Support in all current engines.
Location
オブジェクトのURLのクエリーを返す(空でない場合は先頭の"?
"を含む)。
(先頭の"?
"を無視して)変更されたクエリーと同じURLにナビゲートするように、設定可能である。
location.hash
Support in all current engines.
Location
オブジェクトのURLのフラグメントを返す(空でない場合は先頭の"#
"を含む)。
(先頭の"#
"を無視して)変更されたフラグメントと同じURLにナビゲートするように、設定可能である。
location.assign(url)
Support in all current engines.
与えられたURLにナビゲートする。
location.replace(url)
Support in all current engines.
セッション履歴から現在のページを削除し、与えられたURLにナビゲートする。
location.reload()
Support in all current engines.
現在のページをリロードする。
location.ancestorOrigins
祖先ナビゲート可能のアクティブな文書の生成元を列挙する DOMStringList
オブジェクトを返す。
A Location
object has an associated relevant Document
, which is its relevant global object's browsing context's active document, if this Location
object's relevant global object's browsing context is non-null, and null otherwise.
A Location
object has an associated url, which is this Location
object's relevant Document
's URL, if this Location
object's relevant Document
is non-null, and about:blank
otherwise.
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 Location
object's relevant Document
.
While current's container document is non-null:
Set current to current's container document.
Append the serialization of current's origin to output.
Return output.
To Location
-object navigate a Location
object location to a URL url, optionally given a history handling behavior historyHandling (default "push
"):
Let navigable be location's relevant global object's navigable.
Let sourceDocument be the incumbent global object's associated Document
.
If location's relevant Document
is not yet completely loaded, and the incumbent global object does not have transient activation, then set historyHandling to "replace
".
Navigate navigable to url using sourceDocument, with exceptionsEnabled set to true and historyHandling set to historyHandling.
The href
getter steps are:
If this's relevant Document
is non-null and its origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
Return this's url, serialized.
The href
setter steps are:
If this's relevant Document
is null, then return.
Parse the given value relative to the entry settings object. If that failed, throw a "SyntaxError
" DOMException
.
The href
setter intentionally has no security check.
The origin
getter steps are:
If this's relevant Document
is non-null and its origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
Return the serialization of this's url's origin.
The protocol
getter steps are:
If this's relevant Document
is non-null and its origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
The protocol
setter steps are:
If this's relevant Document
is null, then return.
If this'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 navigate this to copyURL.
The host
getter steps are:
If this's relevant Document
is non-null and its 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
setter steps are:
If this's relevant Document
is null, then return.
If this's relevant Document
's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
If copyURL has an opaque path, then return.
Basic URL parse the given value, with copyURL as url and host state as state override.
Location
-object navigate this to copyURL.
The hostname
getter steps are:
If this's relevant Document
is non-null and its origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
Return this's url's host, serialized.
The hostname
setter steps are:
If this's relevant Document
is null, then return.
If this's relevant Document
's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
If copyURL has an opaque path, then return.
Basic URL parse the given value, with copyURL as url and hostname state as state override.
Location
-object navigate this to copyURL.
The port
getter steps are:
If this's relevant Document
is non-null and its origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
Return this's url's port, serialized.
The port
setter steps are:
If this's relevant Document
is null, then return.
If this'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 navigate this to copyURL.
The pathname
getter steps are:
If this's relevant Document
is non-null and its origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
Return the result of URL path serializing this Location
object's url.
The pathname
setter steps are:
If this's relevant Document
is null, then return.
If this's relevant Document
's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
If copyURL has an opaque path, then return.
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 navigate this to copyURL.
The search
getter steps are:
If this's relevant Document
is non-null and its origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
If this's url's query is either null or the empty string, return the empty string.
The search
setter steps are:
If this's relevant Document
is null, then return.
If this'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.
そうでなければ、以下のサブ手順を実行する:
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 null, the relevant Document
's document's character encoding, copyURL as url, and query state as state override.
Location
-object navigate this to copyURL.
The hash
getter steps are:
If this's relevant Document
is non-null and its origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
If this's url's fragment is either null or the empty string, return the empty string.
The hash
setter steps are:
If this's relevant Document
is null, then return.
If this'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.
If copyURL's fragment is this's url's fragment, then return.
This bailout is necessary for compatibility with deployed content, which redundantly sets location.hash
on scroll. It does not apply to other mechanisms of fragment navigation, such as the location.href
setter or location.assign()
.
Location
-object navigate this to copyURL.
Unlike the equivalent API for the a
and area
elements, the hash
setter does not special case the empty string, to remain compatible with deployed scripts.
The assign(url)
method steps are:
If this's relevant Document
is null, then return.
If this'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
.
The replace(url)
method steps are:
If this's relevant Document
is null, then return.
Parse url relative to the entry settings object. If that failed, throw a "SyntaxError
" DOMException
.
Location
-object navigate this to the resulting URL record given "replace
".
The replace()
method intentionally has no security check.
The reload()
method steps are:
Let document be this's relevant Document
.
If document is null, then return.
If document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError
" DOMException
.
Reload document's node navigable.
The ancestorOrigins
getter steps are:
If this's relevant Document
is null, then return an empty list.
If this'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'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 Location
object must use the ordinary internal methods except where it is explicitly specified otherwise below.
Also, 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.
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, then return property.
Return ? CrossOriginPropertyFallback(P).
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, V, 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).
History
インターフェイスSupport in all current engines.
Support in all current engines.
enum ScrollRestoration { " auto " , " manual " };
[Exposed =Window ]
interface History {
readonly attribute unsigned long length ;
attribute ScrollRestoration scrollRestoration ;
readonly attribute any state ;
undefined go (optional long delta = 0);
undefined back ();
undefined forward ();
undefined pushState (any data , DOMString unused , optional USVString ? url = null );
undefined replaceState (any data , DOMString unused , optional USVString ? url = null );
};
history.length
Support in all current engines.
現在のトラバース可能なナビゲート可能の全体のセッション履歴エントリーの数を返す。
history.scrollRestoration
Support in all current engines.
history.scrollRestoration = value
アクティブなセッション履歴エントリーのスクロール復元モードをvalueに設定する。
history.state
Support in all current engines.
JavaScript値に逆シリアル化された、アクティブなセッション履歴エントリーのシリアル化された状態を返す。
history.go()
現在のページをリロードする。
history.go(delta)
Support in all current engines.
現在のトラバース可能なナビゲート可能の全体のセッション履歴エントリーリストで、指定された数のステップを前後に移動する。
ゼロ差分は、現在のページをリロードする。
差分が範囲外の場合、何もしない。
history.back()
Support in all current engines.
現在のトラバース可能なナビゲート可能の全体のセッション履歴エントリーリストで1ステップ戻る。
前のページが存在しない場合、何もしない。
history.forward()
Support in all current engines.
現在のトラバース可能なナビゲート可能の全体のセッション履歴エントリーリストで1ステップ進める。
次のページが存在しない場合、何もしない。
history.pushState(data, "")
Support in all current engines.
シリアル化された状態をdataのシリアル化に設定して、セッション履歴に新しいエントリーを追加する。アクティブな履歴エントリーのURLがコピーされ、新しいエントリーのURLに使用される。
(2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。)
history.pushState(data, "", url)
シリアル化された状態をdataのシリアル化に設定し、URLをurlに設定して、セッション履歴に新しいエントリーを追加する。
現在のDocument
がURLをurlに書き換えることができない場合、"SecurityError
" DOMException
が投げられる。
(2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。)
history.replaceState(data, "")
Support in all current engines.
アクティブなセッション履歴エントリーのシリアル化された状態をdataの構造化されたクローンに更新する。
(2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。)
history.replaceState(data, "", url)
アクティブなセッション履歴エントリーのシリアル化された状態をdataの構造化されたクローンに更新し、そのURLをurlに更新する。
現在のDocument
がURLをurlに書き換えることができない場合、"SecurityError
" DOMException
が投げられる。
(2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。)
A Document
has a history object, a History
object.
The history
getter steps are to return this's associated Document
's history object.
Each History
object has state, initially null.
Each History
object has a length, a non-negative integer, initially 0.
Each History
object has an index, a non-negative integer, initially 0.
Although the index is not directly exposed, it can be inferred from changes to the length during synchronous navigations. In fact, that is what it's used for.
The length
getter steps are:
If this's relevant global object's associated Document
is not fully active, then throw a "SecurityError
" DOMException
.
The scrollRestoration
getter steps are:
If this's relevant global object's associated Document
is not fully active, then throw a "SecurityError
" DOMException
.
Return this's node navigable's active session history entry's scroll restoration mode.
The scrollRestoration
setter steps are:
If this's relevant global object's associated Document
is not fully active, then throw a "SecurityError
" DOMException
.
Set this's node navigable's active session history entry's scroll restoration mode to the given value.
The state
getter steps are:
If this's relevant global object's associated Document
is not fully active, then throw a "SecurityError
" DOMException
.
The go(delta)
method steps are to delta traverse this given delta.
The back()
method steps are to delta traverse this given −1.
The forward()
method steps are to delta traverse this given +1.
To delta traverse a History
object history given an integer delta:
Let document be history's relevant global object's associated Document
.
If document is not fully active, then throw a "SecurityError
" DOMException
.
If delta is 0, then reload document's node navigable.
Traverse the history by a delta given document's node navigable's traversable navigable, delta, and document.
The pushState(data, unused, url)
method steps are to run the shared history push/replace state steps given this, data, url, and "push
".
The replaceState(data, unused, url)
method steps are to run the shared history push/replace state steps given this, data, url, and "replace
".
The shared history push/replace state steps, given a History
history, a value data, a scalar value string-or-null url, and a history handling behavior historyHandling, are:
Let document be history's associated Document
.
If document is not fully active, then 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 serializedData be StructuredSerializeForStorage(data). 例外を再度投げる。
Let newURL be document's URL.
If url is not null, then:
Parse url, relative to the relevant settings object of history.
If that fails, then throw a "SecurityError
" DOMException
.
Set newURL to the resulting URL record.
If document cannot have its URL rewritten to newURL, then throw a "SecurityError
" DOMException
.
Run the URL and history update steps given document and newURL, with serializedData set to serializedData and historyHandling set to historyHandling.
User agents may limit the number of state objects added to the session history per page. If a page hits the implementation-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.)
A Document
document can have its URL rewritten to a URL targetURL if the following algorithm returns true:
Let documentURL be document's URL.
If targetURL and documentURL differ in their scheme, username, password, host, or port components, then return false.
If targetURL's scheme is an HTTP(S) scheme, then return true. (Differences in path, query, and fragment are allowed for http:
and https:
URLs.)
If targetURL's scheme is "file
", and targetURL and documentURL differ in their path component, then return false. (Differences in query and fragment are allowed for file:
URLs.)
If targetURL and documentURL differ in their path component or query components, then return false. (Only differences in fragment are allowed for other types of URLs.)
Return true.
document's URL | targetURL | can have its URL rewritten |
---|---|---|
https://example.com/home | https://example.com/home#about | ✅ |
https://example.com/home | https://example.com/home?page=shop | ✅ |
https://example.com/home | https://example.com/shop | ✅ |
https://example.com/home | https://user:pass@example.com/home | ❌ |
https://example.com/home | http://example.com/home | ❌ |
file:///path/to/x | file:///path/to/x#hash | ✅ |
file:///path/to/x | file:///path/to/x?search | ✅ |
file:///path/to/x | file:///path/to/y | ❌ |
about:blank | about:blank#hash | ✅ |
about:blank | about:blank?search | ❌ |
about:blank | about:srcdoc | ❌ |
data:text/html,foo | data:text/html,foo#hash | ✅ |
data:text/html,foo | data:text/html,foo?search | ❌ |
data:text/html,foo | data:text/html,bar | ❌ |
data:text/html,foo | data:bar | ❌ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 | blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43#hash | ✅ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 | blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43?search | ❌ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 | blob:https://example.com/anything | ❌ |
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43 | blob:path | ❌ |
Document
のURLのみが重要であり、その生成元は重要ではないことに注意する。継承された生成元をもつabout:blank
Document
、サンフォボックスiframe
、またはdocument.domain
セッターが使用されている場合のように、これらが一致しないことがある。
ユーザーはいくつかの座標に常にあり、ユーザーが後で再開するための特定の座標に対応するページをブックマークできるような、ユーザーがラインに沿って移動できるゲームを考える。
そのようなゲームでx=5位置を実装する静的ページは次のようになる:
<!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 >
このようなシステムの問題点は、毎回ユーザーがクリックするとページ全体をリロードする必要があることにある。ここで、代わりにスクリプトを使用して、リロードを行うための別の方法:
<!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, "" , '?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 >
スクリプトをもたないシステムにおいて、前の例と同じように動作する。しかし、同じ体験に対するネットワークアクセスが存在しないので、スクリプトをサポートするユーザーは現在はるかに速く移動できる。さらに、経験に反して、ユーザーは単にナイーブなスクリプトベースのアプローチ、ブックマーク、およびセッション履歴の移動が依然として動作する必要がある。
上記の例において、pushState()
メソッドへのdata引数は、サーバーに送信されるものと同じ情報であるが、スクリプトはURLにユーザーが移動するたびに解析する必要はないので、より便利な形式となる。
ほとんどのアプリケーションは、すべての履歴エントリーに同じスクロール復元モード値を使用したいと考えている。これを実現するために、できるだけ早くscrollRestoration
属性を設定して(たとえば、文書のhead
要素の最初のscript
要素で)、履歴セッションに追加されたエントリーが確実に希望のスクロール復元モードになるようにする。
< head >
< script >
if ( 'scrollRestoration' in history)
history. scrollRestoration = 'manual' ;
</ script >
</ head >
PopStateEvent
インターフェイスSupport in all current engines.
[Exposed =Window ]
interface PopStateEvent : Event {
constructor (DOMString type , optional PopStateEventInit eventInitDict = {});
readonly attribute any state ;
};
dictionary PopStateEventInit : EventInit {
any state = null ;
};
event.state
pushState()
またはreplaceState()
へ提供される情報のコピーを返す。
The state
attribute must return the value it was initialized to. It represents the context information for the event, or null, if the state represented is the initial state of the Document
.
HashChangeEvent
インターフェイスSupport in all current engines.
[Exposed =Window ]
interface HashChangeEvent : Event {
constructor (DOMString type , optional HashChangeEventInit eventInitDict = {});
readonly attribute USVString oldURL ;
readonly attribute USVString newURL ;
};
dictionary HashChangeEventInit : EventInit {
USVString oldURL = "";
USVString newURL = "";
};
event.oldURL
Support in all current engines.
以前に現在であったセッション履歴のエントリーのURLを返す。
event.newURL
Support in all current engines.
今現在であるセッション履歴のエントリーのURLを返す。
The oldURL
attribute must return the value it was initialized to. It represents context information for the event, specifically the URL of the session history entry that was traversed from.
The newURL
attribute must return the value it was initialized to. It represents context information for the event, specifically the URL of the session history entry that was traversed to.
PageTransitionEvent
インターフェイスSupport in all current engines.
[Exposed =Window ]
interface PageTransitionEvent : Event {
constructor (DOMString type , optional PageTransitionEventInit eventInitDict = {});
readonly attribute boolean persisted ;
};
dictionary PageTransitionEventInit : EventInit {
boolean persisted = false ;
};
event.persisted
Support in all current engines.
pageshow
に対して、ページが新しく読み込まれている(およびload
イベントが発生する)場合にfalseを返す。そうでなければ、trueを返す。
pagehide
イベントに対して、ページが最後の時間まで出かける場合はfalseを返す。そうでなければtrueを返す。これは、ユーザーがこのページに戻った場合(Document
のsalvageable状態がtrueのままの場合)にページが再利用される可能性があることを意味する。
ページがサルベージ不能になる原因には、次のものがある:
Document
を存続させないことを決定したiframe
を持っているWebSocket
オブジェクトDocument
の中止The persisted
attribute must return the value it was initialized to. It represents the context information for the event.
To fire a page transition event named eventName at a Window
window with a boolean persisted, fire an event named eventName at window, using PageTransitionEvent
, with the persisted
attribute initialized to persisted, the cancelable
attribute initialized to true, the bubbles
attribute initialized to true, and legacy target override flag set.
The values for cancelable
and bubbles
don't make any sense, since canceling the event does nothing and it's not possible to bubble past the Window
object. They are set to true for historical reasons.
BeforeUnloadEvent
インターフェイスSupport in all current engines.
[Exposed =Window ]
interface BeforeUnloadEvent : Event {
attribute DOMString returnValue ;
};
BeforeUnloadEvent
固有の初期化メソッドは存在しない。
BeforeUnloadEvent
インターフェイスは、イベントをキャンセルするだけでなく、returnValue
属性を空文字列以外の値に設定することで、アンロードがユーザーによってキャンセルされたかどうかをチェックできるようにするレガシーインターフェイスである。著者は、returnValue
を使用する代わりに、preventDefault()
メソッド、またはイベントをキャンセルするその他の手段を使用すべきである。
The returnValue
attribute controls the process of checking if unloading is user-canceled. When the event is created, the attribute must be set to the empty string. On getting, it must return the last value it was set to. On setting, the attribute must be set to the new value.
This attribute is a DOMString
only for historical reasons. Any value besides the empty string will be treated as a request to ask the user for confirmation.