HTML: The Living Standard

Edition for Web Developers — Last Updated 27 October 2022

1. 1. 7.5 セッション履歴およびナビゲーション
      1. 7.8.1 ブラウジングセッション
      2. 7.8.2 ブラウジングコンテキストのセッション履歴
      3. 7.8.3 Historyインターフェイス
      4. 7.8.4 Locationインターフェイス

7.8 セッション履歴およびナビゲーション

7.8.1 ブラウジングセッション

7.8.2 ブラウジングコンテキストのセッション履歴

ブラウジングコンテキスト内のDocumentの配列は、そのセッション履歴である。子ブラウジングコンテキストを含む各ブラウジングコンテキストは、個別のセッション履歴を持つ。ブラウジングコンテキストのセッション履歴は、セッション履歴のエントリーのフラットなリストから成る。

ブラウジングコンテキストのセッション履歴における各Documentオブジェクトは、同じ基礎となるセッション履歴をすべてモデル化しなければならない、一意なHistoryオブジェクトに関連付けられる。

セッション履歴エントリーは、以下のアイテムをもつ構造体である：

• URL、URL

• 文書、Documentまたはnull

  各エントリーは、最初に作成されたとき、その文書のDocumentを持つ。しかし、Documentがアクティブでない場合、リソースを解放するために廃棄することができる。次に、セッション履歴エントリーのURLおよびその他のデータは、ユーザーエージェントがそのエントリーにナビゲートする必要があることを発見した場合に、元の代わりに新しいDocumentをもたらすために使用される。

  履歴ナビゲーションが発生し、かつ宛先セッション履歴エントリーのDocumentがnullでない場合（つまり、履歴をトラバースするステップ1の述語がfalseの場合）、ブラウザーがそのDocumentをキャッシュしたことを意味する。 このキャッシュは、バックフォワードキャッシュまたはbfcache（つまり"blazingly fast"キャッシュ）と呼ばれることがよくある。

• シリアライズされた状態、これはシリアライズされた状態またはnullであり、最初はnull

• コンテナーポリシー、コンテナーポリシーまたはnull

• スクロール復元モード、スクロール復元モード、最初は "auto"。

• スクロール位置データ、これは文書の復元可能なスクロール可能領域のスクロール位置データである。

• ブラウジングコンテキスト名、ブラウジングコンテキスト名またはnull、最初はnull

• 永続ユーザー状態、これは実装定義であり、最初はnull

  たとえば、一部のユーザーエージェントは、フォームコントロールの値を永続化したいかもしれない。

  フォームコントロールの値を永続化するユーザーエージェントはまた、それらの方向（要素のdir属性の値）を保持することが推奨される。これは、ユーザーが最初明示的にデフォルト以外の方向をもつ値を入力した場合、履歴走査の後に誤って値を表示することを防ぐ。

シリアライズされた状態は、ユーザーインターフェイスの状態を表すオブジェクトを（StructuredSerializeForStorage経由で）シリアライズしたものである。非公式に"状態オブジェクト"と呼ぶこともあるが、これは著者から提供されたユーザーインターフェイスの状態を表すオブジェクトであり、あるいは、シリアライズされた状態をデシリアライズ（StructuredDeserialize経由で）して作成されたオブジェクトでもある。

ページは、シリアライズされた状態をセッション履歴に追加することができる。ユーザー（またはスクリプト）が履歴に戻るとき、これらはデシリアイズされてスクリプトに返されるため、著者は1ページのアプリケーションでも"ナビゲーション"メタファーを使用できるようになる。

スクロール復元モードは、エントリーに移動するときに、ユーザーエージェントが永続化されたスクロール位置（存在する場合）を復元すべきかどうかを示す。スクロール復元モードは次のいずれかである：

"auto"

ユーザーエージェントは、ナビゲーション時にスクロール位置を復元する責任がある。

"manual"

ページはスクロール位置を復元する責任があり、ユーザーエージェントは自動的に復元を試みない。

セッション履歴内の複数の連続したエントリーは、同じ文書を共有することができる。これは、通常のナビゲーションを介して最初のエントリーに到達し、かつhistory.pushState()を介して次のエントリーが追加された場合に発生する可能性がある。または、フラグメントへのナビゲーションを介して発生する可能性がある。

