# IndexedSnapScroller: Руководства
## Паттерны
### Контролируемый виртуальный индекс
Когда использовать:
- логический индекс страницы должен оставаться синхронизированным с внешним интерфейсом, например с числовыми элементами управления
Заметки о композиции:
- управляйте и внешним элементом, и скроллером из одного состояния индекса
- пусть `onScrollSnapChanging` или `onScrollSnapChange` обновляют это состояние
Компромиссы:
- явная синхронизация
- больше движущихся частей, чем у неконтролируемого скроллера
```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}
);
}
```
### Окно виртуальной ленты
Когда использовать:
- видимый набор страниц должен сдвигаться, когда пользователь движется вперёд или назад
Заметки о композиции:
- настройте `size`, `shift` и `start`
- содержимое страниц должно быть устойчивым к смене логических индексов
Компромиссы:
- масштабируется
- сложнее для понимания, чем фиксированный список страниц
```tsx
import {
IndexedSnapScroller,
IndexedSnapScrollerContent,
Text,
useIndexedSnapScrollerContext,
} from '@vega-ui/react';
import { useCallback, useEffect, useRef, useState } from 'react';
const today = new Date();
const dayFormat = new Intl.DateTimeFormat('en-US', { weekday: 'long', month: 'short', day: 'numeric' });
const moneyFormat = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
interface DayPageProps {
revenue: Record
onNeed(index: number): void
}
function DayPage({ revenue, onNeed }: DayPageProps) {
const { index } = useIndexedSnapScrollerContext();
const day = new Date(today.getFullYear(), today.getMonth(), today.getDate() + index);
const value = revenue[index];
useEffect(() => {
if (value === undefined) onNeed(index);
}, [index, value, onNeed]);
return (
{dayFormat.format(day)}
{value === undefined ? 'Loading…' : moneyFormat.format(value)}
);
}
export default function LazyPageData() {
const [revenue, setRevenue] = useState>({});
const requested = useRef(new Set());
const [extensions, setExtensions] = useState(0);
const load = useCallback((index: number) => {
if (requested.current.has(index)) return;
requested.current.add(index);
window.setTimeout(() => {
const value = 1800 + (Math.abs(index * 7919) % 900);
setRevenue((previous) => ({ ...previous, [index]: value }));
}, 600);
}, []);
return (
);
}
```
### Низкоуровневое пролистывание календаря или ленты
Когда использовать:
- другой подсистеме нужна виртуальная индексация страниц, но обёртки для предметной области ещё нет
Заметки о композиции:
- держите логику предметной области вне скроллера
- используйте предоставляемый контекст индекса при рендере содержимого
Компромиссы:
- переиспользуемая основа
- легко переусложнить, если обёртка более высокого уровня уже существует
```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 (
);
}
```
## Сравнение
### Быстрое правило выбора
Используйте `IndexedSnapScroller`, когда пролистывание должно управляться логическим, возможно неограниченным индексом. Используйте `SnapScroller`, когда набор страниц уже стабилен и задан явно.
### `IndexedSnapScroller` или `SnapScroller`
- Используйте `IndexedSnapScroller` для сдвигающихся логических окон.
- Используйте `SnapScroller` для страниц, заданных напрямую с ключами.
### `IndexedSnapScroller` или `DayPickerScroller` / `YearPickerScroller`
- Используйте `IndexedSnapScroller` как низкоуровневый примитив пролистывания по индексам.
- Используйте скроллеры пикеров, когда предметная область — уже календарное пролистывание.
### Выбирайте этот компонент, когда
- содержимое лучше всего описывается виртуальной последовательностью индексов
- окно страниц должно сдвигаться, когда пользователь приближается к границам
### Не выбирайте этот компонент, когда
- достаточно фиксированного набора страниц
- больше подходят обёртки пролистывания, специфичные для календаря
## Решение проблем
### Видимая страница прыгает после достижения края
#### Симптом
Скроллер доходит до границы, и видимое содержимое будто прыгает.
#### Вероятная причина
Виртуальное окно сдвинулось, а позиция прокрутки не сохранилась, как ожидалось.
#### Как проверить
- проверьте `preserveScroll`
- посмотрите, вызывает ли смещение на границе сброс окна или добавление страниц в начало или конец
#### Исправление
Оставьте `preserveScroll` включённым, если ожидается сохранение текущей привязки.
### Контролируемый `index` и видимое содержимое расходятся
#### Симптом
Родитель считает активным один индекс, а видимое содержимое страницы указывает на другой.
#### Вероятная причина
Обновления контролируемого индекса и внутренние сбросы окна не согласованы.
#### Как проверить
- выведите в лог контролируемый `index`
- сравните его с зафиксированным или ожидающим индексом привязки
#### Исправление
Используйте один явный источник истины и пусть родитель единообразно реагирует на колбэки привязки.
### Состояние страницы протекает между разными логическими индексами
#### Симптом
При смене виртуального индекса содержимое будто переиспользует устаревшее состояние.
#### Вероятная причина
Шаблон содержимого рассчитывал на фиксированную идентичность вместо идентичности для каждого индекса.
#### Как проверить
- изучите ключи дочерних элементов и логику состояния внутри шаблона содержимого
#### Исправление
Сделайте состояние для каждого индекса явным и не предполагайте, что одна физическая страница DOM навсегда равна одной логической странице.