React-API-Referenz

Vollständige Referenz für die Komponenten, Props und Methoden von @reelkit/react.

Props von Reel

ReelProps

Callbacks

Methoden von ReelApi

Auf die Methoden des Sliders greifst du über apiRef zu:

const apiRef = useRef<ReelApi>(null);

// Navigation
apiRef.current?.next();
apiRef.current?.prev();
apiRef.current?.goTo(5);           // instant
apiRef.current?.goTo(5, true);     // animated

// Lifecycle
apiRef.current?.adjust();          // recalculate positions
apiRef.current?.observe();         // start observing keyboard
apiRef.current?.unobserve();       // stop observing keyboard

Props von ReelIndicator

ReelIndicatorProps

Observer-Komponenten

Observe

Verbindet die Signals aus dem Core mit dem Rendern in React, ohne das Elternelement neu zu rendern. Nur die Funktion in children läuft erneut, wenn sich abonnierte Signals ändern.

import { Observe } from '@reelkit/react';

<Observe signals={[controller.state.index]}>
  {() => <span>Current: {controller.state.index.value}</span>}
</Observe>

AnimatedObserve

Abonniert Signals mit animierten Werten und interpoliert sie weich per requestAnimationFrame.

import { AnimatedObserve } from '@reelkit/react';

<AnimatedObserve signal={controller.state.axisValue}>
  {(value) => (
    <div style={{ transform: `translateY(${value}px)` }} />
  )}
</AnimatedObserve>

SwipeToClose

<SwipeToClose> legt seine Kinder in einen Container, der einem vertikalen Wischen folgt und onClose aufruft, sobald das Wischen die Schwelle überschreitet — die Geste zum Schließen der Lightbox und des Stories Player, für ein eigenes Overlay. SwipeToCloseProps typisiert seine Props; SwipeToCloseDirection ist 'up' | 'down'.

SoundProvider

<SoundProvider> erstellt einen SoundController, anfangs stumm, und reicht ihn über useSoundState an seine Kinder weiter. Die Overlays rendern selbst einen; füge deinen eigenen nur um einen eigenen Player hinzu, dessen Bedienelemente sich eine Stummschaltung teilen.

Hooks

useBodyLock

Sperrt das Scrollen des Body und gleicht die Verschiebung durch die Breite der Scrollbar aus.

import { useBodyLock } from '@reelkit/react';

// Lock body scroll when overlay is open
useBodyLock(isOpen);

useOverlayUrlState

OverlayUrlStateOptions

Baut einen URL-State-Controller für ein Overlay, den du einem *UrlOverlay als Prop controller übergibst.

Eine Schritt-für-Schritt-Erklärung und Beispiele findest du unter URL-State im React-Leitfaden.

useReactRouterUrlAdapter

Ein UrlAdapter auf Basis von React Router. Übergib ihn in einer App mit Router als Option adapter an useOverlayUrlState, damit der Router die einzige Quelle der Wahrheit für die Navigation bleibt – wer am Router vorbei history.pushState schreibt, lässt seine Location veralten, und die nächste Navigation verliert den Parameter. Geschrieben wird nur die Query, Pfad und Hash bleiben also unberührt. Jede Änderung meldet, ob der Router auf derselben Seite einen Eintrag angelegt, ersetzt oder sich durch den Verlauf bewegt hat, sodass eine aus einem <Link> geöffnete Galerie mit einem Schritt zurück schließt.

Kommt aus einem eigenen Subpfad, damit eine App ohne Router nie react-router-dom in ihr Bundle zieht. react-router-dom ist eine optionale Peer-Abhängigkeit.

import { useReactRouterUrlAdapter } from '@reelkit/react/react-router-url-adapter';

const adapter = useReactRouterUrlAdapter();
const photo = useOverlayUrlState({
  param: 'photo',
  adapter,
  ...urlIndexKey(() => images.length),
});

useReelContext

useReelContext() liest den ReelContextValue des nächsten übergeordneten <Reel> oder gibt außerhalb davon null zurück. <ReelIndicator> verbindet sich darüber selbst; nutze es in deinen eigenen Bedienelementen, die du als Kinder von <Reel> renderst, damit sie dem Slider ohne Props folgen. ReelContext ist das Context-Objekt dahinter — stelle nur in einem Test oder einem eigenen Wrapper einen eigenen Wert bereit.

useSoundState

useSoundState() liest den SoundController aus dem nächsten <SoundProvider> und wirft außerhalb davon einen Fehler. Der Reel Player, die Lightbox und der Stories Player legen einen Provider um ihren Inhalt, sodass eigene Bedienelemente, die du über ihre Render-Props übergibst, damit die Stummschaltung lesen oder umschalten können.

useFullscreen

useFullscreen({ ref }) steuert die Fullscreen-API für das Element in ref und beendet das Vollbild, wenn die Komponente ausgehängt wird. UseFullscreenProps ist sein Argument; UseFullscreenResult ist das Tupel, das es zurückgibt.

Barrierefreiheit

<Reel> rendert als role="region" mit aria-roledescription="carousel". Setze das Prop ariaLabel, um der Region einen Namen für Screenreader zu geben. Eine höfliche Live-Region kündigt bei jedem Slide-Wechsel "Slide N von M" an, ohne das Karussell neu zu rendern. Inaktive Slides bekommen das Attribut inert, damit Fokus und Navigation von Hilfstechnologien sie überspringen.

<ReelIndicator> rendert als role="tablist" mit wanderndem tabindex auf den Punkten; die Pfeiltasten bewegen den Fokus, und Enter oder Leertaste aktivieren den Slide.

Du baust ein eigenes Modal um <Reel>? captureFocusForReturn, createFocusTrap und getFocusableElements werden aus @reelkit/react erneut exportiert, für die Rückgabe und das Einsperren des Fokus.

Hilfsfunktionen

createDefaultKeyExtractorForLoop

Erzeugt einen Key-Extractor, der doppelte Indizes behandelt, wenn loop eingeschaltet ist.

import { createDefaultKeyExtractorForLoop } from '@reelkit/react';

<Reel
  count={items.length}
  size={size}
  loop
  keyExtractor={createDefaultKeyExtractorForLoop(items.length)}
  itemBuilder={...}
/>

Größenerkennung

observeElementSize, getViewportSize, observeViewportSize, isMobileWidth, fitAspectRatio und isTouchDevice werden aus @reelkit/react erneut exportiert, für ein eigenes Overlay, das seine Größe so bestimmt wie die Overlays von reelkit. Siehe Größenerkennung in der Core-API.

Autoplay und Download

Auch createTimerController, createSlideshowController und downloadFile werden aus @reelkit/react erneut exportiert: der Timer hinter dem Stories Player, die Slideshow hinter autoAdvance der Lightbox und die Hilfsfunktion hinter ihrem Download-Button. Siehe Autoplay und Download in der Core-API.