Реализация пагинации на сайте

Реализация пагинации на сайте

Пагинация делит большой набор данных на страницы фиксированного размера. Это базовый элемент любого сайта с каталогом, таблицей или лентой публикаций. Реализация включает серверную часть (запросы с LIMIT/OFFSET), API-контракт и UI-компонент навигации.

Серверная часть

// Laravel — стандартный paginate()
public function index(Request $request): JsonResponse
{
    $perPage = min($request->integer('per_page', 20), 100);

    $products = Product::where('is_active', true)
        ->orderByDesc('created_at')
        ->paginate($perPage);

    return response()->json([
        'data'         => ProductResource::collection($products->items()),
        'current_page' => $products->currentPage(),
        'last_page'    => $products->lastPage(),
        'per_page'     => $products->perPage(),
        'total'        => $products->total(),
        'from'         => $products->firstItem(),
        'to'           => $products->lastItem(),
    ]);
}

Запрос к API: GET /api/products?page=3&per_page=20

Под капотом Laravel формирует два SQL-запроса: COUNT(*) для total и SELECT ... LIMIT 20 OFFSET 40. На таблицах свыше 500 000 строк COUNT может тормозить — решается кешированием total или переходом на приблизительный подсчёт через pg_class.reltuples.

UI-компонент пагинации

// components/Pagination.tsx
interface PaginationProps {
  currentPage: number
  lastPage: number
  onPageChange: (page: number) => void
}

export function Pagination({ currentPage, lastPage, onPageChange }: PaginationProps) {
  const pages = buildPageRange(currentPage, lastPage)

  return (
    <nav aria-label="Навигация по страницам">
      <ul className="flex items-center gap-1">
        <li>
          <button
            onClick={() => onPageChange(currentPage - 1)}
            disabled={currentPage === 1}
            aria-label="Предыдущая страница"
          >
            ←
          </button>
        </li>

        {pages.map((page, i) =>
          page === '...' ? (
            <li key={`ellipsis-${i}`} aria-hidden="true">…</li>
          ) : (
            <li key={page}>
              <button
                onClick={() => onPageChange(page as number)}
                aria-current={page === currentPage ? 'page' : undefined}
                className={page === currentPage ? 'font-bold' : ''}
              >
                {page}
              </button>
            </li>
          )
        )}

        <li>
          <button
            onClick={() => onPageChange(currentPage + 1)}
            disabled={currentPage === lastPage}
            aria-label="Следующая страница"
          >
            →
          </button>
        </li>
      </ul>
    </nav>
  )
}

// Формирует массив вида [1, 2, '...', 7, 8, 9, '...', 20]
function buildPageRange(current: number, last: number): (number | '...')[] {
  if (last <= 7) return Array.from({ length: last }, (_, i) => i + 1)

  const delta = 2
  const range: (number | '...')[] = []
  const left = current - delta
  const right = current + delta

  let prev: number | null = null
  for (let i = 1; i <= last; i++) {
    if (i === 1 || i === last || (i >= left && i <= right)) {
      if (prev !== null && i - prev > 1) range.push('...')
      range.push(i)
      prev = i
    }
  }
  return range
}

Синхронизация с URL

Номер страницы должен жить в URL — иначе пользователь теряет позицию при обновлении страницы и не может поделиться ссылкой.

// Next.js App Router
'use client'
import { useRouter, useSearchParams, usePathname } from 'next/navigation'

function usePageParam() {
  const searchParams = useSearchParams()
  const router = useRouter()
  const pathname = usePathname()

  const page = Number(searchParams.get('page') ?? '1')

  const setPage = (newPage: number) => {
    const params = new URLSearchParams(searchParams.toString())
    params.set('page', String(newPage))
    router.push(`${pathname}?${params.toString()}`, { scroll: true })
  }

  return [page, setPage] as const
}

// Vanilla React — history API
function setPageInUrl(page: number) {
  const url = new URL(window.location.href)
  url.searchParams.set('page', String(page))
  window.history.pushState({}, '', url)
}

Prefetch следующей страницы

Чтобы переходы ощущались мгновенными, подгружаем данные следующей страницы заранее:

import { useQueryClient } from '@tanstack/react-query'

function useProductsPrefetch(currentPage: number) {
  const queryClient = useQueryClient()

  useEffect(() => {
    if (currentPage < lastPage) {
      queryClient.prefetchQuery({
        queryKey: ['products', currentPage + 1],
        queryFn: () => fetchProducts(currentPage + 1),
        staleTime: 30_000,
      })
    }
  }, [currentPage])
}

SEO

Для поисковых роботов страницы с пагинацией должны быть корректно связаны:

<!-- На странице /catalog?page=3 -->
<link rel="prev" href="/catalog?page=2" />
<link rel="next" href="/catalog?page=4" />
<link rel="canonical" href="/catalog?page=3" />

Google официально не использует rel=prev/next с 2019 года, но Яндекс — да. В Laravel Blade или Next.js Metadata API выводить эти теги стоит.

Сроки

Базовый компонент с API-интеграцией — 1 день. С URL-синхронизацией, prefetch, SEO-тегами и адаптивным отображением — 2 дня.