Довідник API для Angular

Повний довідник @reelkit/angular : компоненти, директиви, сервіси та утиліти.

ReelComponent

Селектор: rk-reel

Inputs

InputТипТипове значенняОпис
countnumberrequiredЗагальна кількість слайдів
direction'vertical' | 'horizontal''vertical'Напрямок прокручування
size[number, number] | undefinedundefinedШирина й висота у вигляді [width, height]. Якщо не задано, вимірюється автоматично через ResizeObserver
initialIndexnumber0Початковий індекс слайда
loopbooleanfalseВмикає нескінченний цикл
transitionTransitionTransformFnslideTransitionФункція ефекту переходу. Вбудовані: slideTransition, fadeTransition, flipTransition, cubeTransition, zoomTransition
transitionDurationnumber300Тривалість анімації в мілісекундах
swipeDistanceFactornumber0.12Поріг свайпу (0–1)
enableGesturesbooleantrueВмикає навігацію перетягуванням дотиком або мишею
enableNavKeysbooleantrueВмикає навігацію стрілками клавіатури
enableWheelbooleanfalseВмикає навігацію колесом миші
wheelDebounceMsnumber200Дебаунс події колеса в мілісекундах
rangeExtractor(index: number, count: number) => number[]defaultRangeExtractorВласна функція, що визначає, які індекси рендеряться
keyExtractor(index: number, indexInRange: number) => string | numberindex => indexВласна функція ключів для виразів track у @for (корисно з циклом)
classNamestring''Клас CSS для кореневого контейнера
ariaLabelstring'Carousel'Доступна назва області каруселі

Outputs

OutputТипОпис
afterChangeEventEmitter<{ index: number; indexInRange: number }>Видається після завершення переходу між слайдами
beforeChangeEventEmitter<{ index: number; nextIndex: number; indexInRange: number }>Видається перед початком переходу між слайдами
slideDragStartEventEmitter<number>Видається на початку перетягування
slideDragEndEventEmitter<number>Видається, коли перетягування завершується (палець або кнопку відпустили)
slideDragCanceledEventEmitter<number>Видається, коли перетягування скасовано (слайд повертається назад)
apiReadyEventEmitter<ReelApi>Видається один раз після ініціалізації подання й відкриває імперативний API

Інтерфейс ReelApi

Отримується через вихід (apiReady) :

typescript
import { type ReelApi } from '@reelkit/angular';

@Component({ ... })
export class AppComponent {
  api: ReelApi | undefined;

  // In template: (apiReady)="api = $event"

  prev()  { this.api?.prev(); }
  next()  { this.api?.next(); }
  jump(i: number) { this.api?.goTo(i, true); }  // animated
}
МетодТипОпис
next()() => voidПерейти до наступного слайда
prev()() => voidПерейти до попереднього слайда
goTo(index, animate?)(number, boolean?) => Promise<void>Перехід до слайда за індексом
adjust()() => voidПерерахувати позиції слайдів (корисно після зміни макета)
observe()() => voidПочати слухати події клавіатури
unobserve()() => voidПрипинити слухати події клавіатури

RkReelItemDirective

Селектор: [rkReelItem] — застосовується до ng-template inside rk-reel.

Контекст шаблону

html
<ng-template rkReelItem let-i let-indexInRange="indexInRange" let-size="size">
  <!-- $implicit (let-i)  : number         — absolute slide index -->
  <!-- indexInRange        : number         — position in the visible window (0, 1, or 2) -->
  <!-- size                : [number,number] — [width, height] of the container -->
</ng-template>
VariableТипОпис
$implicit (let-i)numberАбсолютний індекс слайда (від 0 до count-1)
indexInRangenumberПозиція у видимому вікні (0, 1 або 2)
size[number, number]Поточні розміри слайдера як [width, height] у пікселях

ReelIndicatorComponent

Селектор: rk-reel-indicator

Inputs

InputТипТипове значенняОпис
countnumber | undefinedautoЗагальна кількість елементів. Береться з контексту батьківського rk-reel, якщо компонент вкладений у нього; передавайте явно за окремого використання
activenumber | undefinedautoПоточний активний індекс. Береться з контексту батьківського rk-reel, якщо компонент вкладений у нього; передавайте явно за окремого використання
direction'vertical' | 'horizontal''vertical'Орієнтація індикатора
radiusnumber3Радіус точки в пікселях
visiblenumber5Максимум одночасно видимих точок звичайного розміру
gapnumber4Відстань між точками в пікселях
activeColorstring'#fff'Колір активної точки
inactiveColorstring'rgba(255,255,255,0.5)'Колір неактивної точки
edgeScalenumber0.5Коефіцієнт масштабу крайніх точок за межами видимого
classNamestring''Власний клас CSS для контейнера індикатора
tablistLabelstring'Slide navigation'Доступна назва орієнтира tablist

Outputs

OutputТипОпис
dotClickEventEmitter<number>Видається на клік по точці; передає індекс точки

