ReactとTanStack Queryで「もっと見る」を作る方法

​​React​TanStack Query,TypeScript

商品一覧やコメント欄の下にある「もっと見る」ボタンは、TanStack Query の useInfiniteQuery で作れます。読み込んだページは data.pages に順に積まれ、ボタンでは fetchNextPage を呼ぶだけです。次のページがあるかどうかは hasNextPage で分かるので、その判定を自分で書かずに済みます。

私は検証環境で、猫の一覧を10件ずつ返すサーバーを作り、ボタンを押したときの画面とサーバーが受けたリクエストを記録しました。2ページ目で失敗させたときと、ボタンをダブルクリックしたときの動きも調べています。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。react / react-dom 19.3.1、@tanstack/react-query 5.107.1、@types/react / @types/react-dom 19.3.0、typescript 7.0.2、esbuild 0.28.2 を使いました。.tsx を tsc で型チェックしてから esbuild で本番用のビルドにし、Playwright 1.63.0 の Chromium で開いて操作しました。サーバーは同じマシンで動かした Node.js の検証用のサーバーで、どの応答も 400ms 待ってから返します。StrictMode を付けた開発用のビルド、Chromium 以外のブラウザ、前のページへさかのぼる fetchPreviousPage、1ページ目の取得に失敗したときの表示、人の手の速さでのダブルクリックは試していません。

サーバーは「次はどこから読むか」を返す

検証用のサーバーは、/api/cats?cursor=0 のように読み始める位置を受け取り、10件と、次に読み始める位置 nextCursor を返します。猫は全部で23件なので、3ページ目は3件です。最後のページでは nextCursor を null にします。3ページ目を取得したときの応答です。

text
$ curl -s 'http://localhost:4173/api/cats?cursor=20'
{"items":[{"id":21,"name":"きなこ(21)"},{"id":22,"name":"あずき(22)"},{"id":23,"name":"もも(23)"}],"nextCursor":null}

useInfiniteQuery に渡す取得の関数は次のとおりです。読む位置は、引数の pageParam で受け取ります。signal を fetch に渡しているのは、TanStack Query がクエリを取り消したときに、通信も止めるためです(クエリの取り消しについての公式ガイド)。

ts
export type Cat = { id: number; name: string };
// 1ページ分の応答。次のページがなければ nextCursor は null
export type CatPage = { items: Cat[]; nextCursor: number | null };

