SnapScroller

Паттерны

Карусель с кнопками

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

• поверхность с привязкой должна поддерживать и явные контролы «назад» и «вперёд»

Заметки о композиции:

• держите apiRef стабильным
• пусть внешние контролы вызывают prev() и next()

Компромиссы:

• явно и легко управлять
• больше логики интеграции, чем при пассивной привязке

import {
  Icon,
  IconButton,
  SnapScroller,
  SnapScrollerContent,
  Text,
  type SnapScrollerApiRef,
} from '@vega-ui/react';
import { ChevronLeft, ChevronRight } from '@vega-ui/icons';
import { useRef, useState, type CSSProperties } from 'react';

const products = [

Подсветка текущей страницы

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

• страница, к которой выполнена привязка, должна заметно выделяться

Заметки о композиции:

• вычисляйте подсвеченное состояние из onScrollSnapChange или onScrollSnapChanging
• сохраняйте тот же порядок ключей в списке содержимого

Компромиссы:

• понятнее обратная связь о текущей странице
• ещё один путь синхронизации состояния, который нужно поддерживать

import {
  Heading,
  PageControl,
  PageControlItem,
  SnapScroller,
  SnapScrollerContent,
  Text,
  type SnapScrollerApiRef,
} from '@vega-ui/react';
import { useRef, useState, type CSSProperties } from 'react';

const plans = [

Стабильные страницы мастера

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

• короткому пошаговому сценарию подходит физическое пролистывание страниц

Заметки о композиции:

• держите ширину каждой страницы стабильной
• используйте стабильные индексы, совпадающие с задуманным порядком

Компромиссы:

• осязаемое и понятное продвижение
• разная ширина или нестабильный порядок ухудшают опыт

import {
  Button,
  Fieldset,
  FieldsetLegend,
  Label,
  SnapScroller,
  SnapScrollerContent,
  Text,
  TextField,
  TextFieldInput,
  type SnapScrollerApiRef,
} from '@vega-ui/react';

Сравнение

Быстрое правило выбора

Используйте SnapScroller, когда у страниц уже есть стабильные индексы и нужно только прямое постраничное пролистывание с привязкой. Используйте IndexedSnapScroller, когда прокрутка должна управлять скользящим окном логических индексов.

SnapScroller и IndexedSnapScroller

• SnapScroller — для уже существующих страниц с ключами.
• IndexedSnapScroller — для почти бесконечного пролистывания с окном индексов.

SnapScroller и PageControl

• SnapScroller — для самой поверхности со страницами.
• PageControl — как компактный индикатор или контроллер для короткой последовательности.

Выбирайте этот компонент, когда

• у страниц стабильные индексы
• достаточно колбэков привязки и императивных prev/next

Не выбирайте этот компонент, когда

• список страниц должен виртуально расширяться или сдвигаться
• достаточно простого индикатора без поверхности с привязкой

Решение проблем

Прокрутка привязывается к неожиданным страницам

Симптом

Прокрутка останавливается, но не на той странице, которую ждал пользователь.

Вероятная причина

Индексы или ширина элементов не так стабильны, как предполагает интеграция.

Как проверить

• проверьте зарегистрированные значения index
• сравните ширину и порядок элементов между рендерами

Решение

Держите индексы стабильными и используйте более предсказуемые размеры страниц.

defaultIndex ничего не делает

Симптом

Прокрутка монтируется, но начинается не с нужной страницы.

Вероятная причина

Элемента с ключом для этого индекса нет в момент начальной прокрутки.

Как проверить

• проверьте реальные значения SnapScrollerContent index={...} при монтировании

Решение

Убедитесь, что целевая страница с этим ключом существует при первом рендере.

Внешние контролы расходятся с видимой страницей

Симптом

Кнопки «назад» и «вперёд» или подсвеченное состояние перестают соответствовать текущей позиции привязки.

Вероятная причина

Императивный API и подсвеченное состояние читают не из одного источника истины.

Как проверить

• сравните зафиксированный индекс привязки с состоянием, которое используют внешние контролы

Решение

Управляйте и видимой подсветкой, и императивными контролами из одних и тех же колбэков привязки или зафиксированного индекса.