useImperativeHandle

useImperativeHandle(ref, createHandle, dependencies?)

• リファレンス
  • useImperativeHandle(ref, createHandle, dependencies?)
• 使用法
  • 親コンポーネントにカスタム ref ハンドルを公開する
  • 独自の命令型メソッドを公開する

リファレンス

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、およびコンポーネント内で直接宣言された変数と関数が含まれます。もし linter が React 向けに設定されている場合、linter がすべてのリアクティブな値が依存関係として正しく指定されているかを確認します。依存関係のリストは、一定数の項目があり、[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 がコメントのリストをスクロールできるだけでなく、入力フィールドにフォーカスもできるようになります。