セッション履歴とナビ


【この訳に固有の表記規約】

この訳の,~algoや定義の記述に利用されている各種記号( ~LET, ~IF, ε, 此れ, ~THROW 等々)の意味や定義の詳細は,~SYMBOL_DEF_REFを~~参照されたし。

7.7. ~session履歴と~navi

7.7.1. 閲覧文脈の~session履歴

`閲覧文脈$ %B に`属する文書$たちからなる連列は、 %B の`~session履歴$を成す†。 `入子の閲覧文脈$を含め,どの`閲覧文脈$も、互いに別個の`~session履歴$を有する。 各 `~session履歴@ は,何個かの`~session履歴~entry$からなる平坦な~listである。

【† この記述は、文書と~session履歴~entryとを同一視している。 しかしながら、複数の~entryが同じ文書に対応し得る。 】

各 `~session履歴~entry@ は,次のものからなる:

  • `~URL$
  • `直列形の状態$
  • ~title
  • `文書$
  • ~form~data
  • `~scroll復旧~mode$
  • ~scroll位置
  • `閲覧文脈~名$

これらのうち,`~URL$のみが必須とされる。 ~entryには、これら以外の情報も結付けられ得る。

◎ The sequence of Documents in a browsing context is its session history. Each browsing context, including nested browsing contexts, has a distinct session history. A browsing context's session history consists of a flat list of session history entries. Each session history entry consists, at a minimum, of a URL, and each entry may in addition have serialized state, a title, a Document object, form data, a scroll restoration mode, a scroll position, a browsing context name, and other information associated with it.

注記: 各~entryは、最初に作成された時点で`文書$が結付けられるが、`文書$が`作動中$でないときは,資源を解放するため`破棄-$docされることもある。 `~session履歴~entry$内の`~URL$その他の~dataは、~UAが その`文書$を再び作動化する必要があると見出した場合に,元のものから新たな`文書$に代替わりするときに利用される。 ◎ Each entry, when first created, has a Document. However, when a Document is not active, it's possible for it to be discarded to free resources. The URL and other data in a session history entry is then used to bring a new Document into being to take the place of the original, in case the user agent finds itself having to reactivate that Document.

注記: `~session履歴~entry$の~titleは、`文書$の現在の `title$e に関係する必要はない。 この~titleが意図する所は、利用者が文書の履歴を~navigateできるよう,その時点での文書の状態を説明するためにある。 ◎ Titles associated with session history entries need not have any relation with the current title of the Document. The title of a session history entry is intended to explain the state of the document at that point, so that the user can navigate the document's history.

`直列形の状態$が結付けらていない~URLは、利用者が(または~scriptにより)頁から頁へ~navigateするに伴い,~session履歴に追加される。 ◎ URLs without associated serialized state are added to the session history as the user (or script) navigates from page to page.


`閲覧文脈$の`~session履歴$内の各 `文書$には、一意な `History$I ~objが結付けられる — そのいずれも、同じ下層の`~session履歴$を~model化し~MUST。 ◎ Each Document object in a browsing context's session history is associated with a unique History object which must all model the same underlying session history.

`~window$上の `history@m 属性の取得子は、此れに`結付けられている文書$に結付けられている `History$I ~objを返さ~MUST。 ◎ The history attribute of the Window interface must return the object implementing the History interface for this Window object's associated Document.


`直列形の状態@ は、~UI状態を表現している~objを( `StructuredSerializeForStorage$jA を介して)直列化したものである。 非公式には、 “状態~obj” と呼ばれることもある — それは、[ 作者から給された,~UI状態を表現している~obj ],あるいは[ `直列形の状態$を( `StructuredDeserialize$jA を介して)逆直列化して作成される~obj ]を表す。 ◎ Serialized state is a serialization (via StructuredSerializeForStorage) of an object representing a user interface state. We sometimes informally refer to "state objects", which are the objects representing user interface state supplied by the author, or alternately the objects created by deserializing (via StructuredDeserialize) serialized state.

頁は、~session履歴に`直列形の状態$を追加できる。 これは、利用者(または~script)が履歴~内を後戻したときに,`逆直列化-$された上で ~scriptに返される。 したがって、 1 頁だけの~appにおいても,作者が “~navi” の~metaphorを利用できるようにする。 ◎ Pages can add serialized state to the session history. These are then deserialized and returned to the script when the user (or script) goes back in the history, thus enabling authors to use the "navigation" metaphor even in one-page applications.

