# IndexedSnapScroller
## Кратко
`IndexedSnapScroller` — [составной компонент](https://vega-ui.dev/ru/docs/glossary/#составной-компонент-compound-component) на основе `SnapScroller` для виртуализированного постраничного пролистывания по окну индексов. Он поддерживает скользящую последовательность логических индексов и может сдвигать окно, когда пользователь доходит до границы прокрутки.
## Импорт
```tsx
import {
IndexedSnapScroller,
IndexedSnapScrollerContent,
type IndexedSnapScrollerApiRef,
type IndexedSnapScrollerContentProps,
type IndexedSnapScrollerProps,
} from '@vega-ui/react';
```
## Экспортируемые типы
- `IndexedSnapScrollerProps`
- `IndexedSnapScrollerContentProps`
- `IndexedSnapScrollerApiRef`
## Минимальная композиция
```tsx
import {
IndexedSnapScroller,
IndexedSnapScrollerContent,
useIndexedSnapScrollerContext,
} from '@vega-ui/react';
const today = new Date();
const monthFormat = new Intl.DateTimeFormat('en-US', { month: 'long', year: 'numeric' });
function MonthPage() {
const { index } = useIndexedSnapScrollerContext();
const month = new Date(today.getFullYear(), today.getMonth() + index, 1);
return (
{monthFormat.format(month)}
);
}
export default function MinimalComposition() {
return (
);
}
```
## Обязательные части
- `IndexedSnapScroller`: корневая система постраничного пролистывания по индексам
- `IndexedSnapScrollerContent`: содержимое страницы, привязанное к текущему виртуальному индексу
## Необязательные части
- `apiRef` для императивного управления окном индексов
## Порядок композиции
1. `IndexedSnapScroller`
2. один дочерний шаблон `IndexedSnapScrollerContent`
## Варианты
- Контролируемый логический `index`
- Неконтролируемое пролистывание по окну с `defaultIndex`
- Настраиваемые `size`, `shift`, `start` и `startDir`
## Пограничные случаи
- Контролируемый `index` и сбросы виртуального окна должны оставаться синхронизированными.
- `preserveScroll` меняет ощущение от сдвигов окна индексов.
- Дочерние элементы рендерятся заново для каждого виртуального индекса, поэтому состояние с ключами внутри содержимого страницы должно быть продуманным.
## Частые ошибки
- Предположение, что порядок дочерних элементов статичен, хотя виртуальное окно сдвигается.
- Забывают, что один шаблон содержимого рендерится несколько раз с разными индексами в контексте.
- Внешняя логика контролируемого индекса смешивается с самодельными предположениями о внутреннем смещении.
## Примеры
### Базовый
#### Базовый: бесконечная лента недель
Один шаблон `WeekPage` рендерится для каждого индекса окна и читает свой индекс из `useIndexedSnapScrollerContext`; индекс 0 — текущая неделя. Вычисления дат живут в компоненте страницы, скроллер только сообщает индекс.
```tsx
import {
IndexedSnapScroller,
IndexedSnapScrollerContent,
Text,
useIndexedSnapScrollerContext,
} from '@vega-ui/react';
import type { CSSProperties } from 'react';
const today = new Date();
const daysSinceMonday = (today.getDay() + 6) % 7;
const weekdayFormat = new Intl.DateTimeFormat('en-US', { weekday: 'short' });
const weekFormat = new Intl.DateTimeFormat('en-US', { month: 'long', day: 'numeric' });
function WeekPage() {
const { index } = useIndexedSnapScrollerContext();
const days = Array.from({ length: 7 }, (_, day) => (
new Date(today.getFullYear(), today.getMonth(), today.getDate() - daysSinceMonday + index * 7 + day)
));
return (
{days.map((day) => {
const isToday = day.toDateString() === today.toDateString();
return (
{weekdayFormat.format(day)}
{day.getDate()}
);
})}
);
}
export default function WeekStrip() {
return (
);
}
```
### Контролируемый/с состоянием
#### Контролируемый/с состоянием: заголовок месяца с внешними контролами
`index` хранится в родителе, а `onScrollSnapChange` записывает в него итоговый индекс. Стрелки вызывают `apiRef.next()` и `prev()` для плавного шага; **+1 year** и **This month** задают `index` напрямую — окно перестраивается вокруг цели за его пределами, и переход происходит без анимации.
```tsx
import {
Button,
Icon,
IconButton,
IndexedSnapScroller,
IndexedSnapScrollerContent,
Text,
useIndexedSnapScrollerContext,
type IndexedSnapScrollerApiRef,
} from '@vega-ui/react';
import { ChevronLeft, ChevronRight } from '@vega-ui/icons';
import { useRef, useState } from 'react';
const today = new Date();
const monthFormat = new Intl.DateTimeFormat('en-US', { month: 'long', year: 'numeric' });
function countWorkingDays(year: number, month: number) {
const daysInMonth = new Date(year, month + 1, 0).getDate();
let count = 0;
for (let day = 1; day <= daysInMonth; day++) {
const weekday = new Date(year, month, day).getDay();
if (weekday !== 0 && weekday !== 6) count++;
}
return count;
}
function MonthPage() {
const { index } = useIndexedSnapScrollerContext();
const month = new Date(today.getFullYear(), today.getMonth() + index, 1);
const daysInMonth = new Date(month.getFullYear(), month.getMonth() + 1, 0).getDate();
return (
{monthFormat.format(month)}
{daysInMonth} days, {countWorkingDays(month.getFullYear(), month.getMonth())} working days
);
}
export default function ControlledVirtualIndex() {
const api = useRef(null);
const [index, setIndex] = useState(0);
return (
api.current?.prev()}>
api.current?.next()}>
setIndex(next)}
style={{ gap: 'var(--spacing-6)' }}
>
index = {index}
);
}
```
### Форма/интеграция
#### Форма/интеграция: день доставки в форме
В DOM есть только страницы текущего окна, поэтому выбранный день нельзя хранить в странице: он лежит в состоянии формы и отправляется через скрытое поле, которое читается через `FormData`. Отправка без выбранного дня показывает `HelperText`, связанный с группой через `aria-describedby`; прошедшие дни и воскресенья — отключённые кнопки, а сброс очищает значение и возвращает к текущей неделе через `setIndexTo(0)`.
```tsx
import {
Button,
HelperText,
Icon,
IconButton,
IndexedSnapScroller,
IndexedSnapScrollerContent,
Text,
useIndexedSnapScrollerContext,
type IndexedSnapScrollerApiRef,
} from '@vega-ui/react';
import { ChevronLeft, ChevronRight } from '@vega-ui/icons';
import { useRef, useState, type FormEvent } from 'react';
const today = new Date();
const todayStart = new Date(today.getFullYear(), today.getMonth(), today.getDate());
const daysSinceMonday = (today.getDay() + 6) % 7;
const weekdayFormat = new Intl.DateTimeFormat('en-US', { weekday: 'short' });
const fullDateFormat = new Intl.DateTimeFormat('en-US', { weekday: 'long', month: 'long', day: 'numeric' });
function toIsoDate(date: Date) {
const month = String(date.getMonth() + 1).padStart(2, '0');
const day = String(date.getDate()).padStart(2, '0');
return `${date.getFullYear()}-${month}-${day}`;
}
interface WeekPageProps {
selected: string
onSelect(value: string): void
}
function WeekPage({ selected, onSelect }: WeekPageProps) {
const { index } = useIndexedSnapScrollerContext();
const days = Array.from({ length: 7 }, (_, day) => (
new Date(today.getFullYear(), today.getMonth(), today.getDate() - daysSinceMonday + index * 7 + day)
));
return (
{days.map((day) => {
const value = toIsoDate(day);
const isSelected = value === selected;
const isUnavailable = day < todayStart || day.getDay() === 0;
return (
{weekdayFormat.format(day)}
);
})}
);
}
export default function WeekStripForm() {
const api = useRef(null);
const [selected, setSelected] = useState('');
const [error, setError] = useState('');
const [result, setResult] = useState('');
const select = (value: string) => {
setSelected(value);
setError('');
};
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
const deliveryDate = data.get('deliveryDate');
if (!deliveryDate) {
setError('Choose a delivery day. Sundays are not available.');
return;
}
setResult(`Delivery booked for ${deliveryDate}.`);
};
const onReset = () => {
setSelected('');
setError('');
setResult('');
api.current?.setIndexTo(0);
};
return (
);
}
```
### Раскладка/оверлей
#### Раскладка/оверлей: выбор месяца в поповере
Страницы — это годы, на каждой по двенадцать кнопок месяцев. Поповер рендерит содержимое только в открытом состоянии, поэтому `defaultIndex` открывает выбор на годе выбранного месяца; выбор месяца закрывает поповер и обновляет подпись триггера.
```tsx
import {
Button,
IndexedSnapScroller,
IndexedSnapScrollerContent,
Popover,
PopoverContent,
PopoverTrigger,
Text,
useIndexedSnapScrollerContext,
} from '@vega-ui/react';
import { useState } from 'react';
const currentYear = new Date().getFullYear();
const monthNames = Array.from({ length: 12 }, (_, month) => (
new Intl.DateTimeFormat('en-US', { month: 'short' }).format(new Date(2000, month, 1))
));
interface Selection {
year: number
month: number
}
interface YearPageProps {
selected: Selection
onSelect(value: Selection): void
}
function YearPage({ selected, onSelect }: YearPageProps) {
const { index } = useIndexedSnapScrollerContext();
const year = currentYear + index;
return (
{year}