v0.21

spaルーター

はじめに

dframeworkにはdSPAと呼ばれる完全に統合されたクライアント側ルーターが含まれています。javascriptフレームワーク、ビルドステップ、または設定を必要とせずに、サーバーレンダリングされたアプリケーションをシングルページアプリケーションに変換します。<a>タグはd-link属性が付与されている場合にのみインターセプトされます。<d-link>カスタム要素は常にインターセプトされます。ルーターは遷移先を取得し、ページの残りの部分、レイアウトスクリプト、ソケット接続、音声再生を維持しながら、DOMの対象部分のみを差し替えます。

ルーターはアプリケーションにフレームワークのフロントエンドランタイムが含まれている場合に自動的に読み込まれます。インストールやインポートは不要です。

動作の仕組み

ユーザーがリンクをクリックすると、ルーターはバックグラウンドで遷移先ページをHTMLとして取得します。その後レスポンスを仮想ドキュメントとして解析し、設定された差し替えターゲットセレクター内のコンテンツを抽出し、現在のページの該当領域のみを的確に置き換えます。ブラウザーのURLと履歴はpushStateを介して更新され、ドキュメントタイトルが同期され、CSRFトークンが更新され、新しいコンテンツ内のスクリプトが分離されたスコープ内で実行されます。

ブラウザーの戻るおよび進むナビゲーションは完全に処理されます。ユーザーが戻るボタンを押すと、ルーターは前のURLを取得し順方向ナビゲーションとまったく同様にコンテンツを差し替えます。

デフォルトの差し替えターゲット

デフォルトでは、ルーターはdSPA.targetsおよびwindow.dSPA_DEFAULT_TARGETSを動的に確認し、候補セレクター['#spa-container', 'main', 'body']にフォールバックします。ルーターは現在のページと取得したページの両方に存在する最初のセレクターを解決します。dSPA.targetsまたはwindow.dSPA_DEFAULT_TARGETSを設定することでこれをグローバルに上書きできます。

1<script defer>
2 dSPA.targets = ['main'];
3</script>

リンクとナビゲーション

アンカーのインターセプト

標準の<a>タグはd-link属性が付与されている場合にのみインターセプトされます。クリックされるとルーターはhrefを取得しデフォルトの対象領域を差し替えます。

1<a href="/dashboard" d-link>dashboard</a>

ルーターは以下の場合にインターセプトをスキップします:

<d-link>はインターセプトされた<a>タグと同一に動作するカスタム要素ですが、その属性を通じてターゲット指定および差し替え動作をさらに細かく制御できます。

1<d-link href="/dashboard">dashboard</d-link>

ページのどの部分を置き換えるかはtarget属性を使用して指定できます。

1<d-link href="/admin/users" target="#spa-container">users</d-link>

取得したページでコンテンツ領域に異なるセレクターが使用されている場合、src属性を使用してレスポンスから抽出する要素を指定できます。

1<d-link href="/settings" target="#panel" src="#settings-panel">settings</d-link>

mode属性は新しいコンテンツをターゲット要素にどのように配置するかを制御します。

1<d-link href="/notifications" target="#feed" mode="prepend">load new</d-link>

ナビゲーション後もスクロール位置を維持するにはpreserve-scroll属性を追加します。

1<d-link href="/feed?page=2" target="#feed" preserve-scroll>next page</d-link>

d-linkのない標準の<a>タグはすでに通常のページナビゲーションを実行します。<d-link>要素で強制的にページ全体の再読み込みを行うにはd-full-reload属性を使用します。

1<d-link href="/logout" d-full-reload>logout</d-link>

プログラムによるナビゲーション

dSPA.navigate()を使用してjavascriptからSPAナビゲーションをトリガーできます。これはリンクをクリックするのと同じフェッチ、差し替え、履歴更新のサイクルを実行します。

1dSPA.navigate('/dashboard');

オプションオブジェクトを渡してナビゲーションのターゲット、ソース、モード、トランジションを制御できます。

1dSPA.navigate('/home', {
2 targets: ['#tabContent'],
3 transitions: {
4 beforeSwapTarget(oldEl, meta) {
5 oldEl.style.opacity = '0';
6 },
7 afterSwapTarget(newEl, meta) {
8 newEl.style.opacity = '1';
9 }
10 }
11});

利用可能なオプションは以下のとおりです:

差し替えモード

ルーターはターゲット要素への新しいコンテンツの配置方法を制御する4つの差し替えモードをサポートしています。

