Stories Player

@reelkit/react-stories-player を使った、React 用の Instagram 風のストーリーのオーバーレイです。

ライブデモを見る →

機能

インストール

スタイルのインポートを忘れないでください：

クイックスタート

StoriesOverlay コンポーネントはフルスクリーンのストーリーのプレイヤーを描画します。Instagram 風の入り口として StoriesRingList と組み合わせてください。StoriesGroup オブジェクトの配列を渡し、isOpen で表示を制御します。

ライブデモ

ストーリーのリングをクリックするとプレイヤーが開きます。左右をタップして移動し、スワイプでユーザーを切り替えます。

URL の状態

ライブデモを見る →

StoriesUrlOverlay は、開閉状態をアドレスバーに持つ別のコンポーネントです。2 つの軸が 1 つのパラメーター（?story=<group>.<story>）に乗るので、再生中のストーリーに、共有でき、ブックマークでき、戻るボタンで閉じられるリンクが付きます。useOverlayUrlState と urlIndexTwoAxisKey でコントローラーを作り、controller として渡します。

• 開くと履歴エントリーを 1 つ 積みます。ストーリーのスワイプ も ユーザーの切り替えもそれを 置き換え るので、N 回移動してもエントリーは増えず、1 回戻れば必ずプレイヤーが閉じます。戻るとプレイヤーが閉じ、ストーリーは戻りません。
• 内側の移動も運ばれます。 ストーリーのインデックスはグループ単位で固定されず、ユーザーのストーリー内で進むと ?story=2.n が更新されるので、ディープリンクは正確なストーリーに着きます。
• 戻るで閉じるのは、アプリ内から開いた場合だけです（リンクがエントリーを積んだ場合）。新しいタブで直接開いた共有リンクには前の履歴がないので、ブラウザーの戻るではサイトを離れます。✕ ボタンか Escape なら、その場でパラメーターを取り除いてページにとどまります。
• どのグループやストーリーも指さないパラメーター（古いブックマーク、手で書き換えた値、グループの末尾を超えたストーリー）は、隣を開くのではなく URL から取り除かれます。

ルーターを使うアプリでは、アダプターを渡します。 ルーターの裏で history.pushState を書くと、その位置情報が古くなり、次のナビゲーションでパラメーターが消えます：

安定したリンク。 グループはデフォルトで位置なので、ブックマークした ?story=2.0 はフィードが並べ替えられると別のユーザーを開きます。代わりにグループを安定した id で指してください。outerCodec が id を URL に書き、outerLocator がその場所を探します。ストーリーの側は、解決されたグループ内の単純なインデックスのままです。

無限フィード。 ページングは codec とは関係なく、outerLocator の役目です。locate は同期なので、読み込み済みのグループにしか答えません。20 件を読み込んだフィードの 400 番目のグループへの共有リンクは見つかりません。locateAsync はフォールバックで、locate が見つけられなかったときだけ呼ばれます。ストーリーは、最終的に決まったグループの範囲に合わせて改めて制限されます。

• locateAsync が保留中のあいだ、プレイヤーは閉じたままで、パラメーターはそのまま残るので、ディープリンクは取得のあいだも失われません。null か reject でパラメーターは取り除かれます。
• URL が変わったあと、閉じたあと、アンマウントしたあとに届いた答えは破棄されます。遅い取得が、誰も求めていないストーリーを開くことはありません。
• useOverlayUrlState のすべてのオプションは React API リファレンス に、手順は React ガイド にあります。

見たところを覚えておく

リングは、グループを最後まで見るまでグラデーションを表示し、グループは閲覧者がまだ見ていない最初のストーリーから開きます。どちらも、アドレスバーと同じキーで作った ViewedStateController によるものです。そのため保存されたエントリーは共有リンクのパラメーターとまったく同じになり、キーが id で指すものならフィードが並べ替えられても残ります。

• 最初のストーリーも数えます。 画面にすでに表示されているストーリーはマウント時に既読として報告されるので、ストーリーが 1 つだけのグループは開いて閉じれば見たことになります。
• スワイプで進んでも続きから再開します。 resumeStoryIndex は、このセッションで初めて到達したすべてのグループ（プレイヤーが開いたグループも含む）で参照されます。ただし initialStoryIndex がストーリーを直接指定している場合は別です。すでにスワイプで通過したグループは、離れたところから再び開きます。
• リンクが優先されます。 StoriesUrlOverlay では、何が保存されていても、プレイヤーがどこで開くかはパラメーターが決めます。それ以外では再開のコールバックが決めます。
• 件数は合計ではなく位置です。 エントリーが表すのは到達したいちばん先のストーリーなので、見終えたグループにストーリーを追加するとリングがまた点灯し、途中から削除すると件数が減ります。共有リンクと同じ自己修復です。
• ストレージは差し替えられます。 タブを閉じたら忘れるには createSessionStorageAdapter() を、ほかには独自の StorageAdapter を渡してください。開いている 2 つのタブは、ブラウザーの storage イベントで同期します。

API リファレンス

StoriesOverlayProps

StoriesOverlayProps<T>

StoriesUrlOverlayProps

StoriesUrlOverlayProps<T>

StoriesOverlay の props をすべて受け取りますが、開閉状態の 3 つ（isOpen、initialGroupIndex、initialStoryIndex）は代わりにコントローラーから与えられます。

コールバック

トランジション

