Пропсы корня
| Проп | Тип | По умолчанию |
|---|---|---|
start | number | -2 |
| Начальный индекс для генерации исходной последовательности страниц. Служит логической точкой отсчёта для скользящего окна индексов. | ||
startDir | -1 | 1 | 1 |
Направление, в котором растёт начальная последовательность индексов. 1 — индексы растут вправо (0, 1, 2…); -1 — индексы убывают вправо (0, -1, -2…). Управляет порядком роста начального массива индексов. | ||
size | number | 5 |
| Количество сегментов индексов, отрендеренных одновременно. Определяет размер виртуального «окна», по которому скроллер сдвигается при навигации влево или вправо. | ||
shift | number | 2 |
| Количество страниц, добавляемых, когда прокрутка доходит до конца окна, чтобы быстрый свайп продолжался. Когда прокрутка останавливается, окно заново центрируется на странице привязки. | ||
index | number | — |
| Управляет текущим активным логическим индексом. Если задан, скроллер держит этот индекс в области видимости: прокручивает к нему, если это возможно, или при необходимости перестраивает окно. | ||
preserveScroll | boolean | true |
Сохраняет текущий привязанный элемент после изменения содержимого (например, когда страницы добавляются в начало или конец). Если true, скроллер восстановит тот же индекс привязки через мгновенный scrollIntoView. | ||
apiRef | Ref<IndexedSnapScrollerApiRef> | — |
| Предоставляет императивный API скроллера. Позволяет управлять им программно, например прокручивать к индексу или сбрасывать виртуальное окно. | ||
onOffset | (value: number) => void | — |
Вызывается, когда окно растёт у края. -1 — прокрутка остановилась на первой странице (левый/верхний край); +1 — прокрутка дошла до конца (правый/нижний край). Полезно для бесконечной подгрузки: добавляйте страницы в конец или в начало в зависимости от направления. | ||
ref | Ref<HTMLDivElement> | — |
| Ref на элемент скроллера. | ||
defaultIndex | number | — |
| Начальный индекс элемента, к которому выполняется привязка при монтировании. | ||
onScrollSnapChange | (element: HTMLElement, index: number) => void | — |
| Вызывается, когда операция прокрутки с привязкой полностью завершена и скроллер остановился на новом индексе привязки. Колбэк вызывается после завершения всех анимаций прокрутки и привязки, когда активная позиция привязки считается стабильной. | ||
onScrollSnapChanging | (element: HTMLElement, index: number) => void | — |
| Вызывается, пока операция прокрутки с привязкой идёт и активный индекс привязки ещё меняется. Колбэк может вызываться несколько раз за одну прокрутку или свайп, пока скроллер приближается к конечной позиции привязки. Полезен для оптимистичных обновлений интерфейса, превью или синхронизации промежуточного состояния во время прокрутки. | ||
Также принимает все атрибуты <div>.
Дочерние части
IndexedSnapScrollerContent: шаблон содержимого, привязанный к текущему виртуальному индексу.
IndexedSnapScrollerContent
| Проп | Тип | По умолчанию |
|---|---|---|
ref | Ref<HTMLDivElement> | — |
Внешний ref на корневой элемент элемента. Объединяется с внутренним itemRef(index), чтобы участвовать в логике привязки. | ||
asChild | boolean | — |
Рендерит содержимое как дочерний элемент (через Slot) вместо нативного <div>. Атрибуты и ref остаются привязанными к переданному дочернему элементу. | ||
Также принимает все атрибуты <div>.
Типы
IndexedSnapScrollerPropsIndexedSnapScrollerContentPropsIndexedSnapScrollerApiRef
Модель состояния
- Корень управляет скользящим окном логических индексов.
- Контролируемый
indexможет либо прокрутить к существующему элементу, либо вызвать сброс окна. - Пока прокрутка доходит до конца, страницы добавляются, чтобы она могла продолжаться; когда прокрутка останавливается, окно заново центрируется на привязанной странице.
next()/prev()отсчитывают от страницы, к которой уже движется прокрутка, и сначала расширяют окно, если цель за его пределами.