ServerTable

ServerTable — обёртка над Table для постраничных данных с бэкенда. Страница данных приходит снаружи (items / total / limit / offset), смена страницы, поиск и сортировка делегируются серверу: компонент вызывает onChangePage, search.onChange и sorting.onChange, а отрисовывает то, что передано в пропсах.

Для типовых серверных сценариев есть preset-ы ServerSimpleTable и ServerAdminTable (см. обзор пакета) — они маппят упрощённый API в ServerTable, как SimpleTable / AdminTable маппят в Table.

Когда использовать

• Данные приходят с бэкенда постранично, известно общее количество строк (total).
• Поиск и сортировка выполняются на сервере, а не на клиенте.
• Объём данных слишком велик для загрузки на клиент целиком.

Когда не нужен:

• Данные загружены на клиент целиком:
  • используйте Table или SimpleTable — пагинация, поиск и сортировка работают локально.

Рекомендации по выбору API:

• Простой серверный список (колонки + пагинация) — ServerSimpleTable.
• Админ-экран с поиском, статусом, выбором и действиями — ServerAdminTable.
• Нестандартные колонки, фильтры или поведение тулбара — ServerTable напрямую.

Анатомия

Постраничная загрузка (default limit 10, offset 0)

• items — строки текущей страницы.
• total — общее количество строк; по нему рассчитывается число страниц.
• limit / offset — размер страницы и смещение текущей страницы.
• onChangePage(offset, limit) — вызывается при смене страницы или размера страницы; здесь выполняется запрос новой страницы.
• pagination.options / pagination.optionsLabel — варианты числа строк на страницу и подпись к ним.

Поиск (controlled)

• search.state и search.onChange обязательны — значение поиска хранится снаружи, в отличие от Table.
• search.loading — индикатор загрузки в строке поиска.
• search.initialValue — начальное значение.
• Ввод дебаунсится внутри компонента (500 мс, отдельный таймер на каждый инстанс) — onChange получает значение после паузы ввода. При смене запроса обычно сбрасывают offset в 0.

Серверная сортировка

• По умолчанию включён manualSorting — таблица не сортирует items на клиенте.
• Передайте управляемый sorting.state + sorting.onChange; при смене сортировки запросите новую страницу и сбросьте offset в 0.
• Колонки с enableSorting: true отображают индикатор сортировки; фактическое упорядочивание выполняет бэкенд.

Интеграция с бэкендом

Типичный контракт на стороне приложения:

1. Хранить items, total, loading, offset, limit, search, sorting в state.
2. В useEffect (или data-fetch хуке) запрашивать страницу при изменении offset / limit / search / sorting.
3. В onChangePage обновлять offset и limit; в search.onChange и sorting.onChange — сбрасывать offset в 0.
4. При параллельных запросах отбрасывать устаревшие ответы (счётчик requestId / AbortController) — иначе медленный ответ может перезаписать актуальные данные.
5. Пробрасывать loading в ServerTable и в search.loading на время запроса.

Отличия от Table

• Данные передаются через items (вместо data) — только текущая страница.
• Вырезаны pageSize, pageCount, pagination.state, toolbarCheckBoxMode — пагинацией управляет бэкенд через limit / offset / total.
• Серверная сортировка — manualSorting + управляемый sorting.state / onChange.
• Остальное API — колонки, служебные колонки, выбор строк, дерево, режим карточек, тулбар — наследуется от Table.

Установка

pnpm add @cloud-ru/ds-table

import { ServerTable } from '@cloud-ru/ds-table'

Примеры использования

Серверный сценарий

import { ColumnDefinition, ServerTable, SortingState } from '@cloud-ru/ds-table';
import { useEffect, useRef, useState } from 'react';

type User = {
  id: string;
  name: string;
  email: string;
  role: string;
  balance: number;
};

const NAMES = [
  'Анна Иванова',
  'Борис Петров',
  'Вера Сидорова',
  'Глеб Кузнецов',
  'Дарья Орлова',
  'Егор Морозов',
  'Жанна Волкова',
  'Захар Соколов',
];

