Sayfalama ve sonsuz liste

Sayfa Sayfa Listelemek

Sayfalama ek bir API gerektirmez: sayfa numarasını query key'e koyarsınız.¹

export const productQueries = {
  // ...
  page: (page: number) =>
    queryOptions({
      queryKey: ["products", "list", { page }],
      queryFn: () => fetchProductPage(page), // { items, hasMore }
    }),
};

Bu haliyle çalışır ama her sayfa yeni bir sorgudur. "Sonraki"ye bastığınızda liste kaybolur, yükleme ekranı gelir, sonra yeni sayfa görünür. Ekran her sayfada zıplar.¹

keepPreviousData

placeholderData: keepPreviousData verirseniz yeni sayfa gelene kadar önceki sayfa ekranda kalır:¹

import { keepPreviousData, useQuery } from "@tanstack/react-query";

function ProductTable() {
  const [page, setPage] = useState(1);
  const { data, isPending, isError, error, isFetching, isPlaceholderData } = useQuery({
    ...productQueries.page(page),
    placeholderData: keepPreviousData,
  });

  if (isPending) return <p>Yükleniyor...</p>;
  if (isError) return <p>Hata: {error.message}</p>;

  return (
    <>
      <ul style={{ opacity: isPlaceholderData ? 0.5 : 1 }}>
        {data.items.map((product) => <li key={product.id}>{product.name}</li>)}
      </ul>
      <button onClick={() => setPage((p) => p - 1)} disabled={page === 1}>
        Önceki
      </button>
      <span>Sayfa {page}</span>
      <button
        onClick={() => setPage((p) => p + 1)}
        disabled={isPlaceholderData || !data.hasMore}
      >
        Sonraki
      </button>
      {isFetching && <span> Güncelleniyor...</span>}
    </>
  );
}

isPlaceholderData, ekrandaki verinin önceki sayfadan kaldığını söyler. Yeni sayfa gelene kadar "Sonraki"yi kapatmak ve listeyi soluklaştırmak için kullanın.¹ keepPreviousData aslında (previousData) => previousData fonksiyonudur; placeholderData kendisi cache'e yazılmaz (bkz. Cache ve stale time).

Kullanıcı büyük ihtimalle sonraki sayfaya geçecek. Bir sonraki sayfayı arka planda yükleyin ki tıkladığında hazır olsun:²

const queryClient = useQueryClient();

useEffect(() => {
  if (!isPlaceholderData && data?.hasMore) {
    void queryClient.query(productQueries.page(page + 1)).catch(noop);
  }
}, [data, isPlaceholderData, page, queryClient]);

Sayfa numarasını useState yerine URL'de (?page=2) tutarsanız sayfa paylaşılabilir olur ve tarayıcının geri butonu çalışır. Anahtar aynı kalır; değişen yalnızca değerin nereden okunduğudur.³

Sonsuz Liste

"Daha fazla yükle" butonu ya da kaydırınca yüklenen listeler için useInfiniteQuery var. Tek farkı, verinin sayfalardan oluşan bir yapı olmasıdır:⁴

import { infiniteQueryOptions } from "@tanstack/react-query";

export const reviewQueries = {
  infinite: (productId: number) =>
    infiniteQueryOptions({
      queryKey: ["reviews", productId, "infinite"],
      queryFn: ({ pageParam }) => fetchReviews(productId, pageParam), // { items, nextCursor }
      initialPageParam: 0,
      getNextPageParam: (lastPage) => lastPage.nextCursor,
    }),
};

function Reviews({ productId }: { productId: number }) {
  const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage, status } =
    useInfiniteQuery(reviewQueries.infinite(productId));

  if (status === "pending") return <p>Yükleniyor...</p>;
  if (status === "error") return <p>Yorumlar yüklenemedi.</p>;

  return (
    <>
      {data.pages.flatMap((page) => page.items).map((review) => (
        <p key={review.id}>{review.text}</p>
      ))}
      <button
        onClick={() => fetchNextPage()}
        disabled={!hasNextPage || isFetching}
      >
        {isFetchingNextPage ? "Yükleniyor..." : hasNextPage ? "Daha fazla" : "Hepsi bu kadar"}
      </button>
    </>
  );
}

Butonu isFetching sürerken kapatmak önemlidir. Bir sonsuz listede aynı anda tek bir istek olabilir; tüm sayfalar tek cache girdisini paylaşır. Arka plan yenilemesi sürerken fetchNextPage çağırmak veriyi ezebilir.⁴ Kaydırınca yüklemek için butonu bir IntersectionObserver ile tetiklerken de aynı kontrolü yapın: hasNextPage && !isFetching && fetchNextPage().⁴

Sonsuz Liste Nasıl Yenilenir

Sonsuz liste cache'te tek bir sorgudur; sayfalar birbirine bağlı bir liste gibi durur. Her sayfa bir öncekinden aldığı parametreyle getirilir.⁵ Bu yüzden liste eskiyip yenilendiğinde sayfalar ilk sayfadan başlayarak sırayla yeniden çekilir. Böylece arada eklenen ya da silinen kayıtlar yüzünden eski cursor'larla tekrar eden ya da atlanan kayıt oluşmaz.⁴⁵

Bunun bedeli var: kullanıcı yirmi sayfa yüklediyse yenileme yirmi istek demektir. maxPages cache'te tutulan sayfa sayısını sınırlar. Bunu kullanırsanız iki yönde de gezinebilmek için getPreviousPageParam da vermeniz gerekir:⁴

infiniteQueryOptions({
  // ...
  getPreviousPageParam: (firstPage) => firstPage.prevCursor,
  maxPages: 3,
});

API cursor döndürmüyorsa getNextPageParam üçüncü argüman olarak son sayfanın parametresini alır; lastPageParam + 1 ile sayfa numarasını kendiniz hesaplarsınız.⁴

Hangisi

Binlerce satırı DOM'da tutmak sorgudan bağımsız bir sorundur; sanallaştırma için Render performansı dersine bakın.

Kendin Dene

• Ürün tablosunu keepPreviousData olmadan yazın, sayfalar arasında geçin. Sonra ekleyin; farkı not edin.

• Sonraki sayfayı önceden yükleyin ve Network sekmesinde ne zaman istek gittiğini izleyin.

• Yorumlara sonsuz liste ekleyin. Üç sayfa yükleyin, sekmeden çıkıp dönün; kaç istek gidiyor ve hangi sırayla?

• maxPages: 2 verip tekrar deneyin.

Detaylı Öğrenmek İçin

• Resmi doküman: "Infinite Queries"; iki yönlü liste, sayfaları elle güncelleme ve maxPages.⁴

• Yazı: TkDodo, "How Infinite Queries work"; sonsuz sorgunun cache'teki yapısı ve yenileme davranışı.⁵

• Resmi doküman: "Paginated / Lagged Queries"; placeholderData ve isPlaceholderData.¹