export async function fetchCats({
  pageParam,
  signal,
}: {
  pageParam: number;
  signal: AbortSignal;
}): Promise<CatPage> {
  const res = await fetch(`/api/cats?cursor=${pageParam}`, { signal });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

useInfiniteQuery で、一覧とボタンを作る

コンポーネントの全体です。QueryClientProvider で包んで使います。検証では、QueryClient を new QueryClient({ defaultOptions: { queries: { retry: false } } }) で作りました。失敗をすぐ画面に出すためです。公式ガイドの Query Retries のページによると、初期設定では、待つ時間を1秒、2秒と倍にしながら3回まで再試行するので、エラーが出るまでに時間がかかります。

tsx
import { useInfiniteQuery } from '@tanstack/react-query';
import { fetchCats } from './api';

export function CatList() {
  const {
    data,
    error,
    fetchNextPage,
    hasNextPage,
    isPending,
    isFetching,
    isFetchingNextPage,
    isFetchNextPageError,
  } = useInfiniteQuery({
    queryKey: ['cats'],
    queryFn: fetchCats,
    initialPageParam: 0,
    getNextPageParam: (lastPage) => lastPage.nextCursor,
  });

  if (isPending) return <p>読み込み中…</p>;
  // 1ページ目から読めなかったときだけ、一覧の代わりにエラーを出す
  if (data === undefined) return <p role="alert">読み込めませんでした({error?.message})</p>;

  // ページごとの配列を、1つの一覧につなげる
  const cats = data.pages.flatMap((page) => page.items);

  return (
    <>
      <ul>
        {cats.map((cat) => (
          <li key={cat.id}>{cat.name}</li>
        ))}
      </ul>
      {isFetchNextPageError && (
        <p role="alert">続きを読み込めませんでした({error?.message})</p>
      )}
      <button
        type="button"
        onClick={() => fetchNextPage()}
        disabled={!hasNextPage || isFetching}
      >
        {isFetchingNextPage
          ? '読み込み中…'
          : hasNextPage
            ? 'もっと見る'
            : 'これで全部です'}
      </button>
      {isFetching && !isFetchingNextPage && <p>最新の内容に更新中…</p>}
    </>
  );
}

このコードで useQuery と違うのは、次の2つのオプションです。

  • initialPageParam:1ページ目の pageParam。ここでは 0 です。
  • getNextPageParam:最後に読んだページを受け取り、次のページの pageParam を返す関数。

公式ガイドの Infinite Queries のページにあるとおり、getNextPageParam が null か undefined を返すと、hasNextPage は false になります。サーバーの nextCursor をそのまま返せば、最後のページを読んだところで hasNextPage が false になり、disabled の条件でボタンが押せなくなります。

data.pages は、ページごとの応答の配列です。画面に出すときは flatMap で1つの配列につなげます。ボタンの文字は、isFetchingNextPage(次のページを読んでいる間だけ true)と hasNextPage で3通りに切り替えています。

ボタンを2回押したときの画面です(GIF 用のページでは、一覧を2列に並べ、上に件数とクリック回数を出しています)。1回目で20件、2回目で23件になり、最後まで読み終えると「これで全部です」に変わって押せなくなりました。

「もっと見る」を2回押すと、一覧が10件から20件、23件に増え、最後にボタンが「これで全部です」に変わる画面
「もっと見る」を2回押して、最後のページまで読む様子

同じ操作を Playwright で記録したときの、サーバーが受けたリクエストです。ボタンを押すたびに、次の位置から1回ずつ読んでいます。

text
サーバー:
      0ms  cursor=0  200
    981ms  cursor=10  200
   1708ms  cursor=20  200

2ページ目で失敗しても、一覧を消さない

公式ガイドの例は、status === 'error' のときにエラーだけを表示する書き方です。この書き方のまま、サーバーが2ページ目(cursor=10)の1回目だけ 500 を返すようにしたところ、読み終えていた10件も消えて、エラーの文だけになりました。

tsx
if (status === 'pending') return <p>読み込み中…</p>;
if (status === 'error') return <p role="alert">読み込めませんでした({error.message})</p>;
text
   1037ms  10件 最後=あずき(10) ボタン「読み込み中…」(押せない)
   1436ms  0件 最後=- ボタンなし 「読み込めませんでした(HTTP 500)」

次のページの取得に失敗すると、data に1ページ目が残っていても、status は 'error' になります。useInfiniteQuery のリファレンスでは、status の error は「クエリの取得がエラーになった」ときの値と説明されています。ページが残っているかどうかは、この値の条件に入っていません。

そこで、前の節の CatList では、一覧の代わりにエラーを出すのを「data がまだないとき」だけにしました。次のページで失敗したことは、isFetchNextPageError で見分けて、一覧の下に出します。同じ条件で試したところ、10件を残したまま「続きを読み込めませんでした(HTTP 500)」が出ました。ボタンはもう一度押せる状態に戻りました。サーバーは2回目には正しく返すので、押し直すと2ページ目を読めました。

text
   1430ms  10件 最後=あずき(10) ボタン「もっと見る」(押せる) 「続きを読み込めませんでした(HTTP 500)」
  ---- 「もっと見る」を押す(2回目)
   1770ms  click がボタンに届いた(表示は「もっと見る」)
   1782ms  10件 最後=あずき(10) ボタン「読み込み中…」(押せない) 「続きを読み込めませんでした(HTTP 500)」
   2177ms  20件 最後=こむぎ(20) ボタン「もっと見る」(押せる)

画面が変わる前に2回押すと、同じページを2回取りに行く

ボタンには disabled={!hasNextPage || isFetching} を付けています。それでも、Playwright でボタンをダブルクリックすると、2回の click がどちらもボタンに届きました。2回の click の間は約2msで、ボタンが押せない表示に変わったのは、2回目の click のあとです。

text
  ---- ボタンをダブルクリックする
   1029ms  click がボタンに届いた(表示は「もっと見る」)
   1031ms  click がボタンに届いた(表示は「もっと見る」)
   1035ms  10件 最後=あずき(10) ボタン「読み込み中…」(押せない)
   1441ms  20件 最後=こむぎ(20) ボタン「もっと見る」(押せる)
サーバー:
      0ms  cursor=0  200
    967ms  cursor=10  aborted
    974ms  cursor=10  200

サーバーには cursor=10 のリクエストが2回届き、1回目は途中で切られていました。fetchNextPage は、取得中にもう一度呼ばれると、初期設定(cancelRefetch: true)では進行中の取得を取り消してから取り直します。signal を fetch に渡しているので、取り消された1回目の通信も止まりました。一覧は20件で、同じ猫が2回並ぶことはありませんでした。

同じページへの余計なリクエストを送りたくないなら、fetchNextPage に { cancelRefetch: false } を渡します。こうすると、取得中にもう一度呼んでも、進行中の取得は取り消されません。新しく取り直さず、進行中の取得の結果をそのまま使います。

tsx
onClick={() => fetchNextPage({ cancelRefetch: false })}

同じようにダブルクリックしたところ、サーバーが受けた cursor=10 のリクエストは1回だけでした。

text
サーバー:
      0ms  cursor=0  200
    963ms  cursor=10  200

読み直すときは、1ページ目から順に全部取り直す

3ページ目まで読んだあとで queryClient.invalidateQueries({ queryKey: ['cats'] }) を呼ぶと、3ページ分が1ページ目から順に取り直されました。前のページの応答が届いてから、次のページを取りに行っています。

text
   2389ms  cursor=0  200
   2793ms  cursor=10  200
   3198ms  cursor=20  200

公式ガイドによると、これは次のページの位置を古い応答から決めないための動きです。途中でデータが変わっても、重複や抜けが起きにくくなります。そのかわり、読んだページが多いほど、読み直しに時間がかかります。検証では、1ページ 400ms のサーバーで、3ページの読み直しに約1.2秒かかりました。その間は isFetching が true なので、「最新の内容に更新中…」が出ていました。

何十ページも読む一覧なら、maxPages で data.pages に残すページ数を絞れます。公式ガイドでは、maxPages: 3 のときは読み直しも3ページ分だけになると説明されています。ガイドの例では、data.pages から外れたページを読み戻せるよう、前のページの位置を返す getPreviousPageParam も一緒に指定しています。

​Posted by 86