const ROLES = ['Owner', 'Admin', 'Editor', 'Viewer'];

const ALL_USERS: User[] = Array.from({ length: 23 }, (_, index) => ({
  id: `u-${index + 1}`,
  name: NAMES[index % NAMES.length],
  email: `user-${index + 1}@example.com`,
  role: ROLES[index % ROLES.length],
  balance: (index * 1730) % 20000,
}));

function compareUsers(a: User, b: User, columnId: string, desc: boolean): number {
  const left = a[columnId as keyof User];
  const right = b[columnId as keyof User];
  const order =
    typeof left === 'number' && typeof right === 'number' ? left - right : String(left).localeCompare(String(right));

  return desc ? -order : order;
}

type PageResponse = {
  items: User[];
  total: number;
};

// Имитация бэкенда: фильтрация по имени, сортировка и срез по offset/limit с задержкой.
function fetchUsers(offset: number, limit: number, query: string, sorting: SortingState): Promise<PageResponse> {
  return new Promise(resolve => {
    setTimeout(() => {
      const filtered = query
        ? ALL_USERS.filter(user => user.name.toLowerCase().includes(query.toLowerCase()))
        : ALL_USERS;
      const sortRule = sorting[0];
      const sorted = sortRule ? [...filtered].sort((a, b) => compareUsers(a, b, sortRule.id, sortRule.desc)) : filtered;

      resolve({ items: sorted.slice(offset, offset + limit), total: sorted.length });
    }, 400);
  });
}

const columns: ColumnDefinition<User>[] = [
  { accessorKey: 'name', header: 'Имя', enableSorting: true, size: 200 },
  { accessorKey: 'email', header: 'Email', size: 240 },
  { accessorKey: 'role', header: 'Роль', size: 140 },
  { accessorKey: 'balance', header: 'Баланс', align: 'right', headerAlign: 'right', enableSorting: true, size: 140 },
];

export function ServerDriven() {
  const [items, setItems] = useState<User[]>([]);
  const [total, setTotal] = useState(0);
  const [loading, setLoading] = useState(false);
  const [offset, setOffset] = useState(0);
  const [limit, setLimit] = useState(5);
  const [search, setSearch] = useState('');
  const [sorting, setSorting] = useState<SortingState>([]);
  const requestId = useRef(0);

  useEffect(() => {
    const currentRequest = ++requestId.current;

    setLoading(true);
    fetchUsers(offset, limit, search, sorting).then(response => {
      // Ответы устаревших запросов отбрасываются — состояние обновляет только последний.
      if (currentRequest !== requestId.current) {
        return;
      }

      setItems(response.items);
      setTotal(response.total);
      setLoading(false);
    });
  }, [offset, limit, search, sorting]);

  return (
    <ServerTable
      items={items}
      total={total}
      limit={limit}
      offset={offset}
      loading={loading}
      columnDefinitions={columns}
      onChangePage={(nextOffset, nextLimit) => {
        setOffset(nextOffset);
        setLimit(nextLimit);
      }}
      search={{
        state: search,
        placeholder: 'Поиск по имени',
        loading,
        onChange: value => {
          setOffset(0);
          setSearch(value);
        },
      }}
      sorting={{
        state: sorting,
        onChange: nextSorting => {
          setOffset(0);
          setSorting(nextSorting);
        },
      }}
      manualSorting
      pagination={{ options: [5, 10] }}
      outline
    />
  );
}

Props

Types

ServerTableProps

ColumnDefinition

EmptyStateProps

Except

RowClickHandler

TableLayoutDefaults

TreeColumnDefinitionProps

Unions

View

Related props

FilterRow

LayoutPresets

Storybook

Figma

Смотри также

• Обзор пакета — ServerSimpleTable, ServerAdminTable и выбор компонента.
• Table — клиентская таблица для данных, загруженных целиком.
• SimpleTable — клиентский аналог ServerSimpleTable.
• AdminTable — клиентский аналог ServerAdminTable.