履歴エントリ
開いている行や広げたパネルのように、戻るボタンでは元に戻したい一方で、リンクでは共有したくない状態があります。こうした状態はentryに置きます。
このページの内容
entryのスキーマ
orders-state.tsimport { definePageState } from '@k8ordo/state';
import * as z from 'zod';
export const ordersState = definePageState('orders', {
entry: z.object({
expanded: z.array(z.string()).default([]),
showNotes: z.boolean().default(false),
}),
});definePageStateにentryのスキーマを渡します。値はURLには含まれません。Navigation APIが履歴エントリごとに持つ状態の、定義のキーの下に保存されます。
値は文字列にされず、型の付いたまま保存されます。真偽値はz.boolean()で、数値はz.number()で受けます。書いた値はそのままの型でもう一度スキーマで検証されます。z.stringbool()や型を変えるtransformは、書くたびに既定値に戻ります。
サーバーには履歴エントリが無いので、サーバーの描画とハイドレーションの描画は既定値で行われます。
urlとentryの併用
export const ordersState = definePageState('orders', {
url: z.object({
status: z.enum(['all', 'pending', 'shipped']).default('all'),
}),
entry: z.object({
expanded: z.array(z.string()).default([]),
}),
});
const [{ status, expanded }, update] = useAppState(ordersState);1つの定義にurlとentryの両方を書けます。useAppStateは、2つを1つのオブジェクトにまとめて返します。
フィールドをurlからentryへ移しても、呼び出す側のコードはそのまま動きます。ただし真偽値の書き方は変わります。urlでz.stringbool()だった真偽値は、entryではz.boolean()にします。
同じ名前のフィールドを両方に書くと、型エラーになります。実行時にも、statusを両方に書けば"orders" declares in both url and entry: statusというエラーになります。
書き込みの振り分け
update({ status: 'pending' }, { history: 'push' });
navigation.navigate()が1回
update({ expanded: ['A-102'] });
updateCurrentEntry()で今の履歴エントリを書き換える1回のupdate()で、urlとentryの両方を変えられます。urlの値が変わるかどうかで、書き込み方が決まります。
urlの値が変わるとき:navigation.navigate()を1回呼び、新しいURLとentryの値を一緒に渡します。URLだけ、またはentryだけが変わった状態が表示されることはありません。entryの値だけが変わるとき:navigation.updateCurrentEntry()で今の履歴エントリを書き換えます。遷移しないので、どのルーターの下でも動きます。{ history: 'push' }を付けても、新しい履歴エントリは作られません。
URLを変える書き込みは、今のentryの値を新しい履歴エントリへ持ち越します。ほかの定義が履歴エントリに保存した値も、そのまま残ります。
ブラウザ操作での復元
urlもentryも、ブラウザの履歴エントリにあります。ライブラリは別の記録を持ちません。ブラウザで戻る、進む、再読み込みをすると両方に同じように反映されます。
- 戻る/進む:移った先の履歴エントリにあった
urlとentryが、一緒に戻ります。 - 再読み込み:同じ履歴エントリのまま読み込み直すので、どちらも残ります。
- URLを新しいタブで開く:渡るのはURLだけです。
urlは同じ値になり、entryは既定値から始まります。 - リンクのクリック:新しい履歴エントリには
entryの値がまだ無いので、既定値から始まります。 - セッションの復元:古いスキーマが書いた値が戻ることがあります。スキーマに合わない値は、そのフィールドだけが既定値に戻ります。
urlとentryの比較
絞り込みをurlに、開いている注文をentryに置いたdefinePageStateで、このページのURLと履歴エントリを実際に書き換えます。
- 発送済み
- 未発送
- 未発送
- url
クエリなし- entry
{ expanded: [] }
試してみる
- 「A-102」を開きます。
entryの値は変わりますが、URLのクエリは変わりません。 - 絞り込みを「未発送」に切り替えます。クエリが
?status=pendingになり、「A-102」は開いたまま残ります。 - 「A-103」も開いてから、ブラウザの戻るを押します。絞り込みが「すべて」に戻り、開いている注文も「A-102」だけに戻ります。
- ページを再読み込みしても、絞り込みと開いている注文はそのまま残ります。