React useImperativeHandle — カスタムコンポーネントAPIの公開

useImperativeHandleによるカスタムコンポーネントAPI

useImperativeHandleは、コンポーネントでrefを使用するときに親が見るものをカスタマイズできます。DOM全体を公開する代わりに、公開したいメソッドのみを公開します。

パターン

const Modal = forwardRef<ModalHandle, { children: React.ReactNode }>(
  function Modal({ children }, ref) {
    const dialogRef = useRef<HTMLDialogElement>(null);

    useImperativeHandle(ref, () => ({
      open() { dialogRef.current?.showModal(); },
      close() { dialogRef.current?.close(); },
    }));

    return <dialog ref={dialogRef}>{children}</dialog>;
  }
);

使用するタイミング

• 再利用可能なUIライブラリコンポーネント（モーダル、ドロワー、ビデオプレーヤー）の構築
• サードパーティの命令的APIをラップするコンポーネント
• 宣言的パターンでは不十分な場合にのみ使用

ほとんどの通信はpropsとstateを通じて行うべきです。命令的ハンドルは宣言的パターンでは不十分な場合のエスケープハッチです。