React API リファレンス

@reelkit/react のコンポーネント、props、メソッドの完全なリファレンスです。

Reel の Props

ReelProps

コールバック

ReelApi のメソッド

apiRef からスライダーのメソッドにアクセスします：

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

ReelIndicator の Props

ReelIndicatorProps

オブザーバーコンポーネント

Observe

親を再レンダリングさせずに、コアのシグナルを React の描画につなぎます。購読しているシグナルが変わったときに再実行されるのは、children の関数だけです。

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

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

AnimatedObserve

アニメーションする値のシグナルを購読し、requestAnimationFrame でなめらかに補間します。

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

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

SwipeToClose

<SwipeToClose> は子要素を縦のスワイプに追従するコンテナーで包み、スワイプがしきい値を超えると onClose を呼びます。Lightbox と Stories Player の閉じるジェスチャーを、自分の独自のオーバーレイで使うためのものです。SwipeToCloseProps はそのプロップの型で、SwipeToCloseDirection は 'up' | 'down' です。

SoundProvider

<SoundProvider> は最初はミュートの SoundController を 1 つ作り、useSoundState を通して子に渡します。オーバーレイは自分で 1 つ描画するので、独自のプロバイダーを足すのは、コントロールがミュートの状態を共有する独自のプレイヤーを囲むときだけです。

フック

useBodyLock

body のスクロールを止め、スクロールバーの幅によるずれを補正します。

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

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

useOverlayUrlState

OverlayUrlStateOptions

オーバーレイ用の URL 状態コントローラーを作ります。それを *UrlOverlay の controller プロップに渡します。

手順と例は React ガイドの URL の状態 を参照してください。

useReactRouterUrlAdapter

React Router に連動した UrlAdapter です。ルーターを使うアプリで useOverlayUrlState の adapter オプションに渡すと、ナビゲーションの信頼できる情報源がルーターだけに保たれます。ルーターの裏で history.pushState を書くと、その位置情報が古くなり、次のナビゲーションでパラメーターが消えます。書き込むのはクエリだけなので、パス名とハッシュはそのまま残ります。変更のたびに、ルーターが同じページで push したのか、replace したのか、履歴をたどったのかを報告するので、<Link> から開いたギャラリーは 1 回戻るだけで閉じます。

独自のサブパスから提供されるので、ルーターを使わないアプリのバンドルに react-router-dom が入ることはありません。react-router-dom は任意の peer dependency です。

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

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

useReelContext

useReelContext() は最も近い親の <Reel> の ReelContextValue を読み、外側では null を返します。<ReelIndicator> はこれで自分を接続します。<Reel> の子として描画する独自のコントロールで使えば、プロップなしでスライダーに追従します。ReelContext はその裏にあるコンテキストオブジェクトです。自分の値を渡すのはテストや独自のラッパーの中だけにしてください。

useSoundState

useSoundState() は最も近い <SoundProvider> から SoundController を読み、外側では例外を投げます。Reel Player、Lightbox、Stories Player は中身をプロバイダーで包んでいるので、レンダープロップで渡す独自のコントロールからこれを呼んで、ミュートの状態を読んだり切り替えたりできます。

useFullscreen

useFullscreen({ ref }) は ref の要素に対して Fullscreen API を操作し、コンポーネントがアンマウントされるとフルスクリーンを終了します。UseFullscreenProps はその引数、UseFullscreenResult は返すタプルです。

アクセシビリティ

<Reel> は aria-roledescription="carousel" を持つ role="region" として描画されます。ariaLabel プロップを指定すると、スクリーンリーダー向けの名前が付きます。控えめなライブリージョンが、カルーセルを再レンダリングせずに、スライドが変わるたびに「Slide N of M」と読み上げます。非アクティブなスライドには inert 属性が付くので、フォーカスや支援技術での移動では飛ばされます。

<ReelIndicator> は、ドットにローミング tabindex を持つ role="tablist" として描画されます。矢印キーでフォーカスが移動し、Enter か Space でスライドが有効になります。

<Reel> を囲む独自のモーダルを作るなら、フォーカスを戻したり閉じ込めたりするために captureFocusForReturn、createFocusTrap、getFocusableElements が @reelkit/react から再エクスポートされています。

ユーティリティ

createDefaultKeyExtractorForLoop

loop が有効なときに重複するインデックスを扱うキーエクストラクターを作ります。

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

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

サイズの検出

observeElementSize、getViewportSize、observeViewportSize、isMobileWidth、fitAspectRatio、isTouchDevice は @reelkit/react から再エクスポートされています。reelkit のオーバーレイと同じ方法で自分の大きさを決める独自のオーバーレイに使えます。コア API のサイズの検出を参照してください。

自動再生とダウンロード

createTimerController、createSlideshowController、downloadFile も @reelkit/react から再エクスポートされています。それぞれ Stories Player を動かすタイマー、Lightbox の autoAdvance を動かすスライドショー、そのダウンロードボタンの裏にあるヘルパーです。コア API の自動再生とダウンロードを参照してください。