inner(デフォルト): ターゲット要素の子要素をクリアし新しいコンテンツの子要素を挿入します。ターゲット要素自体は保持されます。

outer: ターゲット要素自体を含めターゲット要素全体を新しいコンテンツ要素に置き換えます。

append: 既存の子要素を削除することなくターゲット要素の最後の子要素として新しいコンテンツを追加します。

prepend: 既存の子要素を削除することなくターゲット要素の最初の子要素として新しいコンテンツを挿入します。

トランジションフック

ルーターはナビゲーション中のコンテンツ遷移をアニメーション化できるライフサイクルフックを公開しています。フックは非同期処理に対応しています。ルーターは返されたプロミスが解決するまで待機してから処理を続行します。

グローバルトランジション

レイアウト内のdSPA.transitionsにオブジェクトを代入することでグローバルトランジションフックを設定します。これらのフックはすべてのSPAナビゲーションで発火します。

1<script defer>
2 const drawer = select('d-drawer');
3
4 dSPA.transitions = {
5 beforeSwap(oldNode, meta) {
6 return drawer.close();
7 },
8 afterSwap(newNode, meta) {
9 return drawer.open();
10 },
11 };
12</script>

beforeSwapフックは古いコンテンツが削除される前に発火します。古いコンテンツの終了アニメーションに使用します。afterSwapフックは新しいコンテンツが挿入された後に発火します。新しいコンテンツの開始アニメーションに使用します。

ナビゲーションごとのトランジション

dSPA.navigate()にtransitionsオブジェクトを渡すことで単一のナビゲーションに対してグローバルフックを上書きできます。

1dSPA.navigate('/' + tab.dataset.tab, {
2 targets: ['#tabContent'],
3 transitions: {
4 beforeSwapTarget(oldEl, meta) {
5 oldEl.style.transform = 'translate3d(0, 5%, 0)';
6 oldEl.style.opacity = '0';
7 },
8 afterSwapTarget(newEl, meta) {
9 newEl.style.transform = 'translate3d(0, 0, 0)';
10 newEl.style.opacity = '1';
11 }
12 }
13});

フックリファレンス

4つのフックが利用可能です。各フックは2つの引数を受け取ります(差し替え対象のDOM要素、およびurl、link、src、dest、modeを含むmetaオブジェクト)。

フックがプロミスを返した場合、ルーターはライフサイクルを続行する前にそれを直接awaitします。dSPA.navigate()に渡されたナビゲーションごとのトランジションはそのナビゲーションにおいてグローバルのdSPA.transitionsを上書きします。

フォーム

基本的な使用法

<d-form>はページ全体の遷移ではなくfetch経由でフォームを送信するカスタム要素です。内部で標準の<form>要素をラップしそのsubmitイベントをインターセプトします。

1<d-form action="/register" method="POST" class="flex-column g-1">
2 <input type="text" name="username" placeholder="username">
3 <input type="password" name="password" placeholder="password">
4 <button type="submit">register</button>
5</d-form>

要素はすべてのリクエストにCSRFトークンを自動注入します。すでに<d-form>内に<form>要素がある場合要素はそれを直接使用します。省略した場合は<d-form>のmethodおよびaction属性を使用して<form>が自動作成されます。

重複リクエストを防ぐため送信中はすべてのフォーム入力が無効化されます。

バリデーション

rules属性を使用してクライアント側バリデーションルールを定義できます。構文はサーバー側のバリデーションルールを反映しています。

1<d-form action="/register" method="POST" rules='{"invite_token": "required"}'>
2 <input type="text" name="invite_token" placeholder="invite token">
3 <button type="submit">submit</button>
4</d-form>

利用可能なクライアント側ルールは以下のとおりです: required、string、number、integer、boolean、array、email、min:value、max:value、in:a,b,c、not_in:a,b,c、nullable。

バリデーションが失敗するとフォームは最も近い.input-wrapper先祖(または入力自体)にerrorクラスを追加し直下にerror-message要素を挿入します。エラーは次回の送信試行時に自動的にクリアされます。

jsonレスポンス

サーバーがJSONで応答した場合、フォームは特定のプロパティについてレスポンスボディを検査します。

レスポンスにredirectプロパティが含まれている場合、フォームはSPAルーターを介してそのURLに遷移します。レスポンスにforce: trueプロパティも含まれている場合は代わりにページ全体のリダイレクトを実行します。

