Angular-API-Referenz

Vollständige Referenz für die Komponenten, Direktiven, Services und Hilfsfunktionen von @reelkit/angular.

ReelComponent

Selektor: rk-reel

Inputs

InputTypStandardBeschreibung
countnumberPflichtGesamtzahl der Slides
direction'vertical' | 'horizontal''vertical'Scrollrichtung
size[number, number] | undefinedundefinedBreite und Höhe als [width, height]. Fehlt der Wert, misst die Komponente selbst über ResizeObserver
initialIndexnumber0Index der ersten Slide
loopbooleanfalseSchaltet die Endlosschleife ein
transitionTransitionTransformFnslideTransitionFunktion für den Übergangseffekt. Eingebaut: slideTransition, fadeTransition, flipTransition, cubeTransition, zoomTransition
transitionDurationnumber300Dauer der Animation in ms
swipeDistanceFactornumber0.12Schwelle für das Wischen (0-1)
enableGesturesbooleantrueSchaltet die Navigation per Touch und Ziehen mit der Maus ein
enableNavKeysbooleantrueSchaltet die Navigation mit den Pfeiltasten ein
enableWheelbooleanfalseSchaltet die Navigation mit dem Mausrad ein
wheelDebounceMsnumber200Debounce für Mausrad-Ereignisse in ms
rangeExtractor(index: number, count: number) => number[]defaultRangeExtractorEigene Funktion, die bestimmt, welche Indizes gerendert werden
keyExtractor(index: number, indexInRange: number) => string | numberindex => indexEigene Schlüsselfunktion für die track-Ausdrücke von @for (nützlich mit loop)
classNamestring''CSS-Klasse für das Wurzelelement des Containers
ariaLabelstring'Carousel'Barrierefreie Bezeichnung für die Region des Karussells

Outputs

OutputTypBeschreibung
afterChangeEventEmitter<{ index: number; indexInRange: number }>Wird ausgelöst, nachdem der Slide-Übergang abgeschlossen ist
beforeChangeEventEmitter<{ index: number; nextIndex: number; indexInRange: number }>Wird ausgelöst, bevor der Slide-Übergang beginnt
slideDragStartEventEmitter<number>Wird ausgelöst, wenn eine Ziehgeste beginnt
slideDragEndEventEmitter<number>Wird ausgelöst, wenn eine Ziehgeste endet (losgelassen)
slideDragCanceledEventEmitter<number>Wird ausgelöst, wenn eine Ziehgeste abgebrochen wird (Zurückschnappen)
apiReadyEventEmitter<ReelApi>Wird einmal nach der Initialisierung der View ausgelöst und stellt die imperative API bereit

Das Interface ReelApi

Du bekommst es über den Output (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
}
MethodeTypBeschreibung
next()() => voidGeht zur nächsten Slide
prev()() => voidGeht zur vorherigen Slide
goTo(index, animate?)(number, boolean?) => Promise<void>Navigiert zu einem bestimmten Slide-Index
adjust()() => voidBerechnet die Positionen der Slides neu (nützlich nach einer Änderung am Layout)
observe()() => voidBeginnt, auf Tastatur-Ereignisse zu hören
unobserve()() => voidHört auf, auf Tastatur-Ereignisse zu hören

RkReelItemDirective

Selektor: [rkReelItem]. Wird auf ein ng-template innerhalb von rk-reel gesetzt.

Template-Kontext

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>
VariableTypBeschreibung
$implicit (let-i)numberAbsoluter Slide-Index (0 bis count-1)
indexInRangenumberPosition im sichtbaren Fenster (0, 1 oder 2)
size[number, number]Aktuelle Maße des Sliders als [width, height] in Pixeln

ReelIndicatorComponent

Selektor: rk-reel-indicator

Inputs

