はじめる
商品一覧の絞り込みをURLに置く例で、@k8ordo/stateの使い方をたどります。状態を1つ定義して、コンポーネントで読み書きするところまで進みます。
このページの内容
インストール
npm install @k8ordo/state zod次の環境で動きます。
- React 19.3以上
- TypeScriptで書くなら、TypeScript 7以上
エージェント向けのガイドはnode_modules/@k8ordo/state/docs/GUIDE.mdに入っています。AGENTS.mdなどからこのパスを参照させてください。
ブラウザでは、URLの書き換えにNavigation APIを使います。polyfillもフォールバックもありません。
メモ
このページの例はzodで書いていますが、zod/miniでも動きます。選び方は置き場所の「zod/mini」の節を見てください。
状態の定義
src/state.tsimport { definePageState } from '@k8ordo/state';
import * as z from 'zod';
export const listState = definePageState('product-list', {
この状態の名前。アプリの中で重ならないものを付ける
url: z.object({
inStock: z.stringbool().default(false),
page: z.coerce.number().int().min(1).default(1),
}),
});リンクを共有したときに同じ一覧が開くように、絞り込みはURLに置きます。URLに置く状態は、definePageStateのurlにスキーマで書きます。
URLのパラメータは欠けることがあるので、どのフィールドにも.default()を付けます。パラメータの値は文字列です。数値はz.coerce.number()で、真偽値はz.stringbool()で受けます。
定義は'use client'の無いモジュールに書き、Server ComponentとClient Componentの両方からimportします。'use client'のファイルからexportすると、Server Componentにはclient referenceが渡り、hrefを呼べません。
フックでの読み書き
src/components/filters.tsx'use client';
import { useAppState } from '@k8ordo/state';
import { listState } from '../state';
export function Filters() {
const [{ inStock, page }, update] = useAppState(listState);
return (
<div>
<label>
<input
checked={inStock}
onChange={(event) => {
update({ inStock: event.target.checked, page: 1 });
今の履歴エントリを書き換える
}}
type="checkbox"
/>
In stock only
</label>
<button
onClick={() => {
update({ page: page + 1 }, { history: 'push' });
新しい履歴エントリを追加する
}}
type="button"
>
Next page
</button>
</div>
);
}Client ComponentでuseAppStateに定義を渡すと、現在の値とupdateが返ります。updateは値を変える関数です。
update()に渡した値は次の描画に反映され、URLへの書き込みはそのあとに行われます。書き込みのまとめ方や待ち方は更新を見てください。
update()は既定では今の履歴エントリを書き換えます。ページ送りには{ history: 'push' }を付けているので、ブラウザの戻るボタンで前のページに戻れます。
絞り込みのデモ
このページのURLを実際に書き換えるdefinePageStateです。
- デスクライト在庫あり
- 木の椅子売り切れ
- クエリ
クエリなし(すべて既定値)
試してみる
- 「在庫があるものだけ」にチェックを入れると、クエリが
?inStock=trueになり、在庫のある商品だけが並びます。 - 「次のページ」を押すと、クエリに
page=2が足されます。そのあとブラウザの戻るボタンを押すと、1ページ目に戻ります。 - チェックを外すと、クエリから
inStockが消えます。falseは既定値なので、URLには書かれません。