レスポンスにerrorsオブジェクトが含まれている場合、フォームはクライアント側バリデーションと同じ規則に従って対応する各入力フィールドの横にエラーメッセージを表示します。

htmlレスポンス

サーバーがHTMLで応答した場合、フォームはその対象要素のコンテンツをレスポンスで置き換えます。対象のデフォルトはbodyですがtarget属性を使用して上書きできます。

1<d-form action="/search" method="GET" target="#results">
2 <input type="text" name="q" placeholder="search">
3 <button type="submit">search</button>
4</d-form>

navigate属性が存在する場合、フォームは単純なコンテンツ置換ではなくSPAルーターの完全なナビゲーションパイプラインを使用します。

1<d-form action="/search" method="GET" target="#results" navigate>
2 <input type="text" name="q" placeholder="search">
3</d-form>

リダイレクト処理

サーバーがHTTPリダイレクト(3xx)で応答した場合、フォームはSPAルーターを通じてそれに従い、新しいページコンテンツをデフォルトのターゲットに差し替えてブラウザーのURLを更新します。

強制リロード

force-reload属性はSPAルーターを通じてレスポンスを処理する代わりに特定の条件下でページ全体の再読み込みをトリガーするようフォームに指示します。

1<d-form action="/save" method="POST" force-reload>
2<d-form action="/register" method="POST" force-reload="success">
3<d-form action="/save" method="POST" force-reload="error">

有効な値はtrue(または同等である空文字列)、all、success、errorです。

コントローラーレスポンスのライフサイクル

以下の表は<d-form>が各サーバーコントローラーレスポンスをどのように処理するか、またforce-reloadがデフォルトの処理をどのように変更するかを示しています:

コントローラーの戻り値 ステータス / タイプ デフォルトの動作(force-reloadなし) force-reload指定時の動作
return json({ data }) 200 (application/json) ペイロードを解析しd-successとd-responseを送出、callbackが定義されている場合は実行、ページリロードなしでフォームを画面に残す force-reload、all、またはsuccessが設定されている場合はページをリロード(error指定時は無視)
return json({ redirect }) 200 (application/json) リロードなしでdSPA.navigate(redirect)を通じて遷移(force: trueまたはX-Redirect-Forceが設定されている場合は完全なページリダイレクトを実行) SPAルーター経由で遷移(force: trueの場合はハードリダイレクト)
return json().withErrors(errors) 422 (application/json) 入力欄に.errorを付与しフィールド直下に.error-message(または上部に.error-banner)を注入、d-errorとd-responseを送出 force-reload、all、またはerrorが設定されている場合はページをリロード(success指定時はインラインエラーを保持)
validate() 失敗 422 (application/json) フィールドバリデーションエラーをインラインでレンダリング、d-errorとd-responseを送出、フォーム状態を維持 force-reload、all、またはerrorが設定されている場合はページをリロード(success指定時はインラインエラーを保持)
return abort(status, message) 4xxまたは5xx (application/json) フォーム上部に.error-bannerを表示、d-errorとd-responseを送出、フォーム入力を再度有効化 force-reload、all、またはerrorが設定されている場合はページをリロード(success指定時はバナーを表示)
return render(view, data) 200 (text/html) 返却されたマークアップを対象セレクター(デフォルトはbody)に差し替え、スクリプトを実行、d-successを送出(navigate設定時はURLを更新) force-reload、all、またはsuccessが設定されている場合はページをリロード(error指定時は差し替えを実行)
予期しないサーバーエラー 500 (text/htmlまたはapplication/json) HTMLの場合はdocument.writeを通じて完全な500エラーページをレンダリング(JSONの場合はエラーバナーを表示) HTMLの場合は500エラーページを表示(JSONの場合はallまたはerror設定時にページをリロード)
予期しない404エラー 404 (text/htmlまたはapplication/json) HTMLの場合は対象を404エラーテンプレートに差し替え(JSONの場合はエラーバナーを表示) allまたはerrorが設定されている場合はページをリロード(success指定時はビューを保持)

コールバック

callback属性に関数名を指定することでレスポンス成功後にjavascript関数を実行できます。関数は解析されたレスポンスデータを引数として受け取ります。

1<d-form action="/api/magic" method="POST" callback="onMagicSuccess">
2 <button type="submit">generate</button>
3</d-form>
4
5<script>
6 function onMagicSuccess(data) {
7 }
8</script>

プログラムによる送信

<d-form>要素上で.submit()を呼び出すことでプログラムからフォームを送信できます。