InputTypStandardBeschreibung
countnumber | undefinedautoGesamtzahl der Elemente. Verbindet sich automatisch mit dem Kontext des umgebenden rk-reel, wenn die Komponente darin steckt; übergib den Wert ausdrücklich, wenn du sie allein nutzt
activenumber | undefinedautoAktuell aktiver Index. Verbindet sich automatisch mit dem Kontext des umgebenden rk-reel, wenn die Komponente darin steckt; übergib den Wert ausdrücklich, wenn du sie allein nutzt
direction'vertical' | 'horizontal''vertical'Ausrichtung des Indikators
radiusnumber3Radius der Punkte in Pixeln
visiblenumber5Höchstzahl der Punkte in normaler Größe, die gleichzeitig sichtbar sind
gapnumber4Abstand zwischen den Punkten in Pixeln
activeColorstring'#fff'Farbe des aktiven Punkts
inactiveColorstring'rgba(255,255,255,0.5)'Farbe der inaktiven Punkte
edgeScalenumber0.5Skalierung für die Punkte am Rand, die über die Anzahl hinausgehen
classNamestring''Eigene CSS-Klasse für den Container des Indikators
tablistLabelstring'Slide navigation'Barrierefreie Bezeichnung für die Landmark der Tablist

Outputs

OutputTypBeschreibung
dotClickEventEmitter<number>Wird beim Klick auf einen Punkt ausgelöst und liefert dessen Index

RK_REEL_CONTEXT

Ein InjectionToken<ReelContextValue>, das rk-reel für seine Nachfahren bereitstellt. rk-reel-indicator nutzt es intern, um sich automatisch zu verbinden. Injiziere es in eigene Komponenten, die den Kontext des Sliders brauchen.

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);
  }
}
EigenschaftTypBeschreibung
indexSignal<number>Reaktiver aktueller Slide-Index
countSignal<number>Reaktive Gesamtzahl der Elemente
goTo(index: number, animate?: boolean) => Promise<void>Navigiert im Code zu einer Slide

BodyLockService

Scroll-Sperre für den Body mit Referenzzählung. Mehrere gleichzeitige Aufrufer (zum Beispiel eine offene Lightbox und ein offenes Modal) können lock/unlock unabhängig voneinander aufrufen — der Body wird erst wiederhergestellt, wenn der letzte Aufrufer ihn freigibt. Wird im Root bereitgestellt und lässt sich überall injizieren.

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(); }
}
MitgliedTypBeschreibung
lockedboolean (getter)Ob der Body gerade gesperrt ist
lock()() => voidSperrt das Scrollen des Body und gleicht die Breite der Scrollbar aus
unlock()() => voidStellt die ursprünglichen Scroll-Styles des Body wieder her

SoundStateService

Stumm- und Sperrzustand für ein Overlay, das Medien abspielt, als Angular-Signals. Stelle den Service auf der Komponente bereit, der die Medien gehören, statt im Root, damit jede Instanz des Overlays ihren eigenen Zustand behält. Jedes Angular-Overlay von reelkit nutzt ihn — @reelkit/angular-reel-player exportiert dieselbe Klasse erneut, ein bestehender Import von dort funktioniert also weiter.

Die Lightbox ist die Ausnahme: Stelle ihn oberhalb von <rk-lightbox-overlay> bereit, denn ihre Video-Slide wird aus deinem eigenen Template gerendert und sähe die Instanz im Overlay sonst nie.

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()"
}
MitgliedTypBeschreibung
muted()Signal<boolean>Ob der Ton gerade stumm ist. Startet stumm
disabled()Signal<boolean>Wahr, solange sich der Ton nicht steuern lässt; der Ton-Button ist dann ausgeblendet. Das Overlay setzt den Wert — RkReelPlayerOverlayComponent setzt ihn, solange eine Slide kein Video hat oder mitten im Übergang ist
controllerSoundController (getter)Der darunterliegende SoundController aus dem Core — übergib ihn an syncMutedToVideo, damit ein <video> dem Stummzustand folgt
toggle()() => voidSchaltet den Stummzustand um
setDisabled()(value: boolean) => voidLegt fest, ob sich der Ton gerade steuern lässt
reset()() => voidKehrt zum Startzustand zurück: stumm, nicht gesperrt

Hilfsfunktionen für Signal-Brücken