同じDocumentを共有する（したがって、特定の文書の単に異なる状態である）すべてのエントリーは、定義により連続する。

任意の時点で、セッション履歴のエントリーの1つは、現在のエントリーである。これは、ブラウジングコンテキストのアクティブ文書を表すエントリーである。現在のエントリーであるそれぞれのエントリーは、この仕様で定義されるアルゴリズムによって変更される。たとえばセッション履歴走査中など。

現在のエントリーは通常、ナビゲーション時に作成される最初のエントリーである。しかし、上記のように、同じ文書を共有する連続したエントリーの1つにすることもできる。

ブラウジングコンテキスト内の各Documentはまた、最新のエントリーを持つことができる。これは、ブラウジングコンテキストのセッション履歴が最後にたどられたDocumentのエントリーである。 Documentが作成されるとき、最初は最新のエントリーを持たない。

7.8.3 Historyインターフェイス

window.history.length

ジョイントセッション履歴内のエントリーの数を返す。

window.history.scrollRestoration [ = value ]

セッション履歴の現在のエントリーのスクロール復元モードを返す。

セッション履歴の現在のエントリーのスクロール復元モードを変更する設定が可能である。

window.history.state

オブジェクトにデシリアライズされた、現在のシリアライズされた状態を返す。

window.history.go([ delta ])

ジョイントセッション履歴内のステップの指定した数の前後に進む。

ゼロ差分は、現在のページをリロードする。

差分が範囲外の場合、何もしない。

window.history.back()

ジョイントセッション履歴内の1つのステップに戻る。

前のページが存在しない場合、何もしない。

window.history.forward()

ジョイントセッション履歴内の1つのステップに進む。

次のページが存在しない場合、何もしない。

window.history.pushState(data, "")

指定されたdataが関連付けられたセッション履歴に新しいエントリーをプッシュする。 現在のエントリーのURLがコピーされ、新しいエントリーのURLに使用される。

（2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。）

window.history.pushState(data, "", url)

指定されたdataが関連付けられ、そのURLがurlに設定される新しいエントリーをセッション履歴にプッシュする。

現在のDocumentがURLをurlに書き換えることができない場合、"SecurityError" DOMExceptionが投げられる。

（2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。）

window.history.replaceState(data, "")

現在のセッション履歴エントリーに保存されているデータをdataに更新する。

（2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。）

window.history.replaceState(data, "", url)

現在のセッション履歴エントリーに保存されているデータをdataに更新し、そのURLをurlに更新する。

現在のDocumentがURLをurlに書き換えることができない場合、"SecurityError" DOMExceptionが投げられる。

（2番目のパラメーターは歴史的な理由で存在し、省略することはできない。空の文字列を渡すことは慣例的なものである。）

トップレベルブラウジングコンテキストのジョイントセッション履歴は、ジョイントセッション履歴の現在のエントリーを除いて削除されたそれぞれのセッション履歴において現在のエントリーであるすべてのエントリーとともに、トップレベルブラウジングコンテキストを共有するすべての完全にアクティブなDocumentオブジェクトのすべてのブラウジングコンテキストに属するすべてのセッション履歴の結合である。

ジョイントセッション履歴の現在のエントリーは、最近そのセッション履歴内の現在のエントリーになったエントリーである。

ジョイントセッション履歴内のエントリーは、それぞれのセッション履歴に追加された時点で時系列に並べられる。各エントリーはインデックスを持つ。最古のエントリーのインデックスは0を持ち、後続のエントリーは連続して増加する整数（1、2、3など）を番号付けされる。

ブラウジングコンテキスト内の各Documentは、異なるイベントループがあるかもしれないので、ジョイントセッション履歴の実際の状態は、不明瞭にできる。たとえば、2つの兄弟iframe要素は、同時に1つの一意な生成元から別のものに互いに横断でき、それらの正確な順序は明確に定義されないかもしれない。それらは後にお互いを知るかもしれないので、同様に、それらはジョイントセッション履歴の長さについて同意しないかもしれない。

A Document document can have its URL rewritten to a URL targetURL if the following algorithm returns true:

1. Let documentURL be document's URL.

2. If targetURL and documentURL differ in their scheme, username, password, host, or port components, then return false.

3. If targetURL's scheme is an HTTP(S) scheme, then return true. (Differences in path, query, and fragment are allowed for http: and https: URLs.)

4. If targetURL's scheme is "file", and targetURL and documentURL differ in their path component, then return false. (Differences in query and fragment are allowed for file: URLs.)

5. If targetURL and documentURL differ in their path component or query components, then return false. (Only differences in fragment are allowed for other types of URLs.)

6. Return true.

<!DOCTYPE HTML>
<!-- this is https://example.com/line?x=5 -->
<html lang="en">
<title>Line Game - 5</title>
<p>You are at coordinate 5 on the line.</p>
<p>
 <a href="?x=6">Advance to 6</a> or
 <a href="?x=4">retreat to 4</a>?
</p>

<!DOCTYPE HTML>
<!-- this starts off as https://example.com/line?x=5 -->
<html lang="en">
<title>Line Game - 5</title>
<p>You are at coordinate <span id="coord">5</span> on the line.</p>
<p>
 <a href="?x=6" onclick="go(1); return false;">Advance to 6</a> or
 <a href="?x=4" onclick="go(-1); return false;">retreat to 4</a>?
</p>
<script>
 var currentPage = 5; // prefilled by server
 function go(d) {
   setupPage(currentPage + d);
   history.pushState(currentPage, "", '?x=' + currentPage);
 }
 onpopstate = function(event) {
   setupPage(event.state);
 }
 function setupPage(page) {
   currentPage = page;
   document.title = 'Line Game - ' + currentPage;
   document.getElementById('coord').textContent = currentPage;
   document.links[0].href = '?x=' + (currentPage+1);
   document.links[0].textContent = 'Advance to ' + (currentPage+1);
   document.links[1].href = '?x=' + (currentPage-1);
   document.links[1].textContent = 'retreat to ' + (currentPage-1);
 }
</script>

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

7.8.4 Locationインターフェイス

各Windowオブジェクトは、Locationオブジェクトの一意なインスタンスに関連付けられており、Windowオブジェクトの作成時に割り当てられる。

document.location [ = value ]

window.location [ = value ]

現在のページの位置とLocationオブジェクトを返す。

別のページにナビゲートするために、設定可能である。

Locationオブジェクトは、Documentのブラウジングコンテキストに属するアクティブ文書のURLの表現を提供し、historyオブジェクトのエントリーを追加または置換することによって、ブラウジングコンテキストのセッション履歴の現在のエントリーを変更可能にする。

location.toString()

location.href

LocationオブジェクトのURLを返す。

与えられたURLにナビゲートするように、設定可能である。

location.origin

Locationオブジェクトの生成元を返す。

location.protocol

Locationオブジェクトのスキームを返す。

変更されたスキームと同じURLにナビゲートするように、設定可能である。

location.host

LocationオブジェクトのURLのホストとポートを返す（スキームのデフォルトポートと異なる場合）。

変更されたホストおよびポートと同じURLにナビゲートするように、設定可能である。

location.hostname

Locationオブジェクトのホストを返す。

変更されたホストと同じURLにナビゲートするように、設定可能である。

location.port

Locationオブジェクトのポートを返す。

変更されたポートと同じURLにナビゲートするように、設定可能である。

location.pathname

Locationオブジェクトのパスを返す。

変更されたパスと同じURLにナビゲートするように、設定可能である。

location.search

LocationオブジェクトのURLのクエリーを返す（空でない場合は先頭の"?"を含む）。

（先頭の"?"を無視して）変更されたクエリーと同じURLにナビゲートするように、設定可能である。

location.hash

LocationオブジェクトのURLのフラグメントを返す（空でない場合は先頭の"#"を含む）。

（先頭の"#"を無視して）変更されたフラグメントと同じURLにナビゲートするように、設定可能である。

location.assign(url)

与えられたURLにナビゲートする。

location.replace(url)

セッション履歴から現在のページを削除し、与えられたURLにナビゲートする。

location.reload()

現在のページをリロードする。

location.ancestorOrigins

親ブラウジングコンテキストからトップレベルブラウジングコンテキストまで、祖先ブラウジングコンテキストの生成元を列挙するDOMStringListオブジェクトを返す。