1select('d-form').submit();

また.serialize()を呼び出すことで現在のフォームデータをFormDataオブジェクトとして取得できます。

1const data = select('d-form').serialize();

スクリプトの実行

ルーターは各ナビゲーション後に差し替えられたコンテンツ内にあるすべての<script>タグを実行します。すべてのスクリプトはタイマー、リスナー、fetch、アニメーションフレームのライフサイクル認識置換を提供する分離されたスコープ内で実行されます。後続のナビゲーション中にスクリプトを所有するコンテンツがDOMから削除されると、そのタイマー、リスナー、保留中のリクエストはすべて自動的にクリーンアップされます。

スコープ付きスクリプト

差し替えられたコンテンツ内のインラインスクリプトは標準ブラウザーAPIのスコープ付きバージョンをローカル変数として受け取ります。グローバルAPIとまったく同じように使用できますがコンテンツから離れるナビゲーションが発生したときに自動的に破棄されます。

すべてのインラインスクリプト内で以下のスコープ付きAPIが利用可能です:

1<div id="counter">0</div>
2<script>
3 let count = 0;
4 const el = document.querySelector('#counter');
5
6 setInterval(() => {
7 count++;
8 el.textContent = count;
9 }, 1000);
10</script>

ユーザーがページから離れるとインターバルは自動的にクリアされます。手動のクリーンアップは不要です。

初期ページロードと永続スクリプト

標準のページビューおよび差し替えられたコンテンツでは通常の<script>タグを記述できます。差し替え領域内のすべてのインラインスクリプトおよび外部スクリプトはルーターによって自動的に管理およびスコープ化されます。

TIP

初回のハードページロード時において管理スコープとアクティブなWebSocket接続へのアクセスが必要なレイアウトスクリプトには`type="text/dspa"`を使用します。dSPA経由で遷移した通常のビューは管理スコープ内で自動的にスクリプトを実行します。

1<script type="text/dspa">
2 Socket.on('update:level', (data) => {
3 selectAll('[data-level]').forEach(el => {
4 el.textContent = data.level;
5 });
6 });
7</script>

ブラウザーパーサーは通常のページ読み込み時にtype="text/dspa"を無視します。DOMContentLoaded時かつSocket.connect()の完了後、ルーターは初回管理スコープ内ですべてのtype="text/dspa"スクリプトを実行し、Socket、listen、自動クリアタイマーなどのスコープ付きユーティリティを提供します。

dSPA経由でナビゲートされる通常のビューおよび差し替えコンテンツでは標準の<script>タグがすでに管理スコープ内で自動実行されるためtype="text/dspa"は不要です。

モジュールスクリプト

ESモジュールスクリプト(type="module")がサポートされています。デフォルトではモジュールスコープの分離によりクラシックスクリプトで使用されるラッピング手法が防止されるため、モジュールスクリプトはスコープ付きAPI変数を受け取りません。

モジュールスクリプトでスコープ注入を有効にするにはd-spa-scope属性を追加します。

1<script type="module" d-spa-scope>
2 const el = document.querySelector('#timer');
3 setInterval(() => {
4 el.textContent = new Date().toLocaleTimeString();
5 }, 1000);
6</script>

外部スクリプト

差し替えられたコンテンツ内の外部スクリプト(src属性を持つスクリプト)はドキュメント順に従ってすべてのSPAナビゲーションで自動的に再実行されます。ルーターは後続のページスクリプトを実行する前にそれらを読み込んで実行します。

SPAナビゲーション時にルーターが特定のスクリプトタグを実行しないようにするにはd-spa-ignore属性を追加します。

1<script src="/analytics.js" d-spa-ignore></script>

永続要素(d-spa-keep)

bodyの差し替えをまたいで保持する必要がある要素やスクリプト(開発ツールや永続的なレイアウトステートなど)にはd-spa-keep属性を使用します。bodyの差し替えが発生した際、d-spa-keepを持つすべての要素が保持され新しいbodyに再アタッチされます。

1<div id="player-container" d-spa-keep>
2</div>

アクティブナビゲーション

ルーターは現在アクティブなナビゲーションリンクをハイライトする宣言的な方法を提供します。任意の要素にd-nav-active属性を追加して現在のURLに基づいてどのCSSクラスを切り替えるかを指定します。

1<d-link
2 href="/home"
3 d-nav-url="/home"
4 d-nav-active="d-link-active"
5 class="text-content bdr hover:bg-container-l tr-03 px-1 py-075 flex-center">
6 <i class="dstrn-home"></i>
7</d-link>