Hilfsfunktionen, die das Signal-System des Core (@reelkit/core) mit der nativen Signal-API von Angular verbinden. ReelComponent nutzt sie intern; sie stehen auch für eigene Framework-Integrationen bereit.

FunktionSignaturBeschreibung
toAngularSignal(source: Subscribable<T>, destroyRef: DestroyRef) => Signal<T>Macht aus einem Subscribable des Core ein schreibgeschütztes Angular-Signal
animatedSignalBridge(source: AnimatedValue, zone: NgZone, cdRef: ChangeDetectorRef, destroyRef: DestroyRef) => Signal<number>Macht aus einem animierten Wert des Core ein Angular-Signal, das sich über requestAnimationFrame außerhalb der Zone aktualisiert
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

Baut einen URL-State-Controller für ein Overlay, den du <rk-lightbox-url-overlay> als Input [controller] übergibst. Rufe die Funktion in einem Injection-Kontext auf, also in einem Feld-Initialisierer oder im Konstruktor; sie bindet sich sofort an und gibt sich über DestroyRef wieder frei. Schritt für Schritt: URL-State auf der Seite der Lightbox für Angular.

OptionTypStandardBeschreibung
paramstringrequiredQuery-Parameter, der die aktive Slide trägt, zum Beispiel photo.
adapterUrlAdapterHistory APIDas Navigationssystem, über das gelesen und geschrieben wird. Übergib in einer App mit Router einen Adapter, der den Router nutzt, damit die Location des Routers nicht veraltet.
codecUrlCodec<Id>requiredDas Format: Text des Parameters zu einer stabilen Identität. Gehört mit locator als Paar zusammen — setze ...urlIndexKey(() => images().length) für die übliche Galerie mit ?photo=3 ein, oder liefere ein eigenes, damit ein Lesezeichen ein Umsortieren übersteht.
locatorUrlLocator<Id>requiredOrdnet die Identität einer Position zu und entscheidet selbst über ihre Gültigkeit: locate (synchron), locateAsync (asynchroner Ausweg für eine Galerie mit Seiten), identify (Schreiben).

createRouterUrlAdapter

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

Ein UrlAdapter, der auf dem Angular Router aufbaut. Übergib ihn in einer App mit Router als Option adapter an createOverlayUrlState, damit der Router die einzige Quelle der Wahrheit für die Navigation bleibt — wer history.pushState am Router vorbei schreibt, lässt dessen Location veralten, und seine nächste Navigation verwirft den Parameter. Geschrieben wird nur die Query, der Pfad, das Fragment und wiederholte Schlüssel wie ?tag=a&tag=b bleiben also unberührt. Jede Änderung meldet, ob der Router auf derselben Seite einen Eintrag angelegt, ersetzt oder sich durch den Verlauf bewegt hat. Eine Galerie, die über einen routerLink geöffnet wurde, schließt sich daher mit einem Schritt zurück. Rufe die Funktion in einem Injection-Kontext auf; das Abo auf den Router wird über DestroyRef freigegeben.

Er kommt aus einem eigenen Unterpfad, eine App ohne Routing zieht @angular/router also nie in ihr Bundle. @angular/router ist eine optionale Peer-Abhängigkeit.

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

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

Barrierefreiheit

<rk-reel> wird als role="region" mit aria-roledescription="carousel" gerendert. Setze den Input ariaLabel, um der Region einen Namen für Screenreader zu geben. Eine höfliche Live-Region sagt bei jedem Slide-Wechsel „Slide N of M“ an. Inaktive Slides bekommen das Attribut inert, damit Fokus und Navigation mit Hilfstechnologien sie überspringen.

<rk-reel-indicator> wird als role="tablist" mit wanderndem tabindex auf den Punkten gerendert; die Pfeiltasten bewegen den Fokus, und Enter oder die Leertaste aktiviert die Slide.

Du baust ein eigenes Modal um <rk-reel>? captureFocusForReturn, createFocusTrap und getFocusableElements werden von @reelkit/angular erneut exportiert, für die Rückgabe und das Festhalten des Fokus.

Exporte des Pakets

Alle öffentlichen Exporte von @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';