命令型コンポーネントAPIの構築
フォーカス管理付き入力欄、open／closeメソッドを持つモーダルなど、命令型コンポーネントのパターンを設計します。
「命令型コンポーネントAPIの構築」はCoddyKit上の無料React Academyレッスンです。 これはレッスン3/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはReact Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 React Academyコースには全4レッスンが含まれています。
FocusableInputの設計
まず契約を定義します。FocusableInputはfocus、blur、getValueを公開します。forwardRefでラップし、実際のinputへの内部refを保持して、useImperativeHandleからこの3つのメソッドを返します。
各メソッドは基になるinputに処理を委譲するため、親コンポーネントは生の要素に触れず、必要な操作だけを正確に利用できます。
play/pause/seekToを公開するVideoPlayer
メディアコンポーネントでは、命令型APIが大きな効果を発揮します。VideoPlayerはplay、pause、seekToを公開し、それぞれ内部のvideo refを通じてネイティブのHTMLVideoElementメソッドに処理を委譲できます。
seekToは秒単位の時刻を受け取り、currentTimeを設定します。これにより、propsだけで再生を制御するよりも、親コンポーネントから正確に再生を制御できます。
next/prev/goToSlideを公開するCarousel
Carouselはnext、prev、goToSlideを公開することで、外部コントロールやキーボードハンドラーから操作できるようになります。内部ではこれらのメソッドがアクティブなインデックスの状態を更新し、コンポーネントが新しいスライドに再レンダリングされます。
これは命令型のトリガーと宣言型のレンダリングを組み合わせたものです。親コンポーネントが切り替えを指示し、Carouselは通常の状態の流れを通じて結果をレンダリングします。
命令型APIのドキュメント化
命令型ハンドルは公開契約であるため、各メソッド、そのパラメーター、戻り値をドキュメント化します。明確なドキュメントによって、利用者はサポートされている機能を把握でき、ドキュメント化されていない内部実装への依存も避けられます。
ハンドルは他のAPIサーフェスと同じように扱います。play()、pause()、seekTo(seconds)などのメソッドを一覧にした簡潔なリファレンスがあれば、誤用や混乱を防げます。
ハンドルを発展させる際の後方互換性
利用者がハンドルに依存するようになった後でメソッドを削除または改名すると、破壊的変更になります。既存のシグネチャを変更するのではなく新しいメソッドを追加し、何かを削除する前に段階的に非推奨化します。
ハンドルをバージョン管理されたAPIとして捉えると、コンポーネントを時間とともに拡張しても、下流のコードが壊れるのを防げます。
命令型と制御されたpropsの併用
実際の多くのコンポーネントでは、両方のスタイルを組み合わせます。VideoPlayerはsrc propやautoPlay propを宣言型に受け取りながら、propsだけではうまく表現できない場面のために命令型のplayやseekToも公開できます。
指針は、状態や設定にはpropsを使い、特定のタイミングで発生する一度限りのアクションには命令型ハンドルを使うことです。
act()とrefコールバックによるテスト
命令型APIをテストするには、refを付けてコンポーネントをレンダリングし、操作をactでラップしてから、ref.currentを通じて公開されたメソッドを呼び出します。そして、動画が一時停止された、スライドのインデックスが変わったなど、観測可能な結果をアサートします。
refコールバックを使えば、レンダリング中にハンドルを取得できるため、テストからメソッドを呼び出すための安定した参照を保持できます。
Storybookのストーリー
Storybookは命令型ハンドルを実演するのに適しています。ストーリーでコンポーネントへのrefを保持し、そのメソッドを呼び出すボタンをレンダリングすれば、レビュアーはplay、pause、goToSlideを実際に操作できます。
これらのストーリーは生きたドキュメントとしても機能し、命令型APIが単独でどのように動作するかを正確に示します。
実際の使用例
命令型ハンドルは、React以外のライブラリをラップするときによく使われます。チャートライブラリはredrawやupdateメソッドを、地図SDKはpanToやsetZoomを、リッチテキストエディターはinsertTextやgetContentsを公開します。
このようなライブラリをReactコンポーネントでラップし、整理されたハンドルを公開すると、アプリの他の部分から整然とした慣用的な方法で操作できます。
ハンドルを安定させる
ハンドルのメソッドは現在の状態をクロージャーに取り込むことが多いため、必要なときに更新されるようuseImperativeHandleの依存配列を使い、古いクロージャーを避けるために内部ヘルパーにはuseCallbackを使います。
適切に管理されたハンドルは常に最新の値を使って動作するため、親コンポーネントがgetValueやseekToを呼び出したとき、最新のレンダリングと一貫した動作になります。
クイックチェック：命令型APIの設計
命令型コンポーネントAPIの設計指針を適用します。
まとめ：命令型コンポーネントAPI
FocusableInput、VideoPlayer、Carouselのハンドルを設計し、それぞれが少数のアクションメソッドを公開するようにしました。利用者はこれらを公開APIとして利用するため、メソッドをドキュメント化し、バージョン管理してください。
命令型のアクションと宣言型のpropsを組み合わせ、act内でref.currentを通じてテストし、Storybookで動作を紹介します。同じパターンで、チャート、地図、エディターのライブラリもきれいにラップできます。
よくある質問
「命令型コンポーネントAPIの構築」レッスンは無料ですか？
はい。「命令型コンポーネントAPIの構築」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、React Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 React Academyコースには全4レッスンが含まれています。
「命令型コンポーネントAPIの構築」で何を学びますか？
フォーカス管理付き入力欄、open／closeメソッドを持つモーダルなど、命令型コンポーネントのパターンを設計します。 ブラウザで直接実行するハンズオンコードでReact Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
React Academyを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのReact Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン3/4です。
「命令型コンポーネントAPIの構築」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このReact Academyレッスンでコードを書いて実行できますか？
はい。すべてのReact Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。