React 用 forwardRef 与 useImperativeHandle 把组件内部方法暴露给父级

为什么需要命令式句柄

多数时候父子组件通过 props 通信就够了。但有些组件天生是"命令式"的：一个弹窗需要父组件触发打开与关闭，一个表单需要父组件主动调用校验或提交。如果为了这些动作设计一堆 props 和状态层层传递，代码会变得很绕。React 提供了 forwardRef 把内部 DOM 或实例透传出去，再用 useImperativeHandle 精确控制向外暴露哪些方法。

forwardRef 转发 DOM 节点

先用 forwardRef 让父组件拿到子组件根节点的真实 DOM，常用于聚焦、测量尺寸。

import { forwardRef } from 'react';

const MyInput = forwardRef<HTMLInputElement>(function MyInput(props, ref) {
  return <input ref={ref} className="field" {...props} />
});

// 父组件
function Form() {
  const inputRef = useRef<HTMLInputElement>(null);
  return (
    <MyInput ref={inputRef} placeholder="请输入" />
  );
}

用 useImperativeHandle 暴露方法

ref 直接透传 DOM 太原始。useImperativeHandle 让你决定"父组件通过 ref 能调用什么"，对外只暴露 open、close、reset 这样的语义方法，内部实现完全隐藏。

import { forwardRef, useImperativeHandle, useRef, useState } from 'react';

export interface ModalHandle {
  open: () => void;
  close: () => void;
}

const Modal = forwardRef<ModalHandle, { title: string }>(function Modal(props, ref) {
  const [visible, setVisible] = useState(false);

  useImperativeHandle(ref, () => ({
    open: () => setVisible(true),
    close: () => setVisible(false),
  }), []);

  if (!visible) return null;
  return (
    <div className="mask">
      <div className="dialog">
        <h3>{props.title}</h3>
        <button onClick={() => setVisible(false)}>关闭</button>
      </div>
    </div>
  );
});

父组件调用命令式句柄

拿到 ref 后，在事件回调里直接调用暴露的方法，不必再为"打开"这件事额外设计状态流。

function Page() {
  const modalRef = useRef<ModalHandle>(null);
  return (
    <>
      <button onClick={() => modalRef.current?.open()}>打开弹窗</button>
      <Modal ref={modalRef} title="确认删除" />
    </>
  );
}

几个注意点

• useImperativeHandle 的第三个参数是依赖数组，方法引用要稳定，避免每次渲染都重建。
• 不要滥用：能用 props/state 表达的交互优先用声明式，命令式句柄只留给"父组件要主动触发"的场景。
• TypeScript 下建议用 interface 约束暴露的句柄类型，父组件调用时才有类型提示。
• ref 默认不转发，必须显式 forwardRef，普通函数组件拿不到内部 ref。