注記: `直列形の状態$には、主に二つの用途が意図されている: ◎ Serialized state is intended to be used for two main purposes:\

  • 一つは、予め構文解析した状態の記述を `~URL$と一緒に格納して,単純な事例では 作者が構文解析せずに済むようにすること(元々利用者から渡された`~URL$を取扱うときは,依然として それを構文解析する必要があるので、これは小さな最適化に過ぎない)。 ◎ first, storing a preparsed description of the state in the URL so that in the simple case an author doesn't have to do the parsing (though one would still need the parsing for handling URLs passed around by users, so it's only a minor optimization).\
  • もう一つは、他からは格納されない状態 — 現在の`文書$~instanceにのみ適用され,同じ~URLの`文書$が新たに開かれるときには再構築される必要があるような、状態 — を,作者が ~URLと一緒に格納できるようにすること。 ◎ Second, so that the author can store state that one wouldn't store in the URL because it only applies to the current Document instance and it would have to be reconstructed if a new Document were opened.

後者の用例には、次が挙げられる: ◎ An example of the latter would be\

  • 利用者が後戻するときに、以前に~animateさせていた~popup `div$e を,同じ所在から~animateし続けれるよう,精確に協調するように追跡する。 ◎ something like keeping track of the precise coordinate from which a pop-up div was made to animate, so that if the user goes back, it can be made to animate to the same location.\
  • [[ `~URL$ 内の情報に基づいて~serverから~fetchされるような~data ]の~cache ]の中への~pointerを保っておいて、後戻する/先進するときに,その情報を再度~fetchせずに済むようにする。 ◎ Or alternatively, it could be used to keep a pointer into a cache of data that would be fetched from the server based on the information in the URL, so that when going back and forward, the information doesn't have to be fetched again.

どの時点においても,`~session履歴$内のある 1 つの~entryが `現在の~entry@ になる。 これは、`閲覧文脈$にて`作動中の文書$を表現している~entryになる。 どの~entryが`現在の~entry$になるかは、この仕様に定義される~algo — 例えば`履歴を走査する$間など — により変更される。 ◎ At any point, one of the entries in the session history is the current entry. This is the entry representing the active document of the browsing context. Which entry is the current entry is changed by the algorithms defined in this specification, e.g. during session history traversal.

【 `作動中の文書$は常にあるので、~session履歴が空になることはない。 】

注記: `現在の~entry$は,通例的には`文書$の`~URL$docに対する~entryであるが、その文書により履歴に追加されたいずれかの`直列形の状態$に対する~entryにもなり得る。 ◎ The current entry is usually an entry for the URL of the Document. However, it can also be one of the entries for serialized state added to the history by that document.

~UAにより定義される状態も持つような~entryは、 `持続的~利用者~状態を伴う@ とされる。 どのような種類の状態を格納し得るかは、この仕様では,指定しない。 ◎ An entry with persisted user state is one that also has user-agent defined state. This specification does not specify what kind of state can be stored.

例えば、~scroll位置や,~form~controlの値を持続化しようと求める~UAもある。 ◎ For example, some user agents might want to persist the scroll position, or the values of form controls.

注記: ~form~controlの値を持続化する~UAには、それらの書字方向性(要素の `dir$a 属性~値)も持続化することが奨励される。 これは、明示的かつ非~既定の書字方向性の下で,利用者が元々手入力した値が,履歴の走査~後に不正に表示されることを防止する。 ◎ User agents that persist the value of form controls are encouraged to also persist their directionality (the value of the element's dir attribute). This prevents values from being displayed incorrectly after a history traversal when the user had originally entered the values with an explicit, non-default directionality.

~entryの `~scroll復旧~mode@ は、~UAがその~entryへ走査したとき,持続的~scroll位置(もしあれば)を復旧するべきかどうかを指示する。 ~scroll復旧~modeは次のいずれかをとり得る: ◎ An entry's scroll restoration mode indicates whether the user agent should restore the persisted scroll position (if any) when traversing to it. The scroll restoration mode may be one of the following:

`auto@l
~UAが、~naviに際して~scroll位置を復旧する責を負う。 ◎ The user agent is responsible for restoring the scroll position upon navigation.
`manual@l
頁が、~naviに際して~scroll位置を復旧する責を負う。 ~UAは、それを自動的に試みない。 ◎ The page is responsible for restoring the scroll position and the user agent does not attempt to do so automatically

指定されていない場合、新たな~entryの`~scroll復旧~mode$は `auto$l に設定され~MUST。 ◎ If unspecified, the scroll restoration mode of a new entry must be set to "auto".

`直列形の状態$を包含する各~entryは、その追加-時に作動中であった頁に対する~entryと同じ`文書$を共有する。 ◎ Entries that contain serialized state share the same Document as the entry for the page that was active when they were added.

`~URL$の`素片$urlのみ相違するような,連続的な各~entryも、同じ`文書$を共有する。 ◎ Contiguous entries that differ just by their URLs' fragments also share the same Document.

注記: 同じ`文書$を共有するすべての~entryは、定義により連続的になる(それらは、単に,特定0の文書の異なる状態たちである)。 ◎ All entries that share the same Document (and that are therefore merely different states of one particular document) are contiguous by definition.

`閲覧文脈$ %B に`属する文書$ %文書 の `最近の~entry@ とは、[ %B の`~session履歴$内の~entry ]のうち[ ~entryの`文書$ ~EQ %文書 ]なるもの ]があれば、それらのうち最も近過去に走査された~entryである。 そのような~entryがなければ(`文書$の作成-時)、 ε (なし)とする。 ◎ Each Document in a browsing context can also have a latest entry. This is the entry for that Document to which the browsing context's session history was most recently traversed. When a Document is created, it initially has no latest entry.

~UAは、`~session履歴$内の~entry %entry に対しては:

  • [ %entry は`現在の~entry$でない ]~AND[ %entry は どの~scriptからも参照されていない ]ならば、 %entry の`文書$を,`破棄-$docしてよい — 利用者/~scriptがそのような頁に~navigateして戻ったときは,頁を再読込みすることになる。 この仕様は、~UAがいつ`文書$を[ 破棄する/~cacheする ]べきかについては指定しない。 ◎ User agents may discard the Document objects of entries other than the current entry that are not referenced from any script, reloading the pages afresh when the user or script navigates back to such pages. This specification does not specify when user agents should discard Document objects and when they should cache them.
  • 前項により %entry の`文書$が破棄されたとしても、下に与える各種~algoの目的0においては,そうでなかったかのように動作し~MUST。 利用者あるいは~scriptが,~DOM~objを~~記憶していない頁へ~navigateして戻った/進んだときは、同じ`文書$を共有していた他の~entryも,その新たな文書~objを共有し~MUST。 ◎ Entries that have had their Document objects discarded must, for the purposes of the algorithms given below, act as if they had not. When the user or script navigates back or forwards to a page which has no in-memory DOM objects, any other entries that shared the same Document object with it must share the new object as well.

7.7.2. `History^I ~interface

enum `ScrollRestoration@I { `auto$l, `manual$l };

[Exposed=Window]
interface `History@I {
  readonly attribute unsigned long `index$m;
  readonly attribute unsigned long `length$m;
  attribute `ScrollRestoration$I `scrollRestoration$m;
  readonly attribute any `state$m;
  void `go$m(optional long %delta = 0);
  void `back$m();
  void `forward$m();
  void `pushState$m(any %data, DOMString %title, optional USVString? %url = null);
  void `replaceState$m(any %data, DOMString %title, optional USVString? %url = null);
};
%window . `history$m . `index$m
`共同~session履歴$の中での,`共同~session履歴の現在の~entry$の~indexを返す。 ◎ Returns the index of the current entry of the joint session history within the joint session history.
%window . `history$m . `length$m
`共同~session履歴$内の~entryの個数を返す。 ◎ Returns the number of entries in the joint session history.
%window . `history$m . `scrollRestoration$m [ = %value ]
`~session履歴$内の現在の~entryの`~scroll復旧~mode$を返す。 ◎ Returns the scroll restoration mode of the current entry in the session history.
設定して、`~session履歴$内の現在の~entryの`~scroll復旧~mode$を変更できる。 ◎ Can be set, to change the scroll restoration mode of the current entry in the session history.
%window . `history$m . `state$m
現在の`直列形の状態$を逆直列化した結果の~objを返す。 ◎ Returns the current serialized state, deserialized into an object.
%window . `history$m . `go$m( [ %delta ] )
`共同~session履歴$内で,指定された段~数だけ後戻する/先進する。 ◎ Goes back or forward the specified number of steps in the joint session history.
%delta に対する~zeroは、現在の頁を再読込みさせることになる。 ◎ A zero delta will reload the current page.
%delta が範囲~外を指す場合は何もしない。 ◎ If the delta is out of range, does nothing.
%window . `history$m . `back$m()
`共同~session履歴$内で 1 段だけ後戻する。 ◎ Goes back one step in the joint session history.
前~頁がない場合は何もしない。 ◎ If there is no previous page, does nothing.
%window . `history$m . `forward$m()
`共同~session履歴$内で 1 段だけ先進する。 ◎ Goes forward one step in the joint session history.
次~頁がない場合は何もしない。 ◎ If there is no next page, does nothing.
%window . `history$m . `pushState$m(%data, %title [, %url ] )
%data, %title を~session履歴に~pushする — %url が与えられていて ~NULL でなければ それも伴わせて。 ◎ Pushes the given data onto the session history, with the given title, and, if provided and not null, the given URL.
%window . `history$m . `replaceState$m(%data, %title [, %url ] )
[ %data, %title, %url(省略時は ~NULL ) ]で,~session履歴~内の現在の~entryのそれらを更新する。 ◎ Updates the current entry in the session history to have the given data, title, and, if provided and not null, URL.

`~top-level閲覧文脈$ %B の `共同~session履歴@ とは、[ 次を満たす各 `閲覧文脈$ %B1 の`~session履歴$内の~entryうち,その`現在の~entry$以外のもの ]すべての和集合に,`共同~session履歴の現在の~entry$を加えたものである:

  • %B1 の`~top-level閲覧文脈$ ~EQ %B
  • %B1 にて`作動中の文書$は、`全部的に作動中$である
◎ The joint session history of a top-level browsing context is the union of all the session histories of all browsing contexts of all the fully active Document objects that share that top-level browsing context, with all the entries that are current entries in their respective session histories removed except for the current entry of the joint session history.

`共同~session履歴の現在の~entry@ は、それを成す`~session履歴$たちの`現在の~entry$のうち,最も近過去にそうなったものを指す。 ◎ The current entry of the joint session history is the entry that most recently became a current entry in its session history.

`共同~session履歴$内の各~entryは,各自が属する`~session履歴$に追加された時刻により時系列的に順序付けられ、その順に 1 ずつ増加する整数~indexが付与される — 最も早期の~entryに付与される~indexは 0 とする。 ◎ Entries in the joint session history are ordered chronologically by the time they were added to their respective session histories. Each entry has an index; the earliest entry has index 0, and the subsequent entries are numbered with consecutively increasing integers (1, 2, 3, etc).

注記: 同じ`閲覧文脈$に`属する文書$たち それぞれの`~event-loop$は,互いに異なり得るので、`共同~session履歴$の実際の状態は,いくぶん漠然としたものになり得る。 例えば、同じ生成元に属していた 2 個の同胞 `iframe$e 要素が,同時に別の生成元へ`履歴を走査する$こともあるので、それらの精確な順序は~well-definedにならないかもしれない。 同様に,互いが他方を後と見出すこともあるため、それぞれにとっての`共同~session履歴$の長さには,食い違いが生じるかもしれない。 ◎ Since each Document in a browsing context might have a different event loop, the actual state of the joint session history can be somewhat nebulous. For example, two sibling iframe elements could both traverse from one unique origin to another at the same time, so their precise order might not be well-defined; similarly, since they might only find out about each other later, they might disagree about the length of the joint session history.

`index@m

取得子は、次を走らせ~MUST:

  1. ~IF[ 此れを結付けている文書は`全部的に作動中$でない ] ⇒ ~THROW `SecurityError$E
  2. ~RET `~top-level閲覧文脈$の`共同~session履歴$の中での,`共同~session履歴の現在の~entry$の~index
◎ The index attribute of the History interface, on getting, must return the index of the current entry of the joint session history within the top-level browsing context's joint session history. If this History object is associated with a Document that is not fully active, getting must instead throw a "SecurityError" DOMException.
`length@m

取得子は、次を走らせ~MUST:

  1. ~IF[ 此れを結付けている文書は`全部的に作動中$でない ] ⇒ ~THROW `SecurityError$E
  2. ~RET `~top-level閲覧文脈$の`共同~session履歴$内の~entryの個数
◎ The length attribute of the History interface, on getting, must return the number of entries in the top-level browsing context's joint session history. If this History object is associated with a Document that is not fully active, getting must instead throw a "SecurityError" DOMException.
~scriptからは、実際の各~entryに~accessし得ない。 ◎ The actual entries are not accessible from script.
`scrollRestoration@m

取得子は、次を走らせ~MUST:

  1. ~IF[ 此れを結付けている文書は`全部的に作動中$でない ] ⇒ ~THROW `SecurityError$E
  2. ~RET `~session履歴$内の`現在の~entry$の`~scroll復旧~mode$
◎ The scrollRestoration attribute of the History interface, on getting, must return the scroll restoration mode of the current entry in the session history.\

設定子は、次を走らせ~MUST:

  1. ~IF[ 此れを結付けている文書は`全部的に作動中$でない ] ⇒ ~THROW `SecurityError$E
  2. `~session履歴$内の`現在の~entry$の`~scroll復旧~mode$ ~SET 所与の値
◎ On setting, the scroll restoration mode of the current entry in the session history must be set to the new value.\ ◎ If this History object is associated with a Document that is not fully active, both getting and setting must instead throw a "SecurityError" DOMException.
`state@m

取得子は、次を走らせ~MUST:

  1. ~IF[ 此れを結付けている文書は`全部的に作動中$でない ] ⇒ ~THROW `SecurityError$E
  2. ~RET ~UAにより設定された最後の値
◎ The state attribute of the History interface, on getting, must return the last value it was set to by the user agent. If this History object is associated with a Document that is not fully active, getting must instead throw a "SecurityError" DOMException.\
この属性は、初期~時には、値は~NULL にされ~MUST。 ◎ Initially, its value must be null.
`go(delta)@m

被呼出時には、次を走らせ~MUST:

  1. ~IF[ 此れを結付けている文書は`全部的に作動中$でない ] ⇒ ~THROW `SecurityError$E
  2. ~IF[ %delta ~NEQ 0 ] ⇒ %delta だけ`履歴を前/後に走査する$
  3. ~ELSE ⇒ `location.reload()$m ~methodが~callされたかのように動作する
◎ When the go(delta) method is invoked, if delta is zero, the user agent must act as if the location.reload() method was called instead. Otherwise, the user agent must traverse the history by a delta whose value is delta. If this History object is associated with a Document that is not fully active, invoking must instead throw a "SecurityError" DOMException.
`back()@m
被呼出時には、 −1 を引数に `go()$m が~callされたかのように動作し~MUST。 ◎ When the back() method is invoked, the user agent must traverse the history by a delta −1. If this History object is associated with a Document that is not fully active, invoking must instead throw a "SecurityError" DOMException.
`forward()@m
被呼出時には、 +1 を引数に `go()$m が~callされたかのように動作し~MUST。 ◎ When the forward() method is invoked, the user agent must traverse the history by a delta +1. If this History object is associated with a Document that is not fully active, invoking must instead throw a "SecurityError" DOMException.

各`~top-level閲覧文脈$は、初期~時には空の `~session履歴~走査~queue@ を持ち,`~task$を追加できる。 ◎ Each top-level browsing context has a session history traversal queue, initially empty, to which tasks can be added.

各`~top-level閲覧文脈$ %B の作成-時には、その時点から`並列的$に,次の~algoを走らせ~MUST — この~algoは, %B に対する `~session履歴~event-loop@ と呼ばれる: ◎ Each top-level browsing context, when created, must begin running the following algorithm, known as the session history event loop for that top-level browsing context, in parallel:

  1. %~queue ~LET %B の`~session履歴~走査~queue$ ◎ ↓
  2. ~WHILE 無条件

    1. %~queue が空でなくなるまで待機する ◎ Wait until this top-level browsing context's session history traversal queue is not empty.
    2. %~queue から最初の`~task$を取出して、それを実行する ◎ Pull the first task from this top-level browsing context's session history traversal queue, and execute it. ◎ Return to the first step of this algorithm.

`~session履歴~event-loop$は、`共同~session履歴$内の各 閲覧文脈~間の遷移を協調させ易くするためにある。 特定0の時点に,各 `閲覧文脈$が有する`~event-loop$は、互いに異なり得るので(これは、~UAが`互いに関係する閲覧文脈~群$ごとに複数の`~event-loop$を有するときに起こり得る)、さもなければ,遷移に際し各~event-loop間の同期をとる必要が生じる。 ◎ The session history event loop helps coordinate cross-browsing-context transitions of the joint session history: since each browsing context might, at any particular time, have a different event loop (this can happen if the user agent has more than one event loop per unit of related browsing contexts), transitions would otherwise have to involve cross-event-loop synchronization.


%delta だけ`履歴を前/後に走査する@ ときは、~UAは,当の`~top-level閲覧文脈$の`~session履歴~走査~queue$に,次の手続きを走らす`~task$を付加し~MUST: ◎ To traverse the history by a delta delta, the user agent must append a task to this top-level browsing context's session history traversal queue, the task consisting of running the following steps:

  1. %履歴 ~LET `共同~session履歴$ ◎ ↓
  2. %index ~LET ( `共同~session履歴の現在の~entry$の~index ) ~PLUS %delta ◎ ↓
  3. ~IF[ %index ~LT ~zero ]~OR[ %index ~GTE %履歴 内の~entry数 ] ⇒ ~RET ◎ If the index of the current entry of the joint session history plus delta is less than zero or greater than or equal to the number of items in the joint session history, then return.
  4. %~entry ~LET %履歴 内の[ ~index ~EQ %index ]なる~entry ◎ Let specified entry be the entry in the joint session history whose index is the sum of delta and the index of the current entry of the joint session history.
  5. %B ~LET %~entry の文書が`属する閲覧文脈$ ◎ Let specified browsing context be the browsing context of the specified entry.
  6. ~IF[ %B にて`作動中の文書$において、現在,`文書を~unload$する~algoは走っている ] ⇒ ~RET ◎ If the specified browsing context's active document's unload a document algorithm is currently running, return.
  7. 次のようにされた`~taskを~queueする$:

    • 関連する`~event-loop$: %B にて`作動中の文書$のそれ
    • `~task源$: `履歴~走査~task源$
    • 走らす手続き: 下に与える手続き
    ◎ Queue a task that consists of running the following substeps. The relevant event loop is that of the specified browsing context's active document. The task source for the queued task is the history traversal task source.

    手続きは次で与えられる:

    1. ~IF[ %B を~navigateしようとする進行中の試みがある ]~AND[ %B はまだ`成熟-$していない(すなわち、 %B はまだ,その`文書$を`作動中$にする段を~~終えていない) ] ⇒ その試みを取消す ◎ If there is an ongoing attempt to navigate specified browsing context that has not yet matured (i.e. it has not passed the point of making its Document the active document), then cancel that attempt to navigate the browsing context.
    2. %文書 ~LET %B にて`作動中の文書$ ◎ ↓
    3. ~IF[ %文書 ~NEQ %~entry の`文書$ ]: ◎ If the specified browsing context's active document is not the same Document as the Document of the specified entry, then run these substeps:

      1. %文書 の`~unloadを~prompt$する ⇒ ~IF[ 利用者は %文書 の`~unloadを拒否-$した ] ⇒ ~RET ◎ Prompt to unload the active document of the specified browsing context. If the user refused to allow the document to be unloaded, then return.
      2. [ %recycle ~SET ~F ]の下で, %文書 を`~unload$する ◎ Unload the active document of the specified browsing context with the recycle parameter set to false.
    4. %B の`履歴を走査する$( %~entry ) ◎ Traverse the history of the specified browsing context to the specified entry.

利用者が`閲覧文脈$を通して~navigateするとき(例えば~browserの戻る/進む~buttonを利用して)、~UAは,利用者により指定される動作に等価な分だけ`履歴を前/後に走査する$ことが要求される。 ◎ When the user navigates through a browsing context, e.g. using a browser's back and forward buttons, the user agent must traverse the history by a delta equivalent to the action specified by the user.


`pushState(data, title, url)@m
`replaceState(data, title, url)@m
`pushState()^m は、状態~obj~entryを履歴に追加する。 ◎ The pushState(data, title, url) method adds a state object entry to the history.
`replaceState()^m は、履歴~内の`現在の~entry$の[ 状態~obj, ~title, ( %url が与えられていれば)`~URL$ ]を更新する。 ◎ The replaceState(data, title, url) method updates the state object, title, and optionally the URL of the current entry in the history.

これらの~methodの被呼出時には、次の手続きを走らせ~MUST: ◎ When either of these methods is invoked, the user agent must run the following steps:

  1. %文書 ~LET 此れを結付けている`文書$ ◎ Let document be the unique Document object this History object is associated with.
  2. ~IF[ %文書 は`全部的に作動中$でない ] ⇒ ~THROW `SecurityError$E ◎ If document is not fully active, throw a "SecurityError" DOMException.
  3. ~UAの任意選択で ⇒ ~RET

    (例えば~UAは、これらの~methodの~callを,[ ~timer / 利用者による明瞭な動作に呼応して誘発されたものではない~event~listener ]によるものである場合や, 立て続けに呼出された場合には、不許可にできる。)

    ◎ Optionally, return. (For example, the user agent might disallow calls to these methods that are invoked on a timer, or from event listeners that are not triggered in response to a clear user action, or that are invoked in rapid succession.)
  4. %宛先~Realm ~LET 此れに`関連する~Realm$ ◎ Let targetRealm be this History object's relevant Realm.
  5. `直列形の~data^V ~LET `StructuredSerializeForStorage$jA( %data ) (例外投出あり) ◎ Let serializedData be StructuredSerializeForStorage(data). Rethrow any exceptions.
  6. %新~URL ~LET ε ◎ ↓
  7. ~IF[ %url ~NEQ ~NULL ]: ◎ If the third argument is not null, run these substeps:

    1. %新~URL ~SET %url を,此れに`関連する設定群~obj$に`相対的に構文解析-$した`結果の~URL~record$ ◎ Parse the value of the third argument, relative to the relevant settings object of this History object.
    2. ~IF[ %新~URL ~EQ ~error ] ⇒ ~THROW `SecurityError$E ◎ If that fails, throw a "SecurityError" DOMException. ◎ Let new URL be the resulting URL record.
    3. %文書~URL ~LET %文書 の`~URL$doc ◎ ↓
    4. ~IF[ 次のいずれかが満たされる ] ⇒ ~THROW `SecurityError$E : ◎ ↓

      • [ %新~URL, %文書~URL ]の[ `~path$url, `~query$url, `素片$url ]以外のある成分が相違する ◎ Compare new URL to document's URL. If any component of these two URL records differ other than the path, query, and fragment components, then throw a "SecurityError" DOMException.
      • 次の両者が満たされる:

        • [ %新~URL の`生成元$url ]~NEQ`生成元$sub[ %文書 の`生成元$ ]
        • [ %新~URL, %文書~URL ]の[ `~path$url, `~query$url ]いずれかの成分は相違する

        (これは、~sandbox化された内容が 同一生成元~上の他の頁を偽装することを防止する。)

        ◎ If the origin of new URL is not same origin with the origin of document, and either the path or query components of the two URL records compared in the previous step differ, throw a "SecurityError" DOMException.(This prevents sandboxed content from spoofing other pages on the same origin.)
  8. %履歴 ~LET %文書 が`属する閲覧文脈$の`~session履歴$ ◎ ↓
  9. %現~entry ~LET %履歴 内の`現在の~entry$ ◎ ↓
  10. ~IF[ %url ~EQ ~NULL ] ⇒ %新~URL ~SET %現~entry の`~URL$ ◎ If the third argument is null, then let new URL be the URL of the current entry.
  11. ~IF[ 呼出された~methodは `pushState()$m である ]: ◎ If the method invoked was the pushState() method:

    1. %履歴 内に %現~entry より後に~entryがあれば,それらすべてを除去する ◎ Remove all the entries in the browsing context's session history after the current entry. If the current entry is the last entry in the session history, then no entries are removed.

      注記: これは、~UAの~UIに 影響するとは限らない。 ◎ This doesn't necessarily have to affect the user agent's user interface.

    2. `~top-level閲覧文脈$の`文書~族$内の~EACH ( 文書 %D )に対し ⇒ `履歴~走査~task源$から~queueされた`~task$のうち, %D に結付けられているものすべてを除去する ◎ Remove any tasks queued by the history traversal task source that are associated with any Document objects in the top-level browsing context's document family.
    3. 適切になるなら、~UAが持続化しようと望む状態を反映するように, %現~entry を更新する — この~entryは、`持続的~利用者~状態を伴う$ものとされる。 ◎ If appropriate, update the current entry to reflect any state that the user agent wishes to persist. The entry is then said to be an entry with persisted user state.
    4. %新~entry ~LET 新たな~entry ◎ ↓
    5. %新~entry の~scroll復旧~mode ~SET %現~entry の`~scroll復旧~mode$ ◎ ↓
    6. %新~entry を %履歴 の中の %現~entry の後に追加する ◎ ↓
    7. %履歴 の`現在の~entry$ ~SET %新~entry ◎ ↓↓Add a session history entry entry to the session history, after the current entry, with serializedData as the serialized state, the given title as the title, new URL as the URL of the entry, and the scroll restoration mode of the current entry in the session history as the scroll restoration mode.
    8. %現~entry ~SET %新~entry ◎ Update the current entry to be this newly added entry.
  12. %現~entry を次のように更新する:

    • `直列形の状態$ ~SET `直列形の~data^V
    • ~title ~SET %title
    • `~URL$ ~SET %新~URL
    ◎ Otherwise, if the method invoked was the replaceState() method: ◎ Update the current entry in the session history so that serializedData is the entry's new serialized state, the given title is the new title, and new URL is the entry's new URL.
  13. ~IF[ %現~entry は非 `GET^h 要請を表現する(例: それは `POST^h 提出の結果であった) ] ⇒ %現~entry を `GET^h 要請を表現するものに更新する ◎ If the current entry in the session history represents a non-GET request (e.g. it was the result of a POST submission) then update it to instead represent a GET request.
  14. %文書 の`~URL$doc ~SET %新~URL ◎ Set document's URL to new URL.

    注記: これは,[ `閲覧文脈$の`~navi$ / `履歴の走査$ ]ではないので、 `hashchange$et ~eventは発火されない。 ◎ Since this is neither a navigation of the browsing context nor a history traversal, it does not cause a hashchange event to be fired.

  15. %state ~SET `StructuredDeserialize$jA( `直列形の~data^V, %宛先~Realm ) ⇒ 例外が投出されたときは、~catchして ⇒ %state ~SET ~NULL (例外は無視する) ◎ Let state be StructuredDeserialize(serializedData, targetRealm). If this throws an exception, catch it, ignore the exception, and set state to null.
  16. 此れの `state$m 属性 ~SET %state ◎ Set history.state to state.
  17. %現~entry の`文書$の`最近の~entry$ ~SET %現~entry ◎ Set the current entry's Document object's latest entry to the current entry.

注記: %title は、もっぱら助言的でしかない。 ~UAは,~titleを~UIに利用するかもしれない。 ◎ The title is purely advisory. User agents might use the title in the user interface.

~UAは、頁ごとに,その~session履歴に追加される状態~objの個数を制限してよい。 頁がこの制限-に抵触した場合、~UAは,新たな~entryが追加された後に,[ その~session履歴~内の~entryのうち,[ 当の`文書$ 【新たな~entryの文書?】 に対する最初の~entry ]の直後の~entryを除去し~MUST(したがって,状態~履歴は、先に入れたものから抹消されるように動作する( FIFO )一方で、~naviに対しては,先に入れたものが最後に残るように動作する( LIFO ))。 ◎ User agents may limit the number of state objects added to the session history per page. If a page hits the UA-defined limit, user agents must remove the entry immediately after the first entry for that Document object in the session history after having added the new entry. (Thus the state history acts as a FIFO buffer for eviction, but as a LIFO buffer for navigation.)

~gameを考える: 利用者は常に,ある “線” 上のある座標に位置していて、線に沿って~navigateでき、特定0の座標に対応する頁を~bookmarkすれば後でそこへ戻れるとする。 ◎ Consider a game where the user can navigate along a line, such that the user is always at some coordinate, and such that the user can bookmark the page corresponding to a particular coordinate, to return to it later.

そのような~gameの,位置 x=5 を実装している静的な頁として、次の様なものがあるとする: ◎ A static page implementing the x=5 position in such a game could look like the following:

<!DOCTYPE HTML>
<!-- ここは https://example.com/line?x=5 -->
<html lang="ja">
<title>Line Game - 5</title>
<p>あなたは線~上の座標 5 に居ます。</p>
<p>
 <a href="?x=6">6 へ進む</a> ・
 <a href="?x=4">4 へ戻る</a>
</p>

そのような~systemにおいて問題になるのは、利用者が~clickするたびに,頁~全体の再読込みを要することである。 次に、~scriptを利用して同じことをする別の仕方を示す: ◎ The problem with such a system is that each time the user clicks, the whole page has to be reloaded. Here instead is another way of doing it, using script:

<!DOCTYPE HTML>
<!-- ここは https://example.com/line?x=5 -->
<html lang="ja">
<title>Line Game - 5</title>
<p>あなたは線~上の座標 <span id="coord">5</span> に居ます。</p>
<p>
 <a href="?x=6"
   onclick="go(1); return false;"
 >6 へ進む</a> ・
 <a href="?x=4"
   onclick="go(-1); return false;"
 >4 へ戻る</a>
</p>
<script>
 var %currentPage = 5; /* ~serverからあてがわれる
◎
prefilled by server
 */
 function go(%d) {
   setupPage(%currentPage + %d);
   history.pushState(%currentPage, document.title, '?x=' + %currentPage);
 }
 onpopstate = function(%event) {
   setupPage(%event.state);
 }
 function setupPage(%page) {
   %currentPage = %page;
   document.title = 'Line Game - ' + %currentPage;
   document.getElementById('coord').textContent = %currentPage;
   document.links[0].href = '?x=' + (%currentPage + 1);
   document.links[0].textContent = 'Advance to ' + (%currentPage + 1);
   document.links[1].href = '?x=' + (%currentPage - 1);
   document.links[1].textContent = 'retreat to ' + (%currentPage - 1);
 }
</script>

これは、~scriptの~supportを切っている~systemにおいても,依然として先掲の例の様に働くが、 切っていない 利用者は,ずっと高速に~navigateできるようになる — 同じ体験に対し~network~accessはないので。 更には、~scriptに基づく素朴な~approachによる利用者~体験と違って,~session履歴を ~bookmarkする/~navigateする のも依然として働く。 ◎ In systems without script, this still works like the previous example. However, users that do have script support can now navigate much faster, since there is no network access for the same experience. Furthermore, contrary to the experience the user would have with just a naïve script-based approach, bookmarking and navigating the session history still work.

上の例において、 `pushState()$m ~methodに対する %data 引数は,~serverへ送信されることになる情報と同じになるが、利用者が~navigateするたびに~scriptが~URLを構文解析しなくとも済むような,より簡便な形になる。 ◎ In the example above, the data argument to the pushState() method is the same information as would be sent to the server, but in a more convenient form, so that the script doesn't have to parse the URL each time the user navigates.


~appは、その時点の`~session履歴~entry$に対する~titleに,文書の `title$e 要素の値と同じ値を利用しないこともできる。 例えばここに、 `title$e 要素~内に,ある~blockを示す単純な頁があるとする。 ~navigateして以前の状態に後戻しても,利用者の時間は後戻しないので、~session履歴~title内に時刻を入れるのは不適切になるであろう。 ◎ Applications might not use the same title for a session history entry as the value of the document's title element at that time. For example, here is a simple page that shows a block in the title element. Clearly, when navigating backwards to a previous state the user does not go back in time, and therefore it would be inappropriate to put the time in the session history title.

<!DOCTYPE HTML>
<HTML LANG=EN>
<TITLE>Line</TITLE>
<SCRIPT>
 setInterval(function () {
   document.title = 'Line - ' + new Date();
 }, 1000);
 var %i = 1;
 function inc() {
   set(%i+1);
   history.pushState(%i, 'Line - ' + i);
 }
 function set(%newI) {
   %i = %newI;
   document.forms.F.I.value = %newI;
 }
</SCRIPT>
<BODY ONPOPSTATE="set(%event.state)">
<FORM NAME=F>
   State:
   <OUTPUT NAME=I>1</OUTPUT>
   <INPUT VALUE="Increment" TYPE=BUTTON ONCLICK="inc()">
</FORM>

ほとんどの~appは、自身の履歴~entryのすべてに対し,同じ`~scroll復旧~mode$値を利用したいと求める。 そのためには、できるだけ早く `scrollRestoration$m 属性を設定して(例えば、文書の `head$e 要素~内の `script$e 要素で),[ 履歴~sessionに追加された~entryが,欲される~scroll復旧~modeを取得する ]ことを確保することにより,達成できる。 ◎ Most applications want to use the same scroll restoration mode value for all of their history entries. To achieve this they can set the scrollRestoration attribute as soon as possible (e.g., in the first script element in the document's head element) to ensure that any entry added to the history session gets the desired scroll restoration mode.

<head>
  <script>
       if ('scrollRestoration' in history)
            history.scrollRestoration = 'manual';
  </script>
</head>

7.7.3. ~session履歴に対する実装~上の注記

~INFORMATIVE

`History$I ~interfaceは、実装が~session履歴を利用者に向けてどう表現するかについて制約を課すものではない。 ◎ The History interface is not meant to place restrictions on how implementations represent the session history to the user.

例えば~session履歴を,各~頁が,複数の “~~前方へ~~枝分かれする” 頁を持つ様な方式で実装することもできる。 この仕様は、 `history$m ~obj内の各~頁からなる一本道の~listが利用者からどう見えるかについて,実際の~session履歴から導出する方法は定義しない。 ◎ For example, session history could be implemented in a tree-like manner, with each page having multiple "forward" pages. This specification doesn't define how the linear list of pages in the history object are derived from the actual session history as seen from the user's perspective.

同様に,ある頁が 2 個の `iframe$e を包含しているとき,頁は各 `iframe$e の `history$m ~objとは別個の `history$m ~objを持つ — [ 2 個の内縁~frameと外縁~頁の~navi ]を互いに差挟むような~session履歴を伴うような。 代表的な~Web~browserは、利用者に “戻る” ~buttonを 1 個しか呈示しない事実があるにもかかわらず。 ◎ Similarly, a page containing two iframes has a history object distinct from the iframes' history objects, despite the fact that typical Web browsers present the user with just one "Back" button, with a session history that interleaves the navigation of the two inner frames and the outer page.

保安: ある頁が `pushState()$m を濫用して,~UAの履歴~navi便宜性を “乗っ取る” のを避けるため、~UAには,以前の頁へ一足飛びに戻る仕方を利用者に提供することが示唆される(単に 1 つ前の状態へ後戻するのでなく)。 例えば、戻る~buttonは,~session履歴~内の頁たちだけを示し,他のどの状態も示さないような ~drop-downを持たせることもできる。 同様に,聴覚~browserは、 2 つ前へ “戻る” ~command — 1 つ前の状態へ後戻するもの, 以前の頁へ一足飛びに戻るもの — を持たせることもできる。 ◎ Security: It is suggested that to avoid letting a page "hijack" the history navigation facilities of a UA by abusing pushState(), the UA provide the user with a way to jump back to the previous page (rather than just going back to the previous state). For example, the back button could have a drop down showing just the pages in the session history, and not showing any of the states. Similarly, an aural browser could have two "back" commands, one that goes back to the previous state, and one that jumps straight back to the previous page.

`pushState()$m, `replaceState()$m いずれに対しても,~UAには、頻繁過ぎる~callや巨大過ぎる状態~objを介するような, これらの~APIの濫用-を防止することが奨励される。 上に詳細を与えたように,~algoでは、適切になるときは,~UAがそのような~callを無視することも 明示的に許容されている。 ◎ For both pushState() and replaceState(), user agents are encouraged to prevent abuse of these APIs via too-frequent calls or over-large state objects. As detailed above, the algorithm explicitly allows user agents to ignore any such calls when appropriate.

7.7.4. `Location^I ~interface

各 `~window$には、その作成-時に,新たな `Location$I ~objが結付けられる。

【 以下,ここでは、この節の内容のうち,~APIに関する部分のみ述べる。 他の内容は、 別ページ にて。 】

%document . `~location0$m [ = %value ]
%window . `location$m [ = %value ]
現在の頁の所在を伴う `Location$I ~objを返す。 ◎ Returns a Location object with the current page's location.
設定して,別の頁へ~navigateできる。 ◎ Can be set, to navigate to another page.
`document.location@m
取得子は、[ 此れが`全部的に作動中$ならば,此れに`関連する大域~obj$の `Location$I ~obj / ~ELSE_ ~NULL ]を返さ~MUST。 ◎ The Document object's location attribute's getter must return this Document object's relevant global object's Location object, if this Document object is fully active, and null otherwise.
`window.location@m
取得子は、此れの `Location$I ~objを返さ~MUST。 ◎ The Window object's location attribute's getter must return this Window object's Location object.

`Location$I ~objは、それに`対応する閲覧文脈$Locにて`作動中の文書$の`~URL$docを表現し、`閲覧文脈$の~session履歴の`現在の~entry$を, `history$m ~obj内[ に~entryを追加する / の~entryを置換する ]ことを通して 変更できるようにする。 ◎ Location objects provide a representation of the URL of the active document of their Document's browsing context, and allow the current entry of the browsing context's session history to be changed, by adding or replacing entries in the history object.

[Exposed=Window]
interface `Location@I { /* 
ただし、
追加の作成~手続き上書きされた内部~method
も見よ。
◎
but see also additional creation steps and overridden internal methods
 */

  [Unforgeable] stringifier attribute USVString `href$m;
  [Unforgeable] readonly attribute USVString `origin$m;
  [Unforgeable] attribute USVString `protocol$m;
  [Unforgeable] attribute USVString `host$m;
  [Unforgeable] attribute USVString `hostname$m;
  [Unforgeable] attribute USVString `port$m;
  [Unforgeable] attribute USVString `pathname$m;
  [Unforgeable] attribute USVString `search$m;
  [Unforgeable] attribute USVString `hash$m;

  [Unforgeable] void `assign$m(USVString %url);
  [Unforgeable] void `replace$m(USVString %url);
  [Unforgeable] void `reload$m();

  [Unforgeable, SameObject] readonly attribute `DOMStringList$I `ancestorOrigins$m;
};
%location . `toString()^m
%location . `href$m
`~url$Locを返す。 ◎ Returns the Location object's URL.
設定して,所与の~URLへ~navigateできる。 ◎ Can be set, to navigate to the given URL.
%location . `origin$m
`~url$Locの生成元を返す。 ◎ Returns the Location object's URL's origin.
%location . `protocol$m
`~url$Locの~schemeを返す。 ◎ Returns the Location object's URL's scheme.
設定して,`~url$Locの~schemeだけ変更した~URLへ~navigateできる。 ◎ Can be set, to navigate to the same URL with a changed scheme.
%location . `host$m
`~url$Locの[ ~host, ~port(~schemeに対する`既定の~port$urlと異なるならば) ]を返す。 ◎ Returns the Location object's URL's host and port (if different from the default port for the scheme).
設定して,`~url$Locの ~host, ~port だけ変更した~URLへ~navigateできる。 ◎ Can be set, to navigate to the same URL with a changed host and port.
%location . `hostname$m
`~url$Locの~hostを返す。 ◎ Returns the Location object's URL's host.
設定して,`~url$Locの~hostだけ変更した~URLへ~navigateできる。 ◎ Can be set, to navigate to the same URL with a changed host.
%location . `port$m
`~url$Locの~port を返す。 ◎ Returns the Location object's URL's port.
設定して,`~url$Locの~portだけ変更した~URLへ~navigateできる。 ◎ Can be set, to navigate to the same URL with a changed port.
%location . `pathname$m
`~url$Locの~path を返す。 ◎ Returns the Location object's URL's path.
設定して,`~url$Locの~pathだけ変更した~URLへ~navigateできる。 ◎ Can be set, to navigate to the same URL with a changed path.
%location . `search$m
`~url$Locの~queryを返す(空でないならば 先頭の `?^l も含する)。 ◎ Returns the Location object's URL's query (includes leading "?" if non-empty).
設定して,`~url$Locの~query(先頭の `?^l は無視する)だけ変更した~URLへ~navigateできる。 ◎ Can be set, to navigate to the same URL with a changed query (ignores leading "?").
%location . `hash$m
`~url$Locの素片を返す(空でないならば 先頭の `#^l を含する)。 ◎ Returns the Location object's URL's fragment (includes leading "#" if non-empty).
設定して,`~url$Locの素片(先頭の `#^l は無視する)だけ変更した~URLへ~navigateできる。 ◎ Can be set, to navigate to the same URL with a changed fragment (ignores leading "#").
%location . `assign$m(%url)
%url へ~navigateする。 ◎ Navigates to the given URL.
%location . `replace$m(%url)
~session履歴から現在の頁を除去した上で,所与の %url へ~navigateする。 ◎ Removes the current page from the session history and navigates to the given URL.
%location . `reload$m()
現在の頁を再読込みする。 ◎ Reloads the current page.
%location . `ancestorOrigins$m
`親~閲覧文脈$から`~top-level閲覧文脈$までの各[ 先祖`閲覧文脈$の生成元の値 ]からなる, `DOMStringList$I ~objを返す。 ◎ Returns a DOMStringList object listing the origins of the ancestor browsing contexts, from the parent browsing context to the top-level browsing context.

各 `Location$I ~obj %L には、次が定義される: ◎ ↓

`対応する閲覧文脈@Loc
%L を結付けている`~window$に`対応する閲覧文脈$を指す。
【 この定義は、訳者の推定による。 原文では, “%L の文書の閲覧文脈” あるいは単に “the 閲覧文脈” 等々としか記されていないが、 %L は`~window$に結付けられるものと定義されているので。 】
`関連する文書@Loc
%L に`対応する閲覧文脈$Locにて`作動中の文書$を指す。 ◎ A Location object has an associated relevant Document, which is this Location object's associated Document object's browsing context's active document.
`~url@Loc
%L に`関連する文書$Locの`~URL$docを指す。 ◎ A Location object has an associated url, which is this Location object's relevant Document's URL.
`先祖~生成元~list@

%L の作成-時に,次の手続きから得られる文字列の~listが結付けられた `DOMStringList$I ~objに設定され~MUST: ◎ 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:

  1. %~list ~LET 新たな空`~list$ ◎ Let output be a new list of strings.
  2. %L に`対応する閲覧文脈$Loc %B の ~EACH( `先祖~閲覧文脈$ %先祖 ) に対し, %B に近い先祖から順に ⇒ %~list に次の結果を`付加-$する ⇒ `生成元を直列化する$( %先祖 にて`作動中の文書$の`生成元$ ) ◎ Let current be the browsing context of the Document with which this Location object is associated. ◎ Loop: If current has no parent browsing context, jump to the step labeled end. ◎ Let current be current's parent browsing context. ◎ Append the serialization of current's active document's origin to output. ◎ Return to the step labeled loop.
  3. ~RET %~list ◎ End: Return output.
【 `ancestorOrigins$m のみから利用される。 】

`~Location~obj設定子により~navigateする@ ときは、所与の ( `Location$I ~obj %L, `~URL~record$ %url ) に対し,次を走らす: ◎ A Location object has an associated Location-object-setter navigate algorithm, which given a url, runs these steps:

  1. `置換え~flag^V ~LET[ 次のいずれかが満たされるならば ~OFF / ~ELSE_ ~ON ]: ◎ If any of the following conditions are met, let replacement flag be unset; otherwise, let it be set:

    • %L に`関連する文書$Locは、`完全に読込まれ$ている ◎ This Location object's relevant Document has completely loaded, or
    • この~algoを走らせている`~task$は、次を満たす~eventに対する[ `作動化の挙動$を現在~処理して / ~event~listenerを取扱って ]いる ⇒ 名前 `click$et ~AND `isTrusted$m ~EQ ~T ◎ In the task in which the algorithm is running, an activation behavior is currently being processed whose click event's isTrusted attribute is true, or ◎ In the task in which the algorithm is running, the event listener for a click event, whose isTrusted attribute is true, is being handled.
  2. 次を与える下で,`~Location~objにより~navigateする$ ⇒ ( %L, %url, `置換え~flag^V ) ◎ Location-object navigate, given url and replacement flag.

`~Location~objにより~navigateする@ ときは、所与の ( `Location$I ~obj %L, `~URL~record$ %url, `置換え~flag^V ) に対し,次を走らす: ◎ To Location-object navigate, given a url and replacement flag, run these steps:

  1. %B ~LET %L に`対応する閲覧文脈$Loc ◎ ↓
  2. 次を与える下で, %url へ %B を`~navigate$する(例外投出あり):

    • `~source閲覧文脈$は、`現任の設定群~obj$により指定される`担当の閲覧文脈$enV
    • `例外~可能化~flag$ ~SET ~ON
    • 次のいずれかに該当する場合は、`置換え可能化~flag$ ~SET ~ON:

      • `置換え~flag^V ~EQ ~ON
      • %B の`~session履歴$は、 %B の作成-時に作成された `about_blank$sc `文書$のみからなる
    ◎ • The source browsing context is the responsible browsing context specified by the incumbent settings object. • Navigate the browsing context to url, with the exceptions enabled flag set. Rethrow any exceptions. • If the replacement flag is set or the browsing context's session history contains only one Document, and that was the about:blank Document created when the browsing context was created, then the navigation must be done with replacement enabled.

`Location$I ~obj %L の `生成元~domainを検査する@ ときは、次を走らす:

  1. ~IF[ %L に`関連する文書$Locの`生成元$ ~NEQ`~domain$sub `入口~設定群~obj$の`生成元$enV ] ⇒ ~THROW `SecurityError$E

【 この手続きは、以下を簡潔に記すためにこの訳に導入したもの。 】

`href@m

取得子は、次の手続きを走らせ~MUST: ◎ The href attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. ~RET `~URLを直列化する$( 此れが指す`~url$Loc ) ◎ Return this Location object's url, serialized.

設定子は、次の手続きを走らせ~MUST: ◎ The href attribute's setter must run these steps:

  1. %~URL~record ~LET 所与の値を,`入口~設定群~obj$に`相対的に構文解析-$した`結果の~URL~record$ ◎ Parse the given value relative to the entry settings object.\
  2. ~IF[ %~URL~record ~EQ ~error ] ⇒ ~THROW `TypeError$E ◎ If that failed, throw a TypeError exception.
  3. 次を与える下で,`~Location~obj設定子により~navigateする$ ⇒ ( 此れ, %~URL~record ) ◎ Location-object-setter navigate to the resulting URL record.
注記: `href$m 属性~設定子に対しては、意図的に保安~検査は行われない。 ◎ The href attribute setter intentionally has no security check.
`origin@m

取得子は、次の手続きを走らせ~MUST: ◎ The origin attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. ~RET `生成元を直列化する$( 此れが指す`~url$Locの`生成元$url ) ◎ Return the serialization of this Location object's url's origin.
`protocol@m

取得子は、次の手続きを走らせ~MUST: ◎ The protocol attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. ~RET 次を順に連結した結果 ⇒ 此れが指す`~url$Locの`~scheme$url,
    `:^l ◎ Return this Location object's url's scheme, followed by ":".

設定子は、次の手続きを走らせ~MUST: ◎ The protocol attribute's setter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %複製~URL ~LET 此れが指す`~url$Locの複製 ◎ Let copyURL be a copy of this Location object's url.
  3. %~protocol文字列 ~LET 次を順に連結した結果 ⇒ 所与の値,
    `:^l ◎ ↓
  4. %possibleFailure ~LET 次を与える下で, %~protocol文字列 を`基本~URL構文解析器$にかけた結果 ⇒ ~URLと上書stateの組: ( %複製~URL, `~scheme開始-~state$url ) ◎ 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.

    注記: ~URL構文解析器は,連続する~colonを無視するので、値に `https:^l を与えても(あるいは `https::::^l でさえ), `https^l を与えるのと同じことになる。 ◎ 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".

  5. ~IF[ %possibleFailure ~EQ `失敗^i ] ⇒ ~THROW `SyntaxError$E ◎ If possibleFailure is failure, then throw a "SyntaxError" DOMException.
  6. ~IF[ %複製~URL の `~scheme$urlは`~HTTP_S~scheme$である ] ⇒ ~RET ◎ If copyURL's scheme is not an HTTP(S) scheme, then terminate these steps.
  7. 次を与える下で,`~Location~obj設定子により~navigateする$ ⇒ ( 此れ, %複製~URL ) ◎ Location-object-setter navigate to copyURL.
`host@m

取得子は、次の手続きを走らせ~MUST: ◎ The host attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %url ~LET 此れが指す`~url$Loc ◎ Let url be this Location object's url.
  3. ~IF[ %url の`~host$url ~EQ ~NULL ] ⇒ ~RET 空~文字列 ◎ If url's host is null, return the empty string.
  4. %~host文字列 ~LET `~hostを直列化する$( %url の`~host$url ) ◎ ↓
  5. ~IF[ %url の`~port$url ~EQ ~NULL ] ⇒ ~RET %~host文字列 ◎ If url's port is null, return url's host, serialized.
  6. ~RET 次を順に連結した結果 ⇒ %~host文字列,
    `:^l,
    `整数を直列化する$( %url の`~port$url ) ◎ Return url's host, serialized, followed by ":" and url's port, serialized.

設定子は、次の手続きを走らせ~MUST: ◎ The host attribute's setter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %複製~URL ~LET 此れが指す`~url$Locの複製 ◎ Let copyURL be a copy of this Location object's url.
  3. ~IF[ %複製~URL の`~cannot-be-a-base-URL~flag$ ~EQ ~ON ] ⇒ ~RET ◎ If copyURL's cannot-be-a-base-URL flag is set, terminate these steps.
  4. 次を与える下で,所与の値を`基本~URL構文解析器$にかける ⇒ ~URLと上書stateの組: ( %複製~URL, `~host~state$url ) ◎ Basic URL parse the given value, with copyURL as url and host state as state override.
  5. 次を与える下で,`~Location~obj設定子により~navigateする$ ⇒ ( 此れ, %複製~URL ) ◎ Location-object-setter navigate to copyURL.
`hostname@m

取得子は、次の手続きを走らせ~MUST: ◎ The hostname attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. ~IF[ 此れが指す`~url$Locの `~host$url ~EQ ~NULL ] ⇒ ~RET 空~文字列 ◎ If this Location object's url's host is null, return the empty string.
  3. ~RET `~hostを直列化する$( 此れが指す`~url$Locの`~host$url ) ◎ Return this Location object's url's host, serialized.

設定子は、次の手続きを走らせ~MUST: ◎ The hostname attribute's setter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %複製~URL ~LET 此れが指す`~url$Locの複製 ◎ Let copyURL be a copy of this Location object's url.
  3. ~IF[ %複製~URL の`~cannot-be-a-base-URL~flag$ ~EQ ~ON ] ⇒ ~RET ◎ If copyURL's cannot-be-a-base-URL flag is set, terminate these steps.
  4. 次を与える下で,所与の値を`基本~URL構文解析器$にかける ⇒ ~URLと上書stateの組: ( %複製~URL, `~hostname~state$url ) ◎ Basic URL parse the given value, with copyURL as url and hostname state as state override.
  5. 次を与える下で,`~Location~obj設定子により~navigateする$ ⇒ ( 此れ, %複製~URL ) ◎ Location-object-setter navigate to copyURL.
`port@m

取得子は、次の手続きを走らせ~MUST: ◎ The port attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. ~IF[ 此れが指す`~url$Locの `~port$url ~EQ ~NULL ] ⇒ ~RET 空~文字列 ◎ If this Location object's url's port is null, return the empty string.
  3. ~RET `整数を直列化する$( 此れが指す`~url$Locの`~port$url ) ◎ Return this Location object's url's port, serialized.

設定子は、次の手続きを走らせ~MUST: ◎ The port attribute's setter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %複製~URL ~LET 此れが指す`~url$Locの複製 ◎ Let copyURL be a copy of this Location object's url.
  3. ~IF[ %複製~URL は `~username/~password/~portを持てない$ ] ⇒ ~RET ◎ If copyURL cannot have a username/password/port, then return.
  4. ~IF[ 所与の値 ~EQ 空~文字列 ] ⇒ %複製~URL の`~port$url ~SET ~NULL ◎ If the given value is the empty string, then set copyURL's port to null.
  5. ~ELSE ⇒ 次を与える下で,所与の値を`基本~URL構文解析器$にかける ⇒ ~URLと上書stateの組: ( %複製~URL, `~port~state$url ) ◎ Otherwise, basic URL parse the given value, with copyURL as url and port state as state override.
  6. 次を与える下で,`~Location~obj設定子により~navigateする$ ⇒ ( 此れ, %複製~URL ) ◎ Location-object-setter navigate to copyURL.
`pathname@m

取得子は、次の手続きを走らせ~MUST: ◎ The pathname attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %url ~LET 此れが指す`~url$Loc ◎ Let url be this Location object's url.
  3. ~IF[ %url の`~cannot-be-a-base-URL~flag$ ~EQ ~ON ] ⇒ ~RET %url の`~path$url内の最初の文字列 ◎ If url's cannot-be-a-base-URL flag is set, return the first string in url's path.
  4. ~IF[ %url の`~path$urlは空である ] ⇒ ~RET 空~文字列 ◎ If url's path is empty, then return the empty string.
  5. ~RET 次を順に連結した結果 ⇒ `/^l,
    [ %url の`~path$url内の各~文字列(空~文字列も含めて)を `/^l で区切って連結した結果 ] ◎ Return "/", followed by the strings in url's path (including empty strings), separated from each other by "/".

設定子は、次の手続きを走らせ~MUST: ◎ The pathname attribute's setter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %複製~URL ~LET 此れが指す`~url$Locの複製 ◎ Let copyURL be a copy of this Location object's url.
  3. ~IF[ %複製~URL の`~cannot-be-a-base-URL~flag$ ~EQ ~ON ] ⇒ ~RET ◎ If copyURL's cannot-be-a-base-URL flag is set, terminate these steps.
  4. %複製~URL の`~path$url ~SET 空~list ◎ Set copyURL's path to the empty list.
  5. 次を与える下で,所与の値を`基本~URL構文解析器$にかける ⇒ ~URLと上書stateの組: ( %複製~URL, `~path開始-~state$url ) ◎ Basic URL parse the given value, with copyURL as url and path start state as state override.
  6. 次を与える下で,`~Location~obj設定子により~navigateする$ ⇒ ( 此れ, %複製~URL ) ◎ Location-object-setter navigate to copyURL.
`search@m

取得子は、次の手続きを走らせ~MUST: ◎ The search attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. ~IF[ 此れが指す`~url$Locの`~query$url ~IN { ~NULL, 空~文字列 } ] ⇒ ~RET 空~文字列 ◎ If this Location object's url's query is either null or the empty string, return the empty string.
  3. ~RET 次を順に連結した結果 ⇒ `?^l,
    此れが指す`~url$Locの`~query$url ◎ Return "?", followed by this Location object's url's query.

設定子は、次の手続きを走らせ~MUST: ◎ The search attribute's setter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %複製~URL ~LET 此れが指す`~url$Locの複製 ◎ Let copyURL be a copy of this Location object's url.
  3. ~IF[ 所与の値 ~EQ 空~文字列 ] ⇒ %複製~URL の`~query$url ~SET ~NULL ◎ If the given value is the empty string, set copyURL's query to null.
  4. ~ELSE: ◎ Otherwise, run these substeps:

    1. %入力 ~LET 所与の値 ◎ ↓
    2. ~IF[ %入力 の最初の文字 ~EQ `?^l ] ⇒ %入力 から最初の文字を除去する ◎ Let input be the given value with a single leading "?" removed, if any.
    3. %複製~URL の`~query$url ~SET 空~文字列 ◎ Set copyURL's query to the empty string.
    4. 次を与える下で,%入力 を`基本~URL構文解析器$にかける ⇒ ~URLと上書stateの組: ( %複製~URL, `~query~state$url ),
      `上書き符号化方式^V: 此れに`関連する文書$Locの`文字~符号化方式$doc ◎ Basic URL parse input, with copyURL as url and query state as state override, and the relevant Document's document's character encoding as encoding override.
  5. 次を与える下で,`~Location~obj設定子により~navigateする$ ⇒ ( 此れ, %複製~URL ) ◎ Location-object-setter navigate to copyURL.
`hash@m

取得子は、次の手続きを走らせ~MUST: ◎ The hash attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. ~IF[ 此れが指す`~url$Locの`素片$url ~IN { ~NULL, 空~文字列 } ] ⇒ ~RET 空~文字列 ◎ If this Location object's url's fragment is either null or the empty string, return the empty string.
  3. ~RET 次を順に連結した結果 ⇒ `#^l,
    此れが指す`~url$Locの`素片$url ◎ Return "#", followed by this Location object's url's fragment.

設定子は、次の手続きを走らせ~MUST: ◎ The hash attribute's setter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %複製~URL ~LET 此れが指す`~url$Locの複製 ◎ Let copyURL be a copy of this Location object's url.
  3. %入力 ~LET 所与の値 ◎ ↓
  4. ~IF[ %入力 の最初の文字 ~EQ `#^l ] ⇒ %入力 から最初の文字を除去する ◎ Let input be the given value with a single leading "#" removed, if any.
  5. %複製~URL の`素片$url ~SET 空~文字列 ◎ Set copyURL's fragment to the empty string.
  6. 次を与える下で, %入力 を`基本~URL構文解析器$にかける ⇒ ~URLと上書stateの組: ( %複製~URL, `素片~state$url ) ◎ Basic URL parse input, with copyURL as url and fragment state as state override.
  7. 次を与える下で,`~Location~obj設定子により~navigateする$ ⇒ ( 此れ, %複製~URL ) ◎ Location-object-setter navigate to copyURL.

注記: `a$e, `area$e 要素に対する等価な~APIと違って, `hash$m 属性の設定子は、[ 空~文字列を,配備済みの~scriptと互換にするよう特別に扱う ]ことはない。 ◎ Unlike the equivalent API for the a and area elements, the hash attribute's setter does not special case the empty string to remain compatible with deployed scripts.

`assign(url)@m

被呼出時には、次の手続きを走らせ~MUST: ◎ When the assign(url) method is invoked, the user agent must run the following steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. %~URL~record ~LET %url を,`入口~設定群~obj$に`相対的に構文解析-$した`結果の~URL~record$ ◎ Parse url relative to the entry settings object.\
  3. ~IF[ %~URL~record ~EQ ~error ] ⇒ ~THROW `SyntaxError$E ◎ If that failed, throw a "SyntaxError" DOMException.
  4. 次を与える下で,`~Location~objにより~navigateする$ ⇒ ( 此れ, %~URL~record ) ◎ Location-object navigate to the resulting URL record.
`replace(url)@m

被呼出時には、次の手続きを走らせ~MUST: ◎ When the replace(url) method is invoked, the user agent must run the following steps:

  1. %~URL~record ~LET %url を,`入口~設定群~obj$に`相対的に構文解析-$した`結果の~URL~record$ ◎ Parse url relative to the entry settings object.\
  2. ~IF[ %~URL~record ~EQ ~error ] ⇒ ~THROW `SyntaxError$E ◎ If that failed, throw a "SyntaxError" DOMException.
  3. 次を与える下で,`~Location~objにより~navigateする$ ⇒ ( 此れ, %~URL~record, ~ON ) ◎ Location-object navigate to the resulting URL record with the replacement flag set.
注記: `replace()$m ~methodに対しては、意図的に保安~検査は行われない。 ◎ The replace() method intentionally has no security check.
`reload()@m

被呼出時には、次の手続きを走らせ~MUST: ◎ When the reload() method is invoked, the user agent must run the appropriate steps from the following list:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin • Throw a "SecurityError" DOMException.
  2. %B ~LET 此れに`対応する閲覧文脈$Loc
  3. ~IF[ 現在~実行-中の`~task$†は、利用者による %B の~resizeに呼応して配送された `resize$et ~eventによるものである†† ] ⇒ %B を塗りなおす††† ◎ If the currently executing task is the dispatch of a resize event in response to the user resizing the browsing context • Repaint the browsing context and return.

    【† `現在~走っている~task$? 】【†† すなわち,この~methodが `resize^et ~event~handlerの中から呼出されたとき? 】【††† “repaint” — 単に再~描画するだけ? 】

  4. ~ELIF[ %B にて`作動中の文書$は`~iframe-srcdoc文書$である ] ⇒ %B の`閲覧文脈~容器$の ~iframe属性を再処理する ◎ If the browsing context's active document is an iframe srcdoc document • Reprocess the iframe attributes of the browsing context's browsing context container.
  5. ~ELIF[ %B にて`作動中の文書$の`再読込み上書き~flag$ ~EQ ~ON ] ⇒ %B を`担当の閲覧文脈$enV†とする下で,`上書きされる再読込み$を遂行する (例外投出あり) ◎ If the browsing context's active document has its reload override flag set • Perform an overridden reload, with the browsing context being navigated as the responsible browsing context. Rethrow any exceptions.

    【† `~source閲覧文脈$の誤記? 】

  6. ~ELSE ⇒ 次を与える下で, %B を此れが指す`~url$Locへ`~navigate$して(例外投出あり)、`閲覧文脈$の`現在の~entry$に対し`~entry更新-$を遂行する:

    • `例外~可能化~flag$ ~SET ~ON
    • `~source閲覧文脈$ ~SET %B

    この~naviは、`再読込みにより誘発され$たものとされる。

    ◎ Otherwise • Navigate the browsing context to this Location object's relevant Document's URL to perform an entry update of the browsing context's current entry, with the exceptions enabled flag set. The source browsing context must be the browsing context being navigated. This is a reload-triggered navigation. Rethrow any exceptions.

利用者から ~UI要素†を通して[ `閲覧文脈$ %B にて`作動中の文書$ %文書 を再読込みする ]よう要請されたときは、~UAは: ◎ When a user requests that the active document of a browsing context be reloaded through a user interface element,\

【† ~browserの “再読込み~button” 等を指すと思われるが,~DOM内の要素も含まれる? 】

  • %B を %文書 と同じ資源へ`~navigate$して,`閲覧文脈$の`現在の~entry$に対し`~entry更新-$を遂行するべきである。 この~naviは、`再読込みにより誘発され$たものとされる。 ◎ the user agent should navigate the browsing context to the same resource as that Document, to perform an entry update of the browsing context's current entry. This is a reload-triggered navigation.\
  • 非冪等~method(例: ~HTTP `POST^meth )の事例では、~UAは先ず,利用者にその演算を確認してもらうよう~promptするべきである — さもなければ~transaction(例:購入や~database改変)が繰返され得るので。 ◎ In the case of non-idempotent methods (e.g. HTTP POST), the user agent should prompt the user to confirm the operation first, since otherwise transactions (e.g. purchases or database modifications) could be repeated.\
  • [ 再読込み時に~cacheを明示的に上書きする ]ことを,利用者に許容してよい。 ◎ User agents may allow the user to explicitly override any caches when reloading.\
  • [ %文書 の`再読込み上書き~flag$ ~EQ ~ON ]の場合、この段落に述べた~naviに代えて,`上書きされる再読込み$を遂行してよい(`~source閲覧文脈$として %B を与える下で)。 ◎ If browsing context's active document's reload override flag is set, then the user agent may instead perform an overridden reload rather than the navigation described in this paragraph (with the browsing context being reloaded as the source browsing context).
`ancestorOrigins@m

取得子は、次の手続きを走らせ~MUST: ◎ The ancestorOrigins attribute's getter must run these steps:

  1. 此れの`生成元~domainを検査する$ ◎ If this Location object's relevant Document's origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.
  2. ~RET 此れの`先祖~生成元~list$ ◎ Otherwise, return this Location object's ancestor origins list.
`ancestorOrigins$m 属性がどう働くかの詳細は、まだ異論があり,変更され得る。 更なる情報は issue #1918 を見よ。 ◎ The details of how the ancestorOrigins attribute works are still controversial and might change. See issue #1918 for more information.

【 以下,この節, およびその各 下位節の内容は、 別ページ にて。 】