フラグメント
スライドの何枚目かのように、リンクで共有したいがサーバーには要らない値は、URLのフラグメントに置けます。こうした値はhashに置きます。
このページの内容
hashのスキーマ
deck-state.tsimport { definePageState, useAppState } from '@k8ordo/state';
import * as z from 'zod';
export const deckState = definePageState('deck', {
url: z.object({ mode: z.enum(['view', 'present']).default('view') }),
hash: z.coerce.number().int().min(1).default(1),
});
// /slides/intro#3
const [{ hash, mode }, update] = useAppState(deckState);
// hash === 3フラグメントは1本の文字列なので、hashにはフィールドのオブジェクトではなく、値1つ分のスキーマを渡します。値は状態のhashというフィールドになり、urlやentryの値と一緒にuseAppStateから返ります。
スキーマの決まりはurlと同じです。値が無いときのために.default()か.optional()を付け、真偽値はz.stringbool()で書きます。urlかentryにhashという名前のフィールドがあると、定義の時点でエラーになります。
フラグメントはサーバーに送られないので、サーバーの描画とハイドレーションの描画は既定値で行われます。
書き込み
update({ hash: 4 }); // /slides/intro#4
update({ hash: 5 }, { history: 'push' });
update({ hash: 1 }); // /slides/intro書き込みもurlと同じです。既定では今の履歴エントリを書き換え、{ history: 'push' }を付けると履歴エントリを足します。既定値を書くと、URLからフラグメントが消えます。続けて書いたときは、urlの書き込みと同じように間引かれます。
フラグメントを書いても、画面の位置は動きません。ただし、その値と同じidの要素がページにあれば、ブラウザはそこへスクロールします。
deckState.href('/slides/intro', { hash: 4 });
// '/slides/intro#4'リンクはhref()で組めます。hashの値がフラグメントになります。
ページ内リンクとの共存
スキーマが受け付けないフラグメントは、この状態の値として扱いません。上のスキーマなら、#mainは既定値の1と読まれ、URLにはそのまま残ります。
この状態で既定値を書いても、urlやentryの値を書いても、#mainは消えません。既定値でない値を書いたときだけ、フラグメントが置き換わります。
訪問者がページ内リンクをたどると、値は既定値に戻ります。スライドのように値を保ちたい画面では、ページ内リンクへの移動をアプリの側で止めます。