RK_REEL_CONTEXT

An InjectionToken<ReelContextValue> який надає rk-reel своїм нащадкам. Використовується всередині rk-reel-indicator для автоматичного під’єднання. Впроваджуйте його у власні компоненти, яким потрібен контекст слайдера.

typescript
import { inject } from '@angular/core';
import { RK_REEL_CONTEXT } from '@reelkit/angular';

@Component({ ... })
export class MyCustomControl {
  private readonly ctx = inject(RK_REEL_CONTEXT, { optional: true });

  jump(index: number) {
    this.ctx?.goTo(index, true);
  }
}
ВластивістьТипОпис
indexSignal<number>Реактивний індекс поточного слайда
countSignal<number>Реактивна загальна кількість елементів
goTo(index: number, animate?: boolean) => Promise<void>Програмний перехід до слайда

BodyLockService

Блокування прокручування body з підрахунком посилань. Кілька одночасних викликачів (наприклад, відкриті водночас Lightbox і модальне вікно) блокують і розблоковують незалежно — body повертається до норми лише коли останній із них звільнить. Надається на рівні кореня — впроваджуйте будь-де.

typescript
import { inject } from '@angular/core';
import { BodyLockService } from '@reelkit/angular';

@Component({ ... })
export class OverlayComponent {
  private readonly bodyLock = inject(BodyLockService);

  open() { this.bodyLock.lock(); }
  close() { this.bodyLock.unlock(); }
}
ЧленТипОпис
lockedboolean (getter)Чи заблоковано body просто зараз
lock()() => voidЗаблокувати прокручування body й компенсувати ширину смуги прокручування
unlock()() => voidПовернути початкові стилі прокручування body

SoundStateService

Стан звуку — вимкнено та недоступно — для оверлея, що відтворює медіа, у вигляді сигналів Angular. Надавайте його на компоненті, який володіє медіа, а не в корені, щоб кожен екземпляр оверлея тримав власний стан. Ним користуються всі оверлеї reelkit для Angular — @reelkit/angular-reel-player реекспортує той самий клас, тож наявний імпорт звідти працює далі.

Виняток — lightbox: надавайте сервіс над <rk-lightbox-overlay>, бо його відеослайд рендериться з вашого шаблону й інакше ніколи не побачить екземпляр усередині оверлея.

typescript
import { inject } from '@angular/core';
import { SoundStateService } from '@reelkit/angular';

@Component({
  // Provide it on the component that owns the media, so two overlays
  // on one page never share a muted state.
  providers: [SoundStateService],
  // ...
})
export class OverlayComponent {
  readonly soundState = inject(SoundStateService);

  // Use in template:
  // [muted]="soundState.muted()"
  // [hidden]="soundState.disabled()"
  // (click)="soundState.toggle()"
}
ЧленТипОпис
muted()Signal<boolean>Чи вимкнено звук просто зараз. Початково вимкнено
disabled()Signal<boolean>Істина, поки звуком не можна керувати, і кнопка звуку ховається. Значення задає оверлей — RkReelPlayerOverlayComponent піднімає його, поки слайд без відео або в переході
controllerSoundController (getter)Базовий SoundController із core — передайте його в syncMutedToVideo, щоб <video> тримався стану звуку
toggle()() => voidПеремикає вимкнення звуку
setDisabled()(value: boolean) => voidЗадає, чи можна керувати звуком просто зараз
reset()() => voidПовертає початковий стан: звук вимкнено, керування доступне

Утиліти мосту сигналів

Допоміжні функції, що з’єднують систему сигналів ядра (@reelkit/core) with Angular's native signal API. Used internally by ReelComponent; also available for custom framework integrations.

FunctionSignatureОпис
toAngularSignal(source: Subscribable<T>, destroyRef: DestroyRef) => Signal<T>Місток від Subscribable з ядра до сигналу Angular лише для читання
animatedSignalBridge(source: AnimatedValue, zone: NgZone, cdRef: ChangeDetectorRef, destroyRef: DestroyRef) => Signal<number>Місток від анімованого значення ядра до сигналу Angular, що оновлюється через requestAnimationFrame поза зоною
typescript
import { DestroyRef, inject } from '@angular/core';
import { toAngularSignal } from '@reelkit/angular';
import { createSliderController } from '@reelkit/core';

// Custom component using low-level signal bridge
const destroyRef = inject(DestroyRef);
const controller = createSliderController({ count: 10 }, {});
const index = toAngularSignal(controller.state.index, destroyRef);

createOverlayUrlState

OverlayUrlStateOptions

Будує контролер стану в URL для оверлея, який ви передаєте в <rk-lightbox-url-overlay> як його [controller] . Викликайте його в контексті впровадження — в ініціалізаторі поля або в конструкторі; він під’єднується одразу й звільняється через DestroyRef. Покроковий розбір: Стан в URL на сторінці Lightbox для Angular.

OptionТипТипове значенняОпис
paramstringrequiredПараметр запиту, що несе активний слайд, наприклад photo.
adapterUrlAdapterHistory APIСистема навігації, через яку читати й писати. У застосунку з роутером передайте адаптер на базі Router, щоб місцеположення роутера не застаріло.
codecUrlCodec<Id>requiredФормат передавання: текст параметра в стабільну ідентичність. Іде разом із локатором як узгоджена пара — розгорніть ...urlIndexKey(() => images().length) для типової галереї з ?photo=3 або передайте власний, щоб закладка пережила зміну порядку.
locatorUrlLocator<Id>requiredЗіставляє ідентичність із позицією і сам відповідає за свою чинність: locate (синхронно), locateAsync (запасний варіант для посторінкової галереї), identify (для запису).

createRouterUrlAdapter

@reelkit/angular/ng-router-url-adapter

A UrlAdapter на базі Angular Router. Передайте його як adapter у createOverlayUrlState у застосунку з роутером, щоб Router лишався єдиним джерелом правди про навігацію: запис history.pushState повз Router лишає його місцеположення застарілим, і наступна навігація втрачає параметр. Запис торкається лише запиту, тож шлях, фрагмент і повторювані ключі на кшталт ?tag=a&tag=b лишаються недоторканими. Кожна зміна повідомляє, чи Router додав запис на тій самій сторінці, замінив його чи пройшов історією, тож галерея, відкрита з routerLink, закривається одним кроком назад. Викликайте його в контексті впровадження; підписка на роутер звільняється через DestroyRef.

Постачається з окремого підшляху, тож застосунок без роутингу ніколи не тягне @angular/router у свій бандл. @angular/router — необов’язкова peer-залежність.

typescript
import { createRouterUrlAdapter } from '@reelkit/angular/ng-router-url-adapter';

protected readonly photo = createOverlayUrlState({
  param: 'photo',
  adapter: createRouterUrlAdapter(),
  ...urlIndexKey(() => this.images().length),
});

Accessibility

<rk-reel> рендериться як role="region" з aria-roledescription="carousel". Задайте пропс ariaLabel щоб дати області назву для екранного читача. Ввічлива жива область оголошує «Слайд N з M» на кожну зміну слайда. Неактивні слайди отримують атрибут inert , тож фокус і навігація допоміжних технологій їх пропускають.

<rk-reel-indicator> рендериться як role="tablist" з рухомим tabindex на точках; стрілки переміщують фокус, а Enter або Space активує слайд.

Будуєте власне модальне вікно навколо <rk-reel>? captureFocusForReturn, createFocusTrap, та getFocusableElements — вони реекспортовані з @reelkit/angular для повернення й утримання фокуса.

Експорти пакета

Усі публічні експорти з @reelkit/angular:

typescript
// Components & directives
import {
  ReelComponent,
  ReelIndicatorComponent,
  RkReelItemDirective,
  RkSwipeToCloseDirective,
} from '@reelkit/angular';

// Types
import type {
  ReelApi,
  ReelContextValue,
  RkReelItemContext,
  CoreSignal,
  Subscribable,
  AnimatedValue,
  RangeExtractor,
  SliderDirection,
  Disposer,
  DisposableList,
  GestureController,
  SliderController,
  ContentLoadingController,
  ContentPreloader,
  ContentPreloaderConfig,
  SoundController,
  BodyLock,
  TransitionTransformFn,
  SlideTransformStyle,
  SwipeToCloseDirection,
} from '@reelkit/angular';

// Context
import { RK_REEL_CONTEXT } from '@reelkit/angular';

// Services
import { BodyLockService, SoundStateService } from '@reelkit/angular';

// Signal bridges
import { toAngularSignal, animatedSignalBridge } from '@reelkit/angular';

// Core re-exports
import {
  // Signals & reactivity
  createSignal, createComputed, reaction, batch,

  // Transitions
  slideTransition, fadeTransition, flipTransition,
  cubeTransition, zoomTransition, getSlideProgress,

  // Content loading & preloading
  createContentLoadingController, createContentPreloader,

  // Sound
  createSoundController, syncMutedToVideo,

  // Fullscreen
  fullscreenSignal, requestFullscreen, exitFullscreen,

  // DOM & cleanup
  observeDomEvent, createDisposableList, createBodyLock, sharedBodyLock,

  // Size detection
  observeElementSize, getViewportSize, observeViewportSize,
  isMobileWidth, fitAspectRatio, isTouchDevice,

  // Autoplay & download
  createTimerController, createSlideshowController, downloadFile,

  // Focus management
  captureFocusForReturn, createFocusTrap, getFocusableElements,

  // Slider & gestures
  createSliderController, createGestureController,
  defaultRangeExtractor, createDefaultKeyExtractorForLoop,

  // Video
  captureFrame, createSharedVideo,

  // Utilities
  animate, noop, clamp, abs, first, last, extractRange,
} from '@reelkit/angular';