groupTransition プロップは、ユーザーのグループ間をスワイプするときの 3D トランジション効果を決めます。トランジション関数は @reelkit/react からインポートします：

コンテンツ読み込みのライフサイクル

各ストーリーのスライドは、SlideRenderProps を通じて渡されるコールバックで読み込み状態を伝えます：

レンダープロップ

UI 要素はすべてレンダープロップで置き換えられます。それぞれが、必要な状態とコールバックをすべて持つ型付きの props を受け取ります。

renderHeader

デフォルトのヘッダー（作者の情報、一時停止とミュートのボタン、閉じるボタン）を置き換えます：

renderFooter

ストーリーの内容の下にフッターを追加します：

renderSlide

デフォルトの画像と動画のスライドを完全に置き換えます。組み込みのメディア処理には ImageStorySlide と VideoStorySlide のサブコンポーネントを使ってください：

renderNavigation

デスクトップのデフォルトの矢印ボタンを置き換えます：

renderProgressBar

デフォルトの canvas の進捗バーを独自の実装に置き換えます。progress シグナルは 0 から 1 の値を出します：

renderLoading

コンテンツの取得中に表示する独自の読み込みインジケーター：

renderError

コンテンツの読み込みに失敗したときの独自のエラーオーバーレイ：

StoriesApi

命令的に制御するには apiRef プロップを使います：

メソッド

ダブルタップといいね

ダブルタップすると組み込みのハートのアニメーションが再生され、すぐに視覚的なフィードバックが返ります。onDoubleTap コールバックはグループとストーリーのインデックス付きで呼ばれるので、いいねを自分の状態（API 呼び出し、ローカルストレージなど）に保存できます。プレイヤー自体は、いいねの状態を内部で管理しません。

ハートのアニメーションをカスタマイズする

アニメーションの速さは --rk-stories-heart-duration トークンで調整します（テーマ設定 を参照）。色、大きさ、またはハートを完全に隠すには、.rk-stories-heart クラスを直接指定してください。HeartAnimation コンポーネントも単独で使えるよう公開されています。

サブコンポーネント

独自のレンダープロップで組み合わせるために公開されている、再利用できる部品です：

CanvasProgressBar

高性能な、canvas で描く分割された進捗バーです。ストーリーごとにセグメントを描き、アクティブなセグメントの塗りを requestAnimationFrame でアニメーションします。ストーリーの多いグループではスライドするウィンドウに対応します。

StoryHeader

作者のアバター、名前、認証バッジ、相対的な時刻、一時停止と再生の切り替え、ミュートの切り替え、読み込みスピナー、閉じるボタンを持つデフォルトのヘッダーです。renderHeader を指定しない場合に自動で使われます。

ImageStorySlide

object-fit: cover の、端まで広がる画像スライドです。ライフサイクルの追跡のために、読み込みとエラーをコールバックで報告します。

VideoStorySlide

iOS で音声を途切れさせないために共有の <video> 要素を使う動画スライドです。自動再生、ポスターのフレーム、サウンドの同期を処理し、長さと再生のライフサイクルのイベントを報告します。

StoriesRing

Instagram 風のグラデーションのリングが付いた円形のアバターです。状態は 2 つで、まだ見るストーリーが残っているグループは回転するグラデーションに、すべて見たグループは落ち着いた平坦なリングになります。

StoriesRingList

作者の名前付きの StoriesRing コンポーネントが横に並ぶ、スクロールできる行です。グループごとに 1 つのリングです。

HeartAnimation

ダブルタップで表示されるハートのアニメーションのオーバーレイです。800ms かけて拡大しながらフェードアウトします。CSS でカスタマイズしてください（ダブルタップといいねの節を参照）。

型

StoryItem

AuthorInfo

StoriesGroup<T>

HeaderRenderProps<T>

FooterRenderProps<T>

SlideRenderProps<T>

NavigationRenderProps

ProgressBarRenderProps<T>

LoadingRenderProps<T>

ErrorRenderProps<T>

StoriesApi

カスタム Story 型

StoryItem を独自のフィールドで拡張し、型パラメーターを StoriesOverlay に渡します。すべてのレンダープロップが拡張した型を受け取ります：

CSS クラス

CSS クラスはすべて通常のクラス（CSS Modules ではありません）なので、@reelkit/react-stories-player/styles.css のあとに読み込むスタイルシートで、詳細度の高いセレクターを使って指定できます。色、サイズ、z-index を変えるなら、下の テーマ設定 で説明している CSS カスタムプロパティを使ってください。

テーマ設定

色、サイズ、z-index、トランジションはすべて CSS カスタムプロパティにあります。:root（またはオーバーレイの任意の祖先）で 1 つでも複数でも上書きすれば、コンポーネントのソースに触れずにテーマを変えられます。

下のスニペットを、@reelkit/react-stories-player/styles.css のあとに読み込むスタイルシートに入れてください。

アクセシビリティ

オーバーレイのルートはモーダルダイアログ（role="dialog"、aria-modal="true"）です。ariaLabel を指定すると、スクリーンリーダーの読み上げが変わります。デフォルトは「Stories player」です。

オーバーレイは開くとフォーカスを取り込み、閉じるとトリガーに戻します。Tab と Shift+Tab は中のフォーカス可能な要素を循環し、外へ出たフォーカス（外側のクリック、プログラムからのフォーカス）は引き戻されます。@reelkit/core の captureFocusForReturn と createFocusTrap で実装されています。

キーボードショートカット