d-nav-urlはこの要素が対応するURLパスを指定します。hrefを持つ要素(<d-link>や<a d-link>など)で省略された場合、ルーターはhrefの読み取りにフォールバックします。先頭と末尾のスラッシュは自動的に正規化されるため、/library/、library、/libraryはすべて一貫して一致します。

デフォルトの一致判定はパスセグメントに基づくプレフィックス一致です。/homeのd-nav-urlは/homeおよび/home/settingsに一致し/home-feedは無視します。完全一致を要求するにはd-nav-exact属性を追加します。

アクティブ状態はすべてのSPAナビゲーション後に自動的に再計算されます。

csrfトークン管理

ルーターはナビゲーション間でCSRFトークンを自動管理します。ページがフェッチされるとルーターはレスポンスからcsrf-tokenおよびshield-challengeメタタグを抽出し現在のページのメタタグを新しい値で更新します。

同一オリジンを対象とするすべての変更系fetchリクエスト(POST、PUT、PATCH、DELETE)にはX-CSRF-TOKENヘッダーが自動注入されます。これはグローバルのfetch()関数とインラインスクリプトに提供されるスコープ付きfetch()の両方に適用されます。クライアント側のリクエストに手動でCSRFトークンを添付する必要は一切ありません。

domモーフィング

差し替え中、ルーターは古いDOMを新しいDOMでやみくもに置き換えることはしません。両方のツリーを走査し古いツリーを新しいツリーに変換するために必要な最小限の変更を適用するモーフィングアルゴリズムを使用します。これによりフォーカス状態、入力値、ネストされたコンテナー内のスクロール位置、および変更されなかったDOMノードに紐づく実行時ステートが保持されます。

モーフィングアルゴリズムは要素属性の更新、テキストノードの変更、IDによる子の並べ替え、input/select/textarea値の同期を処理します。

customElements.defineで登録されたカスタム要素はモーフィング後に適切にアップグレードされます。カスタム要素が検出された場合、古い要素は新しい要素に完全に置き換えられcustomElements.upgrade()を介してアップグレードされます。

スコープライフサイクル

ルーターは差し替えられたコンテンツ内のスクリプトを実行するたびにスコープを作成します。スコープはそれらのスクリプトによって作成されたすべてのタイマー、アニメーションフレーム、fetchリクエスト、イベントリスナーを所有します。スコープを所有するDOMノードが削除されると(後続のナビゲーションまたは直接のDOM操作のいずれかによって)、MutationObserverが削除を検知し自動的にスコープを破棄してすべてのタイマーをクリアし保留中のすべてのfetchを中止しすべてのイベントリスナーを削除します。

これはページスクリプトでクリーンアップコードを記述する必要が一切ないことを意味します。ルーターが自動的に処理します。

スクロールの挙動

デフォルトでは、ルーターはすべてのナビゲーション後にページの最上部までスクロールします。遷移先URLに#hashフラグメントが含まれている場合(例えば/profile#settingsや{{ route('home') }}#native)、ルーターは一致する要素を自動的に見つけてビューまでスクロールします。

現在のページ上の#hashを指すリンクをクリックした際(既に/にいるときの/#layersなど)、ルーターはナビゲーションをインターセプトし不要なネットワークフェッチをスキップしてブラウザー履歴を更新し対象要素をスムーズにスクロール表示します。

TIP

永続レイアウト内のセクションリンクには相対ハッシュフラグメント(`#native`)の代わりにハッシュ付きの完全なルートURL(例: `{{ route('home') }}#native`)を使用することで任意のページからナビゲーションが機能します。

<d-link>にpreserve-scroll属性を追加するかdSPA.navigate()にpreserveScroll: trueを渡すことでナビゲーションごとにスクロールを無効化できます。

デバッグモード

local環境ではフレームワークはルーターのデバッグモードを自動的に有効にします。デバッグモードでは各ナビゲーション、差し替えのタイミング、スコープの作成とクリーンアップ、潜在的なメモリリークに関する詳細情報が記録されます。

ルーターは各スコープが存続したナビゲーションの回数を追跡します。クリーンアップされずにスコープが5回を超えるナビゲーションを存続した場合、潜在的なメモリリークを示す警告がログに出力されます。孤立したスコープ(どのDOMノードにもリンクされていないスコープ)も報告されます。

デバッグモードは手動で切り替えることができます。

1dSPA.debug = true;