HTML
Living Standard — Last Updated 5 May 2025
Living Standard — Last Updated 5 May 2025
Window, WindowProxy, and Location objectsWindowオブジェクトWindowProxy外来オブジェクトLocationインターフェイスHistoryインターフェイスNotRestoredReasonsインターフェイス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", %Symbol.toStringTag%, %Symbol.hasInstance%, or %Symbol.isConcatSpreadable%, then return PropertyDescriptor{ [[Value]]: undefined, [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
Throw a "SecurityError" DOMException.
Return true if the current settings object's origin is same origin-domain with O's relevant settings object's origin, and false otherwise.
This abstract operation does not return a Completion Record.
Here the current settings object roughly corresponds to the "caller", because this check occurs before the execution context for the getter/setter/method in question makes its way onto the JavaScript execution context stack. For example, in the code w.document, this step is invoked before the document getter is reached as part of the [[Get]] algorithm for the WindowProxy w.
If this abstract operation returns undefined and there is no custom behavior, the caller needs to throw a "SecurityError" DOMException. In practice this is handled by the caller calling CrossOriginPropertyFallback.
Let crossOriginKey be a tuple consisting of the current settings object, O's relevant settings object, and P.
For each e of CrossOriginProperties(O):
If SameValue(e.[[Property]], P) is true, then:
If the value of the [[CrossOriginPropertyDescriptorMap]] internal slot of O contains an entry whose key is crossOriginKey, then return that entry's value.
Let originalDesc be OrdinaryGetOwnProperty(O, P).
Let crossOriginDesc be undefined.
If e.[[NeedsGet]] and e.[[NeedsSet]] are absent, then:
Let value be originalDesc.[[Value]].
If IsCallable(value) is true, then set value to an anonymous built-in function, created in the current realm, that performs the same steps as the IDL operation P on object O.
Set crossOriginDesc to PropertyDescriptor{ [[Value]]: value, [[Enumerable]]: false, [[Writable]]: false, [[Configurable]]: true }.
Otherwise:
Let crossOriginGet be undefined.
If e.[[NeedsGet]] is true, then set crossOriginGet to an anonymous built-in function, created in the current realm, that performs the same steps as the getter of the IDL attribute P on object O.
Let crossOriginSet be undefined.
If e.[[NeedsSet]] is true, then set crossOriginSet to an anonymous built-in function, created in the current realm, that performs the same steps as the setter of the IDL attribute P on object O.
Set crossOriginDesc to PropertyDescriptor{ [[Get]]: crossOriginGet, [[Set]]: crossOriginSet, [[Enumerable]]: false, [[Configurable]]: true }.
Create an entry in the value of the [[CrossOriginPropertyDescriptorMap]] internal slot of O with key crossOriginKey and value crossOriginDesc.
Return crossOriginDesc.
Return undefined.
This abstract operation does not return a Completion Record.
The reason that the property descriptors produced here are configurable is to preserve the invariants of the essential internal methods required by the JavaScript specification. In particular, since the value of the property can change as a consequence of navigation, it is required that the property be configurable. (However, see tc39/ecma262 issue #672 and references to it elsewhere in this specification for cases where we are not able to preserve these invariants, for compatibility with existing web content.) [JAVASCRIPT]
The reason the property descriptors are non-enumerable, despite this mismatching the same-origin behavior, is for compatibility with existing web content. See issue #3183 for details.
Let desc be ? O.[[GetOwnProperty]](P).
Assert: desc is not undefined.
If IsDataDescriptor(desc) is true, then return desc.[[Value]].
Assert: IsAccessorDescriptor(desc) is true.
Let getter be desc.[[Get]].
If getter is undefined, then throw a "SecurityError" DOMException.
Return ? Call(getter, Receiver).
Let desc be ? O.[[GetOwnProperty]](P).
Assert: desc is not undefined.
If desc.[[Set]] is present and its value is not undefined, then:
Perform ? Call(desc.[[Set]], Receiver, « V »).
Return true.
Throw a "SecurityError" DOMException.
Let keys be a new empty List.
For each e of CrossOriginProperties(O), append e.[[Property]] to keys.
Return the concatenation of keys and « "then", %Symbol.toStringTag%, %Symbol.hasInstance%, %Symbol.isConcatSpreadable% ».
This abstract operation does not return a Completion Record.
Windowオブジェクト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 Navigation navigation ;
readonly attribute CustomElementRegistry customElements ;
[Replaceable ] readonly attribute BarProp locationbar ;
[Replaceable ] readonly attribute BarProp menubar ;
[Replaceable ] readonly attribute BarProp personalbar ;
[Replaceable ] readonly attribute BarProp scrollbars ;
[Replaceable ] readonly attribute BarProp statusbar ;
[Replaceable ] readonly attribute BarProp toolbar ;
attribute DOMString status ;
undefined close ();
readonly attribute boolean closed ;
undefined stop ();
undefined focus ();
undefined blur ();
// other browsing contexts
[Replaceable ] readonly attribute WindowProxy frames ;
[Replaceable ] readonly attribute unsigned long length ;
[LegacyUnforgeable ] readonly attribute WindowProxy ?top ;
attribute any opener ;
[Replaceable ] readonly attribute WindowProxy ?parent ;
readonly attribute Element ?frameElement ;
WindowProxy ?open (optional USVString url = "", optional DOMString target = "_blank", optional [LegacyNullToEmptyString ] DOMString features = "");
// Since this is the global object, the IDL named getter adds a NamedPropertiesObject exotic
// object on the prototype chain. Indeed, this does not make the global object an exotic object.
// Indexed access is taken care of by the WindowProxy exotic object.
getter object (DOMString name );
// the user agent
readonly attribute Navigator navigator ;
[Replaceable ] readonly attribute Navigator clientInformation ; // legacy alias of .navigator
readonly attribute boolean originAgentCluster ;
// user prompts
undefined alert ();
undefined alert (DOMString message );
boolean confirm (optional DOMString message = "");
DOMString ?prompt (optional DOMString message = "", optional DOMString default = "");
undefined print ();
undefined postMessage (any message , USVString targetOrigin , optional sequence <object > transfer = []);
undefined postMessage (any message , optional WindowPostMessageOptions options = {});
// also has obsolete members
};
Window includes GlobalEventHandlers ;
Window includes WindowEventHandlers ;
dictionary WindowPostMessageOptions : StructuredSerializeOptions {
USVString targetOrigin = "/";
};window.windowSupport in all current engines.
window.framesSupport in all current engines.
window.selfSupport in all current engines.
これらの属性はすべてwindowを返す。
window.documentSupport in all current engines.
windowと関連するDocumentを返す。
document.defaultViewSupport 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.closedSupport in all current engines.
ウィンドウが閉じられている場合はtrueを返し、そうでなければfalseを返す。
window.stop()Support in all current engines.
ドキュメントの読み込みを中止する。
To get noopener for window open, given a Document sourceDocument, an ordered map tokenizedFeatures, and a URL record-or-null url, perform the following steps. They return a boolean.
If url is not null and url's blob URL entry is not null:
Let blobOrigin be url's blob URL entry's environment's origin.
Let topLevelOrigin be sourceDocument's relevant settings object's top-level origin.
If blobOrigin is not same site with topLevelOrigin, then return true.
Let noopener be false.
If tokenizedFeatures["noopener"] exists, then set noopener to the result of parsing tokenizedFeatures["noopener"] as a boolean feature.
Return noopener.
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, then return null.
Let sourceDocument be the entry global object's associated Document.
Let urlRecord be null.
If url is not the empty string, then:
Set urlRecord to the result of encoding-parsing a URL given url, relative to sourceDocument.
If urlRecord is failure, then throw a "SyntaxError" DOMException.
If target is the empty string, then set target to "_blank".
Let tokenizedFeatures be the result of tokenizing features.
Let noreferrer be false.
If tokenizedFeatures["noreferrer"] exists, then set noreferrer to the result of parsing tokenizedFeatures["noreferrer"] as a boolean feature.
Let noopener be the result of getting noopener for window open with sourceDocument, tokenizedFeatures, and urlRecord.
Remove tokenizedFeatures["noopener"] and 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]
If urlRecord is null, then set urlRecord to a URL record representing about:blank.
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 urlRecord is not null, then 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:
If thisTraversable is not a top-level traversable, then return.
If thisTraversable's is closing is true, then return.
Let browsingContext be thisTraversable's active browsing context.
Let sourceSnapshotParams be the result of snapshotting source snapshot params given thisTraversable's active document.
If all the following are true:
thisTraversable is script-closable;
the incumbent global object's browsing context is familiar with browsingContext; and
the incumbent global object's navigable is allowed by sandboxing to navigate thisTraversable, given sourceSnapshotParams,
then:
Set thisTraversable's is closing to true.
Queue a task on the DOM manipulation task source to definitely close thisTraversable.
A navigable is script-closable if it is a top-level traversable, and any of the following are true:
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.lengthSupport 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, since the algorithm would otherwise not have been invoked by Web IDL.
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.
Since the Window interface has the [Global] extended attribute, its named properties follow the rules for named properties objects rather than legacy platform objects.
window.topSupport in all current engines.
window.opener [ = value ]Support in all current engines.
オープナーブラウジングコンテキストに対するWindowProxyを返す。
存在しないまたはnullが設定されている場合、nullを返す。
nullに設定可能である。
window.parentSupport in all current engines.
親ナビゲート可能に対するWindowProxyを返す。
window.frameElementSupport 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 perform ? DefinePropertyOrThrow(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.visibleSupport in all current engines.
window.menubar.visibleSupport in all current engines.
window.personalbar.visibleSupport in all current engines.
window.scrollbars.visibleSupport in all current engines.
window.statusbar.visibleSupport in all current engines.
window.toolbar.visibleSupport 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 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]](%Symbol.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 %Symbol.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, %Symbol.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.hrefSupport in all current engines.
Support in all current engines.
LocationオブジェクトのURLを返す。
与えられたURLにナビゲートするように、設定可能である。
location.originSupport in all current engines.
Locationオブジェクトの生成元を返す。
location.protocolSupport in all current engines.
Locationオブジェクトのスキームを返す。
変更されたスキームと同じURLにナビゲートするように、設定可能である。
location.hostSupport in all current engines.
LocationオブジェクトのURLのホストとポートを返す（スキームのデフォルトポートと異なる場合）。
変更されたホストおよびポートと同じURLにナビゲートするように、設定可能である。
location.hostnameSupport in all current engines.
Locationオブジェクトのホストを返す。
変更されたホストと同じURLにナビゲートするように、設定可能である。
location.portSupport in all current engines.
Locationオブジェクトのポートを返す。
変更されたポートと同じURLにナビゲートするように、設定可能である。
location.pathnameSupport in all current engines.
Locationオブジェクトのパスを返す。
変更されたパスと同じURLにナビゲートするように、設定可能である。
location.searchSupport in all current engines.
LocationオブジェクトのURLのクエリーを返す（空でない場合は先頭の"?"を含む）。
（先頭の"?"を無視して）変更されたクエリーと同じURLにナビゲートするように、設定可能である。
location.hashSupport 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 NavigationHistoryBehavior historyHandling (default "auto"):
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.
Let url be the result of encoding-parsing a URL given the given value, relative to the entry settings object.
If url is failure, then throw a "SyntaxError" DOMException.
Location-object navigate this to url.
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 thisURLFragment be copyURL's fragment if it is non-null; otherwise the empty string.
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 thisURLFragment, 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.
Let urlRecord be the result of encoding-parsing a URL given url, relative to the entry settings object.
If urlRecord is failure, then throw a "SyntaxError" DOMException.
Location-object navigate this to urlRecord.
The replace(url) method steps are:
If this's relevant Document is null, then return.
Let urlRecord be the result of encoding-parsing a URL given url, relative to the entry settings object.
If urlRecord is failure, then throw a "SyntaxError" DOMException.
Location-object navigate this to urlRecord 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.lengthSupport in all current engines.
現在のトラバース可能なナビゲート可能の全体のセッション履歴エントリーの数を返す。
history.scrollRestorationSupport in all current engines.
history.scrollRestoration = valueアクティブなセッション履歴エントリーのスクロール復元モードをvalueに設定する。
history.stateSupport in all current engines.
アクティブなセッション履歴エントリーのクラシック履歴API状態を、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.
クラシック履歴API状態をデータのシリアル化に設定して、セッション履歴に新しいエントリーを追加する。アクティブな履歴エントリーのURLがコピーされ、新しいエントリーのURLに使用される。
（2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。）
history.pushState(data, "", url)クラシック履歴API状態をデータのシリアル化に設定し、 URLをurlに設定して、セッション履歴に新しいエントリーを追加する。
現在のDocumentがURLをurlに書き換えることができない場合、"SecurityError" DOMExceptionが投げられる。
（2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。）
history.replaceState(data, "")Support in all current engines.
アクティブセッション履歴エントリーのクラシック履歴API状態を、 データの構造化クローンに更新する。
（2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。）
history.replaceState(data, "", url)アクティブなセッション履歴エントリーのクラシック履歴API状態を データの構造化クローンに更新し、その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 relevant global object's 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 relevant global object's 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, and return.
Traverse the history by a delta given document's node navigable's traversable navigable, delta, and with sourceDocument set to 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 relevant global object's associated Document.
If document is not fully active, then throw a "SecurityError" DOMException.
Optionally, throw a "SecurityError" DOMException. (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 or the empty string, then:
Set newURL to the result of encoding-parsing a URL given url, relative to the relevant settings object of history.
If newURL is failure, then throw a "SecurityError" DOMException.
If document cannot have its URL rewritten to newURL, then throw a "SecurityError" DOMException.
The special case for the empty string here is historical, and leads to different resulting URLs when comparing code such as location.href = "" (which performs URL parsing on the empty string) versus history.pushState(null, "", "") (which bypasses it).
Let navigation be history's relevant global object's navigation API.
Let continue be the result of firing a push/replace/reload navigate event at navigation with navigationType set to historyHandling, isSameDocument set to true, destinationURL set to newURL, and classicHistoryAPIState set to serializedData.
If continue is false, then return.
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", then:
If targetURL and documentURL differ in their path component, then return false.
Return true.
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 >
この節は非規範的である。
グローバルnavigationプロパティによって提供されるナビゲーションAPIは、ナビゲーションおよび履歴エントリーを管理するための最新のウェブアプリケーションに焦点を当てた方法を提供する。これは、従来のlocationおよびhistoryの後継である。
APIが提供する機能の1つは、セッション履歴エントリーの検査である。たとえば、次の例では、エントリーのURLが順序付きリストに表示される：
const ol = document. createElement( "ol" );
ol. start = 0 ; // so that the list items' ordinal values match up with the entry indices
for ( const entry of navigation. entries()) {
const li = document. createElement( "li" );
if ( entry. index < navigation. currentEntry. index) {
li. className = "backward" ;
} else if ( entry. index > navigation. currentEntry. index) {
li. className = "forward" ;
} else {
li. className = "current" ;
}
li. textContent = entry. url;
ol. append( li);
} navigation.entries()配列にはNavigationHistoryEntryインスタンスが含まれており、これには、ここに示すurlおよびindexプロパティに加えて、その他の便利なプロパティがある。配列には、現在のナビゲート可能を表すNavigationHistoryEntryオブジェクトのみが含まれるため、その内容は、iframeなどのナビゲート可能なコンテナー内のナビゲーションまたは、ナビゲーションAPI自身がiframe内で使用されている場合の親ナビゲート可能のナビゲーションの影響を受けないことに注意する。さらに、同一生成元セッション履歴エントリーを表す NavigationHistoryEntryオブジェクトのみが含まれる。つまり、ユーザーが現在の生成元の前後に他の生成元を訪問した場合、対応するNavigationHistoryEntryは存在しない。
ナビゲーションAPIを使用して、履歴をナビゲート、リロード、またはトラバースすることもできる：
< button onclick = "navigation.reload()" > Reload</ button >
< input type = "url" id = "navigationURL" >
< button onclick = "navigation.navigate(navigationURL.value)" > Navigate</ button >
< button id = "backButton" onclick = "navigation.back()" > Back</ button >
< button id = "forwardButton" onclick = "navigation.forward()" > Forward</ button >
< select id = "traversalDestinations" ></ select >
< button id = "goButton" onclick = "navigation.traverseTo(traversalDestinations.value)" > Traverse To</ button >
< script >
backButton. disabled = ! navigation. canGoBack;
forwardButton. disabled = ! navigation. canGoForward;
for ( const entry of navigation. entries()) {
traversalDestinations. append( new Option( entry. url, entry. key));
}
</ script > ここでも、トラバーサルは同一生成元の宛先に制限されることに注意する。つまり、たとえば、前のセッション履歴エントリーが別の生成元からのページに対するものである場合、navigation.canGoBackはfalseになる。
ナビゲーションAPIの最も強力な部分は、navigateイベントである。このイベントは、現在のナビゲート可能でほとんどすべてのナビゲーションまたはトラバースが発生したときに発火する。
navigation. onnavigate = event => {
console. log( event. navigationType); // "push", "replace", "reload", or "traverse"
console. log( event. destination. url);
console. log( event. userInitiated);
// ... and other useful properties
}; （ナビゲーションの移動先が新しい文書である場合、ロケーションバーによって開始されたナビゲーションまたは他のウィンドウから開始されたナビゲーションに対してはイベントは発火しない。）
ほとんどの場合、イベントの cancelableプロパティはtrueになる。つまり、このイベントはpreventDefault()を使用してキャンセルできる：
navigation. onnavigate = event => {
if ( event. cancelable && isDisallowedURL( event. destination. url)) {
alert( `Please don't go to ${ event. destination. url} !` );
event. preventDefault();
}
};
一部の"traverse"ナビゲーションでは、cancelableプロパティがfalseになる。これには、子ナビゲーション可能内で行われるナビゲーション、新しい生成元に交差するナビゲーション、またはpreventDefault()の前回の呼び出しでトラバースできなかった直後にユーザーが再度トラバースしようとした場合などがある。
NavigateEventのintercept()メソッドを使用すると、ナビゲーションを横取りして、同じ文書のナビゲーションに変換できる：
navigation. addEventListener( "navigate" , e => {
// Some navigations, e.g. cross-origin navigations, we cannot intercept.
// Let the browser handle those normally.
if ( ! e. canIntercept) {
return ;
}
// Similarly, don't intercept fragment navigations or downloads.
if ( e. hashChange || e. downloadRequest !== null ) {
return ;
}
const url = new URL( event. destination. url);
if ( url. pathname. startsWith( "/articles/" )) {
e. intercept({
async handler() {
// The URL has already changed, so show a placeholder while
// fetching the new content, such as a spinner or loading page.
renderArticlePagePlaceholder();
// Fetch the new content and display when ready.
const articleContent = await getArticleContent( url. pathname, { signal: e. signal });
renderArticlePage( articleContent);
}
});
}
}); handlerは、ナビゲーションの非同期進行、および成功または失敗を表すプロミスを返すことができることに注意する。プロミスがまだ保留中である間、ブラウザーUIは、ナビゲーションを進行中として扱うことができる（たとえば、ローディングスピナーを提示することによって）。ナビゲーションAPIの他の部分も、navigation.navigate()の返り値など、これらのプロミスに敏感である：
const { committed, finished } = await navigation. navigate( "/articles/the-navigation-api-is-cool" );
// The committed promise will fulfill once the URL has changed, which happens
// immediately (as long as the NavigateEvent wasn't canceled).
await committed;
// The finished promise will fulfill once the Promise returned by handler() has
// fulfilled, which happens once the article is downloaded and rendered. (Or,
// it will reject, if handler() fails along the way).
await finished; Navigationインターフェイス[Exposed =Window ]
interface Navigation : EventTarget {
sequence <NavigationHistoryEntry > entries ();
readonly attribute NavigationHistoryEntry ? currentEntry ;
undefined updateCurrentEntry (NavigationUpdateCurrentEntryOptions options );
readonly attribute NavigationTransition ? transition ;
readonly attribute NavigationActivation ? activation ;
readonly attribute boolean canGoBack ;
readonly attribute boolean canGoForward ;
NavigationResult navigate (USVString url , optional NavigationNavigateOptions options = {});
NavigationResult reload (optional NavigationReloadOptions options = {});
NavigationResult traverseTo (DOMString key , optional NavigationOptions options = {});
NavigationResult back (optional NavigationOptions options = {});
NavigationResult forward (optional NavigationOptions options = {});
attribute EventHandler onnavigate ;
attribute EventHandler onnavigatesuccess ;
attribute EventHandler onnavigateerror ;
attribute EventHandler oncurrententrychange ;
};
dictionary NavigationUpdateCurrentEntryOptions {
required any state ;
};
dictionary NavigationOptions {
any info ;
};
dictionary NavigationNavigateOptions : NavigationOptions {
any state ;
NavigationHistoryBehavior history = "auto";
};
dictionary NavigationReloadOptions : NavigationOptions {
any state ;
};
dictionary NavigationResult {
Promise <NavigationHistoryEntry > committed ;
Promise <NavigationHistoryEntry > finished ;
};
enum NavigationHistoryBehavior {
" auto " ,
" push " ,
" replace "
};Each Window has an associated navigation API, which is a Navigation object. Upon creation of the Window object, its navigation API must be set to a new Navigation object created in the Window object's relevant realm.
The navigation getter steps are to return this's navigation API.
The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by all objects implementing the Navigation interface:
| イベントハンドラー | イベントハンドラーイベント型 |
|---|---|
onnavigate | navigate |
onnavigatesuccess | navigatesuccess |
onnavigateerror | navigateerror |
oncurrententrychange | currententrychange |
Each Navigation has an associated entry list, a list of NavigationHistoryEntry objects, initially empty.
Each Navigation has an associated current entry index, an integer, initially −1.
The current entry of a Navigation navigation is the result of running the following steps:
If navigation has entries and events disabled, then return null.
Assert: navigation's current entry index is not −1.
Return navigation's entry list[navigation's current entry index].
A Navigation navigation has entries and events disabled if the following steps return true:
Let document be navigation's relevant global object's associated Document.
If document is not fully active, then return true.
If document's is initial about:blank is true, then return true.
falseを返す。
To get the navigation API entry index of a session history entry she within a Navigation navigation:
indexを0にする。
For each nhe of navigation's entry list:
If nhe's session history entry is equal to she, then return index.
Increment index by 1.
Return −1.
ナビゲーションAPI全体で使用されるキータイプは、NavigationType列挙である：
enum NavigationType {
" push " ,
" replace " ,
" reload " ,
" traverse "
};これは、主要なウェブ開発者が目に見える"navigation"のタイプをキャプチャしたものであり、（他の場所で指摘されているように）この標準の特異なナビゲートアルゴリズムに正確に対応していない。それぞれの値の意味は次のとおりである：
push"push"で終わるナビゲート、またはhistory.pushState()の呼び出しに対応する。replace"replace"で終わるナビゲート、またはhistory.replaceState()の呼び出しに対応する。reload"traverse"The value space of the NavigationType enumeration is a superset of the value space of the specification-internal history handling behavior type. Several parts of this standard make use of this overlap, by passing in a history handling behavior to an algorithm that expects a NavigationType.
To initialize the navigation API entries for a new document given a Navigation navigation, a list of session history entries newSHEs, and a session history entry initialSHE:
Assert: navigation's entry list is empty.
Assert: navigation's current entry index is −1.
If navigation has entries and events disabled, then return.
For each newSHE of newSHEs:
Let newNHE be a new NavigationHistoryEntry created in the relevant realm of navigation.
Set newNHE's session history entry to newSHE.
Append newNHE to navigation's entry list.
newSHEs will have originally come from getting session history entries for the navigation API, and thus each newSHE will be contiguous same origin with initialSHE.
Set navigation's current entry index to the result of getting the navigation API entry index of initialSHE within navigation.
To update the navigation API entries for reactivation given a Navigation navigation, a list of session history entries newSHEs, and a session history entry reactivatedSHE:
If navigation has entries and events disabled, then return.
Let newNHEs be a new empty list.
Let oldNHEs be a clone of navigation's entry list.
For each newSHE of newSHEs:
Let newNHE be null.
If oldNHEs contains a NavigationHistoryEntry matchingOldNHE whose session history entry is newSHE, then:
Set newNHE to matchingOldNHE.
Remove matchingOldNHE from oldNHEs.
Otherwise:
Set newNHE to a new NavigationHistoryEntry created in the relevant realm of navigation.
Set newNHE's session history entry to newSHE.
Append newNHE to newNHEs.
newSHEs will have originally come from getting session history entries for the navigation API, and thus each newSHE will be contiguous same origin with reactivatedSHE.
By the end of this loop, all NavigationHistoryEntrys that remain in oldNHEs represent session history entries which have been disposed while the Document was in bfcache.
Set navigation's entry list to newNHEs.
Set navigation's current entry index to the result of getting the navigation API entry index of reactivatedSHE within navigation.
Queue a global task on the navigation and traversal task source given navigation's relevant global object to run the following steps:
For each disposedNHE of oldNHEs:
Fire an event named dispose at disposedNHE.
We delay these steps by a task to ensure that dispose events will fire after the pageshow event. This ensures that pageshow is the first event a page receives upon reactivation.
(However, the rest of this algorithm runs before the pageshow event fires. This ensures that navigation.entries() and navigation.currentEntry will have correctly-updated values during any pageshow event handlers.)
To update the navigation API entries for a same-document navigation given a Navigation navigation, a session history entry destinationSHE, and a NavigationType navigationType:
If navigation has entries and events disabled, then return.
Let oldCurrentNHE be the current entry of navigation.
Let disposedNHEs be a new empty list.
If navigationType is "traverse", then:
Set navigation's current entry index to the result of getting the navigation API entry index of destinationSHE within navigation.
Assert: navigation's current entry index is not −1.
This algorithm is only called for same-document traversals. Cross-document traversals will instead call either initialize the navigation API entries for a new document or update the navigation API entries for reactivation.
Otherwise, if navigationType is "push", then:
Set navigation's current entry index to navigation's current entry index + 1.
Let i be navigation's current entry index.
While i < navigation's entry list's size:
Append navigation's entry list[i] to disposedNHEs.
Set i to i + 1.
Remove all items in disposedNHEs from navigation's entry list.
Otherwise, if navigationType is "replace", then:
Append oldCurrentNHE to disposedNHEs.
If navigationType is "push" or "replace", then:
Let newNHE be a new NavigationHistoryEntry created in the relevant realm of navigation.
Set newNHE's session history entry to destinationSHE.
Set navigation's entry list[navigation's current entry index] to newNHE.
If navigation's ongoing API method tracker is non-null, then notify about the committed-to entry given navigation's ongoing API method tracker and the current entry of navigation.
It is important to do this before firing the dispose or currententrychange events, since event handlers could start another navigation, or otherwise change the value of navigation's ongoing API method tracker.
Prepare to run script given navigation's relevant settings object.
See the discussion for other navigation API events to understand why we do this.
Fire an event named currententrychange at navigation using NavigationCurrentEntryChangeEvent, with its navigationType attribute initialized to navigationType and its from initialized to oldCurrentNHE.
For each disposedNHE of disposedNHEs:
Fire an event named dispose at disposedNHE.
Clean up after running script given navigation's relevant settings object.
In implementations, same-document navigations can cause session history entries to be disposed by falling off the back of the session history entry list. This is not yet handled by the above algorithm (or by any other part of this standard). See issue #8620 to track progress on defining the correct behavior in such cases.
NavigationHistoryEntryインターフェイス[Exposed =Window ]
interface NavigationHistoryEntry : EventTarget {
readonly attribute USVString ? url ;
readonly attribute DOMString key ;
readonly attribute DOMString id ;
readonly attribute long long index ;
readonly attribute boolean sameDocument ;
any getState ();
attribute EventHandler ondispose ;
};entry.urlこのナビゲーション履歴エントリーのURL。
エントリーが現在のものとは異なるDocumentに対応している場合（つまり、 sameDocumentがfalseである場合)、かつDocumentが"no-referrer"または"origin"のリファラーポリシーで取得された場合、nullを返すことができる。これは、問題のDocumentが他の同じ生成元のページからもURLを隠していることを示しているためである。
entry.keyナビゲーション履歴リスト内のこのナビゲーション履歴エントリーの位置を表す、ユーザーエージェントが生成したランダムなUUID文字列。この値は、"replace"ナビゲーションのためにこの値を置き換える他の NavigationHistoryEntryインスタンスによって再利用され、再読み込みおよびセッションの復元後も存続する。
これは、navigation.traverseTo(key)を使用して、ナビゲーション履歴リストのこのエントリーに戻るのに役立つ。
entry.idこの特定のナビゲーション履歴エントリーを表す、ユーザーエージェントによって生成されたランダムなUUID文字列。この値は、他のNavigationHistoryEntryインスタンスによって再利用されない。この値は、リロードおよびセッションのリストア後も保持される。
これは、他のストレージAPIを使用してこのナビゲーション履歴エントリーにデータを関連付ける場合に役立つ。
entry.indexnavigation.entries()内のこのNavigationHistoryEntryのインデックス。または、エントリーがナビゲーション履歴エントリーリストにない場合は-1。
entry.sameDocumentこのナビゲーション履歴エントリーが現在のDocumentと同じかどうかを示す。たとえば、エントリーがフラグメントナビゲーションまたは単一ページのアプリナビゲーションを表す場合、これはtrueになる。
entry.getState()navigation.navigate()またはnavigation.updateCurrentEntry()を用いてエントリーに追加された、このエントリーに格納されている状態のデシリアライズを返す。この状態は、リロードおよびセッションのリストア後も保持される。
一般に、状態値がプリミティブentry.getState() !== entry.getState()でない限り、毎回新しいデシリアライズが返されることに注意する。
この状態は、従来の履歴API history.stateとは関係ない。
Each NavigationHistoryEntry has an associated session history entry, which is a session history entry.
The key of a NavigationHistoryEntry nhe is given by the return value of the following algorithm:
If nhe's relevant global object's associated Document is not fully active, then return the empty string.
Return nhe's session history entry's navigation API key.
The ID of a NavigationHistoryEntry nhe is given by the return value of the following algorithm:
If nhe's relevant global object's associated Document is not fully active, then return the empty string.
Return nhe's session history entry's navigation API ID.
The index of a NavigationHistoryEntry nhe is given by the return value of the following algorithm:
If nhe's relevant global object's associated Document is not fully active, then return −1.
Return the result of getting the navigation API entry index of this's session history entry within this's relevant global object's navigation API.
The url getter steps are:
Let document be this's relevant global object's associated Document.
If document is not fully active, then return the empty string.
Let she be this's session history entry.
If she's document does not equal document, and she's document state's request referrer policy is "no-referrer" or "origin", then return null.
Return she's URL, serialized.
The key getter steps are to return this's key.
The id getter steps are to return this's ID.
The index getter steps are to return this's index.
The sameDocument getter steps are:
Let document be this's relevant global object's associated Document.
If document is not fully active, then return false.
Return true if this's session history entry's document equals document, and false otherwise.
The getState() method steps are:
If this's relevant global object's associated Document is not fully active, then return undefined.
Return StructuredDeserialize(this's session history entry's navigation API state). 例外を再度投げる。
This can in theory throw an exception, if attempting to deserialize a large ArrayBuffer when not enough memory is available.
The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by all objects implementing the NavigationHistoryEntry interface:
| イベントハンドラー | イベントハンドラーイベント型 |
|---|---|
ondispose | dispose |
entries = navigation.entries()現在のナビゲーション履歴エントリーリストを表すNavigationHistoryEntryインスタンスの配列を返す。これはつまり、現在のセッション履歴エントリーと同一生成元で隣接する、このナビゲーション可能のすべてのセッション履歴エントリーである。
navigation.currentEntrynavigation.updateCurrentEntry({ state })navigation.reload()のようなナビゲーションを実行せずに、現在のセッション履歴エントリーのナビゲーションAPI状態を更新する。
このメソッドは、すでに発生しており、ナビゲーションAPI状態に反映する必要があるページの更新をキャプチャするのに最適である。状態の更新がページ更新を駆動することを意図している場合、代わりにnavigation.navigate()または navigation.reload()を使用する。これにより、 navigateイベントがトリガーされる。
navigation.canGoBack現在の現在のセッション履歴エントリーつまり、（currentEntry）がナビゲーション履歴エントリーリストの最初のエントリー（つまり、entries()）でない場合、trueを返す。これは、このナビゲート可能に対して以前のセッション履歴エントリーがあり、その文書状態の生成元が現在のDocumentの生成元と同一生成元であることを意味する。
navigation.canGoForward現在の現在のセッション履歴エントリーつまり、（currentEntry）がナビゲーション履歴エントリーリストの最後のエントリー（つまり、entries()）でない場合、trueを返す。これは、このナビゲート可能に対して次のセッション履歴エントリーがあり、その文書状態の生成元が現在のDocumentの生成元と同一生成元であることを意味する。
The entries() method steps are:
If this has entries and events disabled, then return the empty list.
Return this's entry list.
Recall that because of Web IDL's sequence type conversion rules, this will create a new JavaScript array object on each call. That is, navigation.entries() !== navigation.entries().
The currentEntry getter steps are to return the current entry of this.
The updateCurrentEntry(options) method steps are:
Let current be the current entry of this.
If current is null, then throw an "InvalidStateError" DOMException.
Let serializedState be StructuredSerializeForStorage(options["state"]), rethrowing any exceptions.
Set current's session history entry's navigation API state to serializedState.
Fire an event named currententrychange at this using NavigationCurrentEntryChangeEvent, with its navigationType attribute initialized to null and its from initialized to current.
The canGoBack getter steps are:
If this has entries and events disabled, then return false.
Assert: this's current entry index is not −1.
If this's current entry index is 0, then return false.
Return true.
The canGoForward getter steps are:
If this has entries and events disabled, then return false.
Assert: this's current entry index is not −1.
If this's current entry index is equal to this's entry list's size − 1, then return false.
Return true.
{ committed, finished } = navigation.navigate(url){ committed, finished } = navigation.navigate(url, options)現在のページを指定しurlにナビゲートする。optionsには、次の値を含めることができる：
historyを"replace"に設定すると、新しいセッション履歴エントリーをプッシュする代わりに、現在のセッション履歴エントリーを置き換えることができる。
infoには任意の値を設定できる。対応するNavigateEventのinfoプロパティに値が設定される。
stateには、任意のシリアル化可能な値を設定できる。同じ文書のナビゲーションの場合、ナビゲーションが完了すると、navigation.currentEntry.getState()によって取得された状態が設定される。（異なる文書間のナビゲーションでは無視される。）
デフォルトでは、これは完全なナビゲーションを実行する（つまり、指定されたURLが現在のURLとフラグメントのみが異なる場合を除き、異なる文書間のナビゲーションを実行する）。navigateEvent.intercept()を使用すると、同じ文書のナビゲーションに変換できる。
返されたプロミスは次のように動作する：
ナビゲーションが中止された場合、両方のプロミスは"AbortError" DOMExceptionで拒否される。
navigateEvent.intercept()メソッドを使用して作成された同じ文書のナビゲーションの場合、committedは直ちに実行され、finished>はintercept()に渡されたハンドラーによって返されたpromsiesに従って実行または拒否される。
他の同じ文書ナビゲーション（たとえば、傍受されていないフラグメントナビゲーション）については、両方のプロミスが直ちに実行される。
異なる文書間のナビゲーション、またはサーバーからの204または205ステータスまたは`Content-Disposition: attachment`ヘッダーフィールドになる（したがって実際にはナビゲートしない）ナビゲーションの場合、両方のプロミスは一切解決されない。
いずれの場合も、返されたプロミスが実行されるとき、ナビゲート先のNavigationHistoryEntryが使用される。
{ committed, finished } = navigation.reload(options)現在のページをリロードする。optionsは、上記のように動作するinfoおよびstateを含めることができる。
現在のページのネットワークまたはキャッシュからのリロードを実行するデフォルトの動作は、 navigateEvent.intercept()メソッドを使用して上書きできます。そうすることは、この呼び出しが状態を更新する、または適切なinfoに沿って渡すだけでなく、navigateイベントハンドラーが実行に適していると判断したアクションを実行することを意味する。
返されたプロミスは次のように動作する：
リロードがnavigateEvent.intercept()メソッドを使用してインターセプトされた場合、committedはすぐに実行され、finishedはintercept()に渡されたハンドラによって返されたプロミスに従って実行または拒否される。
そうでなければ、両方のプロミスは決して解決しないだろう。
{ committed, finished } = navigation.traverseTo(key){ committed, finished } = navigation.traverseTo(key, { info })Traverses to the closest session history entry that matches the NavigationHistoryEntry with the given key. info can be set to any value; it will populate the info property of the corresponding NavigateEvent.
そのセッション履歴エントリーへのトラバーサルがすでに進行中である場合、これは元のトラバーサルのプロミスを返し、infoは無視される。
返されたプロミスは次のように動作する：
keyがkeyにマッチするnavigation.entries()にNavigationHistoryEntryがない場合、両方のプロミスは"InvalidStateError" DOMExceptionで拒否される。
navigateEvent.intercept()メソッドによってインターセプトされた同じ文書のトラバースの場合、committedは、トラバースが処理され、navigation.currentEntryが更新されるとすぐに実行され、finished>はintercept()に渡されたハンドラーによって返されたすべてのプロミスに従って実行または拒否される。
インターセプトされていない同じ文書のトラバーサルの場合、トラバーサルが処理され、navigation.currentEntryが更新されるとすぐに、両方のプロミスが実行される。
異なる文書間のトラバーサルでは、最終的にサーバーからの204または205ステータスまたは`Content-Disposition: attachment`ヘッダーフィールドになる（したがって実際にはトラバーサルしない）、異なる文書間のトラバーサルの試みを含めて、両方のプロミスは決して解決されない。
{ committed, finished } = navigation.back(key){ committed, finished } = navigation.back(key, { info })最も近い前方のセッション履歴エントリーに移動し、その結果、このナビゲート可能なトラバースが行われる。つまり、別のNavigationHistoryEntryに対応するため、navigation.currentEntryが変更される。infoには任意の値を設定できる。対応するNavigateEventのinfoプロパティに値が設定される。
そのセッション履歴エントリーへのトラバーサルがすでに進行中である場合、これは元のトラバーサルのプロミスを返し、infoは無視される。
返されたプロミスは、traverseTo()によって返された往路ミスと同じように動作する。
{ committed, finished } = navigation.forward(key){ committed, finished } = navigation.forward(key, { info })最も近い前方のセッション履歴エントリーに移動し、その結果、このナビゲート可能なトラバースが行われる。つまり、別のNavigationHistoryEntryに対応するため、navigation.currentEntryが変更される。infoには任意の値を設定できる。対応するNavigateEventのinfoプロパティに値が設定される。
そのセッション履歴エントリーへのトラバーサルがすでに進行中である場合、これは元のトラバーサルのプロミスを返し、infoは無視される。
返されたプロミスは、traverseTo()によって返された往路ミスと同じように動作する。
The navigate(url, options) method steps are:
Let urlRecord be the result of parsing a URL given url, relative to this's relevant settings object.
If urlRecord is failure, then return an early error result for a "SyntaxError" DOMException.
Let document be this's relevant global object's associated Document.
If options["history"] is "push", and the navigation must be a replace given urlRecord and document, then return an early error result for a "NotSupportedError" DOMException.
Let state be options["state"], if it exists; otherwise, undefined.
Let serializedState be StructuredSerializeForStorage(state). If this throws an exception, then return an early error result for that exception.
It is important to perform this step early, since serialization can invoke web developer code, which in turn might change various things we check in later steps.
If document is not fully active, then return an early error result for an "InvalidStateError" DOMException.
If document's unload counter is greater than 0, then return an early error result for an "InvalidStateError" DOMException.
Let info be options["info"], if it exists; otherwise, undefined.
Let apiMethodTracker be the result of maybe setting the upcoming non-traverse API method tracker for this given info and serializedState.
Navigate document's node navigable to urlRecord using document, with historyHandling set to options["history"] and navigationAPIState set to serializedState.
Unlike location.assign() and friends, which are exposed across origin-domain boundaries, navigation.navigate() can only be accessed by code with direct synchronous access to the window.navigation property. Thus, we avoid the complications about attributing the source document of the navigation, and we don't need to deal with the allowed by sandboxing to navigate check and its acccompanying exceptionsEnabled flag. We just treat all navigations as if they come from the Document corresponding to this Navigation object itself (i.e., document).
If this's upcoming non-traverse API method tracker is apiMethodTracker, then:
If the upcoming non-traverse API method tracker is still apiMethodTracker, this means that the navigate algorithm bailed out before ever getting to the inner navigate event firing algorithm which would promote that upcoming API method tracker to ongoing.
Set this's upcoming non-traverse API method tracker to null.
Return an early error result for an "AbortError" DOMException.
Return a navigation API method tracker-derived result for apiMethodTracker.
The reload(options) method steps are:
Let document be this's relevant global object's associated Document.
Let serializedState be StructuredSerializeForStorage(undefined).
If options["state"] exists, then set serializedState to StructuredSerializeForStorage(options["state"]). If this throws an exception, then return an early error result for that exception.
It is important to perform this step early, since serialization can invoke web developer code, which in turn might change various things we check in later steps.
Otherwise:
Let current be the current entry of this.
If current is not null, then set serializedState to current's session history entry's navigation API state.
If document is not fully active, then return an early error result for an "InvalidStateError" DOMException.
If document's unload counter is greater than 0, then return an early error result for an "InvalidStateError" DOMException.
Let info be options["info"], if it exists; otherwise, undefined.
Let apiMethodTracker be the result of maybe setting the upcoming non-traverse API method tracker for this given info and serializedState.
Reload document's node navigable with navigationAPIState set to serializedState.
Return a navigation API method tracker-derived result for apiMethodTracker.
The traverseTo(key, options) method steps are:
If this's current entry index is −1, then return an early error result for an "InvalidStateError" DOMException.
If this's entry list does not contain a NavigationHistoryEntry whose session history entry's navigation API key equals key, then return an early error result for an "InvalidStateError" DOMException.
Return the result of performing a navigation API traversal given this, key, and options.
The back(options) method steps are:
If this's current entry index is −1 or 0, then return an early error result for an "InvalidStateError" DOMException.
Let key be this's entry list[this's current entry index − 1]'s session history entry's navigation API key.
Return the result of performing a navigation API traversal given this, key, and options.
The forward(options) method steps are:
If this's current entry index is −1 or is equal to this's entry list's size − 1, then return an early error result for an "InvalidStateError" DOMException.
Let key be this's entry list[this's current entry index + 1]'s session history entry's navigation API key.
Return the result of performing a navigation API traversal given this, key, and options.
To perform a navigation API traversal given a Navigation navigation, a string key, and a NavigationOptions options:
Let document be navigation's relevant global object's associated Document.
If document is not fully active, then return an early error result for an "InvalidStateError" DOMException.
If document's unload counter is greater than 0, then return an early error result for an "InvalidStateError" DOMException.
Let current be the current entry of navigation.
If key equals current's session history entry's navigation API key, then return «[ "committed" → a promise resolved with current, "finished" → a promise resolved with current ]».
If navigation's upcoming traverse API method trackers[key] exists, then return a navigation API method tracker-derived result for navigation's upcoming traverse API method trackers[key].
Let info be options["info"], if it exists; otherwise, undefined.
Let apiMethodTracker be the result of adding an upcoming traverse API method tracker for navigation given key and info.
Let navigable be document's node navigable.
Let traversable be navigable's traversable navigable.
Let sourceSnapshotParams be the result of snapshotting source snapshot params given document.
Append the following session history traversal steps to traversable:
Let navigableSHEs be the result of getting session history entries given navigable.
Let targetSHE be the session history entry in navigableSHEs whose navigation API key is key. If no such entry exists, then:
Queue a global task on the navigation and traversal task source given navigation's relevant global object to reject the finished promise for apiMethodTracker with an "InvalidStateError" DOMException.
Abort these steps.
This path is taken if navigation's entry list was outdated compared to navigableSHEs, which can occur for brief periods while all the relevant threads and processes are being synchronized in reaction to a history change.
If targetSHE is navigable's active session history entry, then abort these steps.
This can occur if a previously queued traversal already took us to this session history entry. In that case the previous traversal will have dealt with apiMethodTracker already.
Let result be the result of applying the traverse history step given by targetSHE's step to traversable, given sourceSnapshotParams, navigable, and "none".
If result is "canceled-by-beforeunload", then queue a global task on the navigation and traversal task source given navigation's relevant global object to reject the finished promise for apiMethodTracker with a new "AbortError" DOMException created in navigation's relevant realm.
If result is "initiator-disallowed", then queue a global task on the navigation and traversal task source given navigation's relevant global object to reject the finished promise for apiMethodTracker with a new "SecurityError" DOMException created in navigation's relevant realm.
When result is "canceled-by-beforeunload" or "initiator-disallowed", the navigate event was never fired, aborting the ongoing navigation would not be correct; it would result in a navigateerror event without a preceding navigate event.
In the "canceled-by-navigate" case, navigate is fired, but the inner navigate event firing algorithm will take care of aborting the ongoing navigation.
Return a navigation API method tracker-derived result for apiMethodTracker.
An early error result for an exception e is a NavigationResult dictionary instance given by «[ "committed" → a promise rejected with e, "finished" → a promise rejected with e ]».
A navigation API method tracker-derived result for a navigation API method tracker is a NavigationResult dictionary instance given by «[ "committed" → apiMethodTracker's committed promise, "finished" → apiMethodTracker's finished promise ]».
During any given navigation (in the broad sense of the word), the Navigation object needs to keep track of the following:
| 状態 | Duration | Explanation |
|---|---|---|
The NavigateEvent | For the duration of event firing | So that if the navigation is canceled while the event is firing, we can cancel the event |
| The event's abort controller | Until all promises returned from handlers passed to intercept() have settled | So that if the navigation is canceled, we can signal abort |
| Whether a new element was focused | Until all promises returned from handlers passed to intercept() have settled | So that if one was, focus is not reset |
The NavigationHistoryEntry being navigated to | From when it is determined, until all promises returned from handlers passed to intercept() have settled | So that we know what to resolve any committed and finished promises with |
Any finished promise that was returned | Until all promises returned from handlers passed to intercept() have settled | So that we can resolve or reject it appropriately |
| 状態 | Duration | Explanation |
|---|---|---|
Any state | For the duration of event firing | So that we can update the current entry's navigation API state if the event finishes firing without being canceled |
| 状態 | Duration | Explanation |
|---|---|---|
Any info | Until the task is queued to fire the navigate event | So that we can use it to fire the navigate after the trip through the session history traversal queue. |
Any committed promise that was returned | Until the session history is updated (inside that same task) | So that we can resolve or reject it appropriately |
Whether intercept() was called | Until the session history is updated (inside that same task) | So that we can suppress the normal scroll restoration logic in favor of the behavior given by the scroll option |
We also cannot assume there is only a single navigation requested at any given time, due to web developer code such as:
const p1 = navigation. navigate( url1). finished;
const p2 = navigation. navigate( url2). finished; That is, in this scenario, we need to ensure that while navigating to url2, we still have the promise p1 around so that we can reject it. We can't just get rid of any ongoing navigation promises the moment the second call to navigate() happens.
We end up accomplishing all this by associating the following with each Navigation:
Ongoing navigate event, a NavigateEvent or null, initially null.
Focus changed during ongoing navigation, a boolean, initially false.
Suppress normal scroll restoration during ongoing navigation, a boolean, initially false.
Ongoing API method tracker, a navigation API method tracker or null, initially null.
Upcoming non-traverse API method tracker, a navigation API method tracker or null, initially null.
Upcoming traverse API method trackers, an ordered map from strings to navigation API method trackers, initially empty.
The state here that is not stored in navigation API method trackers is state which needs to be tracked even for navigations that are not initiated via navigation API methods.
A navigation API method tracker is a struct with the following items:
A navigation object, a Navigation
A key, a string or null
An info, a JavaScript value
A serialized state, a serialized state or null
A committed-to entry, a NavigationHistoryEntry or null
A committed promise, a promise
A finished promise, a promise
All this state is then managed via the following algorithms.
To maybe set the upcoming non-traverse API method tracker given a Navigation navigation, a JavaScript value info, and a serialized state-or-null serializedState:
Let committedPromise and finishedPromise be new promises created in navigation's relevant realm.
Mark as handled finishedPromise.
Let apiMethodTracker be a new navigation API method tracker with:
Assert: navigation's upcoming non-traverse API method tracker is null.
If navigation does not have entries and events disabled, then set navigation's upcoming non-traverse API method tracker to apiMethodTracker.
If navigation has entries and events disabled, then committedPromise and finishedPromise will never fulfill (since we never create a NavigationHistoryEntry object for such Documents, and so we have nothing to resolve them with); there is no NavigationHistoryEntry to apply serializedState to; and there is no navigate event to include info with. So, we don't need to track this API method call after all.
Return apiMethodTracker.
To add an upcoming traverse API method tracker given a Navigation navigation, a string destinationKey, and a JavaScript value info:
Let committedPromise and finishedPromise be new promises created in navigation's relevant realm.
Mark as handled finishedPromise.
See the previous discussion about why this is done.
Let apiMethodTracker be a new navigation API method tracker with:
Set navigation's upcoming traverse API method trackers[destinationKey] to apiMethodTracker.
Return apiMethodTracker.
To promote an upcoming API method tracker to ongoing given a Navigation navigation and a string-or-null destinationKey:
Assert: navigation's ongoing API method tracker is null.
If destinationKey is not null, then:
Assert: navigation's upcoming non-traverse API method tracker is null.
If navigation's upcoming traverse API method trackers[destinationKey] exists, then:
Set navigation's ongoing API method tracker to navigation's upcoming traverse API method trackers[destinationKey].
Remove navigation's upcoming traverse API method trackers[destinationKey].
Otherwise:
Set navigation's ongoing API method tracker to navigation's upcoming non-traverse API method tracker.
Set navigation's upcoming non-traverse API method tracker to null.
To clean up a navigation API method tracker apiMethodTracker:
Let navigation be apiMethodTracker's navigation object.
If navigation's ongoing API method tracker is apiMethodTracker, then set navigation's ongoing API method tracker to null.
Otherwise:
Let key be apiMethodTracker's key.
Assert: key is not null.
Assert: navigation's upcoming traverse API method trackers[key] exists.
Remove navigation's upcoming traverse API method trackers[key].
To notify about the committed-to entry given a navigation API method tracker apiMethodTracker and a NavigationHistoryEntry nhe:
Set apiMethodTracker's committed-to entry to nhe.
If apiMethodTracker's serialized state is not null, then set nhe's session history entry's navigation API state to apiMethodTracker's serialized state.
If it's null, then we're traversing to nhe via navigation.traverseTo(), which does not allow changing the state.
At this point, apiMethodTracker's serialized state is no longer needed. Implementations might want to clear it out to avoid keeping it alive for the lifetime of the navigation API method tracker.
Resolve apiMethodTracker's committed promise with nhe.
At this point, apiMethodTracker's committed promise is only needed in cases where it has not yet been returned to author code. Implementations might want to clear it out to avoid keeping it alive for the lifetime of the navigation API method tracker.
To resolve the finished promise for a navigation API method tracker apiMethodTracker:
Assert: apiMethodTracker's committed-to entry is not null.
Resolve apiMethodTracker's finished promise with its committed-to entry.
Clean up apiMethodTracker.
To reject the finished promise for a navigation API method tracker apiMethodTracker with a JavaScript value exception:
Reject apiMethodTracker's committed promise with exception.
This will do nothing if apiMethodTracker's committed promise was previously resolved via notify about the committed-to entry.
Reject apiMethodTracker's finished promise with exception.
Clean up apiMethodTracker.
To abort the ongoing navigation given a Navigation navigation and an optional DOMException error:
Let event be navigation's ongoing navigate event.
Assert: event is not null.
Set navigation's focus changed during ongoing navigation to false.
Set navigation's suppress normal scroll restoration during ongoing navigation to false.
If error was not given, then let error be a new "AbortError" DOMException created in navigation's relevant realm.
If event's dispatch flag is set, then set event's canceled flag to true.
Signal abort on event's abort controller given error.
Set navigation's ongoing navigate event to null.
Let errorInfo be the result of extracting error information from error.
For example, if this algorithm is reached because of a call to window.stop(), these properties would probably end up initialized based on the line of script that called window.stop(). But if it's because the user clicked the stop button, these properties would probably end up with default values like the empty string or 0.
Fire an event named navigateerror at navigation using ErrorEvent, with additional attributes initialized according to errorInfo.
If navigation's ongoing API method tracker is non-null, then reject the finished promise for apiMethodTracker with error.
If navigation's transition is not null, then:
Reject navigation's transition's finished promise with error.
Set navigation's transition to null.
To inform the navigation API about aborting navigation in a navigable navigable:
If this algorithm is running on navigable's active window's relevant agent's event loop, then continue on to the following steps. Otherwise, queue a global task on the navigation and traversal task source given navigable's active window to run the following steps.
Let navigation be navigable's active window's navigation API.
If navigation's ongoing navigate event is null, then return.
Abort the ongoing navigation given navigation.
To inform the navigation API about child navigable destruction given a navigable navigable:
Inform the navigation API about aborting navigation in navigable.
Let navigation be navigable's active window's navigation API.
Let traversalAPIMethodTrackers be a clone of navigation's upcoming traverse API method trackers.
For each apiMethodTracker of traversalAPIMethodTrackers: reject the finished promise for apiMethodTracker with a new "AbortError" DOMException created in navigation's relevant realm.
The ongoing navigation concept is most-directly exposed to web developers through the navigation.transition property, which is an instance of the NavigationTransition interface:
[Exposed =Window ]
interface NavigationTransition {
readonly attribute NavigationType navigationType ;
readonly attribute NavigationHistoryEntry from ;
readonly attribute Promise <undefined > finished ;
};navigation.transition存在する場合、navigatesuccessまたはnavigateerrorステージに到達していない進行中のナビゲーションを表すNavigationTransition。そのような移行が進行中でない場合、nullになる。
navigation.currentEntry（および location.hrefなどの他のプロパティ）はナビゲーションの直後に更新されるため、このnavigation.transitionプロパティは、navigateEvent.intercept()に渡されたハンドラーに従って、そのようなナビゲーションがまだ完全に確定していないときを判断するのに役立つ。
navigation.transition.navigationType"push"、"replace"、"reload"、または "traverse"のいずれかで、このトランジションのナビゲーションの種類を示す。
navigation.transition.from遷移元のNavigationHistoryEntry。これはnavigation.currentEntryと比較するのに役立つ。
navigation.transition.finishednavigatesuccessが発火すると同時に実行されるプロミス、または navigateerrorイベントが発火すると同時に拒否されるプロミス。
Each Navigation has a transition, which is a NavigationTransition or null, initially null.
The transition getter steps are to return this's transition.
Each NavigationTransition has an associated navigation type, which is a NavigationType.
Each NavigationTransition has an associated from entry, which is a NavigationHistoryEntry.
Each NavigationTransition has an associated finished promise, which is a promise.
navigationTypeゲッターステップは、thisのnavigation entryを返す。
The from getter steps are to return this's from entry.
The finished getter steps are to return this's finished promise.
NavigationActivationインターフェイス[Exposed =Window ]
interface NavigationActivation {
readonly attribute NavigationHistoryEntry ? from ;
readonly attribute NavigationHistoryEntry entry ;
readonly attribute NavigationType navigationType ;
};navigation.activationこのDocumentを"activated"にしたナビゲーションである、最新の文書間ナビゲーションに関する情報を含むNavigationActivation。
navigation.currentEntryとDocumentのURLは同じ文書のナビゲーションにより定期的に更新できるが、navigation.activationは一定に保たれ、Documentがreactivated履歴から更新された場合にのみ、そのプロパティは更新される。
navigation.activation.entryDocumentがアクティブになった時点のnavigation.currentEntryプロパティの値と同じNavigationHistoryEntry。
navigation.activation.from現在のDocumentの直前にアクティブであったDocumentを表す NavigationHistoryEntry。前のDocumentがこの文書と同一生成元ではなかった場合、またはinitial about:blank Documentであった場合、値はnullになる。
fromまたはentry NavigationHistoryEntryオブジェクトは、履歴に保持されない可能性があるため、traverseTo()メソッドの実行可能なターゲットにならない場合がある。たとえば、Documentはlocation.replace()を使用してアクティブにすることができ、その初期エントリーはhistory.replaceState()で置き換えることができる。しかし、これらのエントリーのurlプロパティおよびgetState()メソッドには引き続きアクセス可能である。
navigation.activation.navigationType"push"、"replace"、"reload"、または "traverse"のいずれかで、このDocumentをアクティブにしたナビゲーションのタイプを示す。
各Navigationは、関連付けられたactivationがある。これはnull、または最初はnullであるNavigationActivation オブジェクトである。
各NavigationActivationには、次のものがある：
old entry、nullまたはNavigationHistoryEntry。
new entry、nullまたはNavigationHistoryEntry。
navigation type、NavigationType。
activationゲッターステップは、thisのactivationを返す。
fromゲッターステップは、thisのold entryを返す。
entryゲッターステップは、thisのnew entryを返す。
navigationTypeゲッターステップは、thisのnavigation entryを返す。
navigateイベントナビゲーションAPIの主な機能は、navigateイベントである。このイベントはすべてのナビゲーション（広義の意味で）で発火し、ウェブ開発者はそのような発信ナビゲーションを監視できる。多くの場合、イベントはcancelableであり、これはナビゲーションが発生しないようにすることができる。また、NavigateEventクラスのintercept()メソッドを使用して、ナビゲーションをインターセプトし、同じ文書のナビゲーションに置き換えることもできる。
NavigateEventインターフェイス[Exposed =Window ]
interface NavigateEvent : Event {
constructor (DOMString type , NavigateEventInit eventInitDict );
readonly attribute NavigationType navigationType ;
readonly attribute NavigationDestination destination ;
readonly attribute boolean canIntercept ;
readonly attribute boolean userInitiated ;
readonly attribute boolean hashChange ;
readonly attribute AbortSignal signal ;
readonly attribute FormData formData ;
readonly attribute DOMString ? downloadRequest ;
readonly attribute any info ;
readonly attribute boolean hasUAVisualTransition ;
readonly attribute Element ? sourceElement ;
undefined intercept (optional NavigationInterceptOptions options = {});
undefined scroll ();
};
dictionary NavigateEventInit : EventInit {
NavigationType navigationType = "push";
required NavigationDestination destination ;
boolean canIntercept = false ;
boolean userInitiated = false ;
boolean hashChange = false ;
required AbortSignal signal ;
FormData ? formData = null ;
DOMString ? downloadRequest = null ;
any info ;
boolean hasUAVisualTransition = false ;
Element ? sourceElement = null ;
};
dictionary NavigationInterceptOptions {
NavigationInterceptHandler handler ;
NavigationFocusReset focusReset ;
NavigationScrollBehavior scroll ;
};
enum NavigationFocusReset {
" after-transition " ,
" manual "
};
enum NavigationScrollBehavior {
" after-transition " ,
" manual "
};
callback NavigationInterceptHandler = Promise <undefined > ();event.navigationType"push"、"replace"、"reload"、または"traverse"のいずれかで、ナビゲーションの種類を示す。
event.destinationナビゲーションの目的地を表すNavigationDestination。
event.canInterceptintercept()を呼び出してこのナビゲーションをインターセプトし、同じ文書のナビゲーションに変換して通常の動作を置き換えることができる場合はtrue、そうでなければfalse。
一般的にいえば、これは、現在のDocumentが宛先URLにそのURLを書き換えることができる場合は常にtrueになるが、異なる文書間の"traverse"ナビゲーションの場合は例外であり、常にfalseになる。
event.userInitiatedユーザーが a要素をクリックした場合、form要素を送信した場合、またはブラウザーUIを使用して移動した場合はtrue、そうでなければfalse。
event.hashChangeフラグメントナビゲーションの場合はtrue、そうでなければfalse。
event.signalAbortSignalは、たとえばユーザーがブラウザーの"停止"ボタンを押したり、別のナビゲーションがこれを中断したりするなどして、ナビゲーションがキャンセルされた場合、中止される。
期待されるパターンは、開発者がこれをfetch()などの非同期操作に渡すことであり、開発者はこのナビゲーションを処理する一部として実行する。
event.formDataこのナビゲーションがPOSTフォーム送信を表す"push"または"replace"ナビゲーションの場合、このナビゲーションに対して送信されたフォームエントリーを表すFormData。そうでなければnull。
（特に、最初にフォーム送信から作成されたセッション履歴エントリーを再訪問する"reload"または"traverse"ナビゲーションの場合であっても、これはnullになる。）
event.downloadRequestaまたはarea要素のdownload属性を使用することによって、このナビゲーションがダウンロードとして要求されたかどうかを表す。
ダウンロードが要求されなかった場合、このプロパティはnullである。
ダウンロードが要求された場合、download属性の値として指定されたファイル名を返す。(This could be the empty string.)
ダウンロードが要求されても、必ずしもダウンロードが実行されるとは限らないことに注意する。たとえば、ダウンロードがブラウザーのセキュリティポリシーによってブロックされたり、理由は不明だが"push"ナビゲーションとして処理されたりする場合がある。
同様に、ナビゲーションは、たとえダウンロードであることが要求されていなくても、宛先サーバーが`Content-Disposition: attachment`ヘッダーで応答するために、最終的にダウンロードとなる可能性がある。
最後に、navigateイベントは、ブラウザーUIアフォーダンスを使用して開始されたダウンロード、たとえば、リンクのターゲットを右クリックして保存するのを選択することによって作成されたダウンロードに対してはまったく発火しないことに注意する。
event.infoこのナビゲーションを開始したナビゲーションAPIメソッドの1つによって渡される任意のJavaScript値、またはナビゲーションがユーザーまたは別のAPIによって開始された場合、undefined。
event.hasUAVisualTransitionユーザーエージェントが、このイベントをディスパッチする前に、このナビゲーションのビジュアルトランジションを実行した場合、trueを返す。trueの場合、著者がDOMをナビゲーション後の状態に同期的に更新するならば、最高のユーザーエクスペリエンスが得られる。
event.sourceElementこのナビゲーションを担当するElementを返す。これはaまたはarea要素、送信ボタン、または送信されたform要素になる。
event.intercept({ handler, focusReset, scroll })通常の処理を行わずに、宛先URLと同じ種類の同じ文書に変換して、このナビゲーションを途中で取得する。
handlerオプションは、プロミスを返す関数を指定できる。ハンドラー関数は、navigateイベントの発火が終了し、navigation.currentEntryプロパティが同期的に更新された後に実行される。この返されたプロミスは、ナビゲーションの期間と成功または失敗を通知するために使用される。それが落ち着いた後、ブラウザーは、ナビゲーションが終了したことを（たとえば、ローディングスピナーUI、は支援技術を介して）ユーザーに知らせる。さらに、必要に応じてnavigatesuccessまたはnavigateerrorイベントを発火させ、これはウェブアプリケーションの他の部分が応答できるようにする。
デフォルトでは、このメソッドを使用すると、ハンドラーから返されたプロミスが確定するときにフォーカスがリセットされる。フォーカスは、autofocus属性が設定された最初の要素、または属性が存在しない場合body要素にリセットされる。The focusReset option can be set to "manual" to avoid this behavior.
デフォルトでは、このメソッドを使用すると、ハンドラーの返り値が確定するまで、"traverse"または"reloadナビゲーションのブラウザーのスクロール復元ロジック、または"pushもしくは"replace"ナビゲーションのスクロールリセット/フラグメントへのスクロールロジックが遅延される。scrollオプションを"manual"に設定すると、このナビゲーションに対してブラウザーによるスクロール動作を完全にオフにすることができる。また、プロミスが落ち着く前にscroll()を呼び出して、この動作を早期にトリガーすることもできる。
canInterceptがfalseである場合、またはisTrustedがfalseである場合、このメソッドは"SecurityError" DOMExceptionを投げる。イベントのディスパッチ中に同期的に呼び出されなかった場合、"InvalidStateError" DOMExceptionを投げる。
event.scroll()"traverse"または"reload"ナビゲーションの場合、ブラウザーの通常のスクロール復元ロジックを使用してスクロール位置を復元する。
"push"または"replace"ナビゲーションの場合、スクロール位置を文書の先頭にリセットする、またはdestination.urlで指定されたフラグメントがあるいずれかの場合、その場所こスクロールする。
複数回呼び出された場合、scrollオプションが"after-transition"のままになっているために遷移後の自動スクロール処理が行われた後に呼び出された場合、またはナビゲーションがコミットされる前に呼び出された場合、このメソッドは"InvalidStateError" DOMExceptionを投げる。
Each NavigateEvent has an interception state, which is either "none", "intercepted", "committed", "scrolled", or "finished", initially "none".
Each NavigateEvent has a navigation handler list, a list of NavigationInterceptHandler callbacks, initially empty.
Each NavigateEvent has a focus reset behavior, a NavigationFocusReset-or-null, initially null.
Each NavigateEvent has a scroll behavior, a NavigationScrollBehavior-or-null, initially null.
Each NavigateEvent has an abort controller, an AbortController-or-null, initially null.
Each NavigateEvent has a classic history API state, a serialized state or null. It is only used in some cases where the event's navigationType is "push" or "replace", and is set appropriately when the event is fired.
The navigationType, destination, canIntercept, userInitiated, hashChange, signal, formData, downloadRequest, info, hasUAVisualTransition, and sourceElement attributes must return the values they are initialized to.
The intercept(options) method steps are:
Perform shared checks given this.
If this's canIntercept attribute was initialized to false, then throw a "SecurityError" DOMException.
If this's dispatch flag is unset, then throw an "InvalidStateError" DOMException.
Assert: this's interception state is either "none" or "intercepted".
Set this's interception state to "intercepted".
If options["handler"] exists, then append it to this's navigation handler list.
If options["focusReset"] exists, then:
If this's focus reset behavior is not null, and it is not equal to options["focusReset"], then the user agent may report a warning to the console indicating that the focusReset option for a previous call to intercept() was overridden by this new value, and the previous value will be ignored.
Set this's focus reset behavior to options["focusReset"].
If options["scroll"] exists, then:
If this's scroll behavior is not null, and it is not equal to options["scroll"], then the user agent may report a warning to the console indicating that the scroll option for a previous call to intercept() was overridden by this new value, and the previous value will be ignored.
Set this's scroll behavior to options["scroll"].
The scroll() method steps are:
Perform shared checks given this.
If this's interception state is not "committed", then throw an "InvalidStateError" DOMException.
Process scroll behavior given this.
To perform shared checks for a NavigateEvent event:
If event's relevant global object's associated Document is not fully active, then throw an "InvalidStateError" DOMException.
If event's isTrusted attribute was initialized to false, then throw a "SecurityError" DOMException.
If event's canceled flag is set, then throw an "InvalidStateError" DOMException.
NavigationDestinationインターフェイス[Exposed =Window ]
interface NavigationDestination {
readonly attribute USVString url ;
readonly attribute DOMString key ;
readonly attribute DOMString id ;
readonly attribute long long index ;
readonly attribute boolean sameDocument ;
any getState ();
};event.destination.urlナビゲート先のURL。
event.destination.key"traverse"ナビゲーションである場合、宛先NavigationHistoryEntryの keyプロパティの値。そうでなければ空の文字列。
event.destination.id"traverse"ナビゲーションである場合、宛先NavigationHistoryEntryの idプロパティの値。そうでなければ空の文字列。
event.destination.index"traverse"ナビゲーションである場合、宛先NavigationHistoryEntry のindexロパティの値。そうでなければ-1。
event.destination.sameDocumentこのナビゲーションが現在のナビゲーションと同じDocumentであるかどうかを示す。これは、たとえばフラグメントナビゲーションやhistory.pushState()ナビゲーションの場合に当てはまる。
このプロパティは、ナビゲーションの本来の性質を示していることに注意すること。navigateEvent.intercept()を使用して文書間のナビゲーションを同じ文書のナビゲーションに変換しても、このプロパティの値は変わらない。
event.destination.getState()"traverse"ナビゲーションの場合、宛先セッション履歴エントリーに格納されている状態の逆シリアル化を返す。
For "push"または"replace"ナビゲーションの場合、ナビゲーションがそのメソッドによって開始された場合はnavigation.navigate()に渡された状態の逆シリアル化を返し、開始されなかった場合はundefinedを返す。
"reload"ナビゲーションの場合、リロードがnavigation.reload()メソッドによって開始された場合、そのメソッドに渡された状態の逆シリアライズを返す。リロードが開始されなかった場合、undefinedを返す。
Each NavigationDestination has a URL, which is a URL.
Each NavigationDestination has an entry, which is a NavigationHistoryEntry or null.
It will be non-null if and only if the NavigationDestination corresponds to a "traverse" navigation.
Each NavigationDestination has a state, which is a serialized state.
Each NavigationDestination has an is same document, which is a boolean.
The url getter steps are to return this's URL, serialized.
The key getter steps are:
The id getter steps are:
The index getter steps are:
The sameDocument getter steps are to return this's is same document.
The getState() method steps are to return StructuredDeserialize(this's state).
Other parts of the standard fire the navigate event, through a series of wrapper algorithms given in this section.
To fire a traverse navigate event at a Navigation navigation given a session history entry destinationSHE and an optional user navigation involvement userInvolvement (default "none"):
Let event be the result of creating an event given NavigateEvent, in navigation's relevant realm.
Set event's classic history API state to null.
Let destination be a new NavigationDestination created in navigation's relevant realm.
Let destinationNHE be the NavigationHistoryEntry in navigation's entry list whose session history entry is destinationSHE, or null if no such NavigationHistoryEntry exists.
If destinationNHE is non-null, then:
Set destination's entry to destinationNHE.
Set destination's state to destinationSHE's navigation API state.
Otherwise,
Set destination's entry to null.
Set destination's state to StructuredSerializeForStorage(null).
Set destination's is same document to true if destinationSHE's document is equal to navigation's relevant global object's associated Document; otherwise false.
Return the result of performing the inner navigate event firing algorithm given navigation, "traverse", event, destination, userInvolvement, null, null, and null.
To fire a push/replace/reload navigate event at a Navigation navigation given a NavigationType navigationType, a URL destinationURL, a boolean isSameDocument, an optional user navigation involvement userInvolvement (default "none"), an optional Element-or-null sourceElement (default null), an optional entry list-or-null formDataEntryList (default null), an optional serialized state navigationAPIState (default StructuredSerializeForStorage(null)), and an optional serialized state-or-null classicHistoryAPIState (default null):
Let event be the result of creating an event given NavigateEvent, in navigation's relevant realm.
Set event's classic history API state to classicHistoryAPIState.
Let destination be a new NavigationDestination created in navigation's relevant realm.
Set destination's URL to destinationURL.
Set destination's entry to null.
Set destination's state to navigationAPIState.
Set destination's is same document to isSameDocument.
Return the result of performing the inner navigate event firing algorithm given navigation, navigationType, event, destination, userInvolvement, sourceElement, formDataEntryList, and null.
To fire a download request navigate event at a Navigation navigation given a URL destinationURL, a user navigation involvement userInvolvement, an Element-or-null sourceElement, and a string filename:
Let event be the result of creating an event given NavigateEvent, in navigation's relevant realm.
Set event's classic history API state to null.
Let destination be a new NavigationDestination created in navigation's relevant realm.
Set destination's URL to destinationURL.
Set destination's entry to null.
Set destination's state to StructuredSerializeForStorage(null).
Set destination's is same document to false.
Return the result of performing the inner navigate event firing algorithm given navigation, "push", event, destination, userInvolvement, sourceElement, null, and filename.
The inner navigate event firing algorithm consists of the following steps, given a Navigation navigation, a NavigationType navigationType, a NavigateEvent event, a NavigationDestination destination, a user navigation involvement userInvolvement, an Element-or-null sourceElement, an entry list-or-null formDataEntryList, and a string-or-null downloadRequestFilename:
If navigation has entries and events disabled, then:
Assert: navigation's ongoing API method tracker is null.
Assert: navigation's upcoming non-traverse API method tracker is null.
Assert: navigation's upcoming traverse API method trackers is empty.
Return true.
These assertions holds because traverseTo(), back(), and forward() will immediately fail when entries and events are disabled (since there are no entries to traverse to), and if our starting point is instead navigate() or reload(), then we avoided setting the upcoming non-traverse API method tracker in the first place.
Let destinationKey be null.
If destination's entry is non-null, then set destinationKey to destination's entry's key.
Assert: destinationKey is not the empty string.
Promote an upcoming API method tracker to ongoing given navigation and destinationKey.
Let apiMethodTracker be navigation's ongoing API method tracker.
Let navigable be navigation's relevant global object's navigable.
Let document be navigation's relevant global object's associated Document.
If document can have its URL rewritten to destination's URL, and either destination's is same document is true or navigationType is not "traverse", then initialize event's canIntercept to true. Otherwise, initialize it to false.
If either:
navigationType is not "traverse"; or
traverseCanBeCanceled is true,
then initialize event's cancelable to true. Otherwise, initialize it to false.
Initialize event's navigationType to navigationType.
Initialize event's destination to destination.
Initialize event's downloadRequest to downloadRequestFilename.
If apiMethodTracker is not null, then initialize event's info to apiMethodTracker's info. Otherwise, initialize it to undefined.
At this point apiMethodTracker's info is no longer needed and can be nulled out instead of keeping it alive for the lifetime of the navigation API method tracker.
Initialize event's hasUAVisualTransition to true if a visual transition, to display a cached rendered state of the document's latest entry, was done by the user agent. Otherwise, initialize it to false.
Initialize event's sourceElement to sourceElement.
Set event's abort controller to a new AbortController created in navigation's relevant realm.
Initialize event's signal to event's abort controller's signal.
Let currentURL be document's URL.
If all of the following are true:
event's classic history API state is null;
destination's is same document is true;
destination's URL equals currentURL with exclude fragments set to true; and
destination's URL's fragment is not identical to currentURL's fragment,
then initialize event's hashChange to true. Otherwise, initialize it to false.
The first condition here means that hashChange will be true for fragment navigations, but false for cases like history.pushState(undefined, "", "#fragment").
If userInvolvement is not "none", then initialize event's userInitiated to true. Otherwise, initialize it to false.
If formDataEntryList is not null, then initialize event's formData to a new FormData created in navigation's relevant realm, associated to formDataEntryList. Otherwise, initialize it to null.
Assert: navigation's ongoing navigate event is null.
Set navigation's ongoing navigate event to event.
Set navigation's focus changed during ongoing navigation to false.
Set navigation's suppress normal scroll restoration during ongoing navigation to false.
Let dispatchResult be the result of dispatching event at navigation.
If dispatchResult is false:
If navigationType is "traverse", then consume history-action user activation given navigation's relevant global object.
If event's abort controller's signal is not aborted, then abort the ongoing navigation given navigation.
falseを返す。
Let endResultIsSameDocument be true if event's interception state is not "none" or event's destination's is same document is true.
Prepare to run script given navigation's relevant settings object.
If event's interception state is not "none":
Set event's interception state to "committed".
Let fromNHE be the current entry of navigation.
Assert: fromNHE is not null.
Set navigation's transition to a new NavigationTransition created in navigation's relevant realm, whose navigation type is navigationType, whose from entry is fromNHE, and whose finished promise is a new promise created in navigation's relevant realm.
Mark as handled navigation's transition's finished promise.
See the discussion about other finished promises to understand why this is done.
If navigationType is "traverse", then set navigation's suppress normal scroll restoration during ongoing navigation to true.
If event's scroll behavior was set to "after-transition", then scroll restoration will happen as part of finishing the relevant NavigateEvent. Otherwise, there will be no scroll restoration. That is, no navigation which is intercepted by intercept() goes through the normal scroll restoration process; scroll restoration for such navigations is either done manually, by the web developer, or is done after the transition.
If navigationType is "push" or "replace", then run the URL and history update steps given document and event's destination's URL, with serializedData set to event's classic history API state and historyHandling set to navigationType.
Otherwise, if navigationType is "reload", then update the navigation API entries for a same-document navigation given navigation, navigable's active session history entry, and "reload".
If navigationType is "traverse", then this event firing is happening as part of the traversal process, and that process will take care of performing the appropriate session history entry updates.
If endResultIsSameDocument is true:
Let promisesList be an empty list.
For each handler of event's navigation handler list:
If promisesList's size is 0, then set promisesList to « a promise resolved with undefined ».
There is a subtle timing difference between how waiting for all schedules its success and failure steps when given zero promises versus ≥1 promises. For most uses of waiting for all, this does not matter. However, with this API, there are so many events and promise handlers which could fire around the same time that the difference is pretty easily observable: it can cause the event/promise handler sequence to vary. (Some of the events and promises involved include: navigatesuccess / navigateerror, currententrychange, dispose, apiMethodTracker's promises, and the navigation.transition.finished promise.)
Wait for all of promisesList, with the following success steps:
If event's relevant global object's associated Document is not fully active, then abort these steps.
If event's abort controller's signal is aborted, then abort these steps.
Assert: event equals navigation's ongoing navigate event.
Set navigation's ongoing navigate event to null.
Finish event given true.
Fire an event named navigatesuccess at navigation.
If apiMethodTracker is non-null, then resolve the finished promise for apiMethodTracker.
If navigation's transition is not null, then resolve navigation's transition's finished promise with undefined.
Set navigation's transition to null.
and the following failure steps given reason rejectionReason:
If event's relevant global object's associated Document is not fully active, then abort these steps.
If event's abort controller's signal is aborted, then abort these steps.
Assert: event equals navigation's ongoing navigate event.
Set navigation's ongoing navigate event to null.
Finish event given false.
Let errorInfo be the result of extracting error information from rejectionReason.
Fire an event named navigateerror at navigation using ErrorEvent, with additional attributes initialized according to errorInfo.
If apiMethodTracker is non-null, then reject the finished promise for apiMethodTracker with rejectionReason.
If navigation's transition is not null, then reject navigation's transition's finished promise with rejectionReason.
Set navigation's transition to null.
Otherwise, if apiMethodTracker is non-null, then clean up apiMethodTracker.
Clean up after running script given navigation's relevant settings object.
Per the previous note, this stops suppressing any potential promise handler microtasks, causing them to run at this point or later.
If event's interception state is "none", then return true.
falseを返す。
By calling navigateEvent.intercept(), web developers can suppress the normal scroll and focus behavior for same-document navigations, instead invoking cross-document navigation-like behavior at a later time. The algorithms in this section are called at those appropriate later points.
To finish a NavigateEvent event, given a boolean didFulfill:
Assert: event's interception state is not "intercepted" or "finished".
If event's interception state is "none", then return.
Potentially reset the focus given event.
If didFulfill is true, then potentially process scroll behavior given event.
Set event's interception state to "finished".
To potentially reset the focus given a NavigateEvent event:
Assert: event's interception state is "committed" or "scrolled".
Let navigation be event's relevant global object's navigation API.
Let focusChanged be navigation's focus changed during ongoing navigation.
Set navigation's focus changed during ongoing navigation to false.
If focusChanged is true, then return.
If event's focus reset behavior is "manual", then return.
If it was left as null, then we treat that as "after-transition", and continue onward.
Let document be event's relevant global object's associated Document.
Let focusTarget be the autofocus delegate for document.
If focusTarget is null, then set focusTarget to document's body element.
If focusTarget is null, then set focusTarget to document's document element.
Run the focusing steps for focusTarget, with document's viewport as the fallback target.
Move the sequential focus navigation starting point to focusTarget.
To potentially process scroll behavior given a NavigateEvent event:
Assert: event's interception state is "committed" or "scrolled".
If event's interception state is "scrolled", then return.
If event's scroll behavior is "manual", then return.
If it was left as null, then we treat that as "after-transition", and continue onward.
Process scroll behavior given event.
To process scroll behavior given a NavigateEvent event:
Assert: event's interception state is "committed".
Set event's interception state to "scrolled".
If event's navigationType was initialized to "traverse" or "reload", then restore scroll position data given event's relevant global object's navigable's active session history entry.
Otherwise:
Let document be event's relevant global object's associated Document.
If document's indicated part is null, then scroll to the beginning of the document given document. [CSSOMVIEW]
Otherwise, scroll to the fragment given document.
NavigateEventインターフェイスには、その複雑さのために独自の専用セクションを持つ。
NavigationCurrentEntryChangeEventインターフェイス[Exposed =Window ]
interface NavigationCurrentEntryChangeEvent : Event {
constructor (DOMString type , NavigationCurrentEntryChangeEventInit eventInitDict );
readonly attribute NavigationType ? navigationType ;
readonly attribute NavigationHistoryEntry from ;
};
dictionary NavigationCurrentEntryChangeEventInit : EventInit {
NavigationType ? navigationType = null ;
required NavigationHistoryEntry from ;
};event.navigationType現在のエントリーを変更したナビゲーションのタイプを返す。変更の原因がnavigation.updateCurrentEntry()の場合、nullを返す。
event.from現在のエントリーが変更される前のnavigation.currentEntryの値を返す。
navigationTypeがnullまたは"reload"である場合、この値はnavigation.currentEntryと同じになる。この場合、イベントは、たとえ新しいエントリーに移動しなかった、または現在のエントリーを置き換えなかったとしても、エントリーの内容が変更されたことを示す。
The navigationType and from attributes must return the values they were initialized to.
PopStateEventインターフェイスSupport in all current engines.
Support in all current engines.
[Exposed =Window ]
interface PopStateEvent : Event {
constructor (DOMString type , optional PopStateEventInit eventInitDict = {});
readonly attribute any state ;
readonly attribute boolean hasUAVisualTransition ;
};
dictionary PopStateEventInit : EventInit {
any state = null ;
boolean hasUAVisualTransition = false ;
};event.stateSupport in all current engines.
pushState()またはreplaceState()へ提供される情報のコピーを返す。
event.hasUAVisualTransitionユーザーエージェントが、このイベントをディスパッチする前に、このナビゲーションのビジュアルトランジションを実行した場合、trueを返す。trueの場合、著者がDOMをナビゲーション後の状態に同期的に更新するならば、最高のユーザーエクスペリエンスが得られる。
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.
The hasUAVisualTransition attribute must return the value it was initialized to.
HashChangeEventインターフェイスHashChangeEvent/HashChangeEvent
Support in all current engines.
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.oldURLSupport in all current engines.
以前に現在であったセッション履歴のエントリーのURLを返す。
event.newURLSupport 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.
PageSwapEventインターフェイス[Exposed =Window ]
interface PageSwapEvent : Event {
constructor (DOMString type , optional PageSwapEventInit eventInitDict = {});
readonly attribute NavigationActivation activation ;
readonly attribute ViewTransition viewTransition ;
};
dictionary PageSwapEventInit : EventInit {
NavigationActivation ? activation = null ;
ViewTransition viewTransition = null ;
};event.activationドキュメント間ナビゲーションの移動先と種類を表すNavigationActivationオブジェクト。異なる生成元のナビゲーションの場合はnullになる。
event.activation.entryアクティブになるDocumentを表すNavigationHistoryEntry。
event.activation.fromイベントが発火した時点でのnavigation.currentEntryプロパティの値に相当するNavigationHistoryEntry。
event.activation.navigationType"push"、"replace"、"reload"または"traverse"のいずれかで、ページスワップが行われるナビゲーションのタイプを示す。
event.viewTransitionイベントが発火したときに遷移がアクティブである場合、アウトバウンドの文書間の参照の遷移を表すViewTransitionオブジェクトを返す。そうでなければ、nullを返す。
The activation and viewTransition attributes must return the values they were initialized to.
PageRevealEventインターフェイス[Exposed =Window ]
interface PageRevealEvent : Event {
constructor (DOMString type , optional PageRevealEventInit eventInitDict = {});
readonly attribute ViewTransition viewTransition ;
};
dictionary PageRevealEventInit : EventInit {
ViewTransition viewTransition = null ;
};event.viewTransitionイベントが発火したときに遷移がアクティブである場合、インバウンドの文書間の参照の遷移を表す ViewTransitionオブジェクトを返す。そうでなければ、nullを返す。
The viewTransition attribute must return the value it was initialized to.
PageTransitionEventインターフェイスPageTransitionEvent/PageTransitionEvent
Support in all current engines.
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.persistedSupport in all current engines.
pageshowに対して、ページが新しく読み込まれている（およびloadイベントが発生する）場合にfalseを返す。そうでなければ、trueを返す。
pagehideイベントに対して、ページが最後の時間まで出かける場合はfalseを返す。そうでなければtrueを返す。これは、ユーザーがこのページに戻った場合（Documentのsalvageable状態がtrueのままの場合）にページが再利用される可能性があることを意味する。
ページがサルベージ不能になる原因には、次のものがある：
ユーザーエージェントが、アンロード後にセッション履歴エントリーでDocumentを存続させないことを決定した
salvageableではないiframeを持っている
アクティブなWebSocketオブジェクト
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 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.
NotRestoredReasonsインターフェイス[Exposed =Window ]
interface NotRestoredReasonDetails {
readonly attribute DOMString reason ;
[Default ] object toJSON ();
};
[Exposed =Window ]
interface NotRestoredReasons {
readonly attribute USVString ? src ;
readonly attribute DOMString ? id ;
readonly attribute DOMString ? name ;
readonly attribute USVString ? url ;
readonly attribute FrozenArray <NotRestoredReasonDetails >? reasons ;
readonly attribute FrozenArray <NotRestoredReasons >? children ;
[Default ] object toJSON ();
};notRestoredReasonDetails.reasonドキュメントがバック/フォワードキャッシュから処理できなかった理由を説明する文字列を返す。使用可能な文字列値については、bfcache blocking detailsの定義を参照。
notRestoredReasons.src文書がiframe要素である場合、文書のノードナビゲート可能のコンテナーのsrc属性を返す。設定されていない場合、またはiframe要素ではない場合、nullを指定できる。
notRestoredReasons.id文書がiframe要素である場合、文書のノードナビゲート可能のコンテナーのid属性を返す。設定されていない場合、またはiframe要素ではない場合、nullを指定できる。
notRestoredReasons.name文書がiframe要素である場合、文書のノードナビゲート可能のコンテナーのname属性を返す。設定されていない場合、またはiframe要素ではない場合、nullを指定できる。
notRestoredReasons.url文書のURL、または文書が異なる生成元のiframe内にある場合、nullを返す。これは、元のsrc が設定されてからiframeにナビゲートできるため、srcに加えて報告される。
notRestoredReasons.reasons文書のNotRestoredReasonDetails<の配列を返す。文書が生成元をまたいだiframeにある場合、これはnullである。
notRestoredReasons.children文書のNotRestoredReasonsの配列を返す。文書が生成元をまたいだiframeにある場合、これはnullである。
NotRestoredReasonDetailsオブジェクトは、バッキング構造体、復元されていない理由の詳細、またはnullを持ち、最初はnullである。
The reason getter steps are to return this's backing struct's reason.
To create a NotRestoredReasonDetails object given a not restored reason details backingStruct and a realm realm:
Let notRestoredReasonDetails be a new NotRestoredReasonDetails object created in realm.
Set notRestoredReasonDetails's backing struct to backingStruct.
Return notRestoredReasonDetails.
A not restored reason details is a struct with the following items:
reason, a string, initially empty.
The reason is a string that represents the reason that prevented the page from being restored from back/forward cache. The string is one of the following:
fetch"Document was still ongoing and was canceled, so the page was not in a state that could be stored in the back/forward cache.navigation-failure"Document errored, so storing the resulting error document in the back/forward cache was prevented.parser-aborted"Document never finished its initial HTML parsing, so storing the unfinished document in the back/forward cache was prevented.websocket"WebSocket connection was shut down, so the page was not in a state that could be stored in the back/forward cache. [WEBSOCKETS]lock"masked"Document has children that are in a cross-origin iframe, and they prevented back/forward cache; or this Document could not be back/forward cached for user agent-specific reasons, and the user agent has chosen not to use one of the more specific reasons from the list of user-agent specific blocking reasons.In addition to the list above, a user agent might choose to expose a reason that prevented the page from being restored from back/forward cache for user-agent specific blocking reasons. These are one of the following strings:
audio-capture"Document requested audio capture permission by using Media Capture and Streams's getUserMedia() with audio. [MEDIASTREAM]background-work"Document requested background work by calling SyncManager's register() method, PeriodicSyncManager's register() method, or BackgroundFetchManager's fetch() method.broadcastchannel-message"BroadcastChannel connection on the page received a message and message event was fired.idbversionchangeevent"Document had a pending IDBVersionChangeEvent while unloading. [INDEXEDDB]idledetector"Document had an active IdleDetector while unloading.keyboardlock"Keyboard's lock() method was called.mediastream"MediaStreamTrack was in the live state upon unloading. [MEDIASTREAM]midi"Document requested a MIDI permission by calling navigator.requestMIDIAccess().modals"navigating"Document was not in a state that could be stored in back/forward cache.navigation-canceled"window.stop() and the page was not in a state to be stored in back/forward cache.non-trivial-browsing-context-group"Document had more than one top-level browsing context.otpcredential"Document created an OTPCredential.outstanding-network-request"Document had outstanding network requests and was not in a state that could be stored in back/forward cache.paymentrequest"Document had an active PaymentRequest while unloading. [PAYMENTREQUEST]pictureinpicturewindow"Document had an active PictureInPictureWindow while unloading. [PICTUREINPICTURE]plugins"Document contained plugins.request-method-not-get"Document was created from an HTTP request whose method was not `GET`. [FETCH]response-auth-required"Document was created from an HTTP response that required HTTP authentication.response-cache-control-no-store"Document was created from an HTTP response whose `Cache-Control` header included the "no-store" token. [HTTP]response-cache-control-no-cache"Document was created from an HTTP response whose `Cache-Control` header included the "no-cache" token. [HTTP]response-keep-alive"Document was created from an HTTP response that contained a `Keep-Alive` header.response-scheme-not-http-or-https"Document was created from a response whose URL's scheme was not an HTTP(S) scheme. [FETCH]response-status-not-ok"Document was created from an HTTP response whose status was not an ok status. [FETCH]rtc"RTCPeerConnection or RTCDataChannel was shut down, so the page was not in a state that could be stored in the back/forward cache. [WEBRTC]sensors"Document requested sensor access.serviceworker-added"Document's service worker client started to be controlled by a ServiceWorker while the page was in back/forward cache. [SW]serviceworker-claimed"Document's service worker client's active service worker was claimed while the page was in back/forward cache. [SW]serviceworker-postmessage"Document's service worker client's active service worker received a message while the page was in back/forward cache. [SW]serviceworker-version-activated"Document's service worker client's active service worker's version was activated while the page was in back/forward cache. [SW]serviceworker-unregistered"Document's service worker client's active service worker's service worker registration was unregistered while the page was in back/forward cache. [SW]sharedworker"Document was in the owner set of a SharedWorkerGlobalScope.smartcardconnection"Document had an active SmartCardConnection while unloading.speechrecognition"Document had an active SpeechRecognition while unloading.storageaccess"Document requested storage access permission by using the Storage Access API.unload-listener"Document registered an event listener for the unload event.video-capture"Document requested video capture permission by using Media Capture and Streams's getUserMedia() with video. [MEDIASTREAM]webhid"Document called the WebHID API's requestDevice() method.webshare"Document used the Web Share API's navigator.share() method.webtransport"WebTransport connection was shut down, so the page was not in a state that could be stored in the back/forward cache. [WEBTRANSPORT]webxrdevice"Document created a XRSystem.A NotRestoredReasons object has a backing struct, a not restored reasons or null, initially null.
A NotRestoredReasons object has a reasons array, a FrozenArray< or null, initially null.NotRestoredReasonDetails>
A NotRestoredReasons object has a children array, a FrozenArray<NotRestoredReasons> or null, initially null.
The src getter steps are to return this's backing struct's src.
The id getter steps are to return this's backing struct's id.
The name getter steps are to return this's backing struct's name.
The url getter steps are:
If this's backing struct's URL is null, then return null.
Return this's backing struct's URL, serialized.
The reasons getter steps are to return this's reasons array.
The children getter steps are to return this's children array.
To create a NotRestoredReasons object given a not restored reasons backingStruct and a realm realm:
Let notRestoredReasons be a new NotRestoredReasons object created in realm.
Set notRestoredReasons's backing struct to backingStruct.
If backingStruct's reasons is null, set notRestoredReasons's reasons array to null.
Otherwise:
Let reasonsArray be an empty list.
For each reason of backingStruct's reasons:
Create a NotRestoredReasonDetails object given reason and realm, and append it to reasonsArray.
Set notRestoredReasons's reasons array to the result of creating a frozen array given reasonsArray.
If backingStruct's children is null, set notRestoredReasons's children array to null.
Otherwise:
Let childrenArray be an empty list.
For each child of backingStruct's children:
Create a NotRestoredReasons object given child and realm and append it to childrenArray.
Set notRestoredReasons's children array to the result of creating a frozen array given childrenArray.
Return notRestoredReasons.
A not restored reasons is a struct with the following items:
src, a scalar value string or null, initially null.
id, a string or null, initially null.
name, a string or null, initially null.
url, a URL or null, initially null.
reasons, null or a list of not restored reason details, initially null.
children, null or a list of not restored reasons, initially null.
A Document's not restored reasons is its node navigable's active session history entry's document state's not restored reasons, if Document's node navigable is a top-level traversable; otherwise null.