useImperativeHandle
useImperativeHandle
は、ref として公開されるハンドルをカスタマイズするための React フックです。
useImperativeHandle(ref, createHandle, dependencies?)
リファレンス
useImperativeHandle(ref, createHandle, dependencies?)
useImperativeHandle
をコンポーネントのトップレベルで呼び出し、公開される ref ハンドルをカスタマイズします。
import { forwardRef, useImperativeHandle } from 'react'; const MyInput = forwardRef(function MyInput(props, ref) { useImperativeHandle(ref, () => { return { // ... your methods ... }; }, []); // ...
引数
-
ref
:forwardRef
レンダー関数から 2 番目の引数として受け取ったref
です。 -
createHandle
: 引数を受け取らず、公開したい ref ハンドルを返す関数です。ref ハンドルは任意の型が使えます。通常、公開したいメソッドを持つオブジェクトを返します。 -
省略可能
dependencies
:createHandle
コード内で参照されるすべてのリアクティブな値のリストです。リアクティブな値には、props、state、コンポーネント本体に直接宣言されたすべての変数および関数が含まれます。リンタが React 用に設定されている場合、すべてのリアクティブな値が依存値として正しく指定されているか確認できます。依存値のリストは要素数が一定である必要があり、[dep1, dep2, dep3]
のようにインラインで記述する必要があります。React は、Object.is
を使った比較で、それぞれの依存値を以前の値と比較します。再レンダーにより依存値のいずれかが変更された場合、または引数自体を省略した場合、createHandle
関数は再実行され、新しく作成されたハンドルが ref に割り当てられます。
返り値
useImperativeHandle
は undefined
を返します。
使用法
親コンポーネントにカスタム ref ハンドルを公開する
デフォルトでは、コンポーネントはその DOM ノードを親コンポーネントに公開しません。例えば、MyInput
の親コンポーネントが <input>
DOM ノードにアクセスできるようにしたい場合は、forwardRef
を使って明示的に許可する必要があります。
import { forwardRef } from 'react'; const MyInput = forwardRef(function MyInput(props, ref) { return <input {...props} ref={ref} />; });
上記のコードでは、MyInput
の ref は <input>
DOM ノードを受け取ります。ただし、代わりにカスタムな値を公開することもできます。公開されるハンドルをカスタマイズするには、コンポーネントのトップレベルで useImperativeHandle
を呼び出します。
import { forwardRef, useImperativeHandle } from 'react'; const MyInput = forwardRef(function MyInput(props, ref) { useImperativeHandle(ref, () => { return { // ... your methods ... }; }, []); return <input {...props} />; });
上記のコードでは、ref
が <input>
に受け渡しされなくなっていることに注意してください。
例えば、<input>
DOM ノード全体を公開したくはないが、その 2 つのメソッド、focus
と scrollIntoView
は公開したいとします。これを行うには、実際のブラウザの DOM を別の ref に保持しておきます。そして、useImperativeHandle
を使用して、親コンポーネントに呼び出してほしいメソッドのみを含むハンドルを公開します。
import { forwardRef, useRef, useImperativeHandle } from 'react'; const MyInput = forwardRef(function MyInput(props, ref) { const inputRef = useRef(null); useImperativeHandle(ref, () => { return { focus() { inputRef.current.focus(); }, scrollIntoView() { inputRef.current.scrollIntoView(); }, }; }, []); return <input {...props} ref={inputRef} />; });
これで、親コンポーネントが MyInput
への ref を取得し、そのコンポーネントで focus
メソッドと scrollIntoView
メソッドを呼び出すことができるようになります。ただし、親コンポーネントは背後にある <input>
DOM ノードへの完全なアクセス権は持ちません。
独自の命令型メソッドを公開する
命令型ハンドルを介して公開するメソッドは、DOM メソッドと正確に一致する必要はありません。例えば、この Post
コンポーネントは、命令型ハンドルを介して scrollAndFocusAddComment
メソッドを公開します。これにより、ボタンをクリックすると、親である Page
がコメントのリストをスクロールできるだけでなく、入力フィールドにフォーカスもできるようになります。