更新
useAppStateが返すupdate()は、どの置き場所でも同じ書き方で状態を変えます。値が画面に反映される時点と置き場所に書き込まれる時点を知り、それに合わせた書き方ができるようになります。
このページの内容
変えるフィールドだけ
const [{ inStock, page }, update] = useAppState(listState);
update({ inStock: true, page: 1 });update()には、変えるフィールドだけのオブジェクトを渡します。渡さなかったフィールドは今の値のまま残ります。
渡した値はその場で状態に入り、次の描画に反映されます。置き場所への書き込みはそのあとに行われるので、画面がURLやストレージの書き込みを待つことはありません。
定義に無いフィールドは型エラーになります。型チェックを通さずに渡すと、"product-list" has no field "sort"のようなTypeErrorになります。
書き込みの検証
update({ page: 0 });
`page`が`.min(1)`なら、既定値の`1`になるupdate()は、まとめた状態をスキーマに通してから次の描画に反映します。urlのフィールドはURLから読むときと同じ手順で検証されるので、update({ page: 0 })は?page=0を開いたときと同じ結果になります。
URLで表せない値を渡すと、update()の呼び出しそのものがhas no URL serializationで終わるTypeErrorになります。何も書き込まれません。
メモリの状態にはスキーマが無いので、渡した値がそのまま入ります。
replaceとpush
update({ inStock: true, page: 1 });
今の履歴エントリを書き換える
update({ page: page + 1 }, { history: 'push' });
新しい履歴エントリを追加するupdate()は、既定では今の履歴エントリを書き換えます。ブラウザの戻るで取り消したい更新にだけ、{ history: 'push' }を付けます。ページ送りがその例です。
このオプションはdefinePageStateのupdate()にだけあり、urlの値が変わるときにだけ効きます。entryの値だけを変える更新は、今の履歴エントリをその場で書き換えます。同じバッチで1回でもpushを指定すれば、そのバッチの遷移はpushになります。
ページを移るときは、@k8ordo/routerのnavigateToを使います。こちらは既定でpushです。
書き込みのまとめ
const clear = () => {
update({ inStock: false });
update({ page: 1 });
};同じハンドラの中で続けて呼んだupdate()は、ReactのsetStateと同じように1回にまとまります。上の2回の呼び出しも、書き込みは1回です。
1回の書き込みが何になるかは、置き場所と変わった値で決まります。
urlの値が変わるとき:navigation.navigate()を1回。entryの変更も一緒に書き込みます。entryの値だけが変わるとき:navigation.updateCurrentEntry()を1回。- localStorageとsessionStorage:
setItemを1回。 - Cookie:
cookieStore.set()を1回。 - メモリ:まとめません。呼ぶたびにその場で置き換え、呼ぶたびに解決済みのハンドルを返します。
スライダーのようにハンドラをまたいで続けて書くときは、URLへの書き込みが間引かれます。URLの値を変えるreplaceの書き込みは、前の書き込みから100msたつまで待ち、そのあいだのupdate()を1回の遷移にまとめます。画面の値はupdate()のたびにすぐ変わります。WebKitが同じ文書への遷移を10秒に200回までしか通さないためです。{ history: 'push' }の書き込みは待ちません。
ページの状態のバッチの結果が今の値と同じなら、遷移も履歴エントリの書き換えも起きません。localStorageとsessionStorage、Cookieは、値が変わらなくても保存した値を書き直します。ほかの定義やルーターのパラメータが残る仕組みは仕組みを見てください。
committedとfinished
const { committed, finished } = update({ page: 2 });update()は、navigation.navigate()と同じ形の、2つのPromiseを持つオブジェクトを返します。Promiseそのものではないので、無視してもno-floating-promisesのlintには掛かりません。無視するのが普通の使い方です。
committed:書き込みが置き場所に入ったときに解決します。finished:書き込みのあとにルーターが行う処理まで終わったときに解決します。
書き込みを待つときはfinishedを待ちます。下の例では、ページ送りのあとに見出しへフォーカスを移しています。
pager.tsxconst heading = useRef<HTMLHeadingElement>(null);
const onNext = async () => {
await update({ page: page + 1 }, { history: 'push' }).finished;
heading.current?.focus();
};遷移を伴わない書き込みのハンドルは、バッチを書き込んだ時点で解決します。Cookieは、Cookie Store APIが書き終えた時点です。ハンドルがrejectするのは次の2つの場合です。
- あとから来た遷移に追い越された遷移:
AbortError。たとえば同じハンドラで別のページの状態も書いたときです。間引かれて待っているあいだにページを離れた書き込みも、書かれずにAbortErrorになります。ハンドルを待たなければ気づくことはありません。 - localStorage、sessionStorage、Cookieへの書き込みの失敗:その書き込みのエラーでrejectします。容量の上限やサイトのデータの保存を止めたブラウザ、4KBを超えるCookie、書き込む値でスキーマが例外を出したときです。描画した値はそのまま残ります。
メモ
非同期のアクションの中でも同じように待てます。startTransition(async …)やuseTransition、@k8ordo/uiのButtonのonActionがそうです。ただし@k8ordo/routerの下では、別のページを読み込んでいる最中のurlの更新はページの切り替えになります。そのfinishedは、アクションの終わりを待たずに、そのページが表示された時点で解決します。
関数形式の更新
update((current) => ({ page: current.page + 1 }));今の値を元に次の値を作るときは、update()に関数を渡します。関数が受け取るのは、同じバッチでまだ書き込まれていない更新も反映した状態です。
描画で読んだpageを使ってupdate({ page: page + 1 })を同じハンドラで2回呼ぶと、1つしか増えません。関数で書けば2つ増えます。
キーの購読
useAppState(listState);
どのフィールドが変わっても再描画
useAppState(listState, ['page']);
`page`が変わったときだけ再描画
useAppState(listState, []);
何も購読しない(書き込み専用)
useAppState(listState, ['page'], { initialUrl });
オプションはキーの配列のあとuseAppStateの2つ目の引数にキーの配列を渡すと、そのキーが変わったときだけ再描画されます。配列はインラインで書いてかまいません。内部で正規化してから比べるので、useMemoは要りません。
変わらなかったフィールドは前と同じ参照を保つので、memoや依存配列にそのまま渡せます。フィールドの比べ方は仕組みを見てください。
更新の頻度が大きく違う状態は、定義を分けます。再描画は定義の単位で決まるからです。
入力中の値
search-box.tsxexport function SearchBox() {
const [{ q }, update] = useAppState(catalogState, ['q']);
return (
<form
onSubmit={(event) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
update({ q: String(data.get('q') ?? ''), page: 1 });
}}
>
<input defaultValue={q} key={q} name="q" type="search" />
<button type="submit">Search</button>
</form>
);
}キーを押すたびにupdate()を呼ぶと、URLの書き換えも1文字ごとに起きます。入力中の値はDOMかReactのローカルな状態に持たせ、送信やページ送りの区切りでupdate()を呼びます。
key={q}は、戻るボタンなどで外からqが変わったときに、入力欄を新しいdefaultValueで作り直します。
JavaScriptが読み込まれる前から動かすなら、GETフォームでURLを書き換えます。@k8ordo/formと組み合わせる書き方は「検索フォーム」にあります。
落とし穴
定義の値をuseStateに写して同期させないでください。写した値は、戻るボタンやほかのタブの書き込みで更新されません。値が要るところでuseAppStateを呼びます。
書き込みの記録
このページのURLと履歴エントリを実際に書き換えるdefinePageStateで、aとbはURLに、cは履歴エントリに置いています。
useAppState(def){ a: 0, b: 0, c: 0 }描画回数useAppState(def, ['a']){ a: 0 }描画回数useAppState(def, ['b']){ b: 0 }描画回数
試してみる
- 「a + 1」を押すと、記録に
navigate · replaceで始まる行が1つ足されます。続けて「a + 1を3回」を押すと、aは3増えますが、足される行は1つだけです。 - 「c + 1」を押すと、URLは変わらず、記録には
updateCurrentEntryが足されます。 - 「b + 1」を押すと、
['a']を購読している行の描画回数は増えず、ほかの2行だけが増えます。 - 「a = -1」を押すと、
aは既定値の0になります。スキーマが負の数を拒むからです。 - 「a + 1(push)」を押してから、ブラウザの戻るを押します。
aが1つ前の値に戻ります。