このセクションは、ウェブブラウザーに最も直接的に適用される機能について説明する。それでもやはり、特に指定しない限り、このセクションで定義されている要件は、ウェブブラウザーであるかどうかに関わらず、すべてのユーザーエージェントに適用される。
ブラウジングコンテキストはDocument
オブジェクトがユーザーに提示される環境である。
ウェブブラウザーのタブまたはウィンドウは通常、iframe
またはframeset
内のframe
を含む、ブラウジングコンテキストを含む。
ブラウジングコンテキストは、対応するWindowProxy
オブジェクトを持つ。
ブラウジングコンテキストは、オープナーブラウジングコンテキストを持ち、これはnullまたはブラウジングコンテキストである最初はnullである。
ブラウジングコンテキストは、不所有の真偽値を持つ。最初はfalseである。
ブラウジングコンテキストは、閉じている真偽値を持つ。最初はfalseである。
次の例は、ブラウジングコンテキストのさまざまな可能性を示している。不所有、閉じている、どちらでもない、または両方である可能性がある。
// Neither disowned nor is closing:
const popup1 = window. open();
// Disowned, but not is closing:
const popup2 = window. open();
popup2. opener = null ;
// Not disowned, but is closing:
const popup3 = window. open();
popup3. close();
// Disowned, is closing:
const popup4 = window. open();
popup4. opener = null ;
popup4. close();
ブラウジングコンテキストは、ブラウジングコンテキストが提示されていた、している、またはするだろうDocument
オブジェクトを一覧表示するセッション履歴を持つ。Document
のブラウジングコンテキストは、そのようなブラウジングコンテキストが存在しかつ破棄されていない場合、セッション履歴にそのDocument
が含まれるブラウジングコンテキストであり、そうでなければnullである。
Document
は、必ずしも非nullのブラウジングコンテキストを持つとは限らない。具体的には、データマイニングツールはブラウジングコンテキストをインスタンス化できないだろう。createDocument()
のような API を使用して作成されたDocument
は、非nullのブラウジングコンテキストを持つことはない。文書から削除されて以来、iframe
要素で当初は作成されたDocument
は、そのブラウジングコンテキストが破棄されたので、関連付けられたブラウジングコンテキストを持たない。
ブラウジングコンテキストのアクティブウィンドウは、その WindowProxy
オブジェクトの[[Window]]内部スロット値である。ブラウジングコンテキストのアクティブ文書は、そのアクティブウィンドウに関連付けられたDocument
である。
一般に、Document
オブジェクトが非nullブラウジングコンテキストを持っている限り、 Window
オブジェクトからDocument
オブジェクトへのマッピングは1対1になる。例外が1つある。Window
は、マッピングが1対2になるように、同じブラウジングコンテキストで2番目のDocument
のプレゼンテーションに再利用できる。これは、historyHandlingが"replace
"に設定され、ブラウジングコンテキストが初期about:blank
Document
から別のものにナビゲートしたときに起こる。
ブラウジングコンテキストは、仮想ブラウジングコンテキストグループID整数を持つ。最初は0である。これは、クロスオリジンオープナーポリシーレポートで使用され、レポートのみのポリシーが適用された場合に発生したブラウジングコンテキストグループの切り替えを追跡する。
ブラウジングコンテキストは、初期URLを持ち、これはURLまたはnullである。最初はnullである。
ブラウジングコンテキストは、作成時にオープナーオリジンを持ち。これはオリジンまたはnullである。最初はnullである。
Document
オブジェクトdocumentにブラウジングコンテキストbrowsingContextのアクティブ文書を設定するには、次の手順を実行する:
windowをdocumentの関連するグローバルオブジェクトにする。
documentの可視状態をbrowsingContextのトップレベルブラウジングコンテキストのシステムの可視状態に設定する。
browsingContextのアクティブウィンドウをwindowに設定する。
windowの関連Document
をdocumentに設定する。
windowの関連設定オブジェクトの実行準備フラグを設定する。
ブラウジングコンテキストは、関連付けられている作成者の生成元(nullまたは生成元を返す)、作成者のURL(nullまたはURLを返す)、および作成者のベースURL(nullまたはURLを返す)を持つ。これらは最初はnullである。
To determine the origin, given browsing context browsingContext, URL url, sandboxing flag set sandboxFlags, and an origin invocationOrigin:
If sandboxFlags has its sandboxed origin browsing context flag set, then return a new opaque origin.
If url is null, then return a new opaque origin.
If invocationOrigin is non-null and url matches about:blank
, then return invocationOrigin.
The result here is that two documents end up with the same underlying origin, meaning that document.domain
affects both.
If url is about:srcdoc
, then return the origin of browsingContext's container document.
Return url's origin.
To create a new browsing context, given null or a Document
object creator, null or an element embedder, and a browsing context group group, run these steps:
Let browsingContext be a new browsing context.
Let unsafeContextCreationTime be the unsafe shared current time.
If creator is non-null, then set browsingContext's creator origin to return creator's origin, browsingContext's creator URL to return creator's URL, browsingContext's creator base URL to return creator's base URL, and browsingContext's virtual browsing context group ID to creator's top-level browsing context's virtual browsing context group ID.
Let sandboxFlags be the result of determining the creation sandboxing flags given browsingContext and embedder.
Let origin be the result of determining the origin given browsingContext, about:blank
, sandboxFlags, and browsingContext's creator origin.
Let permissionsPolicy be the result of creating a permissions policy given browsingContext and origin. [PERMISSIONSPOLICY]
This needs to use embedder.
Let agent be the result of obtaining a similar-origin window agent given origin, group, and false.
Let realm execution context be the result of creating a new JavaScript realm given agent and the following customizations:
For the global object, create a new Window
object.
For the global this binding, use browsingContext's WindowProxy
object.
Let topLevelCreationURL be about:blank
if embedder is null; otherwise embedder's relevant settings object's top-level creation URL.
Let topLevelOrigin be origin if embedder is null; otherwise embedder's relevant settings object's top-level origin.
Set up a window environment settings object with about:blank
, realm execution context, null, topLevelCreationURL, and topLevelOrigin.
Let loadTimingInfo be a new document load timing info with its navigation start time set to the result of calling coarsen time with unsafeContextCreationTime and the new environment settings object's cross-origin isolated capability.
Let coop be a new cross-origin opener policy.
If creator is non-null and creator's origin is same origin with creator's relevant settings object's top-level origin, then set coop to creator's browsing context's top-level browsing context's active document's cross-origin opener policy.
Let document be a new Document
, marked as an HTML document in quirks mode, whose content type is "text/html
", origin is origin, active sandboxing flag set is sandboxFlags, permissions policy is permissionsPolicy, cross-origin opener policy is coop, load timing info is loadTimingInfo, navigation id is null, and which is ready for post-load tasks.
Assert: document's URL and document's relevant settings object's creation URL are about:blank
.
Set document's is initial about:blank
to true.
Ensure that document has a single child html
node, which itself has two empty child nodes: a head
element, and a body
element.
Set the active document of browsingContext to document.
If browsingContext's creator URL is non-null, then set document's referrer to the serialization of it.
If creator is non-null, then set document's policy container to a clone of creator's policy container.
Append a new session history entry to browsingContext's session history whose URL is about:blank
and document is document.
Completely finish loading document.
Return browsingContext.
To create a new top-level browsing context:
Let group be the result of creating a new browsing context group.
Return group's browsing context set[0].
This creates a top-level browsing context.
To create a new auxiliary browsing context, given a browsing context opener:
Let group be opener's top-level browsing context's group
Assert: group is non-null, as navigating invokes this directly.
Let browsingContext be the result of creating a new browsing context with opener's active document, null, and group.
Append browsingContext to group.
Set browsingContext's opener browsing context to opener.
Set browsingContext's virtual browsing context group ID to opener's top-level browsing context's virtual browsing context group ID.
Set browsingContext's opener origin at creation to opener's active document's origin.
Legacy-clone a browsing session storage shed with opener's browsing session and browsingContext's browsing session. [STORAGE]
Return browsingContext.
This creates a top-level browsing context that is also an auxiliary browsing context.
To create a new nested browsing context, given an element element:
Let group be element's node document's browsing context's top-level browsing context's group.
Let browsingContext be the result of creating a new browsing context with element's node document, element, and group.
Set element's nested browsing context to browsingContext.
If element has a name
attribute, then set browsingContext's name to the value of this attribute.
特定の要素(たとえば、iframe
要素)は、ブラウジングコンテキストをさらにインスタンス化できる。この要素は、ブラウジングコンテキストコンテナーと呼ばれる。
各ブラウジングコンテキストコンテナーは、ブラウジングコンテキストまたはnullのいずれとなる、ネストされたブラウジングコンテキストを持つ。最初はnullである。
ブラウジングコンテキストbcのコンテナーは、ネストされたブラウジングコンテキストがbcであるブラウジングコンテキストコンテナーであり、そのような要素がない場合はnullである。
各ブラウジングコンテキストbcは、コンテナー文書を持ち、これは次の手順を実行した結果である:
childのコンテナー文書がnullでなく、かつchildのコンテナー文書のブラウジングコンテキストがparentである場合、ブラウジングコンテキストchildは、別のブラウジングコンテキストparentの子ブラウジングコンテキストと呼ばれる。
ブラウジングコンテキストchildは、childが子ブラウジングコンテキストであり、かつchildのコンテナーが文書ツリー内である場合、parentの文書ツリーの子ブラウジングコンテキストである。
ブラウジングコンテキストchildは親ブラウジングコンテキストを持ってもよい。もしそのようなブラウジングコンテキストが存在すれば、これは子ブラウジングコンテキストとしてchildを持つ一意なブラウジングコンテキストである。そうでなければ、ブラウジングコンテキストは、親ブラウジングコンテキストを持たない。
ブラウジングコンテキストAがAの子ブラウジングコンテキストであり、かつBの祖先自身であるブラウジングコンテキストA'が存在する場合、またはブラウジングコンテキストAがBの親ブラウジングコンテキストである場合、ブラウジングコンテキストBの祖先であるといわれる。
親ブラウジングコンテキストを持たないブラウジングコンテキストは、それ自身のトップレベルブラウジングコンテキストであり、祖先ブラウジングコンテキストであるブラウジングコンテキストのすべてとなる。
トップレベルブラウジングコンテキストは、関連するグループ(nullまたはブラウジングコンテキストグループ)を持つ。最初はnullである。
トップレベルブラウジングコンテキストは、ポップアップ真偽値を持つ。最初はfalseである。
この仕様での唯一の必須の影響はポップアップであり、関連するBarProp
オブジェクトのvisible
ゲッターにある。しかし、ユーザーエージェントは次の方法でも使用できる:
どちらの場合も、ユーザーエージェントはユーザー設定を追加で組み込むか、ポップアップルートをたどるかどうかの選択肢を提示する場合がある。
そのようなポップアップに最小限のウェブブラウザーユーザーインターフェイスを提供するユーザーエージェントは、ブラウザーのロケーションバーを非表示にしないことを勧める。
コンテナーがnullの間に、トップレベルブラウジングコンテキストに関連する新しいブラウジングコンテキストを作成することができる。そのようなブラウジングコンテキストは、補助ブラウジングコンテキストと呼ばれる。補助ブラウジングコンテキストは常にトップレベルブラウジングコンテキストである。
子ブラウジングコンテキストであるブラウジングコンテキストに対する親ブラウジングコンテキストの推移的クロージャは、祖先ブラウジングコンテキストのリストを与える。
Document
dの子孫ブラウジングコンテキストのリストは、以下のアルゴリズムによって返される(順序付きの)リストである:
listを空のリストにする。
ネストされたブラウジングコンテキストがnullでなく、シャドウを含むルートがdである各ブラウジングコンテキストコンテナーcontainerごとに、シャドウを含むツリーの順序で:
nestedBCをコンテナーのネストされたブラウジングコンテキストにする。
nestedBCをlistに追加する。
nestedBCのアクティブ文書の子孫ブラウジングコンテキストのリストでlistを拡張する。
listを返す。
Document
dは、dのブラウジングコンテキストがnullでなく、dのブラウジングコンテキストのアクティブ文書がdであり、dのブラウジングコンテキストがトップレベルブラウジングコンテキストであるか、dのブラウジングコンテキストのコンテナー文書が完全にアクティブであるかのいずれかの場合に、完全にアクティブであるという。
子ブラウジングコンテキストは要素に関連付けられているため、常にその親ブラウジングコンテキスト内の特定のDocument
に関連付けられている。 ユーザーエージェントは、ユーザーにがいない自身が完全にアクティブでないDocument
にある要素の子ブラウジングコンテキストと対話することを許可してはならない。
次の例は、アクティブなDocument
オブジェクトと完全にアクティブなDocument
オブジェクトの違いを示している。 ここで、a.html
はブラウザーのウィンドウに読み込まれ、b-1.html
は示されているように最初にiframe
に読み込まれ、b-2.html
およびc.html
は省略される(単に空の文書にすることができる)。
<!-- a.html -->
<!DOCTYPE html>
< html lang = "en" >
< title > Browsing context A</ title >
< iframe src = "b-1.html" ></ iframe >
< button onclick = "frames[0].location.href = 'b-2.html'" > Click me</ button >
<!-- b-1.html -->
<!DOCTYPE html>
< html lang = "en" >
< title > Browsing context B</ title >
< iframe src = "c.html" ></ iframe >
この時点で、a.html
、b-1.html
、およびc.html
によって提供される文書はすべて、それぞれのブラウジングコンテキストのアクティブな文書である。それらはまた、すべて完全にアクティブである。
button
をクリックし、b-2.html
からブラウジングコンテキストBに新しいDocument
をロードする後に、次の結果が得られる:
b-1.html
Document
は、ブラウジングコンテキストBのアクティブな文書ではなくなった。そのため、完全にアクティブにもならない。
新しいb-2.html
Document
は、ブラウジングコンテキストBのアクティブな文書になり、完全にアクティブにもなる。
c.html
Document
は引き続きブラウジングコンテキストCのアクティブな文書である。しかし、Cのコンテナー文書はb-1.html
Document
であり、それ自身は完全にアクティブではないため、 c.html
Document
は完全にアクティブにはならない(アクティブであるにもかかわらず)。
ここに含まれる複雑さ、特にセッション履歴に影響を与える詳細については、A Model of Navigation Historyを参照のこと。[NAVMODEL]
子ブラウジングコンテキストは、遅延load
イベントモードにすることができる。新しいDocument
が作成される前に、コンテナーのロードイベントを遅延させるために、ナビゲート時に使用される。
ブラウジングコンテキストの文書ファミリーは、そのブラウジングコンテキストのセッション履歴ですべてのDocument
オブジェクトおよびすべてのそれらDocument
オブジェクトの文書ファミリーの和集合で構成される。Document
オブジェクトの文書ファミリーは、Document
オブジェクトの子孫のブラウジングコンテキストのリストにあるブラウジングコンテキストのすべての文書ファミリーの和集合で構成される。
ブラウジングコンテキストコンテナー containerのコンテンツ文書は、次のアルゴリズムの結果である:
containerのネストされたブラウジングコンテキストがnullである場合、nullを返す。
contextをcontainerのネストされたブラウジングコンテキストにする。
documentをcontextのアクティブ文書にする。
documentを返す。
window.top
Support in all current engines.
window.opener [ = value ]
Support in all current engines.
オープナーブラウジングコンテキストに対するWindowProxy
を返す。
存在しないまたはnullが設定されている場合、nullを返す。
nullに設定可能である。
window.parent
Support in all current engines.
親ブラウジングコンテキストに対するWindowProxy
を返す。
window.frameElement
Support in all current engines.
存在しない場合、生成元をまたいだ状況でnullを返す。
The top
attribute's getter must run these steps:
If this Window
object's browsing context is null, then return null.
Return this Window
object's browsing context's top-level browsing context's WindowProxy
object.
The opener
getter steps are:
Let current be this's browsing context.
If current is null, then return null.
If current's disowned is true, 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 disowned to true.
If the given value is non-null, then return ? OrdinaryDefineOwnProperty(this, "opener
", { [[Value]]: the given value, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true }).
If a browsing context's disowned is true, its window.opener
attribute is null. That prevents scripts in the browsing context from changing any properties of its opener browsing context's Window
object (i.e., the Window
object from which the browsing context was created).
Otherwise, if a browsing context's disowned is false, then scripts in that browsing context can use window.opener
to change properties of its opener browsing context's Window
object. For example, a script running in the browsing context can change the value of window.opener.location
, causing the opener browsing context to navigate to a completely different document.
The parent
attribute's getter must run these steps:
Let current be this Window
object's browsing context.
If current is null, then return null.
If current is a child browsing context of another browsing context parent, then return parent's WindowProxy
object.
Assert: current is a top-level browsing context.
Return current's WindowProxy
object.
The frameElement
getter steps are:
Let current be this Window
object's browsing context.
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 IDL attributes 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 discarded when element
was removed from the document.
A browsing context A is familiar with a second browsing context B if one of the following conditions is true:
A browsing context A is allowed to navigate a second browsing context B if the following algorithm returns true:
If A is not the same browsing context as B, and A is not one of the ancestor browsing contexts of B, and B is not a top-level browsing context, and A's active document's active sandboxing flag set has its sandboxed navigation browsing context flag set, then return false.
Otherwise, if B is a top-level browsing context, and is one of the ancestor browsing contexts of A, then:
If A's active window has transient activation and A's active document's active sandboxing flag set has its sandboxed top-level navigation with user activation browsing context flag set, then return false.
Otherwise, if A's active window does not have transient activation and A's active document's active sandboxing flag set has its sandboxed top-level navigation without user activation browsing context flag set, then return false.
Otherwise, if B is a top-level browsing context, and is neither A nor one of the ancestor browsing contexts of A, and A's Document
's active sandboxing flag set has its sandboxed navigation browsing context flag set, and A is not the one permitted sandboxed navigator of B, then return false.
Return true.
An element has a browsing context scope origin if its Document
's browsing context is a top-level browsing context or if all of its Document
's ancestor browsing contexts all have active documents whose origins are the same origin as the element's node document's origin. If an element has a browsing context scope origin, then its value is the origin of the element's node document.
A user agent holds a browsing context group set (a set of browsing context groups).
A browsing context group holds a browsing context set (a set of top-level browsing contexts).
A top-level browsing context is added to the group when the group is created. All subsequent top-level browsing contexts added to the group will be auxiliary browsing contexts.
A browsing context group has an associated agent cluster map (a weak map of agent cluster keys to agent clusters). User agents are responsible for collecting agent clusters when it is deemed that nothing can access them anymore.
A browsing context group has an associated historical agent cluster key map, which is a map of origins to agent cluster keys. This map is used to ensure the consistency of the origin-keyed agent clusters feature by recording what agent cluster keys were previously used for a given origin.
The historical agent cluster key map only ever gains entries over the lifetime of the browsing context group.
A browsing context group has a cross-origin isolation mode, which is a cross-origin isolation mode. It is initially "none
".
A cross-origin isolation mode is one of three possible values: "none
", "logical
", or "concrete
".
"logical
" and "concrete
" are similar. They are both used for browsing context groups where:
every top-level Document has `Cross-Origin-Opener-Policy: same-origin
`, and
every Document has a `Cross-Origin-Embedder-Policy
` header whose value is compatible with cross-origin isolation.
On some platforms, it is difficult to provide the security properties required to grant safe access to the APIs gated by the cross-origin isolated capability. As a result, only "concrete
" can grant access that capability. "logical
" is used on platform not supporting this capability, where various restrictions imposed by cross-origin isolation will still apply, but the capability is not granted.
To create a new browsing context group, run these steps:
Let group be a new browsing context group.
Append group to the user agent's browsing context group set.
Let browsingContext be the result of creating a new browsing context with null, null, and group.
Append browsingContext to group.
Return group.
To append a top-level browsing context browsingContext to a browsing context group group, run these steps:
Append browsingContext to group's browsing context set.
Set browsingContext's group to group.
To remove a top-level browsing context browsingContext, run these steps:
Assert: browsingContext's group is non-null, because a browsing context only gets discarded once.
Let group be browsingContext's group.
Set browsingContext's group to null.
Remove browsingContext from group's browsing context set.
If group's browsing context set is empty, then remove group from the user agent's browsing context group set.
Append and remove are primitive operations that help define the lifetime of a browsing context group. They are called from creating a new browsing context group, creating a new auxiliary browsing context, and discarding a browsing context.
The HTML Standard used to define "
" and " ". These have been removed as they were not adequate.ブラウジングコンテキストは、ブラウジングコンテキスト名を持つことができる。特に明記しない限り、それは空文字列である。
妥当なブラウジングコンテキスト名は、U+005F LOW LINE文字で始まらない少なくとも1文字をもつ任意の文字列である。(アンダースコアで始まる名前は、特別なキーワードのために予約されている。)
妥当なブラウジングコンテキスト名またはキーワードは、妥当なブラウジングコンテキスト名またはASCII大文字・小文字不区別で_blank
、_self
、_parent
、または_top
の1つに一致するいずれかとなる任意の文字列である。
これらの値は、以下の(非規範的な)テーブルで要約されるように、ページがサンドボックス化されるかどうかに基づいて異なる意味を持つ。この表において、"current"はリンクまたはスクリプト内にあるブラウジングコンテキストを意味し、"parent"はリンクまたはスクリプト内にあるいずれかの親ブラウジングコンテキストを意味し、"top"はリンクまたはスクリプトがあるいずれかのトップレベルブラウジングコンテキストを意味し、"new"はさまざまなユーザー設定とユーザーエージェントのポリシーに次第で、新しいトップレベルブラウジングコンテキストまたは補助ブラウジングコンテキストが作成されることを意味し、"none"は何も起こらないことを意味し、"maybe new"は"allow-popups
"キーワードはまたsandbox
属性で指定される場合(またはユーザーがサンドボックスを覆う場合)、"new"と同じであり、そうでなければ"none"と同じである。
キーワード | 普通の効果 | iframe での効果 | |
---|---|---|---|
sandbox="" | sandbox="allow-top-navigation" | ||
リンクおよびフォーム送信に対して、何も指定しない | current | current | current |
空文字列 | current | current | current |
_blank | new | maybe new | maybe new |
_self | current | current | current |
親が存在しない場合の_parent | current | current | current |
親がまたトップである場合の_parent | parent/top | none | parent/top |
存在するがトップでない場合の_parent | parent | none | none |
トップが現在である場合の_top | current | current | current |
トップが現在でない場合の_top | top | none | top |
名前が存在しない | new | maybe new | maybe new |
名前が存在しかつ子孫である | specified descendant | specified descendant | specified descendant |
名前が存在し現在である | current | current | current |
名前が存在しかつトップとなる祖先である | specified ancestor | none | specified ancestor/top |
名前が存在しかつトップでない祖先である | specified ancestor | none | none |
他の名前が共通のトップとともに存在する | specified | none | none |
familiarかつある許可されたサンドボックス化されたナビゲーターである場合、異なるトップをもつ名前が存在する | specified | specified | specified |
familiarだがある許可されたサンドボックス化されたナビゲーターでない場合、異なるトップをもつ名前が存在する | specified | none | none |
familiarでない、異なるトップをもつ名前が存在する | new | maybe new | maybe new |
サンドボックス化されたブラウジングコンテキストの制限のほとんどは、他のアルゴリズムにより適用される。たとえば、下記で与えられるブラウジングコンテキスト名を選択するための規則でなく、ナビゲーションアルゴリズムとして。
The rules for choosing a browsing context, given a browsing context name name, a browsing context current, and a boolean noopener are as follows:
Let chosen be null.
Let windowType be "existing or none
".
Let sandboxingFlagSet be current's active document's active sandboxing flag set.
If name is the empty string or an ASCII case-insensitive match for "_self
", then set chosen to current.
Otherwise, if name is an ASCII case-insensitive match for "_parent
", set chosen to current's parent browsing context, if any, and current otherwise.
Otherwise, if name is an ASCII case-insensitive match for "_top
", set chosen to current's top-level browsing context, if any, and current otherwise.
Otherwise, if name is not an ASCII case-insensitive match for "_blank
", there exists a browsing context whose name is the same as name, current is familiar with that browsing context, and the user agent determines that the two browsing contexts are related enough that it is ok if they reach each other, set chosen to that browsing context. If there are multiple matching browsing contexts, the user agent should set chosen to one in some arbitrary consistent manner, such as the most recently opened, most recently focused, or more closely related.
This will be made more precise in issue #313.
Otherwise, a new browsing context is being requested, and what happens depends on the user agent's configuration and abilities — it is determined by the rules given for the first applicable option from the following list:
The user agent may inform the user that a popup has been blocked.
The user agent may report to a developer console that a popup has been blocked.
Set windowType to "new and unrestricted
".
If current's top-level browsing context's active document's cross-origin opener policy's value is "same-origin
" or "same-origin-plus-COEP
", then:
Let currentDocument be current's active document.
If currentDocument's origin is not same origin with currentDocument's relevant settings object's top-level origin, then set noopener to true, name to "_blank
", and windowType to "new with no opener
".
In the presence of a cross-origin opener policy, nested documents that are cross-origin with their top-level browsing context's active document always set noopener to true.
If noopener is true, then set chosen to the result of creating a new top-level browsing context.
Otherwise:
Set chosen to the result of creating a new auxiliary browsing context with current.
If sandboxingFlagSet's sandboxed navigation browsing context flag is set, then current must be set as chosen's one permitted sandboxed navigator.
If sandboxingFlagSet's sandbox propagates to auxiliary browsing contexts flag is set, then all the flags that are set in sandboxingFlagSet must be set in chosen's popup sandboxing flag set.
If name is not an ASCII case-insensitive match for "_blank
", then set chosen's name to name.
If the newly created browsing context is immediately navigated, then the navigation will be done with a "replace
" history handling behavior.
Set chosen to current.
Do nothing.
User agents are encouraged to provide a way for users to configure the user agent to always reuse current.
Return chosen and windowType.
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.
When perform a security check is invoked, with a platformObject, identifier, and type, run these steps:
If platformObject is not a Window
or Location
object, then return.
For each e of CrossOriginProperties(platformObject):
If SameValue(e.[[Property]], identifier) is true, then:
If type is "method
" and e has neither [[NeedsGet]] nor [[NeedsSet]], then return.
Otherwise, if type is "getter
" and e.[[NeedsGet]] is true, then return.
Otherwise, if type is "setter
" and e.[[NeedsSet]] is true, then return.
If IsPlatformObjectSameOrigin(platformObject) is false, then throw a "SecurityError
" DOMException
.
Window
and Location
objects both have a [[CrossOriginPropertyDescriptorMap]] internal slot, whose value is initially an empty map.
The [[CrossOriginPropertyDescriptorMap]] internal slot contains a map with entries whose keys are (currentGlobal, objectGlobal, propertyKey)-tuples and values are property descriptors, as a memoization of what is visible to scripts when currentGlobal inspects a Window
or Location
object from objectGlobal. It is filled lazily by CrossOriginGetOwnPropertyHelper, which consults it on future lookups.
User agents should allow a value held in the map to be garbage collected along with its corresponding key when nothing holds a reference to any part of the value. That is, as long as garbage collection is not observable.
For example, with const href = Object.getOwnPropertyDescriptor(crossOriginLocation, "href").set
the value and its corresponding key in the map cannot be garbage collected as that would be observable.
User agents may have an optimization whereby they remove key-value pairs from the map when document.domain
is set. This is not observable as document.domain
cannot revisit an earlier value.
For example, setting document.domain
to "example.com
" on www.example.com means user agents can remove all key-value pairs from the map where part of the key is www.example.com, as that can never be part of the origin again and therefore the corresponding value could never be retrieved from the map.
If O is a Location
object, then return « { [[Property]]: "href
", [[NeedsGet]]: false, [[NeedsSet]]: true }, { [[Property]]: "replace
" } ».
Return « { [[Property]]: "window
", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "self
", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "location
", [[NeedsGet]]: true, [[NeedsSet]]: true }, { [[Property]]: "close
" }, { [[Property]]: "closed
", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "focus
" }, { [[Property]]: "blur
" }, { [[Property]]: "frames
", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "length
", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "top
", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "opener
", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "parent
", [[NeedsGet]]: true, [[NeedsSet]]: false }, { [[Property]]: "postMessage
" } ».
This abstract operation does not return a Completion Record.
Indexed properties do not need to be safelisted in this algorithm, as they are handled directly by the WindowProxy
object.
A JavaScript property name P is a cross-origin accessible window property name if it is "window
", "self
", "location
", "close
", "closed
", "focus
", "blur
", "frames
", "length
", "top
", "opener
", "parent
", "postMessage
", or an array index property name.
If P is "then
", @@toStringTag, @@hasInstance, or @@isConcatSpreadable, then return PropertyDescriptor{ [[Value]]: undefined, [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
Throw a "SecurityError
" DOMException
.
Return true if the current settings object's origin is same origin-domain with O's relevant settings object's origin, and false otherwise.
This abstract operation does not return a Completion Record.
Here the current settings object roughly corresponds to the "caller", because this check occurs before the execution context for the getter/setter/method in question makes its way onto the JavaScript execution context stack. For example, in the code w.document
, this step is invoked before the document
getter is reached as part of the [[Get]] algorithm for the WindowProxy
w.
If this abstract operation returns undefined and there is no custom behavior, the caller needs to throw a "SecurityError
" DOMException
. In practice this is handled by the caller calling CrossOriginPropertyFallback.
Let crossOriginKey be a tuple consisting of the current settings object, O's relevant settings object, and P.
For each e of CrossOriginProperties(O):
If SameValue(e.[[Property]], P) is true, then:
If the value of the [[CrossOriginPropertyDescriptorMap]] internal slot of O contains an entry whose key is crossOriginKey, then return that entry's value.
Let originalDesc be OrdinaryGetOwnProperty(O, P).
Let crossOriginDesc be undefined.
If e.[[NeedsGet]] and e.[[NeedsSet]] are absent, then:
Let value be originalDesc.[[Value]].
If IsCallable(value) is true, then set value to an anonymous built-in function, created in the current Realm Record, 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 Record, 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 Record, that performs the same steps as the setter of the IDL attribute P on object O.
Set crossOriginDesc to PropertyDescriptor{ [[Get]]: crossOriginGet, [[Set]]: crossOriginSet, [[Enumerable]]: false, [[Configurable]]: true }.
Create an entry in the value of the [[CrossOriginPropertyDescriptorMap]] internal slot of O with key crossOriginKey and value crossOriginDesc.
Return crossOriginDesc.
Return undefined.
This abstract operation does not return a Completion Record.
The reason that the property descriptors produced here are configurable is to preserve the invariants of the essential internal methods required by the JavaScript specification. In particular, since the value of the property can change as a consequence of navigation, it is required that the property be configurable. (However, see tc39/ecma262 issue #672 and references to it elsewhere in this specification for cases where we are not able to preserve these invariants, for compatibility with existing web content.) [JAVASCRIPT]
The reason the property descriptors are non-enumerable, despite this mismatching the same-origin behavior, is for compatibility with existing web content. See issue #3183 for details.
Let desc be ? O.[[GetOwnProperty]](P).
Assert: desc is not undefined.
If IsDataDescriptor(desc) is true, then return desc.[[Value]].
Assert: IsAccessorDescriptor(desc) is true.
Let getter be desc.[[Get]].
If getter is undefined, then throw a "SecurityError
" DOMException
.
Return ? Call(getter, Receiver).
Let desc be ? O.[[GetOwnProperty]](P).
Assert: desc is not undefined.
If desc.[[Set]] is present and its value is not undefined, then:
Perform ? Call(setter, Receiver, «V»).
Return true.
Throw a "SecurityError
" DOMException
.
Let keys be a new empty List.
For each e of CrossOriginProperties(O), append e.[[Property]] to keys.
Return the concatenation of keys and « "then
", @@toStringTag, @@hasInstance, @@isConcatSpreadable ».
This abstract operation does not return a Completion Record.