Довідник API для Angular
Повний довідник @reelkit/angular : компоненти, директиви, сервіси та утиліти.
ReelComponent
Селектор: rk-reel
Inputs
| Input | Тип | Типове значення | Опис |
|---|---|---|---|
count | number | required | Загальна кількість слайдів |
direction | 'vertical' | 'horizontal' | 'vertical' | Напрямок прокручування |
size | [number, number] | undefined | undefined | Ширина й висота у вигляді [width, height]. Якщо не задано, вимірюється автоматично через ResizeObserver |
initialIndex | number | 0 | Початковий індекс слайда |
loop | boolean | false | Вмикає нескінченний цикл |
transition | TransitionTransformFn | slideTransition | Функція ефекту переходу. Вбудовані: slideTransition, fadeTransition, flipTransition, cubeTransition, zoomTransition |
transitionDuration | number | 300 | Тривалість анімації в мілісекундах |
swipeDistanceFactor | number | 0.12 | Поріг свайпу (0–1) |
enableGestures | boolean | true | Вмикає навігацію перетягуванням дотиком або мишею |
enableNavKeys | boolean | true | Вмикає навігацію стрілками клавіатури |
enableWheel | boolean | false | Вмикає навігацію колесом миші |
wheelDebounceMs | number | 200 | Дебаунс події колеса в мілісекундах |
rangeExtractor | (index: number, count: number) => number[] | defaultRangeExtractor | Власна функція, що визначає, які індекси рендеряться |
keyExtractor | (index: number, indexInRange: number) => string | number | index => index | Власна функція ключів для виразів track у @for (корисно з циклом) |
className | string | '' | Клас CSS для кореневого контейнера |
ariaLabel | string | 'Carousel' | Доступна назва області каруселі |
Outputs
| Output | Тип | Опис |
|---|---|---|
afterChange | EventEmitter<{ index: number; indexInRange: number }> | Видається після завершення переходу між слайдами |
beforeChange | EventEmitter<{ index: number; nextIndex: number; indexInRange: number }> | Видається перед початком переходу між слайдами |
slideDragStart | EventEmitter<number> | Видається на початку перетягування |
slideDragEnd | EventEmitter<number> | Видається, коли перетягування завершується (палець або кнопку відпустили) |
slideDragCanceled | EventEmitter<number> | Видається, коли перетягування скасовано (слайд повертається назад) |
apiReady | EventEmitter<ReelApi> | Видається один раз після ініціалізації подання й відкриває імперативний API |
Інтерфейс ReelApi
Отримується через вихід (apiReady) :
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.
Контекст шаблону
<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) |
indexInRange | number | Позиція у видимому вікні (0, 1 або 2) |
size | [number, number] | Поточні розміри слайдера як [width, height] у пікселях |
ReelIndicatorComponent
Селектор: rk-reel-indicator
Inputs
| Input | Тип | Типове значення | Опис |
|---|---|---|---|
count | number | undefined | auto | Загальна кількість елементів. Береться з контексту батьківського rk-reel, якщо компонент вкладений у нього; передавайте явно за окремого використання |
active | number | undefined | auto | Поточний активний індекс. Береться з контексту батьківського rk-reel, якщо компонент вкладений у нього; передавайте явно за окремого використання |
direction | 'vertical' | 'horizontal' | 'vertical' | Орієнтація індикатора |
radius | number | 3 | Радіус точки в пікселях |
visible | number | 5 | Максимум одночасно видимих точок звичайного розміру |
gap | number | 4 | Відстань між точками в пікселях |
activeColor | string | '#fff' | Колір активної точки |
inactiveColor | string | 'rgba(255,255,255,0.5)' | Колір неактивної точки |
edgeScale | number | 0.5 | Коефіцієнт масштабу крайніх точок за межами видимого |
className | string | '' | Власний клас CSS для контейнера індикатора |
tablistLabel | string | 'Slide navigation' | Доступна назва орієнтира tablist |
Outputs
| Output | Тип | Опис |
|---|---|---|
dotClick | EventEmitter<number> | Видається на клік по точці; передає індекс точки |
RK_REEL_CONTEXT
An InjectionToken<ReelContextValue> який надає rk-reel своїм нащадкам. Використовується всередині rk-reel-indicator для автоматичного під’єднання. Впроваджуйте його у власні компоненти, яким потрібен контекст слайдера.
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);
}
}| Властивість | Тип | Опис |
|---|---|---|
index | Signal<number> | Реактивний індекс поточного слайда |
count | Signal<number> | Реактивна загальна кількість елементів |
goTo | (index: number, animate?: boolean) => Promise<void> | Програмний перехід д о слайда |
BodyLockService
Блокування прокручування body з підрахунком посилань. Кілька одночасних викликачів (наприклад, відкриті водночас Lightbox і модальне вікно) блокують і розблоковують незалежно — body повертається до норми лише коли останній із них звільнить. Надається на рівні кореня — впроваджуйте будь-де.
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(); }
}| Член | Тип | Опис |
|---|---|---|
locked | boolean (getter) | Чи заблоковано body просто зараз |
lock() | () => void | Заблокувати прокручування body й компенсувати ширину смуги прокручування |
unlock() | () => void | Повернути початкові стилі прокручування body |
SoundStateService
Стан звуку — вимкнено та недоступно — для оверлея, що відтворює медіа, у вигляді сигналів Angular. Надавайте його на компоненті, який володіє медіа, а не в корені, щоб кожен екземпляр оверлея тримав власний стан. Ним користуються всі оверлеї reelkit для Angular — @reelkit/angular-reel-player реекспортує той самий клас, тож наявний імпорт звідти працює далі.
Виняток — lightbox: надавайте сервіс над <rk-lightbox-overlay>, бо його відеослайд рендериться з вашого шаблону й інакше ніколи не побачить екземпляр усередині оверлея.
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 піднімає його, поки слайд без відео або в переході |
controller | SoundController (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.
| Function | Signature | Опис |
|---|---|---|
toAngularSignal | (source: Subscribable<T>, destroyRef: DestroyRef) => Signal<T> | Місток від Subscribable з ядра до сигналу Angular лише для читання |
animatedSignalBridge | (source: AnimatedValue, zone: NgZone, cdRef: ChangeDetectorRef, destroyRef: DestroyRef) => Signal<number> | Місток від анімованого значення ядра до сигналу Angular, що оновлюється через requestAnimationFrame поза зоною |
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 | Тип | Типове значення | Опис |
|---|---|---|---|
param | string | required | Параметр запиту, що несе активний слайд, наприклад photo. |
adapter | UrlAdapter | History API | Система навігації, через яку читати й писати. У застосунку з роутером передайте адаптер на базі Router, щоб місцеположення роутера не застаріло. |
codec | UrlCodec<Id> | required | Формат передавання: текст параметра в стабільну ідентичність. Іде разом із локатором як узгоджена пара — розгорніть ...urlIndexKey(() => images().length) для типової галереї з ?photo=3 або передайте власний, щоб закладка пережила зміну порядку. |
locator | UrlLocator<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-залежність.
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:
// 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';