useImperativeHandle：カスタムインスタンス値

ref を DOM 要素へ直接転送すると、親はその生の DOM ノードを受け取り、すべてのネイティブメソッドとプロパティにアクセスできるようになります。しかし、これは公開したい範囲を超えていることがよくあります。

場合によっては、DOM ノード全体ではなく、必要な機能だけをまとめた小さなオブジェクトを親に渡し、コンポーネントの公開 API を意図的に狭く保ちたいことがあります。

useImperativeHandle を使うと、親の ref が指す値をカスタマイズできます。親が受け取るのは DOM ノードではなく、返した任意のオブジェクトです。そのため、どのメソッドや値を公開するかを正確に決められます。

これにより、転送された ref は内部要素への無制限なパススルーではなく、定義された命令型インターフェースになります。

このフックは、転送された ref を第 1 引数として、ファクトリ関数を第 2 引数として受け取ります。ファクトリ関数は、親の ref.current になるハンドルオブジェクトを返します。

useImperativeHandle(ref, () => ({ ... })) のように呼び出し、ファクトリ関数内で利用可能にしたいメソッドと値のオブジェクトを構築します。

よくあるパターンは、focus と clear だけを公開するカスタム input です。ファクトリ関数内でこの 2 つのメソッドを持つオブジェクトを返し、それぞれが実際の input への内部 ref を操作するようにします。

これで親はフィールドにフォーカスしたり内容を消去したりできますが、生の value 属性を読み取ったり、任意の DOM 動作を実行したりはできません。使い方が予測しやすくなります。

命令型ハンドルはダイアログとよく適合します。Modal コンポーネントで open と close メソッドを公開し、内部の表示状態を切り替えることで、親は open boolean 自体を管理せずに命令型で制御できます。

これは、非同期処理の完了後に確認ダイアログを表示するなど、さまざまな場所からダイアログを起動する必要があるコードで便利です。

サポートするメソッドだけを返すことで、明確な契約を作れます。利用側は広大な DOM API ではなく、小さく文書化された操作セットに依存するため、将来のリファクタリングが安全になります。

命令型 API の公開範囲を狭くすると、テストや推論が容易になり、内部実装を変更しても壊れにくくなります。

useImperativeHandle は、省略可能な第 3 引数として依存配列を受け取ります。いずれかの依存関係が変化すると、useMemo や useEffect と同様にファクトリ関数が再実行され、ハンドルオブジェクトが再作成されます。

公開するメソッドが変化する可能性のある値をクロージャで参照する場合は、それらの値を依存関係に含めてください。そうすれば、親は常に現在の state に結び付いたハンドルを受け取れます。

useImperativeHandle は、forwardRef でラップされたコンポーネント内で使って初めて意味を持ちます。カスタムハンドルを設定するには転送された ref が必要だからです。単独では、値を設定する親の ref がありません。

そのため、この 2 つは一緒に使用します。forwardRef が ref を受け取り、useImperativeHandle がその ref の最終的な参照先を定義します。

ハンドルをテストするには、ref 付きでコンポーネントをレンダーし、act ブロック内で ref.current を通してメソッドを呼び出し、その結果の動作や DOM の変更をアサートします。

公開される範囲が小さく明示的なので、テストも焦点を絞れます。内部の詳細を直接調べるのではなく、文書化された各メソッドが契約どおりに動作することを検証できます。

TypeScript では、focus と clear メソッドを持つものなど、ハンドルを表す interface を定義します。そして、その interface を forwardRef のジェネリック型と親が保持する ref の型付けに使用します。

これにより、呼び出し側で自動補完とコンパイル時チェックが利用でき、存在するメソッドが正確に分かるため、誤った使い方を実行時より前に検出できます。

useImperativeHandle が実際に何のために使われるのかを確認します。

useImperativeHandle は、転送された ref が公開する内容をカスタマイズします。ref と、ハンドルオブジェクトを返すファクトリ関数を受け取ります。これを使って focus と clear のような小さな API や、Modal の open と close を公開できます。

必ず forwardRef と組み合わせて使用し、依存配列によってハンドルを更新できます。また、TypeScript の interface や焦点を絞ったテストとも相性が良い機能です。公開範囲を制限するのは意図的な、良い設計です。