@k8ordo/router

仕組み

@k8ordo/routerがナビゲーションの処理をいつ、どこで行うかと、保証することとしないことが分かります。

このページの内容

処理する場所

ナビゲーションを処理するのは、useInterceptedNavigationというフックです。<Router>はルート表を使ってこのフックを呼びます。@k8ordo/frameworkのランタイムも、同じフックを呼びます。

2つで違うのは、どのナビゲーションを扱うかと、何を読み込むかだけです。このページのほかの動きは、どちらの下でも同じです。

このフックで自分のホストを作るときの書き方は、APIを見てください。

インターセプトの対象

リンクのクリックやnavigateTo、戻る操作と進む操作は、どれも同じnavigateイベントを発火させます。<Router>はこのイベントを受け取り、行き先のパスがルート表にあるものだけをインターセプトします。

次の4つは、フックがインターセプトしません。ルート表に何が書いてあっても、ブラウザがそのまま処理します。

  • 再読み込み:新しいページをサーバーから取得する操作
  • 本文を持つフォームの送信(POST):本文を扱えるのはサーバーだけ
  • ダウンロード:ファイルを保存する操作
  • フラグメント(URLの#より後ろ)だけの変更:同じページの中の移動

別のオリジンへの移動のように、ブラウザがインターセプトを許さないナビゲーションも対象外です。GETのフォームは本文を持たないので、インターセプトします。@k8ordo/stateのupdate()によるURLの書き換えも、同じイベントで処理されます。詳しくは更新を見てください。

finishedの解決

navigateToが返すfinishedは、URLが書き換わったあと、新しいページが描画された時点で解決します。

正確には、Reactが新しいページをコミットしたあと、ブラウザが画面に描く前です。前のスクロール位置で新しいページが1フレーム見えることはありません。

待つのは新しいページの最初のコミットです。ナビゲーションで新しくマウントされた<Suspense>の中でReact.lazyのページがサスペンドすると、fallbackをコミットした時点で解決します。コードの読み込みは待ちません。

状態だけの更新

クエリや履歴エントリの状態だけが変わるナビゲーションでは、パスは画面に出ているページと同じです。ルーターはこれをページの切り替えとして扱わず、何も読み込まずにインターセプトします。ページは作り直されず、フォーカスも動きません。戻ると進むを除けば、スクロール位置も動かず、finishedはURLが書き換わった時点で解決します。

戻ると進むでは、その履歴エントリを離れたときの位置に戻ります。ページがそのエントリの値で描き終わってから戻すので、useDeferredValueで遅らせて描く一覧でも、離れたときの位置に戻ります。finishedはその描画を待ちます。

例外は、useInterceptedNavigationに渡したrefreshがtrueを返したときです。同じパスのページを読み込み直し、finishedはその描画を待ちます。フォーカスは動かさず、トランジションの種類も付けません。スクロール位置は、戻ると進むでだけ、読み込み直したページが出てから戻ります。<Router>は読み込み直しませんが、@k8ordo/frameworkはsearchをexportしたページを読み込み直します。

比べる相手は画面に出ているページのパスで、アドレスバーのパスとは限りません。読み込み中のページのURLで状態だけを更新すると、ルーターはページの切り替えとして扱います。そのページの読み込みはそのまま続き、更新のfinishedもそのページの描画を待ちます。読み込み中に画面のページの履歴エントリへ戻ると、ページの切り替えの取り消しとして扱い、スクロール位置はそのままです。

描画の優先度

新しいページは、useDeferredValueと同じ優先度で描画されます。次のページの準備ができるまで前のページが画面に残り、操作もできます。

この描画はトランジションにしません。そのため、アクションの中でfinishedを待っても止まらず、ほかのアクションが保留中でもページの切り替えは遅れません。

この描画には、navigationとnavigation-pushのようなトランジションの種類を付けます。<ViewTransition>での使い方は切り替えのアニメーションを見てください。

スクロールとフォーカス

新しいページが画面に出ると、フォーカスはページを読み込んだときと同じ場所に移ります。autofocusの要素があればその要素へ、無ければ<body>へ移ります。スクロール位置も、URLにフラグメントがあればその要素へ、無ければページの先頭へ移ります。

フラグメントの要素は、idかname属性が一致するもので探します。デコードしてから探すので、#%E5%B0%8E%E5%85%A5はid="導入"の要素を指します。見つからなければ先頭へ移ります。

ブラウザの戻ると進むでは、その履歴エントリを離れたときの位置に戻ります。戻すのはブラウザでなくルーターで、ページが画面に出るときに一度に置きます。読み込みの間に前のページをスクロールしても、戻る位置は変わりません。読み込み中に取り消したページのように、一度も画面に出なかった履歴エントリへ進んだときは、フラグメントの要素か先頭へ移ります。

例外はWebKitです。別のオリジンから戻って読み直した文書から、それより前の履歴エントリへ戻ると、WebKitは行き先のキーを渡しません。このときはルーターでなくブラウザが位置を戻します。読み込みの間に前のページをスクロールすると、ブラウザは位置を戻さず、スクロールした位置に残ります。

別のサイトから戻ったときは、WebKitが一部の戻る操作を知らせません。別のサイトより前の履歴エントリへ戻るときと、戻ったページから移ったあとにそのページへ戻るときです。移った先の読み込みが終わる前に戻るときも含みます。このときはルーターがページを再読み込みします。サーバーで描いたページはブラウザが位置を戻し、クライアントで描いたページは先頭に着きます。同じページの中で検索だけが変わる戻るは、refreshがそのページを読み込み直すと答えたときと、ページの読み込みの途中のときだけ再読み込みします。再読み込みの途中に押したリンクは、文書の読み込みとして開きます。

ナビゲーションの追い越し

読み込みの途中で次のナビゲーションが始まると、前のナビゲーションは中断されます。中断にはブラウザのAbortSignalを使います。追い越された側のfinishedは、中断の理由でrejectします。そのページは、あとから読み込みが終わっても画面に出ません。

React.lazyのコードの読み込みは取り消せません。動的importはAbortSignalを受け取らないので、読み込みは最後まで進み、次に開いたときに使われます。

保証すること

  • 再読み込みとダウンロード、本文を持つフォームの送信とフラグメントだけの変更は、インターセプトしません。
  • finishedは、Reactが新しいページをコミットしたあと、ブラウザが画面に描く前に解決します。
  • ページの切り替えは、保留中のアクションに待たされません。アクションの中でfinishedを待っても止まりません。
  • クエリや履歴エントリの状態だけが変わるナビゲーションでは、フォーカスを動かしません。戻ると進むを除いて、スクロール位置も動かしません。
  • 戻ると進むでは、同じページの中でも、ページがそのエントリを描き終えてから、そのエントリを離れたときの位置に戻します。
  • 読み込み中に、画面に残るページの履歴エントリへ戻ると、スクロール位置はそのままです。
  • ページを切り替えると、戻ると進むを除いて、フラグメントの要素かページの先頭へスクロールします。新しいページが前のスクロール位置で描かれることはありません。
  • 読み込みの途中で追い越されたナビゲーションは、finishedが中断の理由でrejectし、そのページは画面に出ません。
  • ページを切り替える描画には、navigationとnavigation-pushのような種類を付けます。同じパスでの更新には付けません。

保証しないこと

  • URLと画面のページは、読み込みの間は一致しません。URLが先に書き換わり、前のページが画面に残ります。
  • finishedは、React.lazyのページのコードの読み込みを待ちません。
  • 戻ると進むで戻すのは、文書のスクロール位置だけです。ページの中でスクロールする要素の位置と、ピンチズームの倍率は戻しません。
  • WebKitで別のオリジンや別のサイトから戻った文書では、離れたときの位置に戻らないことがあります。
  • 追い越されたナビゲーションでも、React.lazyのコードの読み込みは止めません。
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。