9.5 组件实例方法调用与 ref 转发（forwardRef）

在 React 的常规数据流中，父组件通过 Props 向子组件传递数据，子组件通过回调函数向父组件通信。但有时我们需要直接调用子组件内部的方法（例如让一个输入框自动聚焦、触发滚动，或调用自定义组件中的业务方法），这时就需要ref配合forwardRef和useImperativeHandle来实现。

9.5.1 基本概念

React 中ref通常用于访问 DOM 元素（如<input>）。当你想调用某个自定义组件内部的特定方法时，因为函数组件默认没有实例，所以不能直接通过ref获取。forwardRef允许组件将接收到的ref转发给内部节点或暴露的方法，而useImperativeHandle则用于自定义暴露给父组件的实例值或方法。

总结流程：

父子组件通过useRef创建 ref 对象。
子组件用forwardRef包裹，接收父组件传入的ref。
子组件内部用useImperativeHandle定义要暴露的方法/属性。

9.5.2 函数组件暴露方法核心示例

比如，我们有一个FancyInput组件，希望父组件能直接调用它的focus和clear方法。

子组件 FancyInput.jsx：

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

const FancyInput = forwardRef((props, ref) => {
  const inputRef = useRef(null);

  // 通过该 Hook 指定暴露给父组件的方法
  useImperativeHandle(ref, () => ({
    focus: () => {
      inputRef.current.focus();
    },
    clear: () => {
      inputRef.current.value = '';
    }
  }));

  return <input ref={inputRef} type="text" placeholder="输入内容..." />;
});

父组件：

import { useRef } from 'react';
import FancyInput from './FancyInput';

function App() {
  const fancyRef = useRef(null);

  return (
    <div>
      <FancyInput ref={fancyRef} />
      <button onClick={() => fancyRef.current.focus()}>聚焦</button>
      <button onClick={() => fancyRef.current.clear()}>清空</button>
    </div>
  );
}

父组件通过fancyRef.current直接调用子组件暴露的focus和clear方法，实现了对子组件内部真实 DOM 的控制。这种方式在封装通用组件时非常实用。

9.5.3 useImperativeHandle 控制暴露内容

useImperativeHandle接收三个参数：

useImperativeHandle(ref, createHandle, [deps])

ref：父组件传入的 ref。
createHandle：一个函数，返回要暴露给父组件的对象。
deps（可选）：依赖数组，当依赖变化时重新生成暴露对象。

你可以选择只暴露部分方法，隐藏内部实现细节，保持组件的封装性。

useImperativeHandle(ref, () => {
  return {
    scrollToTop: () => {
      containerRef.current.scrollTop = 0;
    },
    getInfo: () => {
      return {
        scrollTop: containerRef.current.scrollTop,
        count: items.length
      };
    }
  };
}, [items]); // 依赖 items 变化时更新暴露的方法（确保 getInfo 读取到最新 items）

9.5.4 真实业务场景

场景1：可控制的滚动容器

封装一个聊天消息列表，父组件需要在发送新消息后自动滚动到底部，或提供“回到底部”按钮。

ChatList.jsx：

const ChatList = forwardRef(({ messages }, ref) => {
  const listRef = useRef(null);

  useImperativeHandle(ref, () => ({
    scrollToBottom: () => {
      listRef.current.scrollTop = listRef.current.scrollHeight;
    }
  }));

  return (
    <div ref={listRef} style={{ height: 300, overflow: 'auto' }}>
      {messages.map(msg => <p key={msg.id}>{msg.text}</p>)}
    </div>
  );
});

父组件调用：

const chatRef = useRef(null);
const sendMessage = () => {
  // 发送消息逻辑...
  chatRef.current.scrollToBottom();
};

场景2：表单组件提交验证

封装一个复杂的表单组件，父组件需要调用表单的validate方法，返回校验结果，而不用把表单内部状态提升到父组件。

const ComplexForm = forwardRef(({ onSuccess }, ref) => {
  const [formData, setFormData] = useState({});
  
  useImperativeHandle(ref, () => ({
    validate: () => {
      const errors = {};
      if (!formData.name) errors.name = '姓名必填';
      // ...其他校验
      if (Object.keys(errors).length === 0) {
        onSuccess(formData);
        return true;
      }
      setErrors(errors);
      return false;
    }
  }));

  // 表单渲染
});

父组件中：

const formRef = useRef(null);
const handleSubmit = () => {
  if (formRef.current.validate()) {
    console.log('校验通过');
  }
};

9.5.5 类组件中的实例方法

在类组件中，ref可以直接拿到组件实例，因此可以直接调用实例上的方法，无需forwardRef或useImperativeHandle。这是类组件相较于函数组件的一个小便利，但现代开发已不推荐为此而使用类组件。

class ClassInput extends React.Component {
  focus = () => {
    this.input.focus();
  };

  render() {
    return <input ref={el => this.input = el} />;
  }
}

// 父组件使用 ref 直接调用 focus
const ref = useRef(null);
<ClassInput ref={ref} />
ref.current.focus();

但在函数组件中，必须使用forwardRef和useImperativeHandle才能达到相同效果。

9.5.6 常见注意事项

不要过度使用：ref 调用破坏了典型的单向数据流，应优先使用 Props 和状态提升。仅当需要命令式控制 DOM 或调用外部暴露的方法时才使用。
避免直接暴露整个 DOM ref：如果通过useImperativeHandle直接将内部的 DOM ref 暴露出去，父组件就可以随意操纵子组件的 DOM，这会破坏封装性，增加维护风险。应该只暴露有限的、必要的方法。
ref 不是 Props：ref被 React 特殊处理，不会出现在子组件的props中。如果想把 ref 作为普通 prop 传递，你可以通过forwardRef接收并手动传递，但重命名 prop（例如innerRef）可能更清晰，但会失去ref的自动转发能力。
依赖数组的维护：当暴露的方法依赖了某些闭包变量（如状态或 props）时，务必在useImperativeHandle的依赖数组中声明，否则方法中的变量可能过期。这也是一个常见的闭包陷阱。

9.5.7 总结

forwardRef与useImperativeHandle是函数组件下实现实例方法调用的标准范式。它们在封装通用组件库、处理聚焦、滚动、表单校验等场景下不可或缺。合理使用它们可以在保持组件封装性的同时，提供必要的命令式控制能力，是 React 高阶组件开发必备技能。