Посібник для Vue

Базовий слайдер

The <Reel> загортає контролер слайдера з ядра. Використовуйте слот #item щоб рендерити кожен слайд із віртуалізацією — монтуються лише видимі слайди.

ReelIndicator

Необов’язковий компонент, що показує індикатори прогресу в стилі Instagram із поточною позицією в слайдері. Якщо він усередині <Reel>, він сам під’єднується до count та active значення через provide/inject у Vue — нічого зв’язувати вручну не треба.

Імперативний API — шаблонний ref

The <Reel> надає інтерфейс ReelExpose через шаблонний ref. Скористайтеся ref() щоб зберегти посилання й викликати імперативні методи на кшталт next(), prev(), та goTo().

Горизонтальний напрямок

Set direction="horizontal" для слайдера зі свайпом ліворуч і праворуч. Напрямок індикатора має збігатися.

Auto-sizing

The size необов’язковий. Якщо його не передати, <Reel> сам вимірює свій контейнер через ResizeObserver і підлаштовується під макет, заданий CSS. Розмір контейнера має задавати батьківський елемент — наприклад, flex, grid або явні розміри в CSS.

Переходи

Передайте пропс transition щоб змінити анімацію слайдів. ReelKit має п’ять переходів, які піддаються tree-shaking: slideTransition (типово), fadeTransition, flipTransition, cubeTransition, та zoomTransition.

Режим циклу

Увімкніть нескінченну кругову навігацію пропсом loop . Слайдер безшовно переходить з останнього слайда на перший і навпаки.

Колбеки подій

The <Reel> видає кілька подій для відстеження стану слайдера:

Навігація

Вбудовані способи навігації:

• Дотик / свайп: Тягніть, щоб гортати — з інерцією та прилипанням
• Клавіатура: Стрілки та Escape
• Колесо миші: Увімкніть :enable-wheel="true"
• Програмно: Використовуйте шаблонний ref, щоб дістатися next(), prev(), goTo()

Стан в URL

useOverlayUrlState будує контролер стану в URL для оверлея й повертає його цілком, а ви передаєте його в <LightboxUrlOverlay> як його :controller . Стан відкриття належить адресному рядку, тож прив’язаний оверлей відкривається сам, а посилання — звичайний спосіб його відкрити. Перший запис відсутнього параметра додає один запис в історію, кожен наступний його замінює, тож гортання ніколи не ховає кнопку «назад». Тримайте контролер, щоб читати value/позицією і закривати програмно через set(null), the same low-level write the overlay uses internally on slide change.

Об’єкт опцій приймає param, codec, та locator (усі три обов’язкові) плюс необов’язковий adapter. The codec та locator — узгоджена пара з однаковим Id, so for a plain ?photo=3 галереї розгортайте ...urlIndexKey(() => props.images.length), який повертає обидві половини одразу. urlIndexKey зіставляє параметр з індексом слайда й обмежує його живою кількістю, яку повертає геттер, тож застарілий або позамежний ?photo=99 відхиляється й сам зникає з URL замість того, щоб відкрити слайд, якого ніхто не називав. Передавайте геттер, а не число: у Vue setup виконується один раз, тож захоплена довжина застаріла б, поки посторінкова стрічка росте. Він загортає createIndexLocator (половину-локатор) і поєднує його з indexCodec. Посторінкова стрічка або галерея з адресацією за ідентичністю передає власну узгоджену пару codec + locator . Повна таблиця опцій — у довіднику API для Vue.

Патерн слота #item

Замість render prop із React у Vue використовується слот #item з областю видимості. Саме він дає віртуалізацію: монтуються лише видимі слайди. Область слота надає три властивості:

Composables

@reelkit/vue дає композабли для типових сценаріїв з оверлеями:

Головне

• Composition API

  Import Reel, ReelIndicator, and composables directly into your <script setup> — реєструвати плагін не потрібно

• слот #item з областю видимості

  Відповідник у Vue для пропса itemBuilder із React — дає віртуалізацію звичним синтаксисом шаблонів

• Шаблонний ref

  Використовуйте ref<ReelExpose>() для імперативної навігації — колбеки подій не потрібні

• @after-change

  Emits (index, rangeIndex) — стежить за поточним індексом для оновлення інтерфейсу

• контекст provide/inject

  ReelIndicator сам під’єднується до батьківського Reel через provide/inject у Vue — жодного протягування пропсів вручну

Поради щодо продуктивності

• Тримайте шаблони слайдів легкими

  The #item виконується для кожного видимого слайда (зазвичай трьох одночасно). Уникайте важких обчислень і глибоко вкладених структур усередині.

• Вантажте дані ближче до краю

  Використовуйте @after-change щоб помітити наближення до кінця й підвантажити наступний пакет, доки слайди не скінчилися — так виходить нескінченна стрічка.

• Тримайте імперативний стан у ref

  Зберігайте посилання ReelExpose та поточний індекс у ref()Vue — це дає точкову реактивність без зайвих перерендерів.

• Вимикайте колесо на сторінках із прокручуванням

  Set :enable-wheel="false" коли слайдер вбудований у макет із прокручуванням, щоб не перехоплювати